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.