Custom Arguments

Using Custom Arguments in SiteMaker

The Custom Arguments are located at the end of the Settings Tab.

An example of using custom arguments to trim the processed dataset based on scan times:

--start-time=240 --stop-time=1250

Here, the processing starts from second 240 of the scan and ends at second 1250 of the scan.

There is a strict list of allowed custom arguments. You will find it in the last section of this page.

• You can combine multiple custom arguments with spaces, as long as the arguments do not conflict with each other

  • For example: --start-time=1250 --stop-time=240 will not work.

• Many custom arguments require input from the user:

  • A standalone argument, e.g. --no-pano

  • A numbered value needs to be defined by the user: e.g. --start-time=240

  • Choosing from a list of options: e.g. --cloud-format=e57; here only a selection from {e57,pts,ptx,pcd,xyz,las,ply} is allowed

Adding Custom Arguments

If you need to use post-processing options that are not available in the settings directly, you can add custom arguments. Every custom argument entered is saved in the custom arguments (advanced) drop-down list, which can hold up to 15 different combinations.

Custom arguments override the settings in the other checkboxes if there is a contradiction.

To add custom arguments, do the following:

1. In NavVis SiteMaker, click the Settings tab.

2. Under the Advanced Settings section, from the Custom arguments (advanced) combination box, enter a custom argument, or click the drop-down list and select a previously entered and saved custom argument.

3. Press enter to apply the selection.

To see examples of custom arguments and their meanings, click the blue information button .

List of Custom Arguments

A comprehensive list of custom arguments is accessible on any desktop equipped with SiteMaker. Open a terminal and enter the following command to get all arguments displayed:

navvis-postprocessing --help

Note: You can also process one or multiple data using commands in a terminal window. Examples appear at the end of the Help description.

A list of the Help description including all custom arguments for reference (Status v2.22.14, released Jun 12, 2024):

navvis-postprocessing --help
***************************************************************************
 Post-processing of NavVis datasets, (c) 2023 NavVis GmbH
***************************************************************************
usage: navvis-postprocessing [options] --proc-base-dir=<output> <input>

Post-processes datasets of NavVis mobile mapping systems.
For more information see the documentation at: https://portal.navvis.com
or if you were unable to resolve your issue contact support@navvis.com
    

options:
  -h, --help            show this help message and exit

Standard arguments:
  input                 List of recorded datasets, i.e. one or multiple dataset directories that should
                        be processes. May contain wildcards "/my/data/datasets_rec/*" for processing
                        multiple datasets.
  --proc-base-dir /path/to/datasets_proc
                        Base directory where sub-folders will be created for all output directories.
  --out-dir OUT_DIR     Output directory; only valid if a single dataset is processed. For standard
                        usage, use --proc-base-dir instead.
  --start-time START_TIME
                        Start time defining from which point (in time) a dataset is meant to be
                        processed. The time must be specified either as the time in seconds relative to
                        the beginning of the dataset or as an absolute unix timestamp in seconds. The
                        time stamps are specific for each individual dataset.
  --stop-time STOP_TIME
                        Stop time defining up to which point (in time) a dataset is meant to be
                        processed. The time must be specified either as the time in seconds relative to
                        the beginning of the dataset or as an absolute unix timestamp in seconds. The
                        time stamps are specific for each individual dataset.

Other:
  --sensor-frame SENSOR_FRAME
                        Explicitly specifies a certain calibration file (sensor_frame.xml). (default:
                        None)
  --save-debug-trajectories
                        If set, one trajectory ply file will be saved for each floor (M6 and VLX).
                        (default: False)
  --no-auto-transform   Disables automatic transformation into the control point coordinate system.
                        This only has an impact if the option --use-anchors is specified. (default:
                        False)
  --allocated-memory ALLOCATED_MEMORY
                        Restrict postprocessing to only use the allocated memory, in bytes. Suffixes
                        such as kB, MB, MiB, GB or GiB are supported, e.g. 10GiB. By default all
                        available memory will be used. Note: For stability reasons, the argument
                        --allocated-vcpus must be provided as well.
  --allocated-vcpus ALLOCATED_VCPUS
                        Restrict postprocessing to use only the allocated number of vCPUs. By default,
                        all available CPUs will be used. Note: For stability reasons, the argument
                        --allocated-memory must be provided as well.
  --num-threads-omp NUM_THREADS_OMP
                        Set number of threads for all steps that use openMP. Note that for a few steps
                        the openMP limits are ignored if the arguments --allocated-memory and
                        --allocated-vcpus are provided.
  --laser-vert-box-filter-dim LASER_VERT_BOX_FILTER_DIM
                        Dimensions of the box filter to be applied to the vertical laser. The box is
                        assumed to be in cam_head coordinate system and should be a string. Example:
                        "min_x max_x min_y max_y min_z max_z". The filter is applied both during SLAM
                        and point cloud generation. It is always applied with default dimensions (-0.2,
                        0.9, -0.6, 0.6, -2.1, 0.0) for specific devices. (default: )
  --no-terminal-text-color, --no-color
                        Do not colorize text in terminal. (default: False)

SLAM:
  --use-anchors         If given will use anchor poses in rec dataset for post-processing if they are
                        present or use the file given with --anchor-poses (default: False)
  --anchor-poses ANCHOR_POSES
                        If given in addition to --use-anchors, use anchor poses from provided file for
                        all datasets. File may be in anchor poses txt format or anchor poses csv format
  --anchor-usages ANCHOR_USAGES
                        If given in addition to --use-anchors, use anchor usages file from provided
                        file. Only works when processing a single dataset. When processing more than one
                        dataset change the file (anchors/anchors.txt) directly in the dataset_rec_folder
  --anchor-poses-rec ANCHOR_POSES_REC
                        If given in addition to --use-anchors, use the recorded anchor poses from
                        provided file. These are the anchor poses as recorded by live SLAM and the file
                        is used for anchor verification. The argument only works when processing a
                        single dataset. When processing more than one dataset change the file
                        (anchors/anchor_poses_recorded.txt) directly in the datasets_rec folder
  --anchor-offsets ANCHOR_OFFSETS
                        If given in addition to --use-anchors, use anchor offsets from provided csv
                        file. Use this when the relative position of the control point pointer and
                        device origin is changing from cp to cp as with visual control points. Only
                        works when processing a single dataset. When processing more than one dataset
                        add the file (anchors/anchor_offsets.csv) directly in the dataset_rec_folder
  --ignore-anchor-verification
                        If given will ignore result of anchor verification and continue processing.
                        This will however not fix any slam or control point related issues, just allow a
                        pointcloud to be created even though the trajectory is likely broken (default:
                        False)
  --use-anchor-stage {alignment4DoF,alignment,verification,optimization}
                        Anchor stage of which results shall be used in following pipeline steps. 
                        (default: optimization)
  --slam-config {default,hybrid,reject-outliers,live,legacy}
                        default: Config that should give the highest accuracy in the widest range of
                        scenarios 
                        hybrid: In case the quality map looks more broken in the post-processed dataset
                        than in the recorded dataset, use this option to use a SLAM configuration more
                        similar to the live-mapping one to attempt to fix the problem. Use with care and
                        check the results. Beta, may be removed at any time.
                        reject-outliers: May give more robust results in some scenarios (outdoor,
                        cluttered scene) where many outliers are present. Beta, may be removed at any
                        time.
                        live: Internal use. Use same parameters as in live mapping. Usually use
                        'hybrid' when you think you should use this. May be removed at any time.
                        legacy: Use for processing VLX datasets that succeeded in the past but fail
                        now.
                         (default: default)
  --slam-only           Only steps until SLAM and quality map generation are run. 
                        No pointclouds or panoramas are generated. This may be useful when evaluating
                        different anchor configuration. (default: False)
  --bagplayer-args BAGPLAYER_ARGS
                        Args passed to bag player for SLAM (default: --quiet)
  --no-loop-closures    If given, do not use loop closures in final optimization. (default: False)
  --fixed-datasets-proc FIXED_DATASETS_PROC [FIXED_DATASETS_PROC ...]
                        List of fixed datasets used as a reference for cross dataset loop closure
                        alignment. (default: [])

Point cloud generation:
  --res [0.005, 0.01, ... 0.2]
                        Sets the spatial resolution in [m] of the generated point cloud. (default: 0.01)
  --preset {standard,outdoors,high-confidence}
                        Pointcloud settings which control which regions of the recorded data will
                        appear in final pointcloud (VLX Only). Standard should give good results in a
                        wide range of scenarios. Outdoors gives more complete results in areas where
                        objects were only scanned sparsely and increases maximum range. High-confidence
                        will reduce the maximum range and keep only well scanned areas. This can be used
                        to remove unintentionally scanned regions and keep only the most accurately
                        scanned regions.
  --dynamic-objects-filter-mode {disabled,balanced,aggressive}
                        Desired strength of dynamic object filtering from clouds. (default: balanced)
  --use-all-lasers      EXPERIMENTAL: For M6 only - creates pointcloud from all lasers including the 3D
                        laser (M6).
                        This increases completeness when scanning large areas but may result in a
                        decrease in pointcloud accuracy and increase in processing time. (default:
                        False)
  --max-laser-range MAX_LASER_RANGE
                        Sets the maximum range in [m] used to generate the point cloud. (default: 30.0)
  --min-laser-range MIN_LASER_RANGE
                        Sets the minimum range in [m] used to generate the point cloud.
  --filter-bottom-laser-radius FILTER_BOTTOM_LASER_RADIUS
                        The radius [m] of the cylinder filter for the bottom laser (M6).
  --num-threads-qm-aggregator NUM_THREADS_QM_AGGREGATOR
                        Number of threads that the quality-map uses to aggregate points
  --keep-cloud-tmp-results
                        Do not remove the temporary point cloud results. (default: False)
  --laser-topic-cloud-builder LASER_TOPIC_CLOUD_BUILDER [LASER_TOPIC_CLOUD_BUILDER ...]
                        List of topics that should be used for pointcloud aggregation. List of
                        available topics per config can be found in navvis_launch configs or bag files.
  --cloud-format {e57,pts,ptx,pcd,xyz,las,ply} [{e57,pts,ptx,pcd,xyz,las,ply} ...]
                        Sets the desired pointcloud output format(s). Multiple values can be given if
                        more than one format is desired. (default: ['ply'])
  --cloud-mode {sharp-edges, balanced, smooth-surfaces}
                        Controls the point cloud filtering mode. Only affects M6 datasets. See
                        https://docs.navvis.com/mapping/current/en/html/point_clouds/cloud_modes.html#bgk-cloud-mode
                        for details. (default: sharp-edges)
  --experimental-cloud-pipeline
                        EXPERIMENTAL for M6: Use the scalable, detail retaining and faster point cloud
                        processing pipeline used for VLX. If given, the cloud processing options in the
                        section marked as "default pipeline" will not have any effect on the output.
                        (default: False)
  --store-raw-cloud     Stores the raw point cloud along with the filtered one.Default: Enabled for M6,
                        disabled for VLX. (default: False)
  --num-threads-cloud-builder NUM_THREADS_CLOUD_BUILDER
                        Set the number of threads.
  --num-threads-cloud-filter NUM_THREADS_CLOUD_FILTER
                        Set the number of threads.

Point cloud generation (M6 pipeline):
  --no-cloud-processing
                        Temporary very raw pointclouds are created but no aggregation or filtering is
                        performed.
                        Intermediate clouds will be kept. These may be very large. (Desktop Processing
                        only) (default: False)
  --no-cloud-filtering  Do not filter the raw point cloud. It implies that coloring and panorama
                        stitching will be skipped as well. (Desktop Processing only) (default: False)

Point cloud coloring:
  --color-extrapolation COLOR_EXTRAPOLATION
                        Determines how points not seen by the cameras are treated. (default: fill)
  --no-color-cloud      Do not colorize the point cloud with RGB colors from images. Instead the cloud
                        will have lidar return intensities on the intensity channel. These are usually
                        shown as grayscale values in viewing applications. (default: False)
  --coloring-output-type COLORING_OUTPUT_TYPE
                        Specifies the output type of the colored pointcloud.'rgbi' will store both RGB
                        values and intensity.'rgb' will store only RGB values. (default: rgbi)
  --coloring-max-view-distance COLORING_MAX_VIEW_DISTANCE
                        Sets the maximum range for colorization as maximum distance from a point to a
                        camera. (default: 35.0)

Panorama Rendering:
  --no-pano             Do not render panoramic images. (default: False)
  --no-mask-pano        No "operator mask" is applied to cut out the operator from the panoramic
                        images. Note: Parts of the trolley operator may be visible in the panoramic
                        images!" (default: False)
  --mask-pano MASK_PANO
                        An optional "operator mask" to cut out the operator from the panoramic images.
                        If omitted, a default "operator mask" is computed internally and applied to the
                        panoramic images.
                        See the mapping documentation for how to create an operator mask.
  --no-pano-floor-filling
                        Disable panoramic image floor filling. (default: False)
  --keep-pano-tmp-results
                        Do not remove the temporary stitching results. (default: False)
  --num-threads-panos NUM_THREADS_PANOS
                        Set the number of rendered panoramas in parallel.
                        Allowed values: [1, 2, 3, ...].
                        Note: The maximum amount of rendered panoramas in parallel is limited by the
                        number of available system threads and the available/free system memory (RAM).
                        If omitted, the number of rendered panoramas in parallel is computed internally,
                        whereby the default number of parallel rendered panoramas is limited to 16.
  --save-debug-pano     Save panoramic images overlayed with seams and overlap areas for each capture
                        location to disk,as well as blending masks and projected images.These images
                        serve QA and debugging purposes and are saved in subfolders of the temporary
                        stitching directory (<datasets_proc>/tmp/stitching/). Note: If enabled,
                        temporary stitching artifacts will not be deleted.
                         (default: False)
  --save-pano-zip       Store a ZIP file (pano.zip) containing all panoramic images as well as the
                        quality mapand the pano-poses. (default: False)
  --allow-hardware-rendering
                        Allow use of hardware renderer wherever possible (software rendering otherwise)
                        (default: False)

Image Enhancement Options:
  --no-image-enhancement
                        Disables any image enhancement and will only convert RAW images to JPG.
                        (default: False)
  --hdr-light           Uses a fast variant of image processing with no actual HDR processing but
                        tonemapping with highlight preservation (default: False)
  --always-use-hdr      Forces the use of the HDR pipeline even if images do not officially support it.
                        Use at your own risk. (default: False)
  --camera-wb           Disables auto white balance in image postprocessing (and uses camera white
                        balance instead). (default: False)
  --enable-vignetting   Enables vignetting correction in image postprocessing. (default: False)
  --blur-regions BLUR_REGIONS
                        Path to the directory of the JSON files that describe the image regions to be
                        blurred. The JSON files must be in the format as provided by the AWS Rekognition
                        service. (default: None)
  --num-threads-img-proc NUM_THREADS_IMG_PROC
                        Number of threads used by nv_image-postprocessing. If omitted, the number is
                        computed internally and limited to 12.

Special Options:
  --keep-all-tmp-results
                        Do not remove the temporary results (default: False)
  --rosmaster-port ROS_MASTER_PORT
                        Port on which to run roscore. If not given, processing runs without any roscore
                        for SurveyorSLAM. (default: None)

Force Options:
  --force, -f           Force post-processing: Overwrite existing files/directories. (default: False)
  --force-trajectories  Deprecated. Same behavior as --force. (default: False)
  --force-cloud         Deprecated. Same behavior as --force. (default: False)
  --force-color-cloud   Deprecated. Same behavior as --force. (default: False)
  --force-pano          Deprecated. Same behavior as --force. (default: False)

Action Options:
  --start-from START_FROM
                        Start processing with this action.
                         (default: None)
  --finish-after FINISH_AFTER
                        Finish processing after this action.
                         (default: None)

Usage examples:

  Process a single dataset:
   navvis-postprocessing --proc-base-dir=/data/Project/datasets_proc /data/Project/datasets_rec/2014-11-23_14.48.37 

  Process multiple datasets, one after another:
   navvis-postprocessing --proc-base-dir=/data/Project/datasets_proc /data/Project/datasets_rec/* 

  Process multiple datasets, one after another within a joint coordinate system with SLAM anchors:
   navvis-postprocessing --proc-base-dir=/data/Project/datasets_proc /data/Project/datasets_rec/*  --use-anchors --anchor-poses=/data/Project/my_anchor_poses.txt

  Process a single dataset without panorama stitching:
   navvis-postprocessing --no-pano --proc-base-dir=/data/Project/datasets_proc /data/Project/datasets_rec/2014-11-23_14.48.37 

  Force multiple datasets, overwrite existing data:
   navvis-postprocessing --force --proc-base-dir=/data/Project/datasets_proc /data/Project/datasets_rec/* 

  Process multiple datasets and set desired number of panoramic images rendered in parallel:
   navvis-postprocessing --num-threads-panos=4 --proc-base-dir=/data/Project/datasets_proc /data/Project/datasets_rec/*