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

From class java.lang.Object

Object	clone()
boolean	equals(Object arg0)
void	finalize()
final Class<?>	getClass()
int	hashCode()
final void	notify()
final void	notifyAll()
String	toString()
final void	wait(long arg0, int arg1)
final void	wait(long arg0)
final void	wait()

Fields

public static final Pose IDENTITY

IDENTITY

public static final Pose IDENTITY

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

Public Constructors

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

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

public Pose compose (Pose rhs)

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

public Pose extractRotation ()

extractRotation

public Pose extractRotation()

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

public Pose extractTranslation ()

extractTranslation

public Pose extractTranslation()

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

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

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.

public float[] getRotationQuaternion ()

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}.

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

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

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

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

public float[] getTranslation ()

getTranslation

public float[] getTranslation()

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

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

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.

public float[] getXAxis ()

getXAxis

public float[] getXAxis()

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

public float[] getYAxis ()

getYAxis

public float[] getYAxis()

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

public float[] getZAxis ()

getZAxis

public float[] getZAxis()

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

public Pose inverse ()

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.

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

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

public static Pose makeRotation (float[] quaternion)

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}

public static Pose makeRotation (float x, float y, float z, float 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)

public static Pose makeTranslation (float[] translation)

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}

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

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.

public float qw ()

qw

public float qw()

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

Details
See Also	Pose(float[], float[])

public float qx ()

qx

public float qx()

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

Details
See Also	Pose(float[], float[])

public float qy ()

qy

public float qy()

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

Details
See Also	Pose(float[], float[])

public float qz ()

qz

public float qz()

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

Details
See Also	Pose(float[], float[])

public float[] rotateVector (float[] vectorIn)

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.

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

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.

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

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

public String toString ()

toString

public String toString()

Returns a human-readable representation of this pose.

public float[] transformPoint (float[] x)

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.

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

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.

public float tx ()

tx

public float tx()

Returns the X component of this pose's translation.

public float ty ()

ty

public float ty()

Returns the Y component of this pose's translation.

public float tz ()

tz

public float tz()

Returns the Z component of this pose's translation.