EasyAR coordinate system

In 3D programs, the definition of coordinate systems is crucial. Unless otherwise specified, the following conventions are adopted.

• Vectors are column vectors.

• Matrices are row-major. (OpenGL is column-major)

• Coordinate systems are all right-handed. (Consistent with OpenGL)

• If a physical scale exists for a coordinate system, the unit is meters.

• The negative Y-axis of the world coordinate system is the gravity direction.

• The device coordinate system has the X-axis pointing right, the Y-axis pointing up, and the Z-axis pointing outward from the screen. For devices with rotatable screens, right and up are defined based on their default orientation. Specifically, Android's default orientation follows the system definition. (Glasses and some tablets have landscape as the default orientation; phones and some tablets have portrait as the default orientation). iOS's default orientation is portrait. (Consistent with the definitions in the IMU descriptions for Android and iOS)

Pose of object tracking

The object pose for planar image tracking (ImageTracker) and 3D object tracking (ObjectTracker) is stored in pose, representing the pose of the currently tracked target relative to the camera. Both the camera coordinate system and the target coordinate system are right-handed. The origin of the camera coordinate system is the camera's optical center. The positive X-axis points right, the positive Y-axis points up, and the positive Z-axis points in the direction of light entering the camera (out of the screen). (Right and up here refer to the right and up in the camera image, which may differ from the device's natural orientation.) The data is arranged in row-major order, opposite to OpenGL's column-major.

The pose can be written as:

\[ P = \left( \begin{array}{cccc} p_{11} & p_{12} & p_{13} & p_{14} \\ p_{21} & p_{22} & p_{23} & p_{24} \\ p_{31} & p_{32} & p_{33} & p_{34} \\ 0 & 0 & 0 & 1 \\ \end{array} \right) \]

If the 3D engine uses different axis definitions, this must be considered when setting the transformation matrix in the 3D engine. For example, if both the camera coordinate system and the target coordinate system have opposite Z-axis directions, the transformation matrix value for the target node in the 3D engine should be set to:

\[ \left( \begin{array}{cccc} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & -1 & 0 \\ 0 & 0 & 0 & 1 \\ \end{array} \right)\left( \begin{array}{cccc} p_{11} & p_{12} & p_{13} & p_{14} \\ p_{21} & p_{22} & p_{23} & p_{24} \\ p_{31} & p_{32} & p_{33} & p_{34} \\ 0 & 0 & 0 & 1 \\ \end{array} \right)\left( \begin{array}{cccc} 1 & 0 & 0 & 0 \\ 0 & 1 & 0 & 0 \\ 0 & 0 & -1 & 0 \\ 0 & 0 & 0 & 1 \\ \end{array} \right)=\left( \begin{array}{cccc} p_{11} & p_{12} & -p_{13} & p_{14} \\ p_{21} & p_{22} & -p_{23} & p_{24} \\ -p_{31} & -p_{32} & p_{33} & -p_{34} \\ 0 & 0 & 0 & 1 \\ \end{array} \right) \]

Transform of motion tracking

The transform from surface tracking (SurfaceTracker) and the cameraTransform from motion tracking (MotionTrackerCameraDevice), ARKit (ARKitCameraDevice), and ARCore (ARCoreCameraDevice) represent the transformation of the camera relative to the world coordinate system. Both the camera coordinate system and the world coordinate system are right-handed. The origin of the camera coordinate system is the camera's optical center. The positive X-axis points right, the positive Y-axis points up, and the positive Z-axis points in the direction of light entering the camera (out of the screen). (Right and up here, on mobile devices, refer to the device's natural right and up.) The world coordinate system has its Y-axis pointing up (opposite to gravity direction), and its origin is determined by the motion tracking system. The data is arranged in row-major order, opposite to OpenGL's column-major.

Pose in sparse spatial map and Mega

The getMapPose from the sparse spatial map (SparseSpatialMap) and the pose in Mega represent the position and orientation of the map block in the camera coordinate system. Both the camera coordinate system and the map block coordinate system are right-handed. The origin of the camera coordinate system is the camera's optical center. The positive X-axis points right, the positive Y-axis points up, and the positive Z-axis points in the direction of light entering the camera (out of the screen). (Right and up here, on mobile devices, refer to the device's natural right and up.) The map block coordinate system has its Y-axis pointing up (opposite to gravity direction), and its origin is determined by the map block data. The data is arranged in row-major order, opposite to OpenGL's column-major.