This page describes the frame of references and coordinate systems used by Vuforia Engine for native. Use this information to orient your targets and content with respect to your device and the world coordinate system.
There are three major frames of reference defined in the Vuforia Engine:
- World: Defined as the start position of the device. This is your reference origin for the AR interaction.
- Camera/Device: Origin on the physical device (or, more precisely, the camera position on the device).
- Target: Used for tracking physical objects or environment locations.
Frame of Reference
The CS for world and camera in native uses the right-handed Y-up convention that follows the conventional “GL” frame of reference (right-handed, Y-Up). This convention is familiar to what 3D and graphics developers apply.
- World is right-handed, Y-Up, and gravity-aligned.
- Camera/Device is right-handed and Y-up.
- Target Image Targets have Z-up, but Model Targets’ CS depends on the original model.
Transformations (Poses)
Transformations between coordinate systems are represented by 4x4 matrices, which map 3D points from one coordinate system to another. When tracked over time, these transformations estimate the relative movement of the device and targets, as determined by the Vuforia Engine tracking systems.
Engine API
To create an Augmented Reality experience, the application should retrieve the last tracking state by calling vuEngineAcquireLatestState
. The state contains targets and device observations (see, for example, vuStateGetObservations
). Transformations can be retrieved from the observations by calling vuObservationGetPoseInfo
.
Poses retrieved via vuObservationGetPoseInfo
use a common convention and define transformations to the World coordinate system: From Target to World for target transformations and from Camera/Device to World for the DevicePose transformation (see also vuStateGetDevicePoseObservations
).
NOTE: the DevicePose transformation is also available via the VuRenderState.viewMatrix
(see vuStateGetRenderState
). However, the viewMatrix
is the inverse of the DevicePose available from the DevicePose observation; i.e., the viewMatrix
transforms points from World to Camera instead of Camera to World coordinates. For reference, the relation between the poses delivered by Vuforia and the transformation you will use in your rendering engine (e.g., OpenGL) can be interpreted as:
Vuforia Pose Type |
Rendering engine |
Target Pose |
Model Matrix |
Device Pose |
Inverse of the View Matrix |
RenderState viewMatrix | View Matrix |
Vuforia Engine API math utilities provide functions to manipulate coordinate system transformations. Examples are provided below.
Device position in target coordinates
This example describes how to use the Engine API and the matrix manipulation functions to compute the device's position in a target’s coordinate system (e.g., an Area Target).
Step 1: Get the target pose information from the target observation
12Copy
VuPoseInfo targetPoseInfo; vuObservationGetPoseInfo(targetObservation, &targetPoseInfo);
Step 2: Get the view matrix (i.e., the inverse of the device pose) from the render state
12CopyVuRenderState renderState;
vuStateGetRenderState(state, &renderState);
Step 3: Combine the target pose with the view matrix and get the transformation from target to device coordinates
1Copyauto targetToDevice = vuMatrix44FMultiplyMatrix(renderState.viewMatrix, poseInfo.pose);
Step 4: Invert targetToDevice
and get the transformation from device to target coordinates
1Copyauto deviceToTarget = vuMatrix44FInverse(targetToDevice);
Step 5: The last column of the deviceToTarget
matrix describes the device (x, y, z) position in target coordinates (Note: the matrix is defined column-major)
123Copyfloat x = deviceToTarget.data[12];
float y = deviceToTarget.data[13];
float z = deviceToTarget.data[14];