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 | |
| 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 | |
| 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
Public Constructors
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.
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)
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().
Parameters
| rhs | the pose to combine, as described above |
|---|
public Pose extractTranslation ()
Returns a pose having the translation of this pose but no rotation.
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}.
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 ()
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)
Returns the transformed direction of a local axis.
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)
Computes the transformed direction of a local axis, outputting into a float array.
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 ()
Returns a float[3] containing the translation component of this pose.
public void getTranslation (float[] dest, int offset)
Copies the translation vector into a float array starting at offset.
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 ()
Returns a 3-element array containing the direction of the transformed X axis.
public float[] getYAxis ()
Returns a 3-element array containing the direction of the transformed Y axis.
public float[] getZAxis ()
Returns a 3-element array containing the direction of the transformed Z axis.
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)
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.
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)
Creates a rotation-only pose. See Pose(float[], float[]) for details of the quaternion
definition.
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)
Creates a rotation-only pose. See Pose(float[], float[]) for details of the quaternion
definition.
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)
Creates a translation-only pose. See Pose(float[], float[]) for definition of the
translation.
Parameters
| translation | Components of the translation vector in the order {x, y, z} |
|---|
public static Pose makeTranslation (float tx, float ty, float tz)
Creates a translation-only pose. See Pose(float[], float[]) for definition of the
translation.
Parameters
| tx | X component of the translation. |
|---|---|
| ty | Y component of the translation. |
| tz | Z component of the translation. |
public float qw ()
Returns the W component of this pose's rotation quaternion.
See Also
public float qx ()
Returns the X component of this pose's rotation quaternion.
See Also
public float qy ()
Returns the Y component of this pose's rotation quaternion.
See Also
public float qz ()
Returns the Z component of this pose's rotation quaternion.
See Also
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.
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)
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.
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)
Converts this pose to a model matrix, placing the matrix in column-major order into entries
offset through offset+15 of the dest array.
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 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
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)
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.
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 ()
Returns the X component of this pose's translation.
public float ty ()
Returns the Y component of this pose's translation.
public float tz ()
Returns the Z component of this pose's translation.