Pose

public class Pose

Represents an immutable rigid transformation from one coordinate space to another. As provided from all ARCore APIs, Poses always describe the transformation from object's local coordinate space to the world coordinate space (see below). That is, Poses from ARCore APIs can be thought of as equivalent to OpenGL model matrices.

The transformation is defined using a quaternion rotation about the origin followed by a translation.

Coordinate system is right-handed, like OpenGL conventions.

Translation units are meters.

World Coordinate Space

As ARCore's understanding of the environment changes, it adjusts its model of the world to keep things consistent. When this happens, the numerical location (coordinates) of the camera and Anchors can change significantly to maintain appropriate relative positions of the physical locations they represent.

These changes mean that every frame should be considered to be in a completely unique world coordinate space. The numerical coordinates of anchors and the camera should never be used outside the rendering frame during which they were retrieved. If a position needs to be considered beyond the scope of a single rendering frame, either an anchor should be created or a position relative to a nearby existing anchor should be used.

Fields

public static final Pose IDENTITY The identity pose.

Public Constructors

Pose(float[] translation, float[] rotation)
Returns a new pose having the specified translation and rotation.

Public Methods

Pose
compose(Pose rhs)
Returns the result of composing this with rhs.
Pose
extractRotation()
Returns a pose having the rotation of this pose but no translation.
Pose
extractTranslation()
Returns a pose having the translation of this pose but no rotation.
void
getRotationQuaternion(float[] dest, int offset)
Copies the rotation quaternion into a float array starting at offset.
float[]
getRotationQuaternion()
Returns a float[4] containing the rotation component of this pose.
float[]
getTransformedAxis(int axis, float scale)
Returns the transformed direction of a local axis.
void
getTransformedAxis(int axis, float scale, float[] dest, int offset)
Computes the transformed direction of a local axis, outputting into a float array.
float[]
getTranslation()
Returns a float[3] containing the translation component of this pose.
void
getTranslation(float[] dest, int offset)
Copies the translation vector into a float array starting at offset.
float[]
getXAxis()
Returns a 3-element array containing the direction of the transformed X axis.
float[]
getYAxis()
Returns a 3-element array containing the direction of the transformed Y axis.
float[]
getZAxis()
Returns a 3-element array containing the direction of the transformed Z axis.
Pose
inverse()
Returns a pose that performs the opposite transformation.
static Pose
makeInterpolated(Pose a, Pose b, float t)
Returns a new pose that blends between two input poses.
static Pose
makeRotation(float[] quaternion)
Creates a rotation-only pose.
static Pose
makeRotation(float x, float y, float z, float w)
Creates a rotation-only pose.
static Pose
makeTranslation(float[] translation)
Creates a translation-only pose.
static Pose
makeTranslation(float tx, float ty, float tz)
Creates a translation-only pose.
float
qw()
Returns the W component of this pose's rotation quaternion.
float
qx()
Returns the X component of this pose's rotation quaternion.
float
qy()
Returns the Y component of this pose's rotation quaternion.
float
qz()
Returns the Z component of this pose's rotation quaternion.
float[]
rotateVector(float[] vectorIn)
Rotates the provided vector by the pose's rotation.
void
rotateVector(float[] vectorIn, int inOffset, float[] vectorOut, int outOffset)
Rotates the provided vector by the pose's rotation.
void
toMatrix(float[] dest, int offset)
Converts this pose to a model matrix, placing the matrix in column-major order into entries offset through offset+15 of the dest array.
String
toString()
Returns a human-readable representation of this pose.
float[]
transformPoint(float[] x)
Transforms the provided point by this pose.
void
transformPoint(float[] pointIn, int inOffset, float[] pointOut, int outOffset)
Transforms the provided point by the pose.
float
tx()
Returns the X component of this pose's translation.
float
ty()
Returns the Y component of this pose's translation.
float
tz()
Returns the Z component of this pose's translation.

Inherited Methods

Fields

IDENTITY

public static final Pose IDENTITY

The identity pose. toMatrix() will produce the identity matrix.

Public Constructors

Pose

public Pose(
  float[] translation,
  float[] rotation
)

Returns a new pose having the specified translation and rotation.

Formally, the translation and rotation of an Pose are defined as follows:

Translation is the position vector from the destination (usually world) coordinate space to the local coordinate frame, expressed in destination (world) coordinates.

Rotation is a quaternion following the Hamilton convention. Assume the destination and local coordinate spaces are initially aligned, and the local coordinate space is then rotated counter-clockwise about a unit-length axis, k, by an angle, theta. The quaternion parameters are hence:
x = k.x * sin(theta/2)
y = k.y * sin(theta/2)
z = k.z * sin(theta/2)
w = cos(theta/2)

The contents of both input arrays will be copied - later modifications will not affect the constructed Pose.

Details
Parameters
translation The translation component of the pose. The first three elements will be used as the X, Y, and Z components of the translation respectively.
rotation The rotation component of the pose as described above. Order is {x, y, z, w}.

Public Methods

compose

public Pose compose(
  Pose rhs
)

Returns the result of composing this with rhs. That is, transforming a point by the resulting pose will be equivalent to transforming that point first by rhs, and then transforming the result by this, or in code:

The result satisfies the following relationship: result.toMatrix() == this.toMatrix() * rhs.toMatrix().

Details
Parameters
rhs the pose to combine, as described above

extractRotation

public Pose extractRotation()

Returns a pose having the rotation of this pose but no translation.

extractTranslation

public Pose extractTranslation()

Returns a pose having the translation of this pose but no rotation.

getRotationQuaternion

public void getRotationQuaternion(
  float[] dest,
  int offset
)

Copies the rotation quaternion into a float array starting at offset. The values are written in the order {x, y, z, w}.

Details
Parameters
dest Array in which to write the quaternion at indices offset..offset+3.
offset Location within dest of the first element to write.

getRotationQuaternion

public float[] getRotationQuaternion()

Returns a float[4] containing the rotation component of this pose. The quaternion values are written in the order {x, y, z, w}.

getTransformedAxis

public float[] getTransformedAxis(
  int axis,
  float scale
)

Returns the transformed direction of a local axis.

Details
Parameters
axis the axis index 0=X, 1=Y, 2=Z
scale length of the resulting vector

getTransformedAxis

public void getTransformedAxis(
  int axis,
  float scale,
  float[] dest,
  int offset
)

Computes the transformed direction of a local axis, outputting into a float array.

Details
Parameters
axis the axis index 0=X, 1=Y, 2=Z
scale length of the resulting vector
dest destination array
offset index of the first element to set

getTranslation

public float[] getTranslation()

Returns a float[3] containing the translation component of this pose.

getTranslation

public void getTranslation(
  float[] dest,
  int offset
)

Copies the translation vector into a float array starting at offset.

Details
Parameters
dest Array in which to write the translation at indices offset..offset+2.
offset Location within dest of the first element to write.

getXAxis

public float[] getXAxis()

Returns a 3-element array containing the direction of the transformed X axis.

getYAxis

public float[] getYAxis()

Returns a 3-element array containing the direction of the transformed Y axis.

getZAxis

public float[] getZAxis()

Returns a 3-element array containing the direction of the transformed Z axis.

inverse

public Pose inverse()

Returns a pose that performs the opposite transformation.

pose.compose(pose.inverse()) will, allowing for floating point precision errors, produce an identity pose.

makeInterpolated

public static Pose makeInterpolated(
  Pose a,
  Pose b,
  float t
)

Returns a new pose that blends between two input poses. Linear and spherical-linear interpolation are performed on the translation and rotation respectively.

Rotation interpolation always takes the short path, negating the components of b's rotation if the result is more similar to a's rotation. As a result, while the resulting transformation will approach b's transformation as t approaches 1, the numerical representation as a quaternion may not.

The returned value is equal to a when t == 0, and equal to b when t == 1. Values of t outside the range [0, 1] will result in overshoot of the transformation, though correct operation well outside that range is not guaranteed.

Details
Parameters
a The pose to return when t == 0
b The pose to return when t == 1
t the blending factor

makeRotation

public static Pose makeRotation(
  float[] quaternion
)

Creates a rotation-only pose. See Pose(float[], float[]) for details of the quaternion definition.

Details
Parameters
quaternion Components of the rotation quaternion in the order {x, y, z, w}

makeRotation

public static Pose makeRotation(
  float x,
  float y,
  float z,
  float w
)

Creates a rotation-only pose. See Pose(float[], float[]) for details of the quaternion definition.

Details
Parameters
x sin(theta/2)*rx
y sin(theta/2)*ry
z sin(theta/2)*rz
w cos(theta/2)

makeTranslation

public static Pose makeTranslation(
  float[] translation
)

Creates a translation-only pose. See Pose(float[], float[]) for definition of the translation.

Details
Parameters
translation Components of the translation vector in the order {x, y, z}

makeTranslation

public static Pose makeTranslation(
  float tx,
  float ty,
  float tz
)

Creates a translation-only pose. See Pose(float[], float[]) for definition of the translation.

Details
Parameters
tx X component of the translation.
ty Y component of the translation.
tz Z component of the translation.

qw

public float qw()

Returns the W component of this pose's rotation quaternion.

Details
See Also

qx

public float qx()

Returns the X component of this pose's rotation quaternion.

Details
See Also

qy

public float qy()

Returns the Y component of this pose's rotation quaternion.

Details
See Also

qz

public float qz()

Returns the Z component of this pose's rotation quaternion.

Details
See Also

rotateVector

public float[] rotateVector(
  float[] vectorIn
)

Rotates the provided vector by the pose's rotation. Does not apply translation.

Equivalent to taking the rotation matrix portion of this pose and doing: out = R * v.

Details
Parameters
vectorIn A float[3] containing the input vector.
Returns A float[3] containing the rotated vector.

rotateVector

public void rotateVector(
  float[] vectorIn,
  int inOffset,
  float[] vectorOut,
  int outOffset
)

Rotates the provided vector by the pose's rotation. Does not apply translation. In-place operation is allowed.

Equivalent to taking the rotation matrix portion of this pose and doing: out = R * v.

Details
Parameters
vectorIn Array containing the input vector.
inOffset Location within vectorIn of the first element to read.
vectorOut Array in which to write the output vector.
outOffset Location within vectorOut of the first element to write.

toMatrix

public void toMatrix(
  float[] dest,
  int offset
)

Converts this pose to a model matrix, placing the matrix in column-major order into entries offset through offset+15 of the dest array.

Details
Parameters
dest Array in which to write the matrix at indices offset..offset+15
offset Location within dest of the first element to write

toString

public String toString()

Returns a human-readable representation of this pose.

transformPoint

public float[] transformPoint(
  float[] x
)

Transforms the provided point by this pose.

Letting x = point_local, this is semantically equivalent to
point_world = this.toMatrix() * point_local

Details
Parameters
x A 3-element array containing the point to transform.
Returns A newly-allocated 3-element array containing the transformed point.

transformPoint

public void transformPoint(
  float[] pointIn,
  int inOffset,
  float[] pointOut,
  int outOffset
)

Transforms the provided point by the pose. In-place operation is allowed. Applies the pose's transformation to pointIn[inOffset..inOffset+2], placing the result in pointOut[outOffset..outOffset+2]

Equivalent to taking the matrix M from toMatrix and doing out = M * in.

Details
Parameters
pointIn Array containing the input point.
inOffset Location within pointIn of the first element to read.
pointOut Array in which to write the output point.
outOffset Location within pointOut of the first element to write.

tx

public float tx()

Returns the X component of this pose's translation.

ty

public float ty()

Returns the Y component of this pose's translation.

tz

public float tz()

Returns the Z component of this pose's translation.