Using the Positional Tracking API
Positional Tracking Configuration
To configure positional tracking, use InitParameters at initialization and RuntimeParameters to change specific parameters during use.
Enabling Positional Tracking
After opening the camera, enable positional tracking using enablePositionalTracking() with default PositionalTrackingParameters.
You can disable tracking anytime using disablePositionalTracking().
For more information on positional tracking settings, refer to the Positional Tracking Settings page.
Getting Pose
The camera 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().
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().
Getting Velocity
The velocity gets updated with every new frame. To retrieve velocity data, use getPosition() after grabbing a frame. In the following example, we extract the velocity relative to the Camera Frame and retrieve the linear and angular velocities along the [x,y,z] axes.
Using a Motion Prior
Since ZED SDK 5.6, GEN_3 positional tracking can fuse the motion measured by your own source, such as wheel odometry, an external visual-inertial system, or the difference between two consecutive GNSS fixes. This motion prior keeps the tracking accurate through fast motion, low texture and occlusion. It constrains how far the camera can have moved between two images; the images still determine the final pose.
Give each measurement to ingestMotionPrior() as a RelativePoseData:
start_timestampandend_timestamp: the time interval the motion was measured over, on the same clock as the images (getTimestamp(TIME_REFERENCE::IMAGE)). Feed the samples back to back: each interval starts where the previous one ended.motion: the motion of your source over that interval, along its own axes, in thecoordinate_unitsofInitParameters.measured_axes: the axes your source actually measures, for exampleTX,TYandRZfor wheel encoders. Declaring an axis the source does not measure is the most common reason for a motion prior to degrade the tracking.covariance: the uncertainty of the motion, 6x6 row-major, ordered[tx, ty, tz, rx, ry, rz], likePose::pose_covariance. Only the measured axes are read.sensor_transform: where your source is mounted relative to the camera, in thecoordinate_systemofInitParameters. Leave it at identity when the source measures along the axes of that coordinate system.is_stationary: set it, with a small but non-zero covariance, when the vehicle is stopped, so the position holds perfectly still.rejection_threshold: how far the motion may disagree with the images, as a multiple of its uncertainty, before it is discarded (default 3).
There is nothing to enable: the motion prior is used from the first sample on. Call ingestMotionPrior() before grab(), from any thread, as many times as your source produces samples. A source faster than the camera is used on every image; a slower one, or a sample that arrives after its image, corrects the trajectory over longer stretches, provided it arrives within 2 seconds. A missing sample is never an error: the tracking then uses the images alone.
ingestMotionPrior() returns:
ERROR_CODE::INVALID_FUNCTION_CALLwhen the tracking is not enabled inGEN_3.ERROR_CODE::INVALID_FUNCTION_PARAMETERSfor an unusable sample: timestamps left at 0 or not ordered, no measured axis, unusable covariance, or invalidsensor_transformorrejection_threshold.ERROR_CODE::INVALID_TIMESTAMPfor a sample ending more than 2 seconds before the last grabbed image.
getPositionalTrackingStatus().relative_pose_fusion_status reports how the motion prior was used for each image, see Positional Tracking Status.
A wrong sensor_transform rotation is the most likely reason for a motion prior to be rejected. Your source must also have the same handedness as the selected coordinate system: convert the motion of a left-handed source before ingesting it.
The motion prior is also available in C# (IngestMotionPrior()) and in the Sensors API (Sensors::ingestMotionPrior(), see Multi-Camera Tracking). To replay a motion prior from an SVO2 file, record it into the file with the -ingest-motion-prior option of ZED SVO Editor.
Saving an Area Map
Relocalizing within an Area map
Code Example
For code examples, check out the Tutorial and Sample on GitHub.

