Table of Contents

EasyAR coordinate systems

In 3D programs, the definition of coordinate systems is very important. Unless otherwise stated, the following conventions are used.

  • Vectors are column vectors.

  • Matrices use row-major order. (OpenGL is column-major)

  • Coordinate systems use right-handed coordinate systems. (Consistent with OpenGL)

  • If a coordinate system has a physical scale, the unit is meter.

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

  • The X-axis of the device coordinate system points to the right, the Y-axis points up, and the Z-axis points outward from the screen. For devices whose screens can rotate, the definitions of right and up are based on the default orientation. In particular, Android's default orientation follows the system definition. (Landscape placement is the default orientation for glasses and some tablets, and portrait placement is the default orientation for phones and some tablets.) The default orientation of iOS is portrait placement. (Consistent with the definitions in the Android and iOS IMU documentation)

Pose for object tracking

The object pose of planar image tracking (ImageTracker) and 3D object tracking (ObjectTracker) is stored in pose, and represents the pose of the currently tracked target relative to the camera. Both the camera coordinate system and target coordinate system are right-handed coordinate systems. The origin of the camera coordinate system is the optical center of the camera, the positive x-axis points right, the positive y-axis points up, and the positive z-axis points in the direction where light enters the camera (outward from the screen). (Here, right and up refer to right and up in the camera image, which may differ from the device's natural orientation.) The data layout is row-major, the opposite of 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 other coordinate-axis definitions, this needs to be considered when setting the transform matrix in the 3D engine. For example, when the z directions of both the camera coordinate system and target coordinate system are opposite, the transform matrix value of 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 for motion tracking

transform of surface tracking (SurfaceTracker), and cameraTransform of motion tracking (MotionTrackerCameraDevice), ARKit (ARKitCameraDevice), and ARCore (ARCoreCameraDevice), represent the transform of the camera relative to the world coordinate system. Both the camera coordinate system and world coordinate system are right-handed coordinate systems. The origin of the camera coordinate system is the optical center of the camera, the positive x-axis points right, the positive y-axis points up, and the positive z-axis points in the direction where light enters the camera (outward from the screen). (Here, right and up on mobile devices refer to right and up in the device's natural orientation.) The y-axis of the world coordinate system points up (opposite to gravity), and the origin is determined by the motion tracking system. The data layout is row-major, the opposite of OpenGL's column-major.

Pose in sparse spatial maps and Mega

getMapPose of the sparse spatial map SparseSpatialMap and 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 coordinate systems. The origin of the camera coordinate system is the optical center of the camera, the positive x-axis points right, the positive y-axis points up, and the positive z-axis points in the direction where light enters the camera (outward from the screen). (Here, right and up on mobile devices refer to right and up in the device's natural orientation.) The y-axis of the map block coordinate system points up (opposite to gravity), and the origin is determined by the map block data. The data layout is row-major, the opposite of OpenGL's column-major.