Package us.ihmc.euclid.orientation.interfaces

Interface Orientation3DBasics

All Superinterfaces:

Orientation3DReadOnly

All Known Subinterfaces:

AxisAngleBasics, QuaternionBasics

All Known Implementing Classes:

AxisAngle, AxisAngle32, Quaternion, Quaternion32, RotationMatrix

public interface Orientation3DBasics
extends Orientation3DReadOnly

Write and read interface for a 3D orientation.

Even though the representation used is unknown at this level of abstraction, this interface allows to enforce a minimum set of features that all representations of an orientation should provide, such as appending and prepending orientations to each other.

Author:

Sylvain Bertrand

Field Summary

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

ORIENTATION_2D_EPSILON

Method Summary

Modifier and Type	Method	Description
void	append(Orientation3DReadOnly orientation)	Appends the given orientation to this orientation.
default void	appendInvertBoth(Orientation3DReadOnly orientation)	Inverts this and then appends the inverse of the given orientation to this orientation.
void	appendInvertOther(Orientation3DReadOnly orientation)	Appends the inverse of the given orientation to this orientation.
default void	appendInvertThis(Orientation3DReadOnly orientation)	Inverts this and then appends the given orientation.
void	appendPitchRotation(double pitch)	Appends a rotation R(pitch) about the y-axis to this orientation.
void	appendRollRotation(double roll)	Appends a rotation R(roll) about the x-axis to this orientation.
void	appendYawRotation(double yaw)	Appends a rotation R(yaw) about the z-axis to this orientation.
void	invert()	Inverses this orientation.
void	normalize()	For representations of orientations with more variables than degrees of freedom, some or all of the variables are constrained.
void	prepend(Orientation3DReadOnly orientation)	Prepends the given orientation to this orientation.
default void	prependInvertBoth(Orientation3DReadOnly orientation)	Inverts this and then prepends the inverse of the given orientation to this orientation.
void	prependInvertOther(Orientation3DReadOnly orientation)	Prepends the inverse of the given orientation to this orientation.
default void	prependInvertThis(Orientation3DReadOnly orientation)	Inverts this and then prepends the given orientation.
void	prependPitchRotation(double pitch)	Prepends a rotation R(pitch) about the y-axis to this orientation.
void	prependRollRotation(double roll)	Appends a rotation R(roll) about the x-axis to this orientation.
void	prependYawRotation(double yaw)	Prepends a rotation R(yaw) about the z-axis to this orientation.
void	set(Orientation3DReadOnly orientation3DReadOnly)	Converts, if necessary, and sets this orientation to represents the same orientation as orientation3DReadOnly.
default void	setAndInvert(Orientation3DReadOnly orientation3DReadOnly)	Sets this orientation to represent the inverse of the given orientation3DReadOnly.
default void	setAndNormalize(Orientation3DReadOnly orientation3DReadOnly)	Converts, if necessary, and sets this orientation to represents the same orientation as orientation3DReadOnly and then normalize this orientation.
void	setAxisAngle(double x, double y, double z, double angle)	Sets this orientation to represents the same orientation as an axis-angle given its 4 components.
default void	setEuler(double rotX, double rotY, double rotZ)	Sets this orientation to represent the same orientation as the given Euler angles.
default void	setEuler(Vector3DReadOnly eulerAngles)	Sets this orientation to represent the same orientation as the given Euler angles eulerAngles.
void	setQuaternion(double x, double y, double z, double s)	Sets this orientation to represents the same orientation as a quaternion given its 4 components.
void	setRotationMatrix(double m00, double m01, double m02, double m10, double m11, double m12, double m20, double m21, double m22)	Sets this orientation to represents the same orientation as a rotation matrix given its 9 components.
void	setRotationVector(double x, double y, double z)	Sets this orientation to represents the same orientation as a rotation vector given its 3 components.
default void	setRotationVector(Vector3DReadOnly rotationVector)	Sets this orientation to represent the same orientation as the given rotationVector.
default void	setYawPitchRoll(double[] yawPitchRoll)	Sets this orientation to represents the same orientation as a yaw-pitch-roll representation.
void	setYawPitchRoll(double yaw, double pitch, double roll)	Sets this orientation to represents the same orientation as a yaw-pitch-roll representation.

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

addTransform, addTransform, checkIfOrientation2D, checkIfOrientation2D, get, get, get, getEuler, getPitch, getRoll, getRotationVector, getYaw, getYawPitchRoll, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, inverseTransform, isOrientation2D, isOrientation2D, toStringAsYawPitchRoll, transform, transform, transform, transform, transform, transform, transform, transform, transform, transform, transform, transform, transform, transform, transform, transform

Method Detail

normalize

void normalize()

For representations of orientations with more variables than degrees of freedom, some or all of the variables are constrained. This method updates the variables considering this constraint.

The actual implementation of this function strongly depends on the type of orientation.

invert

void invert()

Inverses this orientation.

If this orientation describes the orientation of a coordinate system A with respect to a coordinate system B, after this method, the orientation will describe the orientation of B with respect to A.

Note that appending or prepending an orientation with its inverse will result into a "zero" orientation.

setRotationMatrix

void setRotationMatrix(double m00,
                       double m01,
                       double m02,
                       double m10,
                       double m11,
                       double m12,
                       double m20,
                       double m21,
                       double m22)

Sets this orientation to represents the same orientation as a rotation matrix given its 9 components.

Parameters:

m00 - the new 1st row 1st column coefficient of the rotation matrix.

m01 - the new 1st row 2nd column coefficient of the rotation matrix.

m02 - the new 1st row 3rd column coefficient of the rotation matrix.

m10 - the new 2nd row 1st column coefficient of the rotation matrix.

m11 - the new 2nd row 2nd column coefficient of the rotation matrix.

m12 - the new 2nd row 3rd column coefficient of the rotation matrix.

m20 - the new 3rd row 1st column coefficient of the rotation matrix.

m21 - the new 3rd row 2nd column coefficient of the rotation matrix.

m22 - the new 3rd row 3rd column coefficient of the rotation matrix.

setAxisAngle

void setAxisAngle(double x,
                  double y,
                  double z,
                  double angle)

Sets this orientation to represents the same orientation as an axis-angle given its 4 components.

Parameters:

x - x-component of the axis part of the axis-angle.

y - y-component of the axis part of the axis-angle.

z - z-component of the axis part of the axis-angle.

angle - the angle part of the axis-angle.

setQuaternion

void setQuaternion(double x,
                   double y,
                   double z,
                   double s)

Sets this orientation to represents the same orientation as a quaternion given its 4 components.

Parameters:

x - the x-component of the quaternion.

y - the y-component of the quaternion.

z - the z-component of the quaternion.

s - the s-component of the quaternion.

setRotationVector

void setRotationVector(double x,
                       double y,
                       double z)

Sets this orientation to represents the same orientation as a rotation vector given its 3 components.

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.

Parameters:

x - the x-component of the rotation vector.

y - the y-component of the rotation vector.

z - the z-component of the rotation vector.

setYawPitchRoll

void setYawPitchRoll(double yaw,
                     double pitch,
                     double roll)

Sets this orientation to represents the same orientation as 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) /
 

Parameters:

yaw - the angle to rotate about the z-axis.

pitch - the angle to rotate about the y-axis.

roll - the angle to rotate about the x-axis.

setYawPitchRoll

default void setYawPitchRoll(double[] yawPitchRoll)

Sets this orientation to represents the same orientation as 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) /
 

Parameters:

yawPitchRoll - array containing the yaw-pitch-roll angles. Not modified.

setRotationVector

default void setRotationVector(Vector3DReadOnly rotationVector)

Sets this orientation to represent the same orientation as the given rotationVector.

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.

Parameters:

rotationVector - the rotation vector to set this orientation. Not modified.

setEuler

default void setEuler(Vector3DReadOnly eulerAngles)

Sets this orientation to represent the same orientation as the given Euler angles eulerAngles.

This is equivalent to setYawPitchRoll(double, double, double) with yaw = eulerAngles.getZ(), pitch = eulerAngles.getY(), and roll = eulerAngles.getX().

Parameters:

eulerAngles - the Euler angles to copy the orientation from. Not modified.

setEuler

default void setEuler(double rotX,
                      double rotY,
                      double rotZ)

Sets this orientation to represent the same orientation as the given Euler angles.

This is equivalent to setYawPitchRoll(double, double, double) with yaw = rotZ, pitch = rotY, and roll = rotX.

Parameters:

rotX - the angle to rotate about the x-axis.

rotY - the angle to rotate about the y-axis.

rotZ - the angle to rotate about the z-axis.

set

void set(Orientation3DReadOnly orientation3DReadOnly)

Converts, if necessary, and sets this orientation to represents the same orientation as orientation3DReadOnly.

Parameters:

orientation3DReadOnly - the new orientation. Not modified.

setAndNormalize

default void setAndNormalize(Orientation3DReadOnly orientation3DReadOnly)

Converts, if necessary, and sets this orientation to represents the same orientation as orientation3DReadOnly and then normalize this orientation.

Parameters:

orientation3DReadOnly - the new orientation. Not modified.

setAndInvert

default void setAndInvert(Orientation3DReadOnly orientation3DReadOnly)

Sets this orientation to represent the inverse of the given orientation3DReadOnly.

Parameters:

orientation3DReadOnly - the new orientation. Not modified.

append

void append(Orientation3DReadOnly orientation)

Appends the given orientation to this orientation.

Let's consider the following:

• three coordinate systems A, B, and C.
• this represents the orientation of B relative to A.
• orientation represents the orientation of C relative to B.

The result of calling this method will be that this, represents the orientation of C relative to A.

Appending orientations is in some way similar to summing translations. However, while the addition for translation is commutative, the "append" operation on orientation is NOT commutative. Such that: this.append(orientation) ≠ orientation.append(this).

Parameters:

orientation - the orientation to append to this orientation. Not modified.

appendInvertOther

void appendInvertOther(Orientation3DReadOnly orientation)

Appends the inverse of the given orientation to this orientation.

Let's consider the following:

• three coordinate systems A, B, and C.
• this represents the orientation of B relative to A.
• orientation represents the orientation of B relative to C.

The result of calling this method will be that this, represents the orientation of C relative to A.

This operation is in some way similar to subtracting translations, as in this operation can be seen as subtracting orientation to this.

Parameters:

orientation - the orientation which the inverse is to be appended to this orientation. Not modified.

appendInvertThis

default void appendInvertThis(Orientation3DReadOnly orientation)

Inverts this and then appends the given orientation.

Let's consider the following:

• three coordinate systems A, B, and C.
• this represents the orientation of A relative to B.
• orientation represents the orientation of C relative to B.

The result of calling this method will be that this, represents the orientation of C relative to A.

This operation is in some way similar to subtracting translations, as in this operation can be seen as subtracting this to orientation.

Parameters:

orientation - the orientation to append to the inverse of this orientation. Not modified.

appendInvertBoth

default void appendInvertBoth(Orientation3DReadOnly orientation)

Inverts this and then appends the inverse of the given orientation to this orientation.

Let's consider the following:

• three coordinate systems A, B, and C.
• this represents the orientation of A relative to B.
• orientation represents the orientation of B relative to C.

The result of calling this method will be that this, represents the orientation of C relative to A.

This operation is in some way similar to subtracting translations, as in this operation can be seen as subtracting orientation to this.

Parameters:

orientation - the orientation which the inverse is to be appended to this orientation. Not modified.

appendYawRotation

void appendYawRotation(double yaw)

Appends a rotation R(yaw) about the z-axis to this orientation.

          / cos(yaw) -sin(yaw) 0 \
 R(yaw) = | sin(yaw)  cos(yaw) 0 |
          \    0         0     1 /
 

Note that the z-axis refers to the local coordinate system described by this orientation.

Parameters:

yaw - the angle to rotate about the z-axis.

appendPitchRotation

void appendPitchRotation(double pitch)

Appends a rotation R(pitch) about the y-axis to this orientation.

            /  cos(pitch) 0 sin(pitch) \
 R(pitch) = |      0      1     0      |
            \ -sin(pitch) 0 cos(pitch) /
 

Note that the y-axis refers to the local coordinate system described by this orientation.

Parameters:

pitch - the angle to rotate about the y-axis.

appendRollRotation

void appendRollRotation(double roll)

Appends a rotation R(roll) about the x-axis to this orientation.

           / 1     0          0     \
 R(roll) = | 0 cos(roll) -sin(roll) |
           \ 0 sin(roll)  cos(roll) /
 

Note that the x-axis refers to the local coordinate system described by this orientation.

Parameters:

roll - the angle to rotate about the x-axis.

prepend

void prepend(Orientation3DReadOnly orientation)

Prepends the given orientation to this orientation.

Let's consider the following:

• three coordinate systems A, B, and C.
• this represents the orientation of C relative to B.
• orientation represents the orientation of B relative to A.

The result of calling this method will be that this, represents the orientation of C relative to A.

Prepending orientations is in some way similar to summing translations. However, while the addition for translation is commutative, the "prepend" operation on orientation is NOT commutative. Such that: this.prepend(orientation) ≠ orientation.prepend(this).

Parameters:

orientation - the orientation to prepend to this orientation. Not modified.

prependInvertOther

void prependInvertOther(Orientation3DReadOnly orientation)

Prepends the inverse of the given orientation to this orientation.

Let's consider the following:

• three coordinate systems A, B, and C.
• this represents the orientation of B relative to C.
• orientation represents the orientation of B relative to A.

The result of calling this method will be that this, represents the orientation of C relative to A.

This operation is in some way similar to subtracting translations, as in this operation can be seen as subtracting orientation to this.

Parameters:

orientation - the orientation which the inverse is to be appended to this orientation. Not modified.

prependInvertThis

default void prependInvertThis(Orientation3DReadOnly orientation)

Inverts this and then prepends the given orientation.

Let's consider the following:

• three coordinate systems A, B, and C.
• this represents the orientation of C relative to B.
• orientation represents the orientation of A relative to B.

The result of calling this method will be that this, represents the orientation of C relative to A.

This operation is in some way similar to subtracting translations, as in this operation can be seen as subtracting this to orientation.

Parameters:

orientation - the orientation to append to the inverse of this orientation. Not modified.

prependInvertBoth

default void prependInvertBoth(Orientation3DReadOnly orientation)

Inverts this and then prepends the inverse of the given orientation to this orientation.

Let's consider the following:

• three coordinate systems A, B, and C.
• this represents the orientation of B relative to C.
• orientation represents the orientation of A relative to B.

The result of calling this method will be that this, represents the orientation of C relative to A.

This operation is in some way similar to subtracting translations, as in this operation can be seen as subtracting orientation to this.

Parameters:

orientation - the orientation which the inverse is to be appended to this orientation. Not modified.

prependYawRotation

void prependYawRotation(double yaw)

Prepends a rotation R(yaw) about the z-axis to this orientation.

          / cos(yaw) -sin(yaw) 0 \
 R(yaw) = | sin(yaw)  cos(yaw) 0 |
          \    0         0     1 /
 

Note that the z-axis refers to the base coordinate system in which this orientation is expressed.

Parameters:

yaw - the angle to rotate about the z-axis.

prependPitchRotation

void prependPitchRotation(double pitch)

Prepends a rotation R(pitch) about the y-axis to this orientation.

            /  cos(pitch) 0 sin(pitch) \
 R(pitch) = |      0      1     0      |
            \ -sin(pitch) 0 cos(pitch) /
 

Note that the y-axis refers to the base coordinate system in which this orientation is expressed.

Parameters:

pitch - the angle to rotate about the y-axis.

prependRollRotation

void prependRollRotation(double roll)

Appends a rotation R(roll) about the x-axis to this orientation.

           / 1     0          0     \
 R(roll) = | 0 cos(roll) -sin(roll) |
           \ 0 sin(roll)  cos(roll) /
 

Note that the x-axis refers to the base coordinate system in which this orientation is expressed.

Parameters:

roll - the angle to rotate about the x-axis.