ROS Parameters

This page contains all parameters exposed to ROS 2. For the provided examples in the nvblox_example_bringup package, parameters are set using YAML configuration files under nvblox_examples/nvblox_examples_bringup/config.

The base parameters are set in nvblox_base.yaml and there exist multiple specialization files that overwrite parameters from the base file depending on the configuration of the launched example/mode.

File tree:

config
├── nvblox
    ├── nvblox_base.yaml
    └── specializations
        ├── nvblox_sim.yaml
        ├── nvblox_realsense.yaml
        ├── nvblox_segmentation.yaml
        └── nvblox_dynamics.yaml

Loaded specializations for each example/mode:

Parameter file	Example/mode
`nvblox_sim.yaml`	`realsense_example.launch.py`
`nvblox_realsense.yaml`	`isaac_sim_example.launch.py`
`nvblox_segmentation.yaml`	`mode:=people`
`nvblox_dynamics.yaml`	`mode:=dynamic`

General Parameters

ROS Parameter	Type	Default	Description
`back_projection_subsampling`	`integer`	`1`	Only back project and publish every n-th depth image.
`clear_map_outside_radius_rate_hz`	`double`	`1.000`	The desired rate for clearing the map from blocks far away from the robot.
`connected_mask_component_size_threshold`	`integer`	`2000`	The minimum number of pixels of a connected component in the mask image to count as a dynamic detection. Otherwise the component is (optionally) removed.
`decay_dynamic_occucancy_rate_hz`	`double`	`10.000`	The desired rate for decaying the dynamic occupancy layer.
`decay_tsdf_rate_hz`	`double`	`5.000`	The desired rate for decaying the TSDF layer.
`enable_mesh_markers`	`boolean`	`False`	Whether to also publish a mesh marker message in additional to the custom nvblox mesh message.
`esdf_and_gradients_unobserved_value`	`double`	`-1000.000`	This value will be used for for unobserved voxels in the dense output grid.
`esdf_mode`	`integer`	`1`	Whether to compute the ESDF in 3D (0) or 2D (1).
`global_frame`	`string`	`odom`	The name of the TF frame in which the map is built. For the RealSense examples, this parameter is exposed as a launch argument.
`input_qos`	`string`	`SYSTEM_DEFAULT`	QOS for subscribers. Can be any of [SYSTEM_DEFAULT, BEST_EFFORT, SENSOR_DATA]
`integrate_color_rate_hz`	`double`	`5.000`	The desired integration frequency of color images.
`integrate_depth_rate_hz`	`double`	`40.000`	The desired integration frequency of depth images.
`integrate_lidar_rate_hz`	`double`	`40.000`	The desired integration frequency of lidar scans.
`layer_visualization_exclusion_height_m`	`double`	`2.000`	Voxels with a z coordinate above this value are not visualized.
`layer_visualization_exclusion_radius_m`	`double`	`5.000`	Voxels further from the robot than this value are not visualized.
`layer_visualization_max_tsdf_distance_m`	`double`	`0.050`	TSDF voxels with a distance above this value are not visualized.
`layer_visualization_min_tsdf_weight`	`double`	`0.100`	TSDF voxels with a weight lower than this value are not visualized.
`layer_visualization_undo_gamma_correction`	`boolean`	`False`	Apply a undo-gamma operation on the RGB values of the visualized layer. Usable if the rendering pipeline includes gamma correction, which is the case when rendering mesh markers in Foxglove.
`lidar_height`	`integer`	`16`	Height of the LIDAR scan, in number of beams. Default works for the VLP16.
`lidar_vertical_fov_rad`	`double`	`0.524`	The vertical field of view of the LIDAR scan, in radians (assuming beams are centered around 0 elevation). Default is for the VLP16.
`lidar_width`	`integer`	`1800`	Width of the LIDAR scan, in number of beams. Default works for the VLP16.
`map_clearing_frame_id`	`string`	`base_link`	The name of the TF frame around which we clear the map.
`map_clearing_radius_m`	`double`	`5.000`	Radius around the `map_clearing_frame_id` outside which we clear the map. Note that values <= 0.0 indicate that no clearing is performed.
`mapping_type`	`string`	`static_tsdf`	Type of mapper to use. See docs for description
`max_angle_above_zero_elevation_rad`	`double`	`0.262`	The angle above zero elevation of the highest beam (specified as a positive number in radians). Default is for the Hesai PandarXT32.
`max_back_projection_distance`	`double`	`5.000`	The maximum depth in meters when visualizing the back-projected point cloud.
`maximum_sensor_message_queue_length`	`integer`	`10`	How many messages to store in the sensor messages queues (depth, color, lidar) before deleting oldest messages.
`min_angle_below_zero_elevation_rad`	`double`	`0.349`	The angle below zero elevation of the lowest beam (specified as a positive number in radians). Default is for the Hesai PandarXT32.
`num_cameras`	`integer`	`1`	Number of cameras supported (number of subscribers created)
`pose_frame`	`string`	`base_link`	Only used if use_topic_transforms is set to true. Pose and transform messages will be interpreted as being in this pose frame, and the remaining transform to the sensor frame will be looked up on the TF tree.
`print_delays_to_console`	`boolean`	`False`	Whether to print delay stats to the console.
`print_rates_to_console`	`boolean`	`False`	Whether to print rate stats to the console.
`print_statistics_on_console_period_ms`	`integer`	`10000`	Specified how often to print timing and rate statistics to the terminal.
`print_timings_to_console`	`boolean`	`False`	Whether to print timing stats to the console.
`publish_esdf_distance_slice`	`boolean`	`True`	Whether to output a distance slice of the ESDF to be used for path planning.
`publish_layer_rate_hz`	`double`	`10.000`	The desired rate for publishing layer visualization messages.
`qos_overrides./parameter_events.publisher.depth`	`integer`	`1000`	QoS policy {depth} for publisher {/parameter_events} Constraints: Read only: true
`qos_overrides./parameter_events.publisher.durability`	`string`	`volatile`	QoS policy {durability} for publisher {/parameter_events} Constraints: Read only: true
`qos_overrides./parameter_events.publisher.history`	`string`	`keep_last`	QoS policy {history} for publisher {/parameter_events} Constraints: Read only: true
`qos_overrides./parameter_events.publisher.reliability`	`string`	`reliable`	QoS policy {reliability} for publisher {/parameter_events} Constraints: Read only: true
`slice_visualization_attachment_frame_id`	`string`	`base_link`	Frame to which the map slice bounds visualization is centered on the `xy`-plane.
`slice_visualization_side_length`	`double`	`10.000`	Side length of the map slice bounds visualization plane.
`tick_period_ms`	`integer`	`10`	Specifies How often the main tick function of the node is ticked.
`update_esdf_rate_hz`	`double`	`5.000`	The desired ESDF update frequency.
`update_mesh_rate_hz`	`double`	`5.000`	The desired mesh update frequency.
`use_color`	`boolean`	`True`	Whether to integrate color images to color the mesh.
`use_depth`	`boolean`	`True`	Whether to integrate depth images.
`use_lidar`	`boolean`	`True`	Whether to integrate LiDAR scans.
`lidar_min_valid_range_m`	`double`	`0.100`	The minimum valid range of the lidar.
`lidar_max_valid_range_m`	`double`	`50.00`	The maximum valid range of the lidar.
`use_non_equal_vertical_fov_lidar_params`	`boolean`	`False`	Whether to use non equal vertical FoV for the LiDAR (not centered around 0 elevation). Should be set to false for a VLP16 and to true for Hesai PandarXT32. The LiDAR model will use the `lidar_vertical_fov_rad` parameter if set to false and `min_angle_below_zero_elevation_rad` / `max_angle_below_zero_elevation_rad` if set to true.
`use_sim_time`	`boolean`	`False`	Whether to use simulation time.
`use_tf_transforms`	`boolean`	`True`	Whether to use transforms from the TF tree.
`use_topic_transforms`	`boolean`	`False`	Whether to use transforms as topics.
`voxel_size`	`double`	`0.050`	Voxel size (side of cube in meters) to use for the map.

Mapping Type Parameter

The nvblox node holds two individual mappers (contained in a multi-mapper object). Depth frames received by nvblox are passed to the multi-mapper and split into a static and dynamic part based on a mask image. While the static part is processed by the static_mapper, the dynamic part is handled by the dynamic_mapper.

Depending on the mapping_type parameter these mappers update different layers:

static_tsdf:
- static_mapper: mapping static obstacles using a TSDF layer
- dynamic_mapper: disabled
static_occupancy:
- static_mapper: mapping static obstacles using an occupancy layer
- dynamic_mapper: disabled
dynamic:
- static_mapper: mapping static obstacles using a TSDF layer and updating a freespace layer (needed for dynamic mapping)
- dynamic_mapper: mapping dynamic obstacles in an occupancy layer
human_with_static_tsdf:
- static_mapper: mapping static obstacles using a TSDF layer
- dynamic_mapper: mapping people in an occupancy layer
human_with_static_occupancy:
- static_mapper: mapping static obstacles using an occupancy layer
- dynamic_mapper: mapping people in an occupancy layer

The mapping_type must be specified as a string and defaults to static_tsdf.

Note

The mapping types [static_tsdf, static_occupancy, dynamic] are only valid when running the nvblox_node. In contrast, the mapping types [human_with_static_tsdf, human_with_static_occupancy] can only run with the nvblox_human_node. The nvblox_human_node is adding additional topic subscriptions for the mask image containing the people semantic segmentation.

Mapper Parameters

The static and dynamic mappers share the same parameter set. By specifying the parent parameter name <mapper_name>, the parameters can be set for the corresponding mapper (i.e. static_mapper or dynamic_mapper).

ROS Parameter	Type	Default	Description
`<mapper_name>.check_neighborhood`	`boolean`	`True`	Whether to check the occupancy of the neighboring voxels for the high confidence freespace update.
`<mapper_name>.depth_preprocessing_num_dilations`	`integer`	`4`	Number of times to run the invalid region dilation in the depth preprocessing pipeline (if do_depth_preprocessing is enabled).
`<mapper_name>.do_depth_preprocessing`	`boolean`	`False`	Whether or not to run the preprocessing pipeline on the input depth image. Currently, this preprocessing only consists of dilating invalid regions in the input depth image.
`<mapper_name>.esdf_integrator_max_distance_m`	`double`	`2.000`	Maximum distance to compute the ESDF up to, in meters.
`<mapper_name>.esdf_integrator_max_site_distance_vox`	`double`	`1.000`	Maximum distance to consider a voxel within a surface for the ESDF calculation.
`<mapper_name>.esdf_integrator_min_weight`	`double`	`0.000`	Minimum weight of the TSDF to consider for inclusion in the ESDF.
`<mapper_name>.esdf_slice_height`	`double`	`1.000`	The output slice height for the distance slice and ESDF pointcloud. Does not need to be within min and max height below. In units of meters.
`<mapper_name>.esdf_slice_max_height`	`double`	`1.000`	The maximum height, in meters, to consider obstacles part of the 2D ESDF slice.
`<mapper_name>.esdf_slice_min_height`	`double`	`0.000`	The minimum height, in meters, to consider obstacles part of the 2D ESDF slice.
`<mapper_name>.exclude_last_view_from_decay`	`boolean`	`False`	Whether contributions from the last depth frame should be excluded when decaying
`<mapper_name>.free_region_decay_probability`	`double`	`0.550`	The decay probability that is applied to the free region on decay. Must be in [0.5, 1.0].
`<mapper_name>.free_region_occupancy_probability`	`double`	`0.300`	The inverse sensor model occupancy probability for voxels observed as free space.
`<mapper_name>.lidar_projective_integrator_max_integration_distance_m`	`double`	`10.000`	The maximum distance, in meters, to integrate the depth values for LiDAR scans.
`<mapper_name>.max_tsdf_distance_for_occupancy_m`	`double`	`0.150`	TSDF distance below which we assume a voxel to be occupied (non freespace).
`<mapper_name>.max_unobserved_to_keep_consecutive_occupancy_ms`	`integer`	`200`	Maximum duration of no observed occupancy to keep consecutive occupancy alive.
`<mapper_name>.mesh_bandwidth_limit_mbps`	`double`	`25.000`	Limits the mesh size returned by update-mesh.
`<mapper_name>.mesh_integrator_min_weight`	`double`	`0.000`	Minimum weight of the TSDF to consider for inclusion in the mesh.
`<mapper_name>.mesh_integrator_weld_vertices`	`boolean`	`True`	Whether to weld identical vertices together in the mesh.
`<mapper_name>.mesh_streamer_exclusion_height_m`	`double`	`-1.000`	Mesh blocks above this height will not be streamed.
`<mapper_name>.mesh_streamer_exclusion_radius_m`	`double`	`-1.000`	Mesh blocks outside this radius (centered on the robot) will not be streamed.
`<mapper_name>.min_consecutive_occupancy_duration_for_reset_ms`	`integer`	`2000`	Minimum duration of consecutive occupancy to turn a high confidence free voxel back to occupied.
`<mapper_name>.min_duration_since_occupied_for_freespace_ms`	`integer`	`1000`	Minimum duration since last observed occupancy to consider voxel as free.
`<mapper_name>.occupied_region_decay_probability`	`double`	`0.400`	The decay probability that is applied to the occupied region on decay. Must be in [0.0, 0.5].
`<mapper_name>.occupied_region_half_width_m`	`double`	`0.100`	Half the width of the region which is considered as occupied.
`<mapper_name>.occupied_region_occupancy_probability`	`double`	`0.700`	The inverse sensor model occupancy probability for voxels observed as occupied.
`<mapper_name>.projective_integrator_max_integration_distance_m`	`double`	`7.000`	The maximum distance, in meters, to integrate the depth or color image values.
`<mapper_name>.projective_integrator_max_weight`	`double`	`5.000`	Maximum weight for the TSDF and color integrations. Setting this number higher will lead to higher-quality reconstructions but worse performance in dynamic scenes.
`<mapper_name>.projective_integrator_truncation_distance_vox`	`double`	`4.000`	The truncation distance, in units of voxels, for the TSDF or occupancy map.
`<mapper_name>.projective_integrator_weighting_mode`	`string`	`kInverseSquareWeight`	The weighting mode, applied to TSDF and color integrations. Options: [0:constant, 1:constant_drop-off, 2:inverse_square, 3:inverse_square_drop-off, 4:inverse_square_TSDF_distance_penalty]
`<mapper_name>i.tsdf_decay_factor`	`double`	`0.950`	Decay factor that is applied to the TSDF weight when the TSDF decay is called.
`<mapper_name>.unobserved_region_occupancy_probability`	`double`	`0.500`	The inverse sensor model occupancy probability for unobserved voxels.

Note

Decay of the occupancy layer is needed to handle dynamic objects like people. Without the decay observed dynamic objects stay in the map even if not seen for a long time period. In that time the object might have moved and the map is therefore invalid. Using the decay we simulate the loss of knowledge about parts of the dynamic map currently not observed over time.

People Reconstruction Parameters

The mapping types [human_with_static_tsdf, human_with_static_occupancy] are executed using the nvblox_human_node. Below you find additional parameters that only exist for the nvblox_human_node:

ROS Parameter	Type	Default	Description
`human_debug_publish_rate_hz`	`float`	`10.0`	The rate (in Hz) at which to publish debug visualization for people mapping.