Main Content

so3

SO(3) rotation

Since R2022b

    Description

    The so3 object represents an SO(3) rotation in 3-D in a right-handed Cartesian coordinate system.

    The SO(3) rotation is a 3-by-3 orthonormal rotation matrix. For example, these are orthonormal rotation matrices for rotations of ϕ, ψ, and θ about the x-, y-, and z-axis, respectively:

    Rx(ϕ)=[1000cosϕsinϕ0sinϕcosϕ], Ry(ψ)=[cosψ0sinψ010sinψ0cosψ], Rz(θ)=[cosθsinθ0sinθcosθ0001]

    For more information, see the 3-D Orthonormal Rotation Matrix section.

    This object acts like a numerical matrix, enabling you to compose rotations using multiplication and division.

    Creation

    Description

    3-D Rotation Representations

    rotation = so3 creates an SO(3) rotation representing an identity rotation with no translation.

    rotation=[100010001]

    rotation = so3(rotation) creates an SO(3) rotation representing a pure rotation defined by the orthonormal rotation rotation.

    rotation=[r11r12r13r11r22r23r31r32r33]

    rotation = so3(quaternion) creates an SO(3) rotation from the rotations defined by the quaternion quaternion.

    rotation = so3(transformation) creates an SO(3) rotation from the SE(3) transformation transformation.

    Other Numeric 3-D Rotation Representations

    rotation = so3(euler,"eul") creates an SO(3) rotation from the rotations defined by the Euler angles euler.

    example

    rotation = so3(euler,"eul",sequence) specifies the sequence of the Euler angle rotations sequence. For example, the sequence "ZYX" rotates the z-axis, then the y-axis and x-axis.

    rotation = so3(quat,"quat") creates an SO(3) rotation from the rotations defined by the numeric quaternions quat.

    rotation = so3(axang,"axang") creates an SO(3) rotation from the rotations defined by the axis-angle rotation axang.

    rotation = so3(angle,axis) creates an SO(3) rotation from the rotations angles about the rotation axis axis.

    Note

    If any inputs contain more than one rotation, then the output rotation is an N-element array of so3 objects corresponding to each of the N input rotations.

    Input Arguments

    expand all

    Orthonormal rotation, specified as a 3-by-3 matrix, a 3-by-3-byN array, a scalar so3 object, or an N-element array of so3 objects. N is the total number of rotations.

    If rotation is an array, the resulting number of created so3 objects in the output array is equal to N.

    Example: eye(3)

    Homogeneous transformation, specified as a 4-by-4 matrix, a 4-by-4-by-N array, a scalar se3 object, or an N-element array of se3 objects. N is the total number of transformations specified.

    If transformation is an array, the resulting number of created so3 objects is equal to N.

    Example: eye(4)

    Data Types: single | double

    Quaternion, specified as a scalar quaternion object or as an N-element array of quaternion objects. N is the total number of specified quaternions.

    If quaternion is an N-element array, the resulting number of created so3 objects is equal to N.

    Example: quaternion(1,0.2,0.4,0.2)

    Euler angles, specified as an N-by-3 matrix, in radians. Each row represents one set of Euler angles with the axis-rotation sequence defined by the sequence argument. The default axis-rotation sequence is ZYX.

    If euler is an N-by-3 matrix, the resulting number of created so3 objects is equal to N.

    Example: [pi/2 pi pi/4]

    Data Types: single | double

    Axis-rotation sequence for the Euler angles, specified as one of these string scalars:

    • "ZYX" (default)

    • "ZYZ"

    • "ZXY"

    • "ZXZ"

    • "YXY"

    • "YZX"

    • "YXZ"

    • "YZY"

    • "XYX"

    • "XYZ"

    • "XZX"

    • "XZY"

    These are orthonormal rotation matrices for rotations of ϕ, ψ, and θ about the x-, y-, and z-axis, respectively:

    Rx(ϕ)=[1000cosϕsinϕ0sinϕcosϕ], Ry(ψ)=[cosψ0sinψ010sinψ0cosψ], Rz(θ)=[cosθsinθ0sinθcosθ0001]

    When constructing the rotation matrix from this sequence, each character indicates the corresponding axis. For example, if the sequence is "XYZ", then the so3 object constructs the rotation matrix R by multiplying the rotation about x-axis with the rotation about the y-axis, and then multiplying that product with the rotation about the z-axis:

    R=Rx(ϕ)·Ry(ψ)·Rz(θ)

    Example: so3([pi/2 pi/3 pi/4],"eul","ZYZ") rotates a point by pi/4 radians about the z-axis, then rotates the point by pi/3 radians about the y-axis, and then rotates the point by pi/2 radians about the z-axis. This is equivalent to so3(pi/2,"rotz") * so3(pi/3,"roty") * so3(pi/4,"rotz")

    Data Types: string | char

    Numeric quaternion, specified as an N-by-4 matrix. N is the number of specified quaternions. Each row represents one quaternion of the form [qw qx qy qz], where qw is a scalar number.

    If quat is an N-by-4 matrix, the resulting number of created so3 objects is equal to N.

    Note

    The so3 object normalizes the input quaternions before converting the quaternions to a rotation matrix.

    Example: [0.7071 0.7071 0 0]

    Data Types: single | double

    Axis-angle rotation, specified as an N-by-4 matrix in the form [x y z theta]. N is the total number of axis-angle rotations. x, y, and z are vector components from the x-, y-, and z-axis, respectively. The vector defines the axis to rotate by the angle theta, in radians.

    If axang is an N-by-4 matrix, the resulting number of created so3 objects is equal to N.

    Example: [.2 .15 .25 pi/4] rotates the axis, defined as 0.2 in the x-axis, 0.15 along the y-axis, and 0.25 along the z-axis, by pi/4 radians.

    Data Types: single | double

    Single-axis-angle rotation, specified as an N-by-M matrix. Each element of the matrix is an angle, in radians, about the axis specified using the axis argument, and the so3 object creates an so3 object for each angle.

    If angle is an N-by-M matrix, the resulting number of created so3 objects is equal to N.

    The rotation angle is counterclockwise positive when you look along the specified axis toward the origin.

    Data Types: single | double

    Axis to rotate, specified as one of these options:

    • "rotx" — Rotate about the x-axis:

      Rx(ϕ)=[1000cosϕsinϕ0sinϕcosϕ]

    • "roty" — Rotate about the y-axis:

      Ry(ψ)=[cosψ0sinψ010sinψ0cosψ]

    • "rotz" — Rotate about the z-axis:

      Rz(θ)=[cosθsinθ0sinθcosθ0001]

    Use the angle argument to specify how much to rotate about the specified axis.

    Example: Rx = so3(phi,"rotx");

    Example: Ry = so3(psi,"roty");

    Example: Rz = so3(theta,"rotz");

    Data Types: string | char

    Object Functions

    expand all

    mtimes, *Transformation or rotation multiplication
    mrdivide, /Transformation or rotation right division
    rdivide, ./Element-wise transformation or rotation right division
    times, .*Element-wise transformation or rotation multiplication
    interpInterpolate between transformations
    distCalculate distance between transformations
    normalizeNormalize transformation or rotation matrix
    transformApply rigid body transformation to points
    axangConvert transformation or rotation into axis-angle rotations
    eulConvert transformation or rotation into Euler angles
    rotmExtract rotation matrix
    quatConvert transformation or rotation to numeric quaternion
    trvecExtract translation vector
    tformExtract homogeneous transformation
    xyzquatConvert transformation or rotation to compact 3-D pose representation
    se3SE(3) homogeneous transformation
    quaternionCreate quaternion array

    Examples

    collapse all

    Create SO(3) rotation defined by a Euler angles.

    eul1 = [pi/4 pi/3 pi/8]
    eul1 = 1×3
    
        0.7854    1.0472    0.3927
    
    
    R = so3(eul1,"eul")
    R = so3
        0.3536   -0.4189    0.8364
        0.3536    0.8876    0.2952
       -0.8660    0.1913    0.4619
    
    

    Get the Euler angles from the transformation.

    eul2 = eul(R)
    eul2 = 1×3
    
        0.7854    1.0472    0.3927
    
    

    Algorithms

    expand all

    Extended Capabilities

    C/C++ Code Generation
    Generate C and C++ code using MATLAB® Coder™.

    Version History

    Introduced in R2022b

    expand all