Mapping Development Example

Mandatory: Please use the DR02 Pro robot to perform the operations in this guide. The DR02 robot does not support the operations described herein.

Overview

Mapping refers to the process where the robot, while walking, uses LiDAR and other sensors to collect surrounding environment data in real time, determines its current pose, and builds a map of the surroundings. The constructed map may take various forms, such as point clouds or occupancy grids, and will be used by downstream modules such as localization and path planning.

The current mapping function only supports building point cloud and occupancy grid maps for small areas (50m × 50m).

Mapping Route Planning

Users need to plan the robot’s mapping route in advance, ensuring the route:

1. Forms a loop closure, i.e., repeatedly visiting already-scanned areas during mapping, creating intersections or overlapping segments with historical trajectories;
2. Preferably complete small loops first, then larger loops;
3. Covers the entire task area.

Recommended Route	Not Recommended
Route has crossovers, can form loop closures Covers all areas	Route has no crossovers, no loop closures Does not cover all areas

Mapping Steps

Note: Avoid large numbers of people walking back and forth or the presence of large temporary objects during mapping.

Note: Do not obstruct the LiDAR during mapping, as this may cause mapping failure.

Note: Clear debris from the mapping route in advance and open all doors in the task area.

1. Ensure the robot is standing still before starting the mapping program;

2. SSH into the Navigation Host NOS (or open a terminal via the NOS VNC remote desktop), and initialize the ROS2 environment:

   source /opt/robot/scripts/setup_ros2.sh

3. Select and enter the corresponding mapping command as needed:

   • Default Mapping: Uses small-area mapping mode. The map is named “map-[date]-[time]” by default. RViz is enabled by default during mapping. The map is activated by default after mapping for localization and navigation:

     drmap mapping

   • Specify Map Name: Use the -n flag followed by the map name:

     drmap mapping -n xxx    # Specify map name as xxx via -n flag

   • Without RViz: Use the -s flag:

     drmap mapping -s

   • Do Not Activate Map Immediately: Use the -B flag:

     drmap mapping -b

4. Wait approximately 3-5 seconds. When the prompt “正在建图，Building map” appears, the mapping program startup and initialization are complete, and mapping has begun;

5. Remotely control the robot to walk smoothly along the planned mapping route. Avoid sudden acceleration, deceleration, sharp turns, or vigorous movements;

6. After completing the full route, open a terminal and enter the command drmap stop_mapping to end the mapping program and start post-processing. After the terminal prompts that mapping has ended, you can close the terminal.

Note: If stuttering occurs during the mapping termination process, you can execute the stop mapping command multiple times to ensure the mapping program is closed and post-processing can proceed.

Map Folder and Map Package

Each mapping session generates a map package as a separate folder, named [specified name]-[date]-[time]. All map packages are stored in the map folder at /var/opt/robot/data/maps.

There is a symlink named active in the map folder. The map package it points to is in the activated state, meaning it will be used for localization, navigation, and planning. Only one map package can be activated at a time.

Note: Each map package contains all necessary data. Please refer to “Map Package Operations” and use the drmap command to transfer, back up, or replace the entire map package. Do not modify or replace individual files within the package.

Viewing Point Cloud Maps

Open a terminal and enter the following command to open the PCD viewer and view the constructed 3D point cloud map:

cd /var/opt/robot/data/maps/XXXX-XX-XXXXX #XXXX-XX-XXXXX is the folder containing the point cloud map to view
pcl_viewer full_cloud.pcd

PCD Viewer Basic Operations:

1. Scroll wheel to control point cloud model zoom
2. Left-click drag to control point cloud model rotation
3. Middle-click drag to control point cloud model panning
4. Number keys (1-5) to select point cloud display mode

Occupancy Grid Map Editing

If the occupancy grid map does not fully match the actual environment or you need to manually define passable areas, you can use the GNU Image Manipulation Program (GIMP) to edit the .pgm file:

1. Transfer the .pgm file to be modified from the DR02 Navigation Host (NOS) to the developer’s host;

2. Download and install GIMP on the developer’s host;

3. Right-click the .pgm file transferred to the development host, select Open with Other Application, then select GNU Image Manipulation Program, and click Select;

   • If GIMP does not display the side toolbars, press the Tab key to show them.
   • The toolbar provides foreground and background color tools. The foreground color sets the paint tool color, and the background color sets the eraser tool color. In occupancy grid maps, black represents obstacles (impassable areas), white represents passable areas, and gray represents unknown areas. You can use the paint tool or eraser tool to add or remove black areas. Hold Shift and left-click to draw straight lines; hold Ctrl and left-click to sample colors.

4. After editing, select File - Overwrite occ_grid.pgm from the top menu bar to overwrite the original file (do not select File - Save). When closing the software, a save prompt will appear; click Discard Changes;

   Note: If there are multiple occupancy grid maps, the map file names follow the format occ_grid__XXX_.pgm (where XXX is the map number), e.g., occ_grid_3.pgm. Please edit and save multiple occupancy grid map files in sequence.

5. Transfer the modified .pgm file back to the corresponding original .pgm file directory on the Navigation Host (NOS), overwriting the original .pgm file.

Map Package Operations

Users can execute drmap-related commands in the terminal to pack, back up, reuse, and perform other operations on the entire map package. Command input supports TAB completion, and you can also use the -h option with a command to view basic usage.

1. Compress and Pack: Compress the current map package to a zip file and back up to the /home/user/Downloads folder.

   drmap pack

2. Unpack: Extract the packed map package to the /var/opt/robot/data/maps path.

   drmap unpack [path_to_map_package]     # [path_to_map_package] is the path to the map zip package file to extract

3. Activate: Activate the map to be used for localization and navigation (maps are stored in /var/opt/robot/data/maps by default; restart required after activation to take effect).

   drmap apply [path_to_map_folder]     # [path_to_map_folder] is the path to the map package folder to activate

Localization Initialization

Localization initialization refers to the process of confirming the robot’s localization is correct and resetting/correcting it before executing navigation or after localization is accidentally lost.

1. Open a terminal and run the following command to open RViz:

   su
   source /opt/ros/jazzy/setup.bash
   export XAUTHORITY=/home/user/.Xauthority
   rviz2

2. Click “File-Open Config” in the upper left corner. In the popup, select the RViz configuration file localization.rviz under the /opt/robot/share/localization/conf path to load the data required for localization;

3. Check if the real-time point cloud overlaps with the map. If not, proceed to the next step to initialize the robot’s localization;

4. Initialize or reset the robot’s localization:

   • Click 2D Pose Estimate in the top toolbar
   • Determine the robot’s actual position and orientation, move the mouse to the corresponding location on the map, press and hold the left button, and drag an arrow according to the actual orientation, then release the left mouse button
   • If localization initialization is successful, the real-time point cloud will overlap with the map; if it fails, restart from step 1

Navigation

Users can dispatch navigation tasks and obtain execution status through the relevant communication interfaces.

Map Coordinate System and Pixel Coordinate System Conversion

Map Coordinate System	Pixel Coordinate System

The configuration file occ_grid.yaml in the map package contains map image information. Users can use this to convert coordinates between the map coordinate system and the pixel coordinate system:

image: /var/opt/robot/data/maps//map-20250802-151130/occ_grid.pgm
resolution: 0.1                   # Physical length of map image pixels in the actual map Res(m)
origin: [-8.6, -11.2, 0.0]        # First two parameters represent the coordinates [X0,Y0](m) of the lower-left corner of the map image in the map coordinate system
negate: 0
occupied_thresh: 0.65
free_thresh: 0.196

The coordinate conversion formula between the map coordinate system and the pixel coordinate system is as follows:

$$x_p = \frac{\text{Pos} X - X_0}{\text{Res}}$$ $$y_p = H - \frac{\text{Pos} Y - Y_0}{\text{Res}}$$

where $(x_p, y_p)$ are rounded to integers.

The parameters involved in the formula are as follows:

Parameter Name	Parameter Meaning
$(\operatorname{Pos} X, \operatorname{Pos} Y)$	Coordinate values in the map coordinate system
$(x_{p},y_{p})$	Coordinate values in the pixel coordinate system
$Res$	Physical length of map image pixels in the actual map, unit: meters
$(X0,Y0)$	Coordinates of the lower-left corner of the map image in the map coordinate system, unit: meters
$H$	Number of pixels in the height of the map image (obtainable from file properties)