Page Summary
-
A Pose represents an immutable rigid transformation from an object's local coordinate space to the world coordinate space in ARCore, similar to OpenGL model matrices.
-
Poses are defined by a quaternion rotation followed by a translation in a right-handed coordinate system with translation units in meters.
-
Due to ARCore's environment adjustments, the world coordinate space is unique to each frame, meaning numerical coordinates should only be used within the rendering frame they are retrieved.
-
If a position needs to persist beyond a single frame, an Anchor should be created or a position relative to an existing nearby Anchor should be used.
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 Anchor
s 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)
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
|
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
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.
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()
.
rhs
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}.
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.
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.
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.
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.
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.
quaternion
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.
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.
translation
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.
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.
public float qx ()
qx
public float qx ()
Returns the X component of this pose's rotation quaternion.
public float qy ()
qy
public float qy ()
Returns the Y component of this pose's rotation quaternion.
public float qz ()
qz
public float qz ()
Returns the Z component of this pose's rotation quaternion.
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.
vectorIn
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.
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.
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
x
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
.
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.
