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 which example is launched.

File tree:

config
├── nvblox
    ├── nvblox_base.yaml
    └── specializations
        ├── nvblox_dynamics.yaml
        ├── nvblox_humans.yaml
        ├── nvblox_isaac_sim.yaml
        └── nvblox_realsense.yaml

Loaded specializations for each example:

Launch file	Specializations
isaac_sim_example.launch.py	nvblox_isaac_sim.yaml
isaac_sim_humans_example.launch.py	nvblox_isaac_sim.yaml, nvblox_humans.yaml
isaac_sim_dynamics_example.launch.py	nvblox_isaac_sim.yaml, nvblox_dynamics.yaml
realsense_example.launch.py	nvblox_realsense.yaml
realsense_humans_example.launch.py	nvblox_realsense.yaml, nvblox_humans.yaml
realsense_dynamics_example.launch.py	nvblox_realsense.yaml, nvblox_dynamics.yaml

General Parameters

ROS Parameter	Type	Default	Description
global_frame	string	odom	The name of the TF frame in which the map built. For the RealSense examples, this parameter is exposed as a launch argument.
voxel_size	float	0.05	Voxel size (in meters) to use for the map.
use_tf_transforms	bool	true	Whether to use TF transforms at all. If set to false, use_topic_transforms must be true and pose_frame needs to be set.
use_topic_transforms	bool	false	Whether to listen to topics for transforms. If set to true, will try to get global_frame to pose_frame transform from the topics. If set to false, everything will be resolved through TF.
compute_esdf	bool	true	Whether to compute the ESDF (map of distances to the nearest obstacle).
esdf_update_rate_hz	float	2.0	The rate (in Hz) at which to update the ESDF and output the distance slice.
esdf_2d	bool	true	Whether to compute the ESDF in 2D (true) or 3D (false).
publish_esdf_distance_slice	bool	true	Whether to output a distance slice of the ESDF to be used for path planning.
esdf_slice_height	float	1.0	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.
esdf_2d_min_height	float	0.0	The minimum height, in meters, to consider obstacles part of the 2D ESDF slice.
esdf_2d_max_height	float	1.0	The maximum height, in meters, to consider obstacles part of the 2D ESDF slice.
connected_mask_component_size_threshold	int	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.
compute_mesh	bool	true	Whether to output a mesh for visualization in RViz, to be used with nvblox_rviz_plugin.
mesh_update_rate_hz	float	5.0	The rate (in Hz) at which to update and publish the mesh.
use_color	bool	true	Whether to integrate color images to color the mesh.
max_color_update_hz	float	5.0	The maximum rate (in Hz) at which to integrate color images into the color layer. A value of 0.0 means there is no cap.
use_depth	bool	true	Whether to integrate depth images.
max_depth_update_hz	float	30.0	The maximum rate (in Hz) at which to integrate depth images. A value of 0.0 means there is no cap.
use_lidar	bool	true	Whether to integrate LiDAR scans.
max_lidar_update_hz	float	10.0	The maximum rate (in Hz) at which to integrate LiDAR scans. A value of 0.0 means there is no cap.
lidar_width	int	1800	Width of the LIDAR scan, in number of beams. Default works for the VLP16.
lidar_height	int	16	Height of the LIDAR scan, in number of beams. Default works for the VLP16.
lidar_vertical_fov_rad	float	30 degrees (in radians)	The vertical field of view of the LIDAR scan, in radians (assuming beams are centered around 0 elevation). Default is for the VLP16.
use_non_equal_vertical_fov_lidar_params	bool	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.
min_angle_below_zero_elevation_rad	float	20 degrees (in radians)	The angle below zero elevation of the lowest beam (specified as a positive number in radians). Default is for the Hesai PandarXT32.
max_angle_above_zero_elevation_rad	float	15 degrees (in radians)	The angle above zero elevation of the highest beam (specified as a positive number in radians). Default is for the Hesai PandarXT32.
static_occupancy_publication_rate_hz	float	2.0	The rate (in Hz) at which to publish the static occupancy pointcloud.
dynamic_occupancy_decay_rate_hz	float	10.0	The rate (in Hz) at which to decay the dynamic occupancy layer.
max_poll_rate_hz	float	100.0	Specifies what rate to poll the color & depth updates at. Will exit as no-op if no new images. Set this higher than you expect images to come in at.
maximum_sensor_message_queue_length	int	30	How many messages to store in the sensor messages queues (depth, color, lidar) before deleting oldest messages.
map_clearing_radius_m	float	-1.0	Radius around the map_clearing_frame_id outside which we clear the map. Note that values <= 0.0 indicate that no clearing is performed.
map_clearing_frame_id	string	base_link	The name of the TF frame around which we clear the map.
clear_outside_radius_rate_hz	float	1.0	The rate (in Hz) at which we clear the map outside of the map_clearing_radius_m.
depth_qos	string	SYSTEM_DEFAULT	ROS 2 QoS string for the depth subscription.
color_qos	string	SYSTEM_DEFAULT	ROS 2 QoS string for the color subscription.
pointcloud_qos	string	SYSTEM_DEFAULT	ROS 2 QoS string for the pointcloud subscription.
pose_frame	float	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.
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	float	10.0	Side length of the map slice bounds visualization plane.

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 humans in an occupancy layer

• human_with_static_occupancy:

  • static_mapper: mapping static obstacles using an occupancy layer

  • dynamic_mapper: mapping humans 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 human 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>.do_depth_preprocessing	bool	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>.depth_preprocessing_num_dilations	int	3	Number of times to run the invalid region dilation in the depth preprocessing pipeline (if do_depth_preprocessing is enabled).
<mapper_name>.projective_integrator_max_integration_distance_m	float	7.0	The maximum distance, in meters, to integrate the depth or color image values.
<mapper_name>.lidar_projective_integrator_max_integration_distance_m	float	10.0	The maximum distance, in meters, to integrate the depth values for LiDAR scans.
<mapper_name>.projective_integrator_truncation_distance_vox	float	4.0	The truncation distance, in units of voxels, for the TSDF or occupancy map.
<mapper_name>.weighting_mode	string	inverse_square	The weighting mode, applied to TSDF and color integrations. Options: [constant, constant_dropoff, inverse_square, inverse_square_dropoff, inverse_square_tsdf_distance_penalty].
<mapper_name>.projective_integrator_max_weight	float	100.0	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>.free_region_occupancy_probability	float	0.3	The inverse sensor model occupancy probability for voxels observed as free space.
<mapper_name>.occupied_region_occupancy_probability	float	0.7	The inverse sensor model occupancy probability for voxels observed as occupied.
<mapper_name>.unobserved_region_occupancy_probability	float	0.5	The inverse sensor model occupancy probability for unobserved voxels.
<mapper_name>.occupied_region_half_width_m	float	0.1	Half the width of the region which is considered as occupied.
<mapper_name>.esdf_integrator_min_weight	float	1e-4	Minimum weight of the TSDF to consider for inclusion in the ESDF.
<mapper_name>.esdf_integrator_max_distance_m	float	2.0	Maximum distance to compute the ESDF up to, in meters.
<mapper_name>.esdf_integrator_max_site_distance_vox	float	1.0	Maximum distance to consider a voxel within a surface for the ESDF calculation.
<mapper_name>.mesh_integrator_min_weight	float	1e-4	Minimum weight of the TSDF to consider for inclusion in the mesh.
<mapper_name>.mesh_integrator_weld_vertices	bool	true	Whether to weld identical vertices together in the mesh.
<mapper_name>.tsdf_decay_factor	float	0.95	Decay factor that is applied to the TSDF weight when the TSDF decay is called.
<mapper_name>.free_region_decay_probability	float	0.55	The decay probability that is applied to the free region on decay. Must be in [0.5, 1.0].
<mapper_name>.occupied_region_decay_probability	float	0.4	The decay probability that is applied to the occupied region on decay. Must be in [0.0, 0.5].
<mapper_name>.max_tsdf_distance_for_occupancy_m	float	0.15	TSDF distance below which we assume a voxel to be occupied (non freespace).
<mapper_name>.max_unobserved_to_keep_consecutive_occupancy_ms	int	200	Maximum duration of no observed occupancy to keep consecutive occupancy alive.
<mapper_name>.min_duration_since_occupied_for_freespace_ms	int	1000	Minimum duration since last observed occupancy to consider voxel as free.
<mapper_name>.min_consecutive_occupancy_duration_for_reset_ms	int	2000	Minimum duration of consecutive occupancy to turn a high confidence free voxel back to occupied.
<mapper_name>.check_neighborhood	bool	true	Whether to check the occupancy of the neighboring voxels for the high confidence freespace update.

Note

Decay of the occupancy layer is needed to handle dynamic objects like humans. 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.

Human 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 human mapping.