RelativePoseData Class Reference

Class containing the motion measured by your motion source over one time interval, to be used by the positional tracking as a prior. More...

Functions

Timestamp start_timestamp (self)
 Beginning of the time interval this motion was measured over. More...
 
Timestamp end_timestamp (self)
 End of the time interval this motion was measured over. More...
 
Transform motion (self)
 Motion of your motion source between start_timestamp and end_timestamp. More...
 
POSE_AXIS measured_axes (self)
 Degrees of freedom that your motion source actually measures. More...
 
npt.NDArray[float] covariance (self)
 Uncertainty of motion (NumPy array of 36 values), row-major 6x6, ordered [tx, ty, tz, rx, ry, rz]. More...
 
bool is_stationary (self)
 Whether this sample reports that the camera did not move at all. More...
 
Transform sensor_transform (self)
 Where your motion source is mounted, relative to the camera. More...
 
float rejection_threshold (self)
 How far this motion is allowed to disagree with the images before it is discarded, as a multiple of the uncertainty given in covariance. More...
 

Detailed Description

Class containing the motion measured by your motion source over one time interval, to be used by the positional tracking as a prior.

Use it to give wheel odometry, an external visual-inertial system or the difference between two consecutive GNSS fixes to the ZED SDK through Camera.ingest_motion_prior(). The motion prior constrains how far the camera is allowed to have moved between two images; the images still determine the final pose.

Note
The following conventions are fixed and cannot be configured:
- motion is the pose of your motion source at end_timestamp expressed in the frame that same source was in at start_timestamp, the same direction as the Pose of Camera.get_position().
- motion is expressed along the axes of your motion source, exactly as that source measures it, in the unit selected in InitParameters.coordinate_units. Where those axes point is described only by sensor_transform, read in the coordinate system you selected, so leaving it at identity means your source measures along those very axes.
- covariance is ordered [tx, ty, tz, rx, ry, rz], the same order and quantities as Pose.pose_covariance, so translation first, then the rotation as a rotation vector in radians, not Euler angles.
- covariance describes the error of motion in the frame the source started the interval in, as Pose.pose_covariance does for a pose, and not along the axes the source ends up on.
- Translation variances are in coordinate units squared, rotation variances in radians squared, and the translation/rotation blocks in coordinate units times radians.
# Wheel odometry on a ground robot, with InitParameters.coordinate_system set to
# COORDINATE_SYSTEM.RIGHT_HANDED_Z_UP_X_FWD (ROS): X forward, Y left, Z up. The encoders
# measure along those very axes, so sensor_transform is left at identity.
prior = sl.RelativePoseData()
prior.start_timestamp = previous_ts
prior.end_timestamp = current_ts
motion = sl.Transform()
motion.set_translation(sl.Translation([forward_motion, 0, 0]))
motion.set_rotation_vector(0, 0, heading_change)
prior.motion = motion
prior.measured_axes = sl.POSE_AXIS.TX | sl.POSE_AXIS.TY | sl.POSE_AXIS.RZ
covariance = np.zeros(36)
covariance[0 * 6 + 0] = forward_variance
covariance[1 * 6 + 1] = sideways_variance
covariance[5 * 6 + 5] = heading_variance
prior.covariance = covariance
zed.ingest_motion_prior(prior)

Functions

◆ start_timestamp()

Timestamp start_timestamp (   self)

Beginning of the time interval this motion was measured over.

Set it to the end_timestamp of the RelativePoseData you ingested previously, so that consecutive samples follow each other without a gap. For your very first sample, set it to the instant your source started measuring that increment.

Note
Same time reference as end_timestamp, and earlier than it. It cannot be left at 0.
Accepts a Timestamp or an integer number of nanoseconds.

◆ end_timestamp()

Timestamp end_timestamp (   self)

End of the time interval this motion was measured over.

It must use the same time reference as Camera.get_timestamp() with TIME_REFERENCE.IMAGE.

Note
Accepts a Timestamp or an integer number of nanoseconds.

◆ motion()

Transform motion (   self)

Motion of your motion source between start_timestamp and end_timestamp.

Give it exactly as your source measures it, along its own axes: the ZED SDK moves it into the camera frame using sensor_transform. Only the parts selected by measured_axes are read, the others can hold anything.

Note
The getter returns a copy: assign the whole Transform back to change it.

◆ measured_axes()

POSE_AXIS measured_axes (   self)

Degrees of freedom that your motion source actually measures.

Default: POSE_AXIS.NONE, so it must be set: a sample that declares no axis is rejected by Camera.ingest_motion_prior().

Note
Wheel encoders measure forward, sideways and heading motion only, and should not claim the other three. Declaring an axis that the source does not measure is the most common reason for a motion prior to degrade the tracking instead of improving it.

◆ covariance()

npt.NDArray[float] covariance (   self)

Uncertainty of motion (NumPy array of 36 values), row-major 6x6, ordered [tx, ty, tz, rx, ry, rz].

Only the rows and columns selected by measured_axes are read, which keeps the correlations between the measured axes, for example the coupling between forward motion and heading on a two-wheeled robot. The remaining entries can be left at 0.

The part that is read must be symmetric and describe a real uncertainty. Values too small to be physically achievable are raised to a minimum by the ZED SDK.

Note
The getter returns a copy: assign the whole array back to change it. A 6x6 array is accepted too.

◆ is_stationary()

bool is_stationary (   self)

Whether this sample reports that the camera did not move at all.

Default: False

Note
Set it together with a small but non-zero covariance. It is what allows the ZED SDK to hold the position perfectly still while your vehicle is stopped.

◆ sensor_transform()

Transform sensor_transform (   self)

Where your motion source is mounted, relative to the camera.

Set the pose of the source (the wheel odometry frame, the external tracker, ...) in the camera frame: its translation is where the source sits, its rotation is how the axes it measures along are oriented. The ZED SDK then brings motion and covariance into the camera frame for you, so you fill them exactly as your source produces them.
Default: identity, meaning that the source already reports the motion of the camera itself, along the camera axes.

Note
It is expressed in the InitParameters.coordinate_system you selected, its translation in the InitParameters.coordinate_units you selected.
To fill the rotation, write each axis your source measures along as a column, expressed in that coordinate system. A source measuring forward, left and up, with COORDINATE_SYSTEM.RIGHT_HANDED_Y_UP (right, up, backward) selected, gives the columns (0, 0, -1), (-1, 0, 0) and (0, 1, 0).
A rotation never mirrors an axis, so your source must have the same handedness as the coordinate system you selected. A left-handed source (Unity, Unreal Engine) therefore goes with a left-handed one; otherwise convert the motion and its uncertainty before ingesting it, as a mirroring transform makes Camera.ingest_motion_prior() refuse the sample.
Getting the rotation wrong is the most likely reason for the motion prior to be rejected, which PositionalTrackingStatus.relative_pose_fusion_status reports.
The getter returns a copy: assign the whole Transform back to change it.

◆ rejection_threshold()

float rejection_threshold (   self)

How far this motion is allowed to disagree with the images before it is discarded, as a multiple of the uncertainty given in covariance.

Lower values trust the images more, higher values trust the motion prior more.
Default: 3.0

Note
Must be strictly positive, otherwise Camera.ingest_motion_prior() refuses the sample. To never discard the motion, set a large value.
When several samples cover the same image or keyframe interval, the lowest value applies.
Discarded motion is reported through PositionalTrackingStatus.relative_pose_fusion_status.