Positional Tracking Status

The Positional Tracking module provides real-time status information. The overall tracking state is returned by the getPosition function as a sl::POSITIONAL_TRACKING_STATE value.

Additionally, detailed 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::POSITIONAL_TRACKING_FUSION_STATUS tracking_fusion_status

The state of an area map export is returned separately by the getAreaExportState function, as a sl::AREA_EXPORTING_STATE value.

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.
OK	The positional tracking is functioning normally.
OFF	The positional tracking is currently disabled.
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	The camera is currently searching for the floor plane to establish its position relative to it. The world reference frame will be set afterward.
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

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;
    }
}

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.
UNAVAILABLE	The positional tracking module cannot track the current frame.
INSUFFICIENT_FEATURES	The positional tracking failed to track the current frame because it could not find enough features.

Example: Access the Odometry Status from the API

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;
    }
}

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.
LOOP_CLOSED	Displayed whenever the system has found a loop closure, relocalized within the area map or corrected after a sudden localization loss.
SEARCHING	- Deprecated - This state is no longer in use for GEN_3.
OFF	Displayed when the spatial memory is turned off.
INITIALIZING	Displayed until the camera 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.
KNOWN_MAP	Displayed when the camera is localized within the loaded area map.
MAP_UPDATE	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.
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

#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;
        }
    }
}

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.
RUNNING	The spatial memory is currently being written.
NOT_STARTED	The spatial memory file exportation has not been called.
FILE_EMPTY	The spatial memory contains no data, the file is empty.
FILE_ERROR	The spatial memory file has not been written because of a wrong file name.
SPATIAL_MEMORY_DISABLED	The spatial memory learning is disabled. No file can be created.

Example: Access the Area Exporting State from the API

#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 = zed.getAreaExportState();
    while (exportState == sl::AREA_EXPORTING_STATE::RUNNING) {
        std::cout << "Exporting state: " << sl::toString(exportState) << std::endl;
        sl::sleep_ms(10);
        exportState = zed.getAreaExportState();
    }
    std::cout << "Final exporting status: " << sl::toString(exportState) << std::endl;
    return 0;
}