Spatial Frame of Reference for Native

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

12
Copy
VuPoseInfo targetPoseInfo; vuObservationGetPoseInfo(targetObservation, &targetPoseInfo);

Step 2: Get the view matrix (i.e., the inverse of the device pose) from the render state

12
Copy
VuRenderState renderState; vuStateGetRenderState(state, &renderState);

 Step 3: Combine the target pose with the view matrix and get the transformation from target to device coordinates

1
Copy
auto targetToDevice = vuMatrix44FMultiplyMatrix(renderState.viewMatrix, poseInfo.pose);

Step 4: Invert targetToDevice and get the transformation from device to target coordinates

1
Copy
auto 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)

123
Copy
float x = deviceToTarget.data[12]; float y = deviceToTarget.data[13]; float z = deviceToTarget.data[14];

Can this page be better?
Share your feedback via our issue tracker