This page describes the frame of references and coordinate systems (CS) used by Vuforia Engine. Use this information to orient your targets and content with respect to your device and the world coordinate system as the starting origin
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). Camera/Device pose are reported in the World CS.
- Target: Used for tracking physical objects or environment locations. Target poses are reported in the World CS, but the Up convention varies on the type of target.
Frame of Reference in Unity
In Unity, the coordinate system follows the DirectX convention (left-handed Y-up), and the poses are automatically applied to the scene objects.
- World is left-handed, Y-Up, and gravity aligned.
- Camera/Device is left-handed and Y-up.
- Target varies:
- Model Targets depend on the original model. The X axis is flipped in direction to conform to the left-handed coordinate system convention.
- Other targets are left-handed and Y up.
Set the World Center Mode in Unity
The world origin (0,0,0) can be set to a specific target, to the first target detected, or to the device/camera. The setting is part of the AR Camera GameObject under World Center Mode.
FIRST_TARGET sets the world origin to the first detected Vuforia target. The target is from this moment maintaining its relative position and the AR Camera updates its transform position relative to the target. Other Vuforia targets and digital content are then relative to this first detected target.
SPECIFIC_TARGET sets the world origin to a specified target’s Observer Behaviour present in the Unity scene. Once the Vuforia target is detected, the world origin is set to it and the AR Camera and other content will update their position relative to the specified target.
DEVICE sets the world origin to the AR Camera GameObject. The AR Camera will then maintain a fixed position and the Vuforia targets and content will update their relative position with respect to it. This is for example necessary on eyewear devices.
When you have the DevicePoseObserver
enabled and the World Center Mode set to a FIRST or SPECIFIC target, turning off the DevicePoseObserver
will make the origin only valid for as long as the target is tracked.
Frame of Reference in Native
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 that 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 depend on the original model
API usage
The transformation between CS and device poses are available from vuObservationHasPoseInfo
and vuObservationGetPoseInfo
. In addition to the device pose, retrieve the view pose from the State with vuStateGetRenderState
. Call this after starting the engine and camera and make sure to set vuRenderControllerSetRenderViewConfig()
to determine the view port size. On some platforms, Vuforia Engine might fail to auto-detect the view port and consequently the video rendering data would return 0 if it not set.
For actions to inverse device pose and transposing it, the math utilities have functions for matrix manipulation and vector calculations.
modelMatrix = poseInfo.pose;
// We transpose here because Matrix44FInverse returns a transposed matrix
devicePoseMatrix = SampleMath.vuMatrix44FTranspose(SampleMath.vuMatrix44FInverse(modelMatrix));
The relation between the poses delivered by Vuforia and the transformation you will use in your rendering engine can be interpreted as:
Pose Type |
Used For |
---|---|
Device Pose | Inversing pose for View Matrix |
Target Pose |
Model Matrix |