A rotation in a 3D coordinate frame, represented by a quaternion. More...

#include <frc/geometry/Rotation3d.h>

Public Member Functions
constexpr	Rotation3d ()=default
	Constructs a Rotation3d representing no rotation.

constexpr	Rotation3d (const Quaternion &q)
	Constructs a Rotation3d from a quaternion.

constexpr	Rotation3d (units::radian_t roll, units::radian_t pitch, units::radian_t yaw)
	Constructs a Rotation3d from extrinsic roll, pitch, and yaw.

constexpr	Rotation3d (const Eigen::Vector3d &axis, units::radian_t angle)
	Constructs a Rotation3d with the given axis-angle representation.

constexpr	Rotation3d (const Eigen::Vector3d &rvec)
	Constructs a Rotation3d with the given rotation vector representation.

constexpr	Rotation3d (const Eigen::Matrix3d &rotationMatrix)
	Constructs a Rotation3d from a rotation matrix.

constexpr	Rotation3d (const Eigen::Vector3d &initial, const Eigen::Vector3d &final)
	Constructs a Rotation3d that rotates the initial vector onto the final vector.

constexpr	Rotation3d (const Rotation2d &rotation)
	Constructs a 3D rotation from a 2D rotation in the X-Y plane.

constexpr Rotation3d	operator+ (const Rotation3d &other) const
	Adds two rotations together.

constexpr Rotation3d	operator- (const Rotation3d &other) const
	Subtracts the new rotation from the current rotation and returns the new rotation.

constexpr Rotation3d	operator- () const
	Takes the inverse of the current rotation.

constexpr Rotation3d	operator* (double scalar) const
	Multiplies the current rotation by a scalar.

constexpr Rotation3d	operator/ (double scalar) const
	Divides the current rotation by a scalar.

constexpr bool	operator== (const Rotation3d &other) const
	Checks equality between this Rotation3d and another object.

constexpr Rotation3d	RotateBy (const Rotation3d &other) const
	Adds the new rotation to the current rotation.

constexpr Rotation3d	RelativeTo (const Rotation3d &other) const
	Returns the current rotation relative to the given rotation.

constexpr const Quaternion &	GetQuaternion () const
	Returns the quaternion representation of the Rotation3d.

constexpr units::radian_t	X () const
	Returns the counterclockwise rotation angle around the X axis (roll).

constexpr units::radian_t	Y () const
	Returns the counterclockwise rotation angle around the Y axis (pitch).

constexpr units::radian_t	Z () const
	Returns the counterclockwise rotation angle around the Z axis (yaw).

constexpr Eigen::Vector3d	Axis () const
	Returns the axis in the axis-angle representation of this rotation.

constexpr units::radian_t	Angle () const
	Returns the angle in the axis-angle representation of this rotation.

constexpr Eigen::Matrix3d	ToMatrix () const
	Returns rotation matrix representation of this rotation.

constexpr Eigen::Vector3d	ToVector () const
	Returns rotation vector representation of this rotation.

constexpr Rotation2d	ToRotation2d () const
	Returns a Rotation2d representing this Rotation3d projected into the X-Y plane.

Detailed Description

A rotation in a 3D coordinate frame, represented by a quaternion.

Note that unlike 2D rotations, 3D rotations are not always commutative, so changing the order of rotations changes the result.

As an example of the order of rotations mattering, suppose we have a card that looks like this:

         ┌───┐        ┌───┐
         │ X │        │ x │
  Front: │ | │  Back: │ · │
         │ | │        │ · │
         └───┘        └───┘

If we rotate 90º clockwise around the axis into the page, then flip around the left/right axis, we get one result:

  ┌───┐
  │ X │   ┌───────┐   ┌───────┐
  │ | │ → │------X│ → │······x│
  │ | │   └───────┘   └───────┘
  └───┘

If we flip around the left/right axis, then rotate 90º clockwise around the axis into the page, we get a different result:

  ┌───┐   ┌───┐
  │ X │   │ · │   ┌───────┐
  │ | │ → │ · │ → │x······│
  │ | │   │ x │   └───────┘
  └───┘   └───┘

Because order matters for 3D rotations, we need to distinguish between extrinsic rotations and intrinsic rotations. Rotating extrinsically means rotating around the global axes, while rotating intrinsically means rotating from the perspective of the other rotation. A neat property is that applying a series of rotations extrinsically is the same as applying the same series in the opposite order intrinsically.

Constructor & Destructor Documentation

◆ Rotation3d() [1/8]

frc::Rotation3d::Rotation3d ( )

constexprdefault

Constructs a Rotation3d representing no rotation.

◆ Rotation3d() [2/8]

frc::Rotation3d::Rotation3d ( const Quaternion & q )

inlineexplicitconstexpr

Constructs a Rotation3d from a quaternion.

Parameters

q	The quaternion.

◆ Rotation3d() [3/8]

frc::Rotation3d::Rotation3d	(	units::radian_t	roll,
		units::radian_t	pitch,
		units::radian_t	yaw )

inlineconstexpr

Constructs a Rotation3d from extrinsic roll, pitch, and yaw.

Extrinsic rotations occur in that order around the axes in the fixed global frame rather than the body frame.

Angles are measured counterclockwise with the rotation axis pointing "out of the page". If you point your right thumb along the positive axis direction, your fingers curl in the direction of positive rotation.

Parameters

roll	The counterclockwise rotation angle around the X axis (roll).
pitch	The counterclockwise rotation angle around the Y axis (pitch).
yaw	The counterclockwise rotation angle around the Z axis (yaw).

◆ Rotation3d() [4/8]

frc::Rotation3d::Rotation3d	(	const Eigen::Vector3d &	axis,
		units::radian_t	angle )

inlineconstexpr

Constructs a Rotation3d with the given axis-angle representation.

The axis doesn't have to be normalized.

Parameters

axis	The rotation axis.
angle	The rotation around the axis.

◆ Rotation3d() [5/8]

frc::Rotation3d::Rotation3d ( const Eigen::Vector3d & rvec )

inlineexplicitconstexpr

Constructs a Rotation3d with the given rotation vector representation.

This representation is equivalent to axis-angle, where the normalized axis is multiplied by the rotation around the axis in radians.

Parameters

rvec	The rotation vector.

◆ Rotation3d() [6/8]

frc::Rotation3d::Rotation3d ( const Eigen::Matrix3d & rotationMatrix )

inlineexplicitconstexpr

Constructs a Rotation3d from a rotation matrix.

Parameters

rotationMatrix The rotation matrix.

Throws:: std::domain_error if the rotation matrix isn't special orthogonal.

◆ Rotation3d() [7/8]

frc::Rotation3d::Rotation3d	(	const Eigen::Vector3d &	initial,
		const Eigen::Vector3d &	final )

inlineconstexpr

Constructs a Rotation3d that rotates the initial vector onto the final vector.

This is useful for turning a 3D vector (final) into an orientation relative to a coordinate system vector (initial).

Parameters

initial	The initial vector.
final	The final vector.

◆ Rotation3d() [8/8]

frc::Rotation3d::Rotation3d ( const Rotation2d & rotation )

inlineexplicitconstexpr

Constructs a 3D rotation from a 2D rotation in the X-Y plane.

Parameters

rotation The 2D rotation.

See also: Pose3d(Pose2d); Transform3d(Transform2d)

Member Function Documentation

◆ Angle()

units::radian_t frc::Rotation3d::Angle ( ) const

inlineconstexpr

Returns the angle in the axis-angle representation of this rotation.

◆ Axis()

Eigen::Vector3d frc::Rotation3d::Axis ( ) const

inlineconstexpr

Returns the axis in the axis-angle representation of this rotation.

◆ GetQuaternion()

const Quaternion & frc::Rotation3d::GetQuaternion ( ) const

inlineconstexpr

Returns the quaternion representation of the Rotation3d.

◆ operator*()

Rotation3d frc::Rotation3d::operator* ( double scalar ) const

inlineconstexpr

Multiplies the current rotation by a scalar.

Parameters

scalar The scalar.

Returns: The new scaled Rotation3d.

◆ operator+()

Rotation3d frc::Rotation3d::operator+ ( const Rotation3d & other ) const

inlineconstexpr

Adds two rotations together.

The other rotation is applied extrinsically to this rotation, which is equivalent to this rotation being applied intrinsically to the other rotation. See the class comment for definitions of extrinsic and intrinsic rotations.

Note that a - b + b always equals a, but b + (a - b) sometimes doesn't. To apply a rotation offset, use either offset = -measurement + actual; newAngle = angle + offset; or offset = actual - measurement; newAngle = offset + angle;, depending on how the corrected angle needs to change as the input angle changes.

Parameters

other The rotation to add (applied extrinsically).

Returns: The sum of the two rotations.

◆ operator-() [1/2]

Rotation3d frc::Rotation3d::operator- ( ) const

inlineconstexpr

Takes the inverse of the current rotation.

Returns: The inverse of the current rotation.

◆ operator-() [2/2]

Rotation3d frc::Rotation3d::operator- ( const Rotation3d & other ) const

inlineconstexpr

Subtracts the new rotation from the current rotation and returns the new rotation.

The new rotation is from the perspective of the other rotation (like Pose3d::operator-), so it needs to be applied intrinsically. See the class comment for definitions of extrinsic and intrinsic rotations.

Note that a - b + b always equals a, but b + (a - b) sometimes doesn't. To apply a rotation offset, use either offset = -measurement + actual; newAngle = angle + offset; or offset = actual - measurement; newAngle = offset + angle;, depending on how the corrected angle needs to change as the input angle changes.

Parameters

other The rotation to subtract.

Returns: The difference between the two rotations, from the perspective of the other rotation.

◆ operator/()

Rotation3d frc::Rotation3d::operator/ ( double scalar ) const

inlineconstexpr

Divides the current rotation by a scalar.

Parameters

scalar The scalar.

Returns: The new scaled Rotation3d.

◆ operator==()

bool frc::Rotation3d::operator== ( const Rotation3d & other ) const

inlineconstexpr

Checks equality between this Rotation3d and another object.

◆ RelativeTo()

Rotation3d frc::Rotation3d::RelativeTo ( const Rotation3d & other ) const

inlineconstexpr

Returns the current rotation relative to the given rotation.

Because the result is in the perspective of the given rotation, it must be applied intrinsically. See the class comment for definitions of extrinsic and intrinsic rotations.

Parameters

other The rotation describing the orientation of the new coordinate frame that the current rotation will be converted into.

Returns: The current rotation relative to the new orientation of the coordinate frame.

◆ RotateBy()

Rotation3d frc::Rotation3d::RotateBy ( const Rotation3d & other ) const

inlineconstexpr

Adds the new rotation to the current rotation.

The other rotation is applied extrinsically, which means that it rotates around the global axes. For example, Rotation3d{90_deg, 0, 0}.RotateBy(Rotation3d{0, 45_deg, 0}) rotates by 90 degrees around the +X axis and then by 45 degrees around the global +Y axis. (This is equivalent to Rotation3d{90_deg, 45_deg, 0})

Parameters

other The extrinsic rotation to rotate by.

Returns: The new rotated Rotation3d.

◆ ToMatrix()

Eigen::Matrix3d frc::Rotation3d::ToMatrix ( ) const

inlineconstexpr

Returns rotation matrix representation of this rotation.

◆ ToRotation2d()

Rotation2d frc::Rotation3d::ToRotation2d ( ) const

inlineconstexpr

Returns a Rotation2d representing this Rotation3d projected into the X-Y plane.

◆ ToVector()

Eigen::Vector3d frc::Rotation3d::ToVector ( ) const

inlineconstexpr

Returns rotation vector representation of this rotation.

Returns: Rotation vector representation of this rotation.

◆ X()

units::radian_t frc::Rotation3d::X ( ) const

inlineconstexpr

Returns the counterclockwise rotation angle around the X axis (roll).

◆ Y()

units::radian_t frc::Rotation3d::Y ( ) const

inlineconstexpr

Returns the counterclockwise rotation angle around the Y axis (pitch).

◆ Z()

units::radian_t frc::Rotation3d::Z ( ) const

inlineconstexpr

Returns the counterclockwise rotation angle around the Z axis (yaw).

The documentation for this class was generated from the following file:

frc/geometry/Rotation3d.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ Rotation3d() [1/8]

◆ Rotation3d() [2/8]

◆ Rotation3d() [3/8]

◆ Rotation3d() [4/8]

◆ Rotation3d() [5/8]

◆ Rotation3d() [6/8]

◆ Rotation3d() [7/8]

◆ Rotation3d() [8/8]

Member Function Documentation

◆ Angle()

◆ Axis()

◆ GetQuaternion()

◆ operator*()

◆ operator+()

◆ operator-() [1/2]

◆ operator-() [2/2]

◆ operator/()

◆ operator==()

◆ RelativeTo()

◆ RotateBy()

◆ ToMatrix()

◆ ToRotation2d()

◆ ToVector()

◆ X()

◆ Y()

◆ Z()