Mapping Example

ROS1 Mapping (v3.1.04 and above)

Introduction

This example uses the SLAM Mapping (faster-lio) solution published on GitHub by Dr. Gao Xiang’s team. The main operation flow and data flow diagram:

faster-lio Data Flow (ROS1)

Package Structure

The mapping package is located at ~/lite_cog/slam/src, containing three packages: faster-lio, pcd_2_gridmap, and map_server. The faster-lio package builds 3D point cloud maps (.pcd), pcd_2_gridmap converts 3D point cloud maps (.pcd) to grid maps (.pgm) and publishes them, and map_server saves grid maps (.pgm).

Usage

Note: Before mapping, check if there are previously created maps in /home/ysc/lite_cog/system/map. If so, move them to another folder to avoid overwriting.

Note: Mapping requires significant computing resources. Please disable all AI options on the App first.

Open a terminal and enter the following command to start the LiDAR driver (choose one):

cd /home/ysc/lite_cog/system/scripts/lidar
./start_lslidar.sh    # Leishen LiDAR
./start_livox.sh      # Livox LiDAR
./start_rslidar.sh    # RoboSense LiDAR

If the LiDAR driver node fails to start, check if the LiDAR is connected to the perception host:

ping 192.168.1.201

LiDAR Driver Startup Terminal

Note: This terminal should remain running during mapping.

Start the mapping program:

a) The mapping startup script start_slam.sh is located at /home/ysc/lite_cog/system/scripts/slam:

#!/bin/sh

# Open mapping program
gnome-terminal -x bash -c "source /home/ysc/lite_cog/slam/devel/setup.bash; roslaunch faster_lio mapping_c16.launch; read -p 'Press any key to exit...'"

# Open terminal for generating grid map
gnome-terminal -x bash -c "bash /home/ysc/lite_cog/system/scripts/slam/gridmap.sh; read -p 'Press any key to exit...'"

# Open terminal for saving grid map
gnome-terminal -x bash -c "bash /home/ysc/lite_cog/system/scripts/slam/save_map.sh; read -p 'Press any key to exit...'"

b) Log in to the perception host desktop via NoMachine, remotely control the robot to stand up, then open a terminal and enter:

cd /home/ysc/lite_cog/system/scripts/slam
./start_slam.sh

c) After executing the above command, RViz visualization tool will launch, and three tabs will be generated in the terminal running start_slam.sh, running faster-lio, generating grid map, and saving grid map respectively.

RViz and Mapping Terminal Interface

Operate the robot to move around the designated area to build the map. Slow down when turning and be aware of LiDAR blind spots. Keep at least 0.5 meters distance between the robot and walls.
After scanning the designated area, check in RViz whether the point cloud map matches the actual environment.
After completing the map scan, find the faster-lio tab, press Ctrl+C to stop mapping. The program will automatically save the 3D point cloud file (.pcd) to ~/lite_cog/system/map and display average processing time (for reference only). Press Enter to close the tab.

Input 1 to Generate Grid Map (ROS1 faster-lio)

After successfully saving the 3D point cloud file (.pcd), find the tab shown below, input 1 and press Enter. The pcd_2_gridmap package will be called to convert the point cloud map to a grid map. Proceed to the next step when the RViz window pops up showing the grid map.

Grid Map Displayed in RViz (ROS1 faster-lio)

Input 2 to Save Grid Map (ROS1 faster-lio)

Save the grid map: Select the terminal showing “when you want to save the grid map”, input 2 and press Enter to invoke map_server. Map files will be saved to /home/ysc/lite_cog/system/map, including .yaml, .pgm, and .pcd files.
If the grid map (.pgm) doesn’t perfectly match the actual environment, or you need to manually define passable areas, use GIMP Image Editor. Open a terminal and enter gimp to open GIMP, then drag the grid map (.pgm) into it.

GIMP Editing Grid Map

If the toolbox is not displayed, select [Windows] – [New Toolbox] from the top menu bar.
Foreground Color specifies the pencil color, Background Color specifies the eraser color. In the grid map, black areas are impassable, white areas are passable, and gray areas are unknown. Use the pencil or eraser to remove noise or add virtual walls.
Click [File] – [Overwrite usr_map.pgm] to save the modified map, no need to save again when closing the editor.

After completing all operations, use Ctrl+C to close all terminals to avoid affecting subsequent processes.
Map files are saved to /home/ysc/lite_cog/system/map by default. If you changed the map file path or name, follow these steps to ensure localization and navigation programs can correctly load the map:

a) Update the map file (.pgm) path in the corresponding .yaml file, and rename the .yaml file to match the .pgm filename:

image: /home/ysc/lite_cog/system/map.pgm    # Map file (.pgm) path
resolution: 0.050000
...

b) Navigate to ~/lite_cog/nav/src/hdl_localization/launch and configure the map file name and path in local_rslidar_imu.launch:

<arg name="map_name" default="lite3" />       <!-- Define map filename -->
...
<node name="MapServer" pkg="map_server" type="map_server"
  args="/home/ysc/lite_cog/system/map/$(arg map_name).yaml"/>
...
<param name="globalmap_pcd" value="/home/ysc/lite_cog/system/map/$(arg map_name).pcd" />
...

ROS1 Mapping (below v3.1.04)

Introduction

This example uses the 6DOF SLAM (hdl_graph_slam) solution published on GitHub by Kenji Koide from Toyohashi University of Technology. Main operation flow:

hdl_graph_slam Operation Flow

Data flow diagram:

hdl_graph_slam Data Flow

Program Structure

/home/ysc/lite_cog/slam
├── build
── devel
├── src
│   ├── CMakeLists.txt
│   ├── fast_gicp
│   ├── hdl_graph_slam
│   ├── map_server
│   └── ndt_omp
└── version

The hdl_graph_slam package is responsible for building the map.

Usage

Note: Before mapping, check if there are previously created maps in /home/ysc/lite_cog/system/map. If so, move them to avoid overwriting.

Note: Mapping requires significant computing resources. Please disable all AI options on the App first.

Open a terminal and start the LiDAR driver (choose one):

cd /home/ysc/lite_cog/system/scripts/lidar
./start_lslidar.sh    # Leishen LiDAR
./start_livox.sh      # Livox LiDAR
./start_rslidar.sh    # RoboSense LiDAR

If the LiDAR driver node fails to start:

ping 192.168.1.201    # LiDAR IP is 192.168.1.201

Start the mapping program:

a) The script start_slam.sh is at /home/ysc/lite_cog/system/scripts/slam:

#!/bin/sh

# Open rviz
gnome-terminal -x bash -c "cd /home/ysc/lite_cog/slam; source devel/setup.bash; roslaunch hdl_graph_slam mapping_rslidar_indoor.launch;"

# Open rviz
gnome-terminal -x bash -c "bash /home/ysc/lite_cog/system/scripts/slam/rviz.sh"

# Open terminal for generating grid map
gnome-terminal -x bash -c "bash /home/ysc/lite_cog/system/scripts/slam/gridmap.sh"

# Open terminal for saving map
gnome-terminal -x bash -c "bash /home/ysc/lite_cog/system/scripts/slam/save_map.sh"

b) Log in to the perception host desktop via NoMachine, remotely control the robot to stand up, then:

cd /home/ysc/lite_cog/system/scripts/slam
./start_slam.sh

c) Five terminal windows will be generated: LiDAR driver terminal, mapping script terminal, RViz terminal, grid map terminal, and save map terminal.

LiDAR Driver and Mapping Script Terminals

To see mapping results in real time, find the RViz visualization node terminal (shown below), input 1 and press Enter to open RViz (this will reduce mapping performance; if unsatisfied with results, try without visualization and close NoMachine during mapping).

Open RViz Terminal Prompt

Operate the robot to move around the designated area. Slow down when turning and maintain at least 0.5m distance from walls.
After scanning, check if the point cloud map matches the environment (open RViz if not previously opened). If the map is large or has loops (e.g., went around the building), check if loop closure areas overlap. If not, go around again for loop closure detection.
After scanning, find the grid map terminal (shown below), input 2 and press Enter. The octomap package will convert the point cloud map to a grid map.

Input 2 to Generate Grid Map (ROS1 hdl_graph_slam)

After conversion, find the save map terminal (shown below), input 3 and press Enter. The map_server package will save the grid map to /home/ysc/lite_cog/system/map (including .yaml, .pgm, and .pcd files).

Input 3 to Save Grid Map (ROS1 hdl_graph_slam)

If the grid map needs editing, use GIMP Image Editor as described in the ROS1 faster-lio section above.

GIMP Editing Grid Map

Close all terminals with Ctrl+C after completing all operations.
Map files are saved to /home/ysc/lite_cog/system/map by default. Follow the same configuration steps as the faster-lio section for path/name changes.

ROS2 Mapping

Introduction

This example uses the SLAM Mapping (faster-lio) solution. Main operation flow and data flow:

faster-lio Data Flow (ROS2)

Package Structure

ysc@lite:~/lite_cog_ros2/slam/src$ tree .
.
├── faster-lio
├── map_server
└── pcd2grid

faster-lio builds PCD maps, pcd2grid converts PCD to grid maps, and map_server saves grid maps.

Usage

Note: Before mapping, check /home/ysc/lite_cog_ros2/system/map for existing maps and move them to avoid overwriting.

Note: Mapping requires significant computing resources. Please disable all AI options on the App first.

Start the LiDAR driver (choose one):

cd ~/lite_cog_ros2/system/scripts/lidar
./start_lslidar.sh    # Leishen LiDAR
./start_livox.sh      # Livox LiDAR
./start_rslidar.sh    # RoboSense LiDAR

Check LiDAR connection:

ping 192.168.1.201

Note: This terminal should remain running during mapping.

Start the mapping program:

a) The script start_slam.sh is at ~/lite_cog_ros2/system/scripts/slam:

#!/bin/sh

# start rviz
gnome-terminal -x bash -c "source /home/ysc/lite_cog_ros2/slam/install/setup.bash; ros2 launch faster_lio mapping_c16.launch.py; read -p 'Press Enter to exit...'"

# start a terminal for generating grid_map
gnome-terminal -x bash -c "bash /home/ysc/lite_cog_ros2/system/scripts/slam/gridmap.sh; read -p 'Press Enter to exit...'"

# Open a terminal for Saving Map
gnome-terminal -x bash -c "bash /home/ysc/lite_cog_ros2/system/scripts/slam/save_map.sh; read -p 'Press any key to exit...'; read -p 'Press Enter to exit...'"

b) Log in via NoMachine, stand up the robot, then:

cd ~/lite_cog_ros2/system/scripts/slam
./start_slam.sh

c) Four terminal windows will be generated.

Terminal Interface After Starting Mapping (ROS2)

Operate the robot to build the map. Slow down when turning, maintain 0.5m distance from walls.
After scanning, check if the point cloud map matches the environment.
Find the faster-lio terminal, press Ctrl+C to stop mapping. PCD file will be saved to ~/lite_cog_ros2/system/map.

Terminal Output After Stopping Mapping (ROS2)

After PCD is saved, find the grid map terminal, input 1 and press Enter to convert point cloud to grid map.

Input 1 to Generate Grid Map (ROS2)

Grid Map in RViz (ROS2)

Find the save map terminal, input 2 and press Enter to save the grid map.

Input 2 to Save Grid Map (ROS2)

Edit grid map with GIMP if needed (same procedure as above).

GIMP Editing Grid Map

Close all terminals with Ctrl+C.
Map files are saved to /home/ysc/lite_cog_ros2/system/map. Configure path/name in lite_localization.launch.py:

declare_map_server_config_file_cmd = DeclareLaunchArgument(
    'map_server_config_file',
    default_value=os.path.join(
        '/home/ysc/lite_cog_ros2/system/map/lite3.yaml'
    )
)
...
parameters=[
    {"globalmap_pcd": "/home/ysc/lite_cog_ros2/system/map/lite3.pcd"},
    ...