Positional Tracking Quickstart

Introduction #

The Positional Tracking sample is the fastest way to get started with the positional tracking module.
It is available in C++, Python, and C# languages.

This sample allows you to:

  • Stream live video and visualize the 3D point cloud with OpenGL.
  • Monitor API status in real time to verify module health.
  • Modify the Positional Tracking parameters to customize tracking behavior and evaluate the effects.
  • Open and replay SVO recordings to test different Positional Tracking parameters offline.
  • Record and extract SLAM maps during live sessions.
  • Load existing maps to test relocalization in known environments.

Installation and Setup #

If not already installed, download the latest ZED SDK.

Follow the installation guide for your platform:

Running the Sample (Linux) #

C++ Version #

Open a new terminal and run the following commands:

 //Navigate to the ZED Positional Tracking cpp sample folder
 cd /usr/local/zed/samples/positional\ tracking/positional\ tracking/cpp

 //Create Build folder
 mkdir build && cd build

 //Compile the sample
 cmake .. && make 

 //Run the Positional Tracking sample
 ./ZED_Positional_Tracking

To adjust tracking parameters, edit src/main.cpp and recompile the sample running make in the build folder.

For a detailed explanation of available parameters, see the Positional Tracking Settings page.

Python Version #

 //Navigate to the ZED Positional Tracking Python sample folder
 cd /usr/local/zed/samples/positional\ tracking/positional\ tracking/python

 //Run the Positional Tracking sample
 python3 positional_tracking.py

To modify parameters, edit positional_tracking.py and relaunch the script.

For a detailed explanation of available parameters, see the Positional Tracking Settings page.

Usage #

Command-Line Options #

  --help                      Shows usage information.
  --resolution <mode>         Optional. Resolution options: (HD2K | HD1200 | HD1080 | HD720 | SVGA | VGA)
  --svo <filename.svo>        Optional. Use SVO file input. Mutually exclusive with --stream.
  --stream <ip[:port]>        Optional. Use network streaming input. Mutually exclusive with --svo.
  -i <input_area_file>        Optional. Input area file used in explore mode (default) or --map mode
  --map -o <output_area_file> Optional. Map mode creates or updates an .area file.
                                        Requires -o <output_area_filename> for generated map
  --roi <roi_filepath>        Optional. Region of interest image mask to ignore a static area
  --custom-initial-pose       Optional. Use custom initial pose (see code comments for more detail)
  --2d-ground-mode            Optional. Enable 2D ground mode

Examples #

  ./build/ZED_Positional_Tracking --svo recording.svo2  --map -o new_map.area
  ./build/ZED_Positional_Tracking -i map.area

The sample will take the provided input (connected camera, SVO file, or stream) and display the video feed, tracking status, and 3D rendering of the camera’s current position. When using the --map option, a .area file that contains the mapped area will be exported after the tracking session.

Keyboard Controls #

You can interact with the sample while it’s running:

'space' to toggle camera view visibility
'd' to switch background color from dark to light
'p' to enable / disable current live point cloud display
'l' to enable / disable landmark display
'f' to follow the camera
'z' to reset the view
'ctrl' + drag to rotate
'esc' to exit