QuaternionReadOnly (euclid-core 0.5.1 API)

All Superinterfaces:

Orientation3DReadOnly, Tuple4DReadOnly

All Known Subinterfaces:

QuaternionBasics

All Known Implementing Classes:

Quaternion, Quaternion32
```
public interface QuaternionReadOnly
extends Tuple4DReadOnly, Orientation3DReadOnly
```
Read-only interface for unit-quaternion used to represent 3D orientations.
When describing a 4D tuple, its 4 components are often gathered in two groups: the scalar part s and the vector part (x, y, z).

Note on the difference between applying a 3D transform on a quaternion and a 4D vector:
- When transformed by a homogeneous transformation matrix, a quaternion is only pre-multiplied by the rotation part of the transform, resulting in concatenating the orientations of the transform and the quaternion.
- When transformed by a homogeneous transformation matrix, a 4D vector scalar part s remains unchanged. The vector part (x, y, z) is scaled and rotated, and translated by s times the translation part of the transform. Note that for s = 0, a 4D vector behaves as a 3D vector, and for s = 1 it behaves as a 3D point.

Field Summary

Fields
Modifier and Type	Field and Description
`static double`	`EPS_UNITARY` Default tolerance used to verify that this quaternion is a unit-quaternion.
`static double`	`GEOMETRICALLY_EQUALS_THRESHOLD` Threshold used to trigger a more expensive comparison between two quaternions.

Fields inherited from interface us.ihmc.euclid.orientation.interfaces.Orientation3DReadOnly
ORIENTATION_2D_EPSILON

Method Summary

All Methods Instance Methods Default Methods Deprecated Methods
Modifier and Type	Method and Description
`default void`	`addTransform(Tuple3DReadOnly tupleOriginal, Tuple3DBasics tupleTransformed)` Transforms the tuple `tupleOriginal` by this orientation and adds the result to `tupleTransformed`.
`default void`	`checkIfIsZOnly(double epsilon)` Deprecated. Use `Orientation3DReadOnly.checkIfOrientation2D(double)` instead
`default void`	`checkIfUnitary()` Asserts that this quaternion has a norm equal to 1+/-1.0E-7.
`default void`	`checkIfUnitary(double epsilon)` Asserts that this quaternion has a norm equal to 1+/-`epsilon`.
`default double`	`distance(QuaternionReadOnly other)` Computes and returns the distance from this quaternion to `other`.
`default double`	`distancePrecise(QuaternionReadOnly other)` Computes and returns the distance from this quaternion to `other`.
`default boolean`	`geometricallyEquals(QuaternionReadOnly other, double epsilon)` Tests if `this` and `other` represent the same orientation to an `epsilon`.
`default void`	`get(AxisAngleBasics axisAngleToPack)` Converts, if necessary, and packs this orientation into an axis-angle.
`default void`	`get(QuaternionBasics quaternionToPack)` Converts, if necessary, and packs this orientation in a quaternion.
`default void`	`get(RotationMatrix rotationMatrixToPack)` Converts, if necessary, and packs this orientation into a 3-by-3 rotation matrix.
`default double`	`getAngle()` Calculates and returns the angle of the rotation this quaternion represents.
`default void`	`getEuler(Tuple3DBasics eulerAnglesToPack)` Computes and packs the orientation described by this orientation as the Euler angles.
`default double`	`getPitch()` Computes and returns the pitch angle from the yaw-pitch-roll representation of this orientation.
`default double`	`getRoll()` Computes and returns the roll angle from the yaw-pitch-roll representation of this orientation.
`default void`	`getRotationVector(Vector3DBasics rotationVectorToPack)` Converts and packs this orientation in a 3D rotation vector.
`default double`	`getYaw()` Computes and returns the yaw angle from the yaw-pitch-roll representation of this orientation.
`default void`	`getYawPitchRoll(double[] yawPitchRollToPack)` Converts and packs this orientation in a yaw-pitch-roll representation.
`default void`	`inverseTransform(Matrix3DReadOnly matrixOriginal, Matrix3D matrixTransformed)` Performs the inverse of the transform to the matrix `matrixOriginal` by this orientation and stores the result in `matrixTransformed`.
`default void`	`inverseTransform(Tuple2DReadOnly tupleOriginal, Tuple2DBasics tupleTransformed, boolean checkIfOrientation2D)` Performs the inverse of the transform to the tuple `tupleOriginal` by this orientation and stores the result in `tupleTransformed`.
`default void`	`inverseTransform(Tuple3DReadOnly tupleOriginal, Tuple3DBasics tupleTransformed)` Performs the inverse of the transform to the tuple `tupleOriginal` by this orientation and stores the result in `tupleTransformed`.
`default void`	`inverseTransform(Vector4DReadOnly vectorOriginal, Vector4DBasics vectorTransformed)` Performs the inverse of the transform to the vector part, i.e.
`default boolean`	`isOrientation2D(double epsilon)` Tests if this orientation 3D actually represents a rotation strictly around the z-axis.
`default boolean`	`isUnitary(double epsilon)` Tests if this quaternion has a norm equal to 1+/-`epsilon`.
`default boolean`	`isZOnly(double epsilon)` Deprecated. Use `isOrientation2D(double)` instead
`default double`	`norm()` Efficiently compute the norm of this quaternion.
`default void`	`transform(Matrix3DReadOnly matrixOriginal, Matrix3D matrixTransformed)` Transforms the matrix `matrixOriginal` by this orientation and stores the result in `matrixTransformed`.
`default void`	`transform(Tuple2DReadOnly tupleOriginal, Tuple2DBasics tupleTransformed, boolean checkIfOrientation2D)` Transforms the tuple `tupleOriginal` by this orientation and stores the result in `tupleTransformed`.
`default void`	`transform(Tuple3DReadOnly tupleOriginal, Tuple3DBasics tupleTransformed)` Transforms the tuple `tupleOriginal` by this orientation and stores the result in `tupleTransformed`.
`default void`	`transform(Vector4DReadOnly vectorOriginal, Vector4DBasics vectorTransformed)` Transforms the vector part, i.e.

Methods inherited from interface us.ihmc.euclid.tuple4D.interfaces.Tuple4DReadOnly
containsNaN, dot, epsilonEquals, equals, get, get, get, get, get, get, get, getElement, getElement32, getS, getS32, getX, getX32, getY, getY32, getZ, getZ32, normSquared

Methods inherited from interface us.ihmc.euclid.orientation.interfaces.Orientation3DReadOnly
addTransform, checkIfOrientation2D, checkIfOrientation2D, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, isOrientation2D, toStringAsYawPitchRoll, transform, transform, transform, transform, transform, transform, transform, transform, transform, transform, transform, transform

- Field Detail
  - GEOMETRICALLY_EQUALS_THRESHOLD
```
static final double GEOMETRICALLY_EQUALS_THRESHOLD
```
    Threshold used to trigger a more expensive comparison between two quaternions.
    
    See Also:
    
    Constant Field Values
  - EPS_UNITARY
```
static final double EPS_UNITARY
```
    Default tolerance used to verify that this quaternion is a unit-quaternion.
    
    See Also:
    
    Constant Field Values
- Method Detail
  - isUnitary
```
default boolean isUnitary(double epsilon)
```
    Tests if this quaternion has a norm equal to 1+/-epsilon.
    
    Parameters:
    
    epsilon - the tolerance to use.
    
    Returns:
    
    true if this quaternion is a proper unit-quaternion, false otherwise.
  - isZOnly
```
@Deprecated
default boolean isZOnly(double epsilon)
```
    Deprecated. Use isOrientation2D(double) instead
    
    Tests if this quaternion represents a rotation around the z-axis.
    This is commonly used to test if the quaternion can be used to transform 2D geometry object.
    
    Parameters:
    
    epsilon - the tolerance to use.
    
    Returns:
    
    true if this quaternion represents a rotation around the z-axis, false otherwise.
  - isOrientation2D
```
default boolean isOrientation2D(double epsilon)
```
    Tests if this orientation 3D actually represents a rotation strictly around the z-axis.
    This is commonly used to test if this orientation can be used to transform 2D geometry object.
    
    The implementation of this test depends on the type of representation used for this orientation.
    
    A quaternion is an orientation 2D if:
    - the absolute value of the x component is less than epsilon.
    - the absolute value of the y component is less than epsilon.
    Specified by:
    
    isOrientation2D in interface Orientation3DReadOnly
    
    Parameters:
    
    epsilon - the tolerance to use.
    
    Returns:
    
    true if this orientation represents a 2D orientation in the XY-plane, false otherwise.
  - checkIfUnitary
```
default void checkIfUnitary()
```
    Asserts that this quaternion has a norm equal to 1+/-1.0E-7.
    
    Parameters:
    
    epsilon - the tolerance to use.
    
    Throws:
    
    java.lang.RuntimeException - if this quaternion is not a proper unit-quaternion.
  - checkIfUnitary
```
default void checkIfUnitary(double epsilon)
```
    Asserts that this quaternion has a norm equal to 1+/-epsilon.
    
    Parameters:
    
    epsilon - the tolerance to use.
    
    Throws:
    
    java.lang.RuntimeException - if this quaternion is not a proper unit-quaternion.
  - checkIfIsZOnly
```
@Deprecated
default void checkIfIsZOnly(double epsilon)
```
    Deprecated. Use Orientation3DReadOnly.checkIfOrientation2D(double) instead
    
    Asserts that this quaternion represents a rotation around the z-axis.
    This is commonly used to test if the quaternion can be used to transform 2D geometry object.
    
    Parameters:
    
    epsilon - the tolerance to use.
    
    Throws:
    
    NotAMatrix2DException - if this quaternion does not represent a rotation around the z-axis.
  - norm
```
default double norm()
```
    Efficiently compute the norm of this quaternion.
    
    Specified by:
    
    norm in interface Tuple4DReadOnly
    
    Returns:
    
    the norm's value of this tuple.
  - distance
```
default double distance(QuaternionReadOnly other)
```
    Computes and returns the distance from this quaternion to other.
    
    Parameters:
    
    other - the other quaternion to measure the distance. Not modified.
    
    Returns:
    
    the angle representing the distance between the two quaternions. It is contained in [0, 2pi]
  - distancePrecise
```
default double distancePrecise(QuaternionReadOnly other)
```
    Computes and returns the distance from this quaternion to other.
    This method is equivalent to distance(QuaternionReadOnly) but is more accurate when computing the distance between two quaternions that are very close. Note that it is also more expensive.
    
    Parameters:
    
    other - the other quaternion to measure the distance. Not modified.
    
    Returns:
    
    the angle representing the distance between the two quaternions. It is contained in [0, 2pi]
  - getAngle
```
default double getAngle()
```
    Calculates and returns the angle of the rotation this quaternion represents.
    
    Returns:
    
    the angle ∈ [-2pi;2pi].
  - get
```
default void get(RotationMatrix rotationMatrixToPack)
```
    Converts, if necessary, and packs this orientation into a 3-by-3 rotation matrix.
    
    Specified by:
    
    get in interface Orientation3DReadOnly
    
    Parameters:
    
    rotationMatrixToPack - the rotation matrix into which this orientation is to be stored. Modified.
  - get
```
default void get(AxisAngleBasics axisAngleToPack)
```
    Converts, if necessary, and packs this orientation into an axis-angle.
    
    Specified by:
    
    get in interface Orientation3DReadOnly
    
    Parameters:
    
    axisAngleToPack - the axis-angle into which this orientation is to be stored. Modified.
  - get
```
default void get(QuaternionBasics quaternionToPack)
```
    Converts, if necessary, and packs this orientation in a quaternion.
    
    Specified by:
    
    get in interface Orientation3DReadOnly
    
    Parameters:
    
    quaternionToPack - the quaternion into which this orientation is to be stored. Modified.
  - getRotationVector
```
default void getRotationVector(Vector3DBasics rotationVectorToPack)
```
    Converts and packs this orientation in a 3D rotation vector.
    WARNING: a rotation vector is different from a yaw-pitch-roll or Euler angles representation. A rotation vector is equivalent to the axis of an axis-angle that is multiplied by the angle of the same axis-angle.
    
    Specified by:
    
    getRotationVector in interface Orientation3DReadOnly
    
    Parameters:
    
    rotationVectorToPack - the rotation vector in which this orientation is to be stored. Modified.
  - getYawPitchRoll
```
default void getYawPitchRoll(double[] yawPitchRollToPack)
```
    Converts and packs this orientation in a yaw-pitch-roll representation.
    WARNING: the Euler angles or yaw-pitch-roll representation is sensitive to gimbal lock and is sometimes undefined.
    
    The yaw-pitch-roll representation describes a 3D orientation as a succession of three rotations around three axes:
    1. yaw: rotation around the z-axis,
    2. pitch: rotation around the y-axis,
    3. roll: rotation around the x-axis.
    As an example, a rotation matrix can be computed from a yaw-pitch-roll representation as follows:
```
     / cos(yaw) -sin(yaw) 0 \   /  cos(pitch) 0 sin(pitch) \   / 1     0          0     \
 R = | sin(yaw)  cos(yaw) 0 | * |      0      1     0      | * | 0 cos(roll) -sin(roll) |
     \    0         0     1 /   \ -sin(pitch) 0 cos(pitch) /   \ 0 sin(roll)  cos(roll) /
 
```
    Specified by:
    
    getYawPitchRoll in interface Orientation3DReadOnly
    
    Parameters:
    
    yawPitchRollToPack - the array in which the yaw-pitch-roll angles are stored. Modified.
  - getEuler
```
default void getEuler(Tuple3DBasics eulerAnglesToPack)
```
    Computes and packs the orientation described by this orientation as the Euler angles.
    WARNING: the Euler angles or yaw-pitch-roll representation is sensitive to gimbal lock and is sometimes undefined.
    
    Specified by:
    
    getEuler in interface Orientation3DReadOnly
    
    Parameters:
    
    eulerAnglesToPack - the tuple in which the Euler angles are stored. Modified.
  - getYaw
```
default double getYaw()
```
    Computes and returns the yaw angle from the yaw-pitch-roll representation of this orientation.
    WARNING: the Euler angles or yaw-pitch-roll representation is sensitive to gimbal lock and is sometimes undefined.
    
    Specified by:
    
    getYaw in interface Orientation3DReadOnly
    
    Returns:
    
    the yaw angle around the z-axis.
  - getPitch
```
default double getPitch()
```
    Computes and returns the pitch angle from the yaw-pitch-roll representation of this orientation.
    WARNING: the Euler angles or yaw-pitch-roll representation is sensitive to gimbal lock and is sometimes undefined.
    
    Specified by:
    
    getPitch in interface Orientation3DReadOnly
    
    Returns:
    
    the pitch angle around the y-axis.
  - getRoll
```
default double getRoll()
```
    Computes and returns the roll angle from the yaw-pitch-roll representation of this orientation.
    WARNING: the Euler angles or yaw-pitch-roll representation is sensitive to gimbal lock and is sometimes undefined.
    
    Specified by:
    
    getRoll in interface Orientation3DReadOnly
    
    Returns:
    
    the roll angle around the x-axis.
  - transform
```
default void transform(Tuple3DReadOnly tupleOriginal,
                       Tuple3DBasics tupleTransformed)
```
    Transforms the tuple tupleOriginal by this orientation and stores the result in tupleTransformed.
    If the given tuple is expressed in the local frame described by this orientation, then the tuple is transformed such that it is, after this method is called, expressed in the base frame in which this orientation is expressed.
    
    Specified by:
    
    transform in interface Orientation3DReadOnly
    
    Parameters:
    
    tupleOriginal - the original value of the tuple to be transformed. Not modified.
    
    tupleTransformed - the result of the original tuple after transformation. Modified.
  - addTransform
```
default void addTransform(Tuple3DReadOnly tupleOriginal,
                          Tuple3DBasics tupleTransformed)
```
    Transforms the tuple tupleOriginal by this orientation and adds the result to tupleTransformed.
    If the given tuple is expressed in the local frame described by this orientation, then the tuple is transformed such that it is, after this method is called, expressed in the base frame in which this orientation is expressed.
    
    Specified by:
    
    addTransform in interface Orientation3DReadOnly
    
    Parameters:
    
    tupleOriginal - the original value of the tuple to be transformed. Not modified.
    
    tupleTransformed - the result of the original tuple after transformation. Modified.
  - transform
```
default void transform(Tuple2DReadOnly tupleOriginal,
                       Tuple2DBasics tupleTransformed,
                       boolean checkIfOrientation2D)
```
    Transforms the tuple tupleOriginal by this orientation and stores the result in tupleTransformed.
    If the given tuple is expressed in the local frame described by this orientation, then the tuple is transformed such that it is, after this method is called, expressed in the base frame in which this orientation is expressed.
    
    Specified by:
    
    transform in interface Orientation3DReadOnly
    
    Parameters:
    
    tupleOriginal - the original value of the tuple to be transformed. Not modified.
    
    tupleTransformed - the result of the original tuple after transformation. Modified.
    
    checkIfOrientation2D - whether this method should assert that this orientation represents a transformation in the XY plane.
  - transform
```
default void transform(Matrix3DReadOnly matrixOriginal,
                       Matrix3D matrixTransformed)
```
    Transforms the matrix matrixOriginal by this orientation and stores the result in matrixTransformed.
    If the given matrix is expressed in the local frame described by this orientation, then the matrix is transformed such that it is, after this method is called, expressed in the base frame in which this orientation is expressed.
    
    Specified by:
    
    transform in interface Orientation3DReadOnly
    
    Parameters:
    
    matrixOriginal - the original value of the matrix to be transformed. Not modified.
    
    matrixTransformed - the result of the original matrix after transformation. Modified.
  - transform
```
default void transform(Vector4DReadOnly vectorOriginal,
                       Vector4DBasics vectorTransformed)
```
    Transforms the vector part, i.e. the x, y, and z components, of the given vectorOriginal and stores the result in vectorTransformed.
    The scalar component s remains unaffected by this operation and is simply copied over.
    
    If the given vector part is expressed in the local frame described by this orientation, then the vector part is transformed such that it is, after this method is called, expressed in the base frame in which this orientation is expressed.
    
    Specified by:
    
    transform in interface Orientation3DReadOnly
    
    Parameters:
    
    vectorOriginal - the original value of the vector to be transformed. Not modified.
    
    vectorTransformed - the result of the original vector after transformation. Modified.
  - inverseTransform
```
default void inverseTransform(Tuple3DReadOnly tupleOriginal,
                              Tuple3DBasics tupleTransformed)
```
    Performs the inverse of the transform to the tuple tupleOriginal by this orientation and stores the result in tupleTransformed.
    If the given tuple is expressed in the base frame in which this orientation is expressed, then the tuple is transformed such that it is, after this method is called, expressed in the local frame described by this orientation.
    
    Specified by:
    
    inverseTransform in interface Orientation3DReadOnly
    
    Parameters:
    
    tupleOriginal - the original value of the tuple to be transformed. Not modified.
    
    tupleTransformed - the result of the original tuple after transformation. Modified.
  - inverseTransform
```
default void inverseTransform(Tuple2DReadOnly tupleOriginal,
                              Tuple2DBasics tupleTransformed,
                              boolean checkIfOrientation2D)
```
    Performs the inverse of the transform to the tuple tupleOriginal by this orientation and stores the result in tupleTransformed.
    If the given tuple is expressed in the base frame in which this orientation is expressed, then the tuple is transformed such that it is, after this method is called, expressed in the local frame described by this orientation.
    
    Specified by:
    
    inverseTransform in interface Orientation3DReadOnly
    
    Parameters:
    
    tupleOriginal - the original value of the tuple to be transformed. Not modified.
    
    tupleTransformed - the result of the original tuple after transformation. Modified.
    
    checkIfOrientation2D - whether this method should assert that this orientation represents a transformation in the XY plane.
  - inverseTransform
```
default void inverseTransform(Vector4DReadOnly vectorOriginal,
                              Vector4DBasics vectorTransformed)
```
    Performs the inverse of the transform to the vector part, i.e. the x, y, and z components, of the given vectorOriginal and stores the result in vectorTransformed.
    The scalar component s remains unaffected by this operation and is simply copied over.
    
    If the given vector part is expressed in the local frame described by this orientation, then the vector part is transformed such that it is, after this method is called, expressed in the base frame in which this orientation is expressed.
    
    Specified by:
    
    inverseTransform in interface Orientation3DReadOnly
    
    Parameters:
    
    vectorOriginal - the original value of the vector to be transformed. Not modified.
    
    vectorTransformed - the result of the original vector after transformation. Modified.
  - inverseTransform
```
default void inverseTransform(Matrix3DReadOnly matrixOriginal,
                              Matrix3D matrixTransformed)
```
    Performs the inverse of the transform to the matrix matrixOriginal by this orientation and stores the result in matrixTransformed.
    If the given matrix is expressed in the base frame in which this orientation is expressed, then the matrix is transformed such that it is, after this method is called, expressed in the local frame described by this orientation.
    
    Specified by:
    
    inverseTransform in interface Orientation3DReadOnly
    
    Parameters:
    
    matrixOriginal - the original value of the matrix to be transformed. Not modified.
    
    matrixTransformed - the result of the original matrix after transformation. Modified.
  - geometricallyEquals
```
default boolean geometricallyEquals(QuaternionReadOnly other,
                                    double epsilon)
```
    Tests if this and other represent the same orientation to an epsilon.
    Two quaternions are considered geometrically equal if the magnitude of their difference is less than or equal to epsilon.
    
    Note that two quaternions of opposite sign are considered equal, such that the two quaternions q1 = (x, y, z, s) and q2 = (-x, -y, -z, -s) are considered geometrically equal.
    
    Note that this.geometricallyEquals(other, epsilon) == true does not necessarily imply this.epsilonEquals(other, epsilon) and vice versa.
    
    Parameters:
    
    other - the other quaternion to compare against this. Not modified.
    
    epsilon - the maximum angle of the difference quaternion can be for the two quaternions to be considered equal.
    
    Returns:
    
    true if the two quaternions represent the same geometry, false otherwise.

Interface QuaternionReadOnly

Field Summary

Fields inherited from interface us.ihmc.euclid.orientation.interfaces.Orientation3DReadOnly

Method Summary

Methods inherited from interface us.ihmc.euclid.tuple4D.interfaces.Tuple4DReadOnly

Methods inherited from interface us.ihmc.euclid.orientation.interfaces.Orientation3DReadOnly

Field Detail

GEOMETRICALLY_EQUALS_THRESHOLD

EPS_UNITARY

Method Detail

isUnitary

isZOnly

isOrientation2D

checkIfUnitary

checkIfUnitary

checkIfIsZOnly

norm

distance

distancePrecise

getAngle

get

get

get

getRotationVector

getYawPitchRoll

getEuler

getYaw

getPitch

getRoll

transform

addTransform

transform

transform

transform

inverseTransform

inverseTransform

inverseTransform

inverseTransform

geometricallyEquals