Positional Tracking Status

The Positional Tracking module provides real-time status information about the tracking state, odometry status, spatial memory status, and area exporting state through the getPosition function, which returns a sl::POSITIONAL_TRACKING_STATE value.

Additionally, detailed Visual Odometry tracking status can be accessed via the getPositionalTrackingStatus function, which returns a sl::PositionalTrackingStatus structure containing the following fields:

sl::ODOMETRY_STATUS odometry_status
sl::SPATIAL_MEMORY_STATUS spatial_memory_status
sl::AREA_EXPORTING_STATE area_exporting_state

POSITIONAL_TRACKING_STATE #

Positional Tracking State indicates the current status of the positional tracking module. It provides insights into whether the tracking is functioning correctly or if there are any issues affecting its performance.

Enumerator	Description
SEARCHING	- DEPRECATED - This state is no longer in use.
SEARCHING	OK	The positional tracking is functioning normally.
OFF	OK	The positional tracking is currently disabled.
OFF	FPS_TOO_LOW	The effective FPS is too low to provide accurate motion tracking results. Consider adjusting performance parameters (e.g., depth mode, camera resolution) to improve tracking quality.
SEARCHING_FLOOR_PLANE	FPS_TOO_LOW	The camera is currently searching for the floor plane to establish its position relative to it. The world reference frame will be set afterward.
SEARCHING_FLOOR_PLANE	UNAVAILABLE	The tracking module was unable to perform tracking from the previous frame to the current frame.

For more information, refer to the API documentation page.

Example: Access the Positional Tracking State information from the API #

C++
Python
C#

sl::Camera zed;
zed.open();

// Start positional tracking
sl::PositionalTrackingParameters tracking_params;
zed.enablePositionalTracking(tracking_params);

sl::Pose camera_pose;
sl::POSITIONAL_TRACKING_STATE tracking_state;

while (true) {
    if (zed.grab() == sl::ERROR_CODE::SUCCESS) {
        tracking_state = zed.getPosition(camera_pose);

        std::cout << "Tracking state: " << tracking_state << std::endl;

        // Or convert to string:
        std::cout << "Tracking state (string): " 
                  << sl::toString(tracking_state).c_str() << std::endl;
    }
}

import pyzed.sl as sl

zed = sl.Camera()
zed.open()

tracking_params = sl.PositionalTrackingParameters()
zed.enable_positional_tracking(tracking_params)

camera_pose = sl.Pose()

while True:
    if zed.grab() == sl.ERROR_CODE.SUCCESS:
        state = zed.get_position(camera_pose)

        print("Tracking state:", state)
        # Or using the string conversion:
        print("Tracking state (string):", state.name)

using sl;

Camera zed = new Camera();
zed.Open();

PositionalTrackingParameters trackingParams = new PositionalTrackingParameters();
zed.EnablePositionalTracking(ref trackingParams);

Pose cameraPose = new Pose();

while (true)
{
    if (zed.Grab() == ERROR_CODE.SUCCESS)
    {
        POSITIONAL_TRACKING_STATE state = zed.GetPosition(ref cameraPose);

        Console.WriteLine("Tracking state: " + state);
        // Same as string output automatically
    }
}

ODOMETRY_STATUS #

Odometry Status indicates the current state of the Visual Odometry (VO) tracking process. It provides insights into whether the VO is functioning correctly or if there are any issues affecting its performance.

Enumerator	Description
OK	The positional tracking module successfully tracked from the previous frame to the current frame.
OK	UNAVAILABLE	The positional tracking module cannot track the current frame.
INSUFFICIENT_FEATURES	UNAVAILABLE	The positional tracking failed to track the current frame because it could not find enought features.

Example: Access the Odometry Status from the API #

C++
Python
C#

sl::Camera zed;
zed.open();

// Enable positional tracking
sl::PositionalTrackingParameters tracking_params;
zed.enablePositionalTracking(tracking_params);

sl::PositionalTrackingStatus tracking_status;

while (true) {
    if (zed.grab() == sl::ERROR_CODE::SUCCESS) {

        tracking_status = zed.getPositionalTrackingStatus();

        sl::ODOMETRY_STATUS odom_status = tracking_status.odometry_status;

        std::cout << "Odometry status: " << odom_status << std::endl;
        std::cout << "Odometry status (string): "
                  << sl::toString(odom_status).c_str() << std::endl;
    }
}

import pyzed.sl as sl

zed = sl.Camera()
zed.open()

tracking_params = sl.PositionalTrackingParameters()
zed.enable_positional_tracking(tracking_params)

tracking_status = sl.PositionalTrackingStatus()

while True:
    if zed.grab() == sl.ERROR_CODE.SUCCESS:

        tracking_status = zed.get_positional_tracking_status()

        odom_status = tracking_status.odometry_status

        print("Odometry status:", odom_status)
        print("Odometry status (string):", odom_status.name)

using sl;

Camera zed = new Camera();
zed.Open();

PositionalTrackingParameters trackingParams = new PositionalTrackingParameters();
zed.EnablePositionalTracking(ref trackingParams);

PositionalTrackingStatus trackingStatus = new PositionalTrackingStatus();

while (true)
{
    if (zed.Grab() == ERROR_CODE.SUCCESS)
    {
        trackingStatus = zed.GetPositionalTrackingStatus();

        ODOMETRY_STATUS odomStatus = trackingStatus.odometry_status;

        Console.WriteLine("Odometry status: " + odomStatus);
    }
}

SPATIAL_MEMORY_STATUS (VSLAM Status) #

Spatial Memory Status indicates the current state of the Visual SLAM (VSLAM) tracking process. It provides insights into whether the VSLAM is functioning correctly or if there are any issues affecting its performance.

Enumerator	Description
OK	- Deprecated - This state is no longer in use for GEN_3.
OK	LOOP_CLOSED	Displayed whenever the system has found a loop closure, relocalized within the area map or corrected after a sudden localization loss.
SEARCHING	LOOP_CLOSED	- Deprecated - This state is no longer in use for GEN_3.
SEARCHING	OFF	Displayed when the spatial memory is turned off.
INITIALIZING	OFF	Displayed until the cameras has acquired enough memory (Initial Area Mapping) or has found its first loop closure and is localized in the loaded area map (Lifelong Mapping/Localization). Users need to keep moving the camera for it to get updated.
INITIALIZING	KNOWN_MAP	Displayed when the camera is localized within the loaded area map.
MAP_UPDATE	KNOWN_MAP	Displayed when the robot is mapping (Initial Area Mapping) or when the robot is getting out of the area map bounds (Lifelong Mapping). Displayed as `TRACKING` when in exploratory mode with SLAM engaged.
MAP_UPDATE	LOST	Displayed when localization cannot operate anymore (camera completely obstructed, sudden localization jumps after being localized) in Mapping/ Localization modes. It can also include the case where the camera jumps or is located out of map bounds in Localization mode. This should be an indicator for users to stop the robot.

Example: Access the Spatial Memory Status from the API #

C++
Python
C#

#include <sl/Camera.hpp>
#include <iostream>

int main() {
    sl::Camera zed;
    zed.open();

    sl::PositionalTrackingParameters tracking_params;
    zed.enablePositionalTracking(tracking_params);

    sl::PositionalTrackingStatus tracking_status;

    while (true) {
        if (zed.grab() == sl::ERROR_CODE::SUCCESS) {
            
            tracking_status = zed.getPositionalTrackingStatus();

            sl::SPATIAL_MEMORY_STATUS mem_status = tracking_status.spatial_memory_status;

            std::cout << "Spatial Memory Status: " << mem_status << std::endl;
            std::cout << "Spatial Memory Status (string): "
                      << sl::toString(mem_status).c_str() << std::endl;
        }
    }
}

import pyzed.sl as sl

zed = sl.Camera()
zed.open()

tracking_params = sl.PositionalTrackingParameters()
zed.enable_positional_tracking(tracking_params)

while True:
    if zed.grab() == sl.ERROR_CODE.SUCCESS:

        tracking_status = zed.get_positional_tracking_status()

        mem_status = tracking_status.spatial_memory_status

        print("Spatial Memory Status:", mem_status)
        print("Spatial Memory Status (string):", mem_status.name)

using sl;
using System;

class Program {
    static void Main() {

        Camera zed = new Camera();
        zed.Open();

        PositionalTrackingParameters trackingParams = new PositionalTrackingParameters();
        zed.EnablePositionalTracking(ref trackingParams);

        PositionalTrackingStatus trackingStatus = new PositionalTrackingStatus();

        while (true)
        {
            if (zed.Grab() == ERROR_CODE.SUCCESS)
            {
                trackingStatus = zed.GetPositionalTrackingStatus();

                SPATIAL_MEMORY_STATUS memStatus = trackingStatus.spatial_memory_status;

                Console.WriteLine("Spatial Memory Status: " + memStatus);
            }
        }
    }
}

AREA_EXPORTING_STATE #

Area Exporting State indicates the current status of the spatial memory exportation process. It provides insights into whether the exportation is functioning correctly or if there are any issues affecting its performance.

Enumerator	Description
SUCCESS	The spatial memory file has been successfully created.
SUCCESS	RUNNING	The spatial memory is currently being written.
NOT_STARTED	RUNNING	The spatial memory file exportation has not been called.
NOT_STARTED	FILE_EMPTY	The spatial memory contains no data, the file is empty.
FILE_ERROR	FILE_EMPTY	The spatial memory file has not been written because of a wrong file name.
FILE_ERROR	SPATIAL_MEMORY_DISABLED	The spatial memory learning is disabled. No file can be created.

Example: Access the Area Exporting State from the API #

C++
Python
C#

#include <sl/Camera.hpp>
#include <iostream>

int main() {
    sl::Camera zed;
    zed.open();

    sl::PositionalTrackingParameters tracking_params;
    zed.enablePositionalTracking(tracking_params);

    // Export area map
    zed.saveAreaMap("my_scene.area");

    // Query export state until complete
    sl::AREA_EXPORTING_STATE exportState = sl::AREA_EXPORTING_STATE::NOT_STARTED;
    while (exportState == sl::AREA_EXPORTING_STATE::RUNNING) {
        exportState = zed.getAreaExportState();
        std::cout << "Exporting state: " << sl::toString(exportState) << std::endl;
    }

    std::cout << "Final exporting status: " << sl::toString(exportState) << std::endl;

    return 0;
}

import pyzed.sl as sl

zed = sl.Camera()
zed.open()

tracking_params = sl.PositionalTrackingParameters()
zed.enable_positional_tracking(tracking_params)

while True:
    if zed.grab() == sl.ERROR_CODE.SUCCESS:

        status = zed.get_positional_tracking_status()

        export_state = status.area_exporting_state

        print("Area Exporting State:", export_state)
        print("Area Exporting State (string):", export_state.name)

using sl;
using System;

class Program {
    static void Main() {

        Camera zed = new Camera();
        zed.Open();

        PositionalTrackingParameters trackingParams = new PositionalTrackingParameters();
        zed.EnablePositionalTracking(ref trackingParams);

        PositionalTrackingStatus status = new PositionalTrackingStatus();

        while (true)
        {
            if (zed.Grab() == ERROR_CODE.SUCCESS)
            {
                status = zed.GetPositionalTrackingStatus();

                AREA_EXPORTING_STATE exportState = status.area_exporting_state;

                Console.WriteLine("Area Exporting State: " + exportState);
            }
        }
    }
}