Skip to content
NKU-MobFly-RoboticsPublic

About

[ICRA-2026] A memoRy-lIte and comPutatioN-Efficient Occupancy mappiNg (RIPNEON) method with real-time map update and low memory usage for exploration-oriented planning.

Resources

Stars

12 stars

Watchers

4 watching

Forks

Latest commit

 

History

27 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

RIPNEON

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

MIT License ROS Noetic Ubuntu 20.04

Overview

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

Dataset demonstrations

RIPNEON on KITTI sequence 01 RIPNEON on KITTI sequence 04

RIPNEON on KITTI sequence 09 RIPNEON on the SBAC dataset

Requirements

The project has been developed and tested with:

  • Ubuntu 20.04
  • ROS Noetic
  • C++14
  • Eigen3
  • PCL
  • OpenCV and cv_bridge
  • catkin (catkin_make) and catkin_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-msgs

Install 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.git

Build

Create 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.bash

To make the workspace available in every new terminal, optionally add the following line to ~/.bashrc:

source ~/catkin_ws/devel/setup.bash

Quick Start

Required: Configure the read/write directory first

Warning

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_maps

Then 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_maps

Replace <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.

Download the example bags

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.launch

Then 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.bag

Replace both the bag name and launch file according to the table above to run a different sequence.

Run with your own data

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.launch

The 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_topic

Play 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.bag

Dataset-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.launch

Each launch file loads its matching configuration from Test/resource. Check and update its input-topic remappings and filesystem paths before use.

ROS Interface

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.

Configuration

Mapping parameters are stored in YAML files under Test/resource.

Map geometry and local working set

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.

Occupancy update

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

Frames, storage, and execution

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

Visualization and statistics

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.

Library Usage

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.

Repository Structure

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

Troubleshooting

EIGEN_CONSTEXPR does not name a type

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_make

No map appears in RViz

Check that:

  • The point-cloud and pose/odometry messages have close timestamps.
  • The launch-file remappings match the topics in your dataset.
  • PointBlock/world_frame_pts matches the frame of the input cloud.
  • The sensor pose lies inside the configured global map bounds.
  • The RViz fixed frame is world.

Map files are not created

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.

Citation

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.

License

RIPNEON is released under the MIT License.

Acknowledgements

We thank the open-source ROS, Eigen, PCL, and OpenCV communities. Please consider starring the repository if you find this project useful.

About

[ICRA-2026] A memoRy-lIte and comPutatioN-Efficient Occupancy mappiNg (RIPNEON) method with real-time map update and low memory usage for exploration-oriented planning.

Resources

Stars

12 stars

Watchers

4 watching

Forks

Releases

Packages

Contributors

Languages