Coordinate Frames

Motion is relative to an observing position. For example, if a user is holding and walking with a ZED, the camera will not be in motion relative to the user, but it will be in motion relative to the floor. In the same way, the ZED needs to express its motion information relative to a reference frame. This reference frame can either be the World Frame or the previous Camera Frame.

Camera Frame

The Camera Frame is the frame attached to the camera. Located at the back of the left eye of the device, it represents the viewport of the camera and allows to express relative pose. To get the movement between the current camera position and the one corresponding to the previous image, use getPosition(zed_pose, REFERENCE_FRAME_CAMERA).

World Frame

Describing the position of the camera in absolute real-world space requires a reference point that remains stationary as the device moves. This global reference frame is called World Frame. If no initial parameters are set, the World Frame is located at the place where the ZED first started motion tracking, and is oriented in the direction where the device was looking. To get the position of the camera in real-world space, use getPosition(zed_pose, REFERENCE_FRAME_WORLD).

World Frame Transform

You can change the initial location of the Camera Frame relative to the World Frame:

  • By setting an initial world transform in TrackingParameters, the Camera Frame will start at the given position and orientation in world space. This is useful when using the ZED with an IMU, so that the two sensors provide pose data relative to a common reference frame.

    sl::Transform initial_position;
    // Set the initial positon of the Camera Frame at 1m80 above the World Frame
    tracking_parameters.initial_world_transform = initial_position;
  • If Spatial Memory is enabled and an Area file is loaded, the World Frame will be the one stored in the Area file.

Frame Transforms

When the ZED is moving, the motion of the left eye and the center of the camera is not the same. To describe the actual motion of the center of the camera, you need to use a frame transform. A frame transform expresses the rotational and translational offsets between coordinate frames. Since getPosition() provides the pose of the Camera Frame located on the left eye, a rigid transformation is required to get the movement of the center of the camera.

Getting Pose in a local coordinate frame

To get pose data in a user-specified coordinate frame:

  • Measure the spatial transformation (translation and/or rotation) between the left eye of the camera and the local frame you want to get the pose data into.
  • Get pose updates using getPosition().
  • Transform each pose into the new coordinate frame using the translation and orientation offsets measured initially.
  • Use the transformed pose in your application.

Frame transforms can be used to measure the movement of different local components of a rigid body. For example, when using an HMD in VR applications, it is important to transform pose data at the pivot point of the user’s head and neck to accurately describe head movements. A rigid spatial transformation between an IMU frame and the Camera coordinate frame is also required for sensor fusion.

See Positional Tracking sample for an example of spatial transformation.

Selecting a Coordinate System

The ZED uses a three-dimensional Cartesian coordinate system (X, Y, Z) to specify positions and orientations. The coordinate system can be either right-handed or left-handed. By default, the ZED uses an image coordinate system which is right-handed with the positive Y-axis pointing down, X-axis pointing right and Z-axis pointing away from the camera.

Different coordinate systems can be selected using InitParameters:

  • Right handed, y-down (default)
  • Left handed, y-up (Unity)
  • Right handed, y-up (OpenGL)
  • Left handed, z-up (Unreal Engine)
  • Right handed, z-up (ROS)
init_params.coordinate_system = COORDINATE_SYSTEM_RIGHT_HANDED_Y_UP;

Note: Camera Frame and World Frame always share the same coordinate system.

Coordinate Units

By default, coordinate values are in millimeters. It is possible to change coordinate units to meters, centimeters, feet and inches using:

init_params.coordinate_units = UNIT_METER; // Set units in meters