VSLAM - Mapping Tutorial

Visual SLAM (Visual Simultaneous Localization and Mapping) relies on recognizing and reusing spatial information collected during the explorations of an environment. Just as humans form mental maps of familiar places—like the layout of a building or the arrangement of streets — the ZED SDK builds and refines a spatial representation of its surroundings through its positional tracking module.

When the enable_area_memory parameter is enabled, this spatial representation is stored in a compact structure called an Area map. Area maps efficiently encode the visual and geometric features of an environment—including the keyframes and landmarks detected during the mapping session. They enable relocalization, allowing applications to:

Improve localization accuracy through loop closure: when the camera returns to a previously mapped area, the system recognizes it and corrects accumulated drift to realign the trajectory with the original map.
Maintain stable and repeatable tracking performance in known environments.

This section provides a step-by-step tutorial outlining the recommended mapping workflow for generating a high-quality Area map. Mapping can be performed online, directly during camera operation, or offline by recording an SVO of your trajectory and computing the Area map afterward.

For creating maps efficiently, we recommend using the Positional Tracking sample, which offers all the essential tools to guide and visualize the mapping process. Refer to this page to learn how to install and use the Positional Tracking sample.

At all times, the Spatial Memory Status displayed in the sample provides an indication of the map status.

Mapping Procedure #

Choose the Map Starting Point and Mapping Camera #

Begin by selecting a strategic map starting point, as this position will be used by default as the origin when the saved map is reloaded for relocalization. Physically placing the camera at this same location when starting the Positional Tracking module ensures fast and reliable initial localization. Ideally, the starting point should:

Face an open space with rich, static visual features,
Remain unobstructed on a daily basis so the camera can be placed there easily.

To consistently reposition the camera at this spot, you can mark the floor or place a fiducial marker with a known pose in the map.

📌 Note: If the Positional Tracking module is started away from the map’s starting point, localization will still converge after some movement and ensure accurate tracking, but it may take longer to achieve this result.

Next, choose and prepare the mapping camera. It should be:

Securely mounted using rigid, vibration-resistant hardware.
Properly maintained, with a clean lens free of smudges, dust, or droplets.
Optimally positioned, with a wide and unobstructed field of view. Avoid pointing the camera downward, as this limits detectable features.

Finally, connect the mapping camera to the computing system and place it precisely at the chosen starting point before beginning the mapping process.

Choose the Mapping option #

Two options are proposed to create an Area map:

Option 1 - Offline Mapping process (SVO recording) : launch ZED_Explorer or ZED_Studio to record an SVO. Svos can also be recorded directly from the API or from the ROS2 wrapper (ie: use the start_svo_recording ROS2 service).
Option 2 - Online Mapping process - direct mapping camera live recording using the sample. Ensure GEN_3 is selected for the positional tracking module and enable_area_memory is set to true. The sample can be started with the mapping options following this command:
```
./build/ZED_Positional_Tracking --map -o map_name.area
```

📌 Note: If the Offline Mapping option is chosen, follow the Mapping Procedure best practices as the camera is moved. For this option, the Spatial Memory status is not shown live as it would only be shown within the sample. The recorded SVO can then be loaded directly in the sample to produce the area map.

Mapping Procedure best practices #

Initially, the Spatial Memory status is set to INITIALIZING, indicating that the system has not yet collected enough motion or keyframes to begin building the map. Once the camera starts moving and sufficient keyframes are accumulated, the status transitions to MAP_UPDATE. This change signals that mapping is actively underway and that you should continue moving the camera following the recommended mapping best practices.

The goal is to manually move the mapping camera through the environment, ensuring it captures as much of the area as possible. As the camera moves, positional drift naturally accumulates. To counter this, it is recommended to explore the environment in successive loops, forcing the mapping trajectory to revisit previously seen regions and detect loop closures to correct the drift. Whenever a loop closure is detected, the Spatial Memory status briefly switches to LOOP_CLOSED before returning to MAP_UPDATE. This transition confirms that the system successfully recognized a previously visited location, resulting in a more accurate and consistent map.

In order to build the most accurate map graph possible, single loop trajectories should not exceed roughly 20m. As a consequence, large environments should be divided into several mapping sections.

For example :

Typical office environment: Offices can be large environment with several smaller rooms. Each room can be considered a mapping section. Large open space areas can be divided into multiple mapping sections.
Typical Warehouse environment: Warehouses are generally filled with narrower but long alleys. Divide each alleys in several mapping sections.

The goal is for the camera to capture as much as possible of the environment, from various angles. For each mapping section, follow the instructions below :

Clockwise closed loop segment - Begin at a designated starting point and proceed to examine the perimeter of the section in a clockwise loop direction, following its boundary until returning to the original position.
Anti clockwise closed loop segment - From the same starting point, turn 180 degrees and examine the perimeter of the section in a anti clockwise loop directon, following its boundary until returning to the original position.
Exploration from various angles - From the same starting point, explore the section and capture it from multiple angles with several turns. Make sure all the static features of the environments (e.g tables, walls, furniture) are captured. These features will enhance relocalization within feature-rich environments. This step must be longer in featureless environments or with repetitive patterns. We recommend doubling the number of loops in such areas to help building a stronger map graph.
Drive to the next mapping section starting point and restart the process.

📌 Note: At certain times, mapping issues may temporarily reduce tracking reliability. In these cases, the Spatial Memory status may briefly switch to LOST before returning to MAP_UPDATE once tracking stabilizes or a loop closure is detected. When this happens, any accumulated drift is automatically corrected.

Example of an environment exploration with three distincts mapping sections:

When all the mapping sections of the environment have been explored, stop the recording if you’ve chosen the offline procedure or stop the sample to retrieve the Area map on the online procedure.

If the offline procedure option was chosen, the area map can also be retrieved directly from the sample. Launch it with these specified options:

./build/ZED_Positional_Tracking --svo recording.svo2 --map -o map_name.area

Lifelong Mapping #

The SDK fully supports lifelong mapping, allowing an existing Area map to be loaded, updated, extended, and saved again with newly explored regions. By enabling positional tracking with an existing .area file, the system seamlessly merges new keyframes with the previously mapped environment, expanding coverage without discarding past data. This makes it possible to continuously grow and refine a map over time, ensuring compatibility with long-term deployment and incremental environment exploration.

To enter this mode, launch the sample with these options after placing the camera back at the initial map starting point:

./build/ZED_Positional_Tracking -i map.area --map -o extended_map.area

Once the camera successfully localizes itself within the loaded Area map, the Spatial Memory status switches from INITIALIZING to KNOWN_MAP.

Starting in a previously mapped region is essential, as it enables the system to anchor the existing map to newly explored areas that will extend it.

As the camera moves into unexplored regions, the status transitions to MAP_UPDATE, indicating that new parts of the environment are being captured.

During this phase, you should follow the recommended mapping best practices to maximize LOOP_CLOSED events and ensure high-quality map expansion.

When the camera returns to a previously mapped part of the environment and the graph reconnects, the status transitions back to KNOWN_MAP.

When done, the newly extended Area map is then directly created by the sample.

Relocalization within an Area Map #

Once an Area map or extended Area map has been collected, relocalization can be enabled directly from the sample. Place the camera back at the map starting point and launch the sample:

./build/ZED_Positional_Tracking -i map.area

As long as the camera remains within previously mapped regions, the Spatial Memory status stays at KNOWN_MAP.

When the camera enters an unfamiliar or insufficiently mapped area, the status may briefly transition to LOST, indicating that localization is no longer reliable and may accumulate drift.

In this situation, you should guide the camera back toward known areas to re-establish tracking and continue the mapping process effectively.

📌 Note: refer to this page for examples on saving an Area map or relocalizing within one using the ZED SDK API.