Memory-Lite and Computation-Efficient Occupancy Mapping via Block Read-Write and Key Grids Expansion
2026 IEEE International Conference on Robotics and Automation (ICRA)
Qianli Dong, Xuebo Zhang, Shiyong Zhang, Haobo Xi, Ziyu Wang, Zhe Ma, Zhiyong Zhang
RIPNEON is a memory-lite, computation-efficient 3D occupancy mapping framework designed for exploration-oriented planning. It maintains only a bounded local working set in memory and transparently saves and reloads voxel blocks as the robot moves. The map is updated in real time, while frontier voxels can be detected during the same update process.
Main features:
- Block-based voxel storage with on-demand disk read/write
- Bounded local-map memory for large environments
- Efficient point-cloud insertion and ray-based free-space updates
- Online occupied, free, unknown, and frontier voxel classification
- Configurable voxel inflation for collision-aware planning
- ROS visualization and computation/memory statistics
The project has been developed and tested with:
- Ubuntu 20.04
- ROS Noetic
- C++14
- Eigen3
- PCL
- OpenCV and
cv_bridge catkin(catkin_make) andcatkin_simple
Install the binary dependencies:
sudo apt update
sudo apt install \
libeigen3-dev \
ros-noetic-cv-bridge \
ros-noetic-pcl-conversions \
ros-noetic-pcl-ros \
ros-noetic-tf \
ros-noetic-tf2-ros \
ros-noetic-visualization-msgsInstall catkin_simple in the same workspace if it is not already available:
mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src
git clone https://github.com/catkin/catkin_simple.gitCreate a catkin workspace and clone RIPNEON:
mkdir -p ~/catkin_ws/src
cd ~/catkin_ws/src
git clone https://github.com/NKU-MobFly-Robotics/RipNeon.git ripneon
cd ..
source /opt/ros/noetic/setup.bash
rosdep install --from-paths src --ignore-src -r -y
catkin_make
source devel/setup.bashTo make the workspace available in every new terminal, optionally add the following line to ~/.bashrc:
source ~/catkin_ws/devel/setup.bashWarning
Do not launch RIPNEON before completing this step. Every example requires
an existing, writable directory for block-map storage. If PointBlock/Path
is invalid or its parent directory does not exist, map files cannot be saved.
Create the storage directory:
mkdir -p ~/ripneon_mapsThen open the YAML file used by your launch file under
Test/resource and set PointBlock/Path to the directory's
absolute path. For example, sequence 01 uses
Test/resource/pbmap_kitti01.yaml:
PointBlock/Path: /home/<user>/ripneon_mapsReplace <user> with your Linux username. Do not use ~ in the YAML value
because it is not expanded. RIPNEON creates a timestamped run subdirectory, but
it does not create the parent directory specified by PointBlock/Path.
Note: The KITTI rosbag files are currently being uploaded and may not yet be available. Once the upload is complete, they can be downloaded from Google Drive.
Download the required bag to any local directory before running a demonstration.
| Bag file | Launch file |
|---|---|
kitti_01.bag |
pbmap_kitti01.launch |
kitti_04.bag |
pbmap_kitti04.launch |
kitti_07.bag |
pbmap_kitti07.launch |
kitti_09.bag |
pbmap_kitti9.launch |
These bags provide /velodyne_points (sensor_msgs/PointCloud2) and /gt_pose
(geometry_msgs/PoseStamped), which are already remapped by the corresponding
KITTI launch files.
For example, run KITTI sequence 01 in one terminal:
source ~/catkin_ws/devel/setup.bash
roslaunch Test pbmap_kitti01.launchThen play the downloaded bag in another terminal:
source ~/catkin_ws/devel/setup.bash
rosparam set use_sim_time true
rosbag play --clock /path/to/kitti_01.bagReplace both the bag name and launch file according to the table above to run a different sequence.
Before launching, edit the selected YAML file in Test/resource and set PointBlock/Path to an existing, writable directory. RIPNEON creates a timestamped subdirectory there for the block-map data.
For a generic registered point cloud and odometry stream:
mkdir -p ~/ripneon_maps
# Set PointBlock/Path: /home/<user>/ripneon_maps in Test/resource/pbmap.yaml
source ~/catkin_ws/devel/setup.bash
roslaunch Test pbmap.launchThe default launch file expects:
- Point clouds on
/cloud_registered(sensor_msgs/PointCloud2) - Odometry on
/aft_mapped_to_init(nav_msgs/Odometry)
Use ROS remapping when your topics have different names:
roslaunch Test pbmap.launch \
/cloud_registered:=/your/point_cloud_topic \
/aft_mapped_to_init:=/your/odometry_topicPlay the rosbag in another terminal. Use simulated time when the bag or the rest of your pipeline requires it:
rosparam set use_sim_time true
rosbag play --clock your_dataset.bagDataset-specific launch files are also provided:
roslaunch Test pbmap_kitti01.launch
roslaunch Test pbmap_kitti04.launch
roslaunch Test pbmap_kitti07.launch
roslaunch Test pbmap_kitti9.launch
roslaunch Test pbmap_pad.launch
roslaunch Test pbmap_real.launchEach launch file loads its matching configuration from Test/resource. Check and update its input-topic remappings and filesystem paths before use.
The test node supports either of the following synchronized input pairs:
| Input | Message type | Internal topic |
|---|---|---|
| Point cloud + odometry | sensor_msgs/PointCloud2 + nav_msgs/Odometry |
/pcl + /odom |
| Point cloud + pose | sensor_msgs/PointCloud2 + geometry_msgs/PoseStamped |
/pcl2 + /pose |
The launch files remap these internal names to dataset-specific topics.
Important outputs from the default pbmap_test node include:
| Output | Message type | Description |
|---|---|---|
/pbmap_test/PointBlock/voxvis |
visualization_msgs/MarkerArray |
Occupancy voxel visualization |
/pbmap_test/PointBlock/frontier |
visualization_msgs/MarkerArray |
Frontier voxel visualization |
/pbmap_test/PointBlock/points |
visualization_msgs/MarkerArray |
Input-point visualization |
/pbmap_test/PointBlock/stat_v |
std_msgs/Float32 |
Optional statistics output |
/world_pcl |
sensor_msgs/PointCloud2 |
Point cloud relabeled in the world frame |
/world_odom |
nav_msgs/Odometry |
Pose relabeled in the world frame |
RViz starts automatically with the supplied launch files.
Mapping parameters are stored in YAML files under Test/resource.
| Parameter | Description |
|---|---|
PointBlock/minX, minY, minZ |
Lower bounds of the global map in metres |
PointBlock/maxX, maxY, maxZ |
Upper bounds of the global map in metres |
PointBlock/resolution |
Voxel resolution in metres |
PointBlock/blockX, blockY, blockZ |
Number of voxels in each block dimension |
PointBlock/LocalBlockNumX, LocalBlockNumY, LocalBlockNumZ |
Number of blocks retained in the local working set |
PointBlock/sensor_max_range |
Maximum sensor integration range in metres |
The approximate local-map dimensions are:
local size = resolution × block size × local block count
Increasing the local block count reduces disk swapping but increases memory use.
| Parameter | Description |
|---|---|
PointBlock/occ_max |
Maximum occupancy probability |
PointBlock/occ_min |
Minimum occupancy probability and free-space threshold |
PointBlock/pro_miss_free |
Inverse sensor-model probability used for free-space updates |
PointBlock/inflate_scale |
Obstacle inflation scale in metres |
PointBlock/Dtheta, PointBlock/Dpsi |
Angular resolution of the ray-depth image in radians |
| Parameter | Description |
|---|---|
PointBlock/world_frame_pts |
Set true if input points are already expressed in the world frame |
PointBlock/rot_x, rot_y, rot_z, rot_w |
Fixed sensor-to-odometry quaternion |
PointBlock/Path |
Existing parent directory used to store swapped map blocks |
PointBlock/thread_num |
Number of read/write worker threads |
| Parameter | Description |
|---|---|
PointBlock/show_freq |
Visualization update frequency in Hz |
PointBlock/show_voxel |
Publish voxel markers |
PointBlock/show_pts |
Publish point markers |
PointBlock/show_frontier |
Publish frontier markers |
PointBlock/statistic_v |
Enable mapping statistics |
Exp/min*, Exp/max* |
Bounding box used by the statistics module |
Computation/dir |
Output directory for computation statistics |
Disable PointBlock/statistic_v if no statistics output is needed. If it is enabled, ensure that Computation/dir exists and is writable.
The main public interface is declared in RipNeon/include/RipNeon/ripneon_map.h. A typical update sequence is:
#include <RipNeon/ripneon_map.h>
Ripneon map;
map.Init(nh, private_nh);
// For every synchronized pose and point cloud:
map.SetMsgTime(timestamp);
map.ResetLocalMap(sensor_position);
map.SetPose(sensor_pose);
map.InsertPts(point_cloud);Call ResetLocalMap before insertion so blocks leaving the local working set are saved and newly required blocks are loaded. The Ripneon destructor saves all remaining blocks.
ripneon/
├── RipNeon/ # Core occupancy-map library
│ ├── include/ # Public headers and voxel data structures
│ ├── src/ # Mapping, ray casting, block I/O, and debugging
│ └── color/ # RViz height-color palettes
├── data_statistics/ # Runtime and memory statistics helpers
├── Test/ # ROS test nodes, launch files, YAML files, and RViz configs
├── ripneon_gif/ # Demonstration media
└── LICENSE
This usually means headers from two Eigen installations are being mixed, for example Eigen 3.3 from /usr/include/eigen3 and Eigen 3.4 from /usr/local/include/eigen3.
Use Eigen's normal include form consistently:
#include <Eigen/Core>
#include <Eigen/Dense>Do not combine it with #include <eigen3/Eigen/...>. Ensure that only one Eigen include directory is present in the compiler command, then clean and rebuild:
cd ~/catkin_ws
catkin_make clean
catkin_makeCheck that:
- The point-cloud and pose/odometry messages have close timestamps.
- The launch-file remappings match the topics in your dataset.
PointBlock/world_frame_ptsmatches the frame of the input cloud.- The sensor pose lies inside the configured global map bounds.
- The RViz fixed frame is
world.
PointBlock/Path must point to an existing parent directory. RIPNEON creates a timestamped run directory inside it. Verify that the ROS process has write permission there.
If RIPNEON is useful in your research, please cite the associated ICRA 2026 paper. The BibTeX entry and publication links will be added when they become available.
RIPNEON is released under the MIT License.
We thank the open-source ROS, Eigen, PCL, and OpenCV communities. Please consider starring the repository if you find this project useful.



