voxel-layer

To configure 3D obstacle clearing, enable the voxel layer in your local_costmap and set z_voxels, z_resolution, and origin_z to match your depth camera setup. This enables volumetric raycasting across multiple height layers for accurate clearance of elevated obstacles.

Standard obstacle layers lack 3D raycasting, causing overhanging obstacles to persist in the costmap. A voxel layer applies volumetric raycasting across z_voxels to properly clear elevated geometry and overhanging structures detected by 3D LiDAR.

3D raycasting in a voxel grid performs simultaneous clearance across multiple height layers within each costmap cell. It improves robot navigation by accurately clearing elevated obstacles and verifying vertical clearance when using height-varying sensors like depth cameras.

Increasing z_voxels expands the 3D voxel grid height per costmap cell, which directly increases memory consumption. You must balance z_voxels and z_resolution against your sensor's vertical range to manage memory usage while maintaining sufficient height-aware obstacle detection.

A voxel layer is designed for height-varying sensors like depth cameras and 3D LiDAR rather than 2D LiDAR. For 2D LiDAR obstacle avoidance, standard 2D costmap layers are more appropriate and avoid unnecessary 3D voxel grid memory overhead.

You tune mark_threshold in the voxel costmap to adjust how many sensor observations are required before marking a 3D voxel as an obstacle. Lowering it increases sensitivity to detected obstacles, while raising it filters out transient noise.