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

Pose Stay organized with collections Save and categorize content based on your preferences.

World Coordinate Space

Fields

Public Constructors

Public Methods

Inherited Methods

Fields

Public Constructors

Public Methods

Pose