Using the API

Positional Tracking Configuration

To configure positional tracking, use InitParameters at initialization and RuntimeParameters to change specific parameters during use.

// Set configuration parameters
InitParameters init_params;
init_params.camera_resolution = RESOLUTION_HD720; // Use HD720 video mode (default fps: 60)
init_params.coordinate_system = COORDINATE_SYSTEM_RIGHT_HANDED_Y_UP; // Use a right-handed Y-up coordinate system
init_params.coordinate_units = UNIT_METER; // Set units in meters
# Set configuration parameters
init_params = sl.InitParameters()
init_params.camera_resolution = sl.RESOLUTION.RESOLUTION_HD720 # Use HD720 video mode (default fps: 60)
init_params.coordinate_system = sl.COORDINATE_SYSTEM.COORDINATE_SYSTEM_RIGHT_HANDED_Y_UP # Use a right-handed Y-up coordinate system
init_params.coordinate_units = sl.UNIT.UNIT_METER # Set units in meters

Positional tracking uses image and depth information to estimate the position of the camera in 3D space. To improve tracking results, use high FPS video modes such as HD720 and WVGA.

Enabling Positional Tracking

After opening the camera, enable positional tracking using enableTracking() with default TrackingParameters.

// Enable positional tracking with default parameters
sl::TrackingParameters tracking_parameters;
err = zed.enableTracking(tracking_parameters);
if (error != SUCCESS)
# Enable positional tracking with default parameters
tracking_parameters = sl.TrackingParameters()
err = zed.enable_tracking(tracking_parameters)
if err != sl.ERROR_CODE.SUCCESS :

You can disable tracking anytime using disableTracking(). For more information on positional tracking settings, see TrackingParameters.

Getting Pose

Position gets updated with every new frame. To retrieve pose data, use getPosition() after grabbing a frame. In the following example, we extract the pose relative to the World Frame and retrieve the translation and orientation quaternion values using getTranslation() and getOrientation().

sl::Pose zed_pose;
if (zed.grab() == SUCCESS) {
        // Get the pose of the camera relative to the world frame
        TRACKING_STATE state = zed.getPosition(zed_pose, REFERENCE_FRAME_WORLD);
        // Display translation and timestamp
        printf("Translation: tx: %.3f, ty:  %.3f, tz:  %.3f, timestamp: %llu\r",
        zed_pose.getTranslation().tx, zed_pose.getTranslation().ty, zed_pose.getTranslation().tz, zed_pose.timestamp);
        // Display orientation quaternion
        printf("Orientation: ox: %.3f, oy:  %.3f, oz:  %.3f, ow: %.3f\r",
        zed_pose.getOrientation().ox, zed_pose.getOrientation().oy, zed_pose.getOrientation().oz, zed_pose.getOrientation().ow);
zed_pose = sl.Pose()
if zed.grab(runtime_parameters) == sl.ERROR_CODE.SUCCESS :
        # Get the pose of the camera relative to the world frame
        state = zed.get_position(zed_pose, sl.REFERENCE_FRAME.REFERENCE_FRAME_WORLD)
        # Display translation and timestamp
        py_translation = sl.Translation()
        tx = round(zed_pose.get_translation(py_translation).get()[0], 3)
        ty = round(zed_pose.get_translation(py_translation).get()[1], 3)
        tz = round(zed_pose.get_translation(py_translation).get()[2], 3)
        print("Translation: tx: {0}, ty:  {1}, tz:  {2}, timestamp: {3}\n".format(tx, ty, tz, zed_pose.timestamp))
        #Display orientation quaternion
        py_orientation = sl.Orientation()
        ox = round(zed_pose.get_orientation(py_orientation).get()[0], 3)
        oy = round(zed_pose.get_orientation(py_orientation).get()[1], 3)
        oz = round(zed_pose.get_orientation(py_orientation).get()[2], 3)
        ow = round(zed_pose.get_orientation(py_orientation).get()[3], 3)
        print("Orientation: ox: {0}, oy:  {1}, oz: {2}, ow: {3}\n".format(ox, oy, oz, ow))

The class Pose is used to store camera position and additional information such as timestamp and confidence. Since position is always relative to a reference, it is important to set the coordinate frame that will be used as base. To get camera position in real world space, use REFERENCE_FRAME_WORLD, otherwise use REFERENCE_FRAME_CAMERA to get the change in pose relative to the last position (odometry).

By default, the pose of the left eye of the camera is returned. To get the pose at the center of the camera, see Frame Transforms. You can also retrieve a translation, orientation or rotation matrix using getTranslation(), getOrientation() and getRotation().

Tracking States

getPosition() returns a TRACKING_STATE. When a new position is available, TRACKING_STATE_OK is returned. During initialization or when an Area file is loaded, TRACKING_STATE_SEARCHING is returned till the camera recognizes the area. If positional tracking framerate is too low, the state will turn to TRACKING_STATE_FPS_TOO_LOW and stop returning new positions.

Code Example

For code examples, check out the Tutorial and Sample on GitHub.