Rotation3d

class wpimath.Rotation3d(*args, **kwargs)

Bases: pybind11_object

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.

Overloaded function.

  1. __init__(self: wpimath._wpimath.Rotation3d) -> None

Constructs a Rotation3d representing no rotation.

  1. __init__(self: wpimath._wpimath.Rotation3d, q: wpimath._wpimath.Quaternion) -> None

Constructs a Rotation3d from a quaternion.

Parameters:

q – The quaternion.

  1. __init__(self: wpimath._wpimath.Rotation3d, roll: wpimath.units.radians, pitch: wpimath.units.radians, yaw: wpimath.units.radians) -> None

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).

  1. __init__(self: wpimath._wpimath.Rotation3d, axis: typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[3, 1]”], angle: wpimath.units.radians) -> None

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.

  1. __init__(self: wpimath._wpimath.Rotation3d, rvec: typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[3, 1]”]) -> None

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.

  1. __init__(self: wpimath._wpimath.Rotation3d, rotationMatrix: typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[3, 3]”]) -> None

Constructs a Rotation3d from a rotation matrix.

Parameters:

rotationMatrix – The rotation matrix. @throws std::domain_error if the rotation matrix isn’t special orthogonal.

  1. __init__(self: wpimath._wpimath.Rotation3d, initial: typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[3, 1]”], final: typing.Annotated[numpy.typing.ArrayLike, numpy.float64, “[3, 1]”]) -> None

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.

  1. __init__(self: wpimath._wpimath.Rotation3d, rotation: wpimath._wpimath.Rotation2d) -> None

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

Parameters:

rotation – The 2D rotation. @see Pose3d(Pose2d) @see Transform3d(Transform2d)

WPIStruct = <capsule object "WPyStruct">
X() → wpimath.units.radians

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

Y() → wpimath.units.radians

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

Z() → wpimath.units.radians

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

property angle
property angle_degrees
axis() → Annotated[numpy.typing.NDArray[numpy.float64], '[3, 1]']

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

static fromDegrees(roll: wpimath.units.degrees, pitch: wpimath.units.degrees, yaw: wpimath.units.degrees) → wpimath._wpimath.Rotation3d
getQuaternion() → wpimath._wpimath.Quaternion

Returns the quaternion representation of the Rotation3d.

interpolate(endValue: wpimath._wpimath.Rotation3d, t: SupportsFloat | SupportsIndex) → wpimath._wpimath.Rotation3d

Interpolates between this rotation and another.

Parameters:

  • endValue – The other rotation.

  • t – How far between the two rotations we are (0 means this rotation, 1 means other rotation).

Returns:

The interpolated value.

inverse() → wpimath._wpimath.Rotation3d

Takes the inverse of the current rotation.

Returns:

The inverse of the current rotation.

relativeTo(other: wpimath._wpimath.Rotation3d) → wpimath._wpimath.Rotation3d

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(other: wpimath._wpimath.Rotation3d) → wpimath._wpimath.Rotation3d

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() → Annotated[numpy.typing.NDArray[numpy.float64], '[3, 3]']

Returns rotation matrix representation of this rotation.

toRotation2d() → wpimath._wpimath.Rotation2d

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

toVector() → Annotated[numpy.typing.NDArray[numpy.float64], '[3, 1]']

Returns rotation vector representation of this rotation.

Returns:

Rotation vector representation of this rotation.

property x
property x_degrees
property y
property y_degrees
property z
property z_degrees