voxel-layer

Configure Nav2 VoxelLayer for 3D obstacle detection with depth cameras and lidar.

Updated Aug 16, 2026
One-click install
npx skills add https://github.com/three1324/yeonjinautomotive --skill voxel-layer-three1324
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: voxel-layer
Source: https://github.com/three1324/yeonjinautomotive/tree/main/.claude/skills/voxel-layer
Command: npx skills add https://github.com/three1324/yeonjinautomotive --skill voxel-layer-three1324

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve? 2D costmap layers project all sensor data onto a plane, so obstacles detected by a high-mounted depth camera get erased by a low lidar's clearing rays, and overhanging obstacles like shelves or table edges are missed entirely. This Skill guides correct configuration of the Nav2 VoxelLayer, which maintains a true 3D voxel grid with volumetric raycasting. ## Core Features & Use Cases - 3D Voxel Grid Configuration: Set z_voxels, z_resolution, origin_z, and mark_threshold to define the monitored vertical volume and control 3D-to-2D projection sensitivity. - Multi-Height Sensor Fusion: Combine a low 2D lidar and a high depth camera in one voxel layer so clearing rays only affect voxels at the ray's actual height. - Debugging with Voxel Map Visualization: Enable publish_voxel_map to inspect marked voxels in RViz and diagnose ground-hit false positives or stuck obstacles. - Use Case: A mobile robot with a lidar at 15cm and a depth camera at 80cm must track table-top obstacles; the VoxelLayer keeps camera marks in upper voxels intact even when the lidar raytraces through the same (x, y) column below. ## Quick Start Ask the AI to configure a Nav2 local costmap voxel layer that fuses a LaserScan lidar and a PointCloud2 depth camera with proper z_voxels and height filtering.

Frequently Asked Questions about voxel-layer

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I configure the Nav2 voxel layer for a depth camera?

Add a VoxelLayer plugin to your costmap with z_voxels, z_resolution, and origin_z defining the vertical grid, then add the depth camera as a PointCloud2 observation source with marking and clearing enabled. Set min_obstacle_height around 0.05 to filter ground hits.

What is the difference between VoxelLayer and ObstacleLayer in Nav2?

VoxelLayer maintains a 3D voxel grid and raytraces in 3D, so clearing rays only affect voxels at the ray's height. ObstacleLayer projects everything to 2D, meaning a low lidar's clearing ray can erase obstacles marked by a higher camera.

When should I use VoxelLayer instead of ObstacleLayer?

Use VoxelLayer when you have sensors at different heights, need to track overhanging obstacles like shelves or table edges, or have tilted sensors that see the ground. Use ObstacleLayer for a single fixed-height 2D lidar or when CPU is very constrained.

Why are ground points marked as obstacles in my costmap?

Ground hits appear as obstacles when the depth camera source lacks height filtering. Set min_obstacle_height to about 0.05 on the depth source, or raise origin_z above the ground plane so floor points fall outside the voxel grid.

Why are obstacles not clearing after being removed?

Obstacles persist when no clearing-enabled source covers the voxels where they were marked. Verify clearing is true on a source that observes that height, and visualize the voxel grid in RViz via publish_voxel_map to find stuck upper voxels.

How much memory does the Nav2 voxel grid use?

The voxel grid uses 2 bits per voxel. A 5m x 5m costmap at 0.05m resolution with 10 z-voxels needs roughly 24 KB, so memory usage is negligible even for large costmaps with many z-voxels.