user: Describe Math Types & Utilities (mathutils) from the Blender manual or Python API, including usage steps and snippets.

assistant: # Math Types & Utilities (mathutils)

This module provides access to math operations.

The [`mathutils`](#module-mathutils "mathutils") module provides the following classes:

- [`Color`](#mathutils.Color "mathutils.Color"),
- [`Euler`](#mathutils.Euler "mathutils.Euler"),
- [`Matrix`](#mathutils.Matrix "mathutils.Matrix"),
- [`Quaternion`](#mathutils.Quaternion "mathutils.Quaternion"),
- [`Vector`](#mathutils.Vector "mathutils.Vector"),

```
import mathutils
from math import radians

vec = mathutils.Vector((1.0, 2.0, 3.0))

mat_rot = mathutils.Matrix.Rotation(radians(90.0), 4, 'X')
mat_trans = mathutils.Matrix.Translation(vec)

mat = mat_trans @ mat_rot
mat.invert()

mat3 = mat.to_3x3()
quat1 = mat.to_quaternion()
quat2 = mat3.to_quaternion()

quat_diff = quat1.rotation_difference(quat2)

print(quat_diff.angle)
```

*class* mathutils.Color(*rgb=(0.0, 0.0, 0.0)*, */*)
:   This object gives access to Colors in Blender.

    Most colors returned by Blender APIs are in scene linear color space, as defined by the OpenColorIO configuration. The notable exception is user interface theming colors, which are in sRGB color space.

    Parameters:
    :   **rgb** (*Sequence**[**float**]*) – (red, green, blue) color values where (0, 0, 0) is black & (1, 1, 1) is white.

    ```
    import mathutils

    # Color values are represented as RGB values from 0 - 1, this is blue.
    col = mathutils.Color((0.0, 0.0, 1.0))

    # As well as r/g/b attribute access you can adjust them by h/s/v.
    col.s *= 0.5

    # You can access its components by attribute or index.
    print("Color R:", col.r)
    print("Color G:", col[1])
    print("Color B:", col[-1])
    print("Color HSV: {:.2f}, {:.2f}, {:.2f}".format(*col))

    # Components of an existing color can be set.
    col[:] = 0.0, 0.5, 1.0

    # Components of an existing color can use slice notation to get a tuple.
    print("Values: {:f}, {:f}, {:f}".format(*col))

    # Colors can be added and subtracted.
    col += mathutils.Color((0.25, 0.0, 0.0))

    # Color can be multiplied, in this example color is scaled to 0-255
    # can printed as integers.
    print("Color: {:d}, {:d}, {:d}".format(*(int(c) for c in (col * 255.0))))

    # This example prints the color as hexadecimal.
    print("Hexadecimal: {:02x}{:02x}{:02x}".format(int(col.r * 255), int(col.g * 255), int(col.b * 255)))

    # Direct buffer access is supported.
    print(memoryview(col).tobytes())
    ```

    copy()
    :   Returns a copy of this color.

        Returns:
        :   A copy of the color.

        Return type:
        :   [`Color`](#mathutils.Color "mathutils.Color")

    freeze()
    :   Make this object immutable.

        After this the object can be hashed, used in dictionaries & sets.

        Returns:
        :   An instance of this object.

    from_aces_to_scene_linear()
    :   Convert from ACES2065-1 linear to scene linear color space.

        Returns:
        :   A color in scene linear color space.

        Return type:
        :   [`Color`](#mathutils.Color "mathutils.Color")

    from_acescg_to_scene_linear()
    :   Convert from ACEScg linear to scene linear color space.

        Returns:
        :   A color in scene linear color space.

        Return type:
        :   [`Color`](#mathutils.Color "mathutils.Color")

    from_rec2020_linear_to_scene_linear()
    :   Convert from Rec.2020 linear color space to scene linear color space.

        Returns:
        :   A color in scene linear color space.

        Return type:
        :   [`Color`](#mathutils.Color "mathutils.Color")

    from_rec709_linear_to_scene_linear()
    :   Convert from Rec.709 linear color space to scene linear color space.

        Returns:
        :   A color in scene linear color space.

        Return type:
        :   [`Color`](#mathutils.Color "mathutils.Color")

    from_scene_linear_to_aces()
    :   Convert from scene linear to ACES2065-1 linear color space.

        Returns:
        :   A color in ACES2065-1 linear color space.

        Return type:
        :   [`Color`](#mathutils.Color "mathutils.Color")

    from_scene_linear_to_acescg()
    :   Convert from scene linear to ACEScg linear color space.

        Returns:
        :   A color in ACEScg linear color space.

        Return type:
        :   [`Color`](#mathutils.Color "mathutils.Color")

    from_scene_linear_to_rec2020_linear()
    :   Convert from scene linear to Rec.2020 linear color space.

        Returns:
        :   A color in Rec.2020 linear color space.

        Return type:
        :   [`Color`](#mathutils.Color "mathutils.Color")

    from_scene_linear_to_rec709_linear()
    :   Convert from scene linear to Rec.709 linear color space.

        Returns:
        :   A color in Rec.709 linear color space.

        Return type:
        :   [`Color`](#mathutils.Color "mathutils.Color")

    from_scene_linear_to_srgb()
    :   Convert from scene linear to sRGB color space.

        Returns:
        :   A color in sRGB color space.

        Return type:
        :   [`Color`](#mathutils.Color "mathutils.Color")

    from_scene_linear_to_xyz_d65()
    :   Convert from scene linear to CIE XYZ (Illuminant D65) color space.

        Returns:
        :   A color in XYZ color space.

        Return type:
        :   [`Color`](#mathutils.Color "mathutils.Color")

    from_srgb_to_scene_linear()
    :   Convert from sRGB to scene linear color space.

        Returns:
        :   A color in scene linear color space.

        Return type:
        :   [`Color`](#mathutils.Color "mathutils.Color")

    from_xyz_d65_to_scene_linear()
    :   Convert from CIE XYZ (Illuminant D65) to scene linear color space.

        Returns:
        :   A color in scene linear color space.

        Return type:
        :   [`Color`](#mathutils.Color "mathutils.Color")

    b
    :   Blue color channel.

        Type:
        :   float

    g
    :   Green color channel.

        Type:
        :   float

    h
    :   HSV Hue component in [0, 1].

        Type:
        :   float

    hsv
    :   HSV Values in [0, 1].

        Type:
        :   tuple[float, float, float]

    is_frozen
    :   True when this object has been frozen (read-only).

        Type:
        :   bool

    is_valid
    :   True when the owner of this data is valid.

        Type:
        :   bool

    is_wrapped
    :   True when this object wraps external data (read-only).

        Type:
        :   bool

    owner
    :   The item this is wrapping or None (read-only).

    r
    :   Red color channel.

        Type:
        :   float

    s
    :   HSV Saturation component in [0, 1].

        Type:
        :   float

    v
    :   HSV Value component in [0, 1].

        Type:
        :   float

*class* mathutils.Euler(*angles=(0.0, 0.0, 0.0)*, *order='XYZ'*, */*)
:   This object gives access to Eulers in Blender.

    Parameters:
    :   - **angles** (*Sequence**[**float**]*) – (X, Y, Z) angles in radians.
        - **order** (*Literal**[**'XYZ'**,* *'XZY'**,* *'YXZ'**,* *'YZX'**,* *'ZXY'**,* *'ZYX'**]*) – Euler rotation order.

    ```
    import mathutils
    import math

    # Create a new euler with default axis rotation order.
    eul = mathutils.Euler((0.0, math.radians(45.0), 0.0), 'XYZ')

    # Rotate the euler.
    eul.rotate_axis('Z', math.radians(10.0))

    # You can access its components by attribute or index.
    print("Euler X", eul.x)
    print("Euler Y", eul[1])
    print("Euler Z", eul[-1])

    # Components of an existing euler can be set.
    eul[:] = 1.0, 2.0, 3.0

    # Components of an existing euler can use slice notation to get a tuple.
    print("Values: {:f}, {:f}, {:f}".format(*eul))

    # The order can be set at any time too.
    eul.order = 'ZYX'

    # Eulers can be used to rotate vectors.
    vec = mathutils.Vector((0.0, 0.0, 1.0))
    vec.rotate(eul)

    # Often its useful to convert the euler into a matrix so it can be used as
    # transformations with more flexibility.
    mat_rot = eul.to_matrix()
    mat_loc = mathutils.Matrix.Translation((2.0, 3.0, 4.0))
    mat = mat_loc @ mat_rot.to_4x4()

    # Direct buffer access is supported.
    print(memoryview(eul).tobytes())
    ```

    copy()
    :   Returns a copy of this euler.

        Returns:
        :   A copy of the euler.

        Return type:
        :   [`Euler`](#mathutils.Euler "mathutils.Euler")

    freeze()
    :   Make this object immutable.

        After this the object can be hashed, used in dictionaries & sets.

        Returns:
        :   An instance of this object.

    make_compatible(*other*, */*)
    :   Make this euler compatible with another,
        so interpolating between them works as intended.

        Parameters:
        :   **other** ([`Euler`](#mathutils.Euler "mathutils.Euler")) – Other euler rotation.

    rotate(*other*, */*)
    :   Rotates the euler by another mathutils value.

        Parameters:
        :   **other** ([`Euler`](#mathutils.Euler "mathutils.Euler") | [`Quaternion`](#mathutils.Quaternion "mathutils.Quaternion") | [`Matrix`](#mathutils.Matrix "mathutils.Matrix")) – rotation component of mathutils value

    rotate_axis(*axis*, *angle*, */*)
    :   Rotates the euler a certain amount and returning a unique euler rotation
        (no 720 degree pitches).

        Parameters:
        :   - **axis** (*Literal**[**'X'**,* *'Y'**,* *'Z'**]*) – An axis string.
            - **angle** (*float*) – angle in radians.

    to_matrix()
    :   Return a matrix representation of the euler.

        Returns:
        :   A 3x3 rotation matrix representation of the euler.

        Return type:
        :   [`Matrix`](#mathutils.Matrix "mathutils.Matrix")

    to_quaternion()
    :   Return a quaternion representation of the euler.

        Returns:
        :   Quaternion representation of the euler.

        Return type:
        :   [`Quaternion`](#mathutils.Quaternion "mathutils.Quaternion")

    zero()
    :   Set all values to zero.

    is_frozen
    :   True when this object has been frozen (read-only).

        Type:
        :   bool

    is_valid
    :   True when the owner of this data is valid.

        Type:
        :   bool

    is_wrapped
    :   True when this object wraps external data (read-only).

        Type:
        :   bool

    order
    :   Euler rotation order.

        Type:
        :   Literal[‘XYZ’, ‘XZY’, ‘YXZ’, ‘YZX’, ‘ZXY’, ‘ZYX’]

    owner
    :   The item this is wrapping or None (read-only).

    x
    :   Euler axis angle in radians.

        Type:
        :   float

    y
    :   Euler axis angle in radians.

        Type:
        :   float

    z
    :   Euler axis angle in radians.

        Type:
        :   float

*class* mathutils.Matrix(*rows=Matrix.Identity(4)*, */*)
:   This object gives access to Matrices in Blender, supporting square and rectangular
    matrices from 2x2 up to 4x4.

    Parameters:
    :   **rows** (*Sequence**[**Sequence**[**float**]**]*) – Sequence of rows.

    ```
    import mathutils
    import math

    # Create a location matrix.
    mat_loc = mathutils.Matrix.Translation((2.0, 3.0, 4.0))

    # Create an identity matrix.
    mat_sca = mathutils.Matrix.Scale(0.5, 4, (0.0, 0.0, 1.0))

    # Create a rotation matrix.
    mat_rot = mathutils.Matrix.Rotation(math.radians(45.0), 4, 'X')

    # Combine transformations.
    mat_out = mat_loc @ mat_rot @ mat_sca
    print(mat_out)

    # Extract components back out of the matrix as two vectors and a quaternion.
    loc, rot, sca = mat_out.decompose()
    print(loc, rot, sca)

    # Recombine extracted components.
    mat_out2 = mathutils.Matrix.LocRotScale(loc, rot, sca)
    print(mat_out2)

    # It can also be useful to access components of a matrix directly.
    mat = mathutils.Matrix()
    mat[0][0], mat[1][0], mat[2][0] = 0.0, 1.0, 2.0

    mat[0][0:3] = 0.0, 1.0, 2.0

    # Each item in a matrix is a vector so vector utility functions can be used.
    mat[0].xyz = 0.0, 1.0, 2.0

    # Direct buffer access is supported.
    print(memoryview(mat).tobytes())
    ```

    *classmethod* Diagonal(*vector*, */*)
    :   Create a diagonal (scaling) matrix using the values from the vector.

        Parameters:
        :   **vector** ([`Vector`](#mathutils.Vector "mathutils.Vector")) – The vector of values for the diagonal.

        Returns:
        :   A diagonal matrix.

        Return type:
        :   [`Matrix`](#mathutils.Matrix "mathutils.Matrix")

    *classmethod* Identity(*size*, */*)
    :   Create an identity matrix.

        Parameters:
        :   **size** (*int*) – The size of the identity matrix to construct [2, 4].

        Returns:
        :   A new identity matrix.

        Return type:
        :   [`Matrix`](#mathutils.Matrix "mathutils.Matrix")

    *classmethod* LocRotScale(*location*, *rotation*, *scale*, */*)
    :   Create a matrix combining translation, rotation and scale,
        acting as the inverse of the decompose() method.

        Any of the inputs may be replaced with None if not needed.

        Parameters:
        :   - **location** ([`Vector`](#mathutils.Vector "mathutils.Vector") | None) – The translation component.
            - **rotation** ([`Matrix`](#mathutils.Matrix "mathutils.Matrix") | [`Quaternion`](#mathutils.Quaternion "mathutils.Quaternion") | [`Euler`](#mathutils.Euler "mathutils.Euler") | None) – The rotation component as a 3x3 matrix, quaternion, euler or None for no rotation.
            - **scale** ([`Vector`](#mathutils.Vector "mathutils.Vector") | None) – The scale component.

        Returns:
        :   Combined transformation as a 4x4 matrix.

        Return type:
        :   [`Matrix`](#mathutils.Matrix "mathutils.Matrix")

        ```
        # Compute local object transformation matrix:
        if obj.rotation_mode == 'QUATERNION':
            matrix = mathutils.Matrix.LocRotScale(obj.location, obj.rotation_quaternion, obj.scale)
        else:
            matrix = mathutils.Matrix.LocRotScale(obj.location, obj.rotation_euler, obj.scale)
        ```

    *classmethod* OrthoProjection(*axis*, *size*, */*)
    :   Create a matrix to represent an orthographic projection.

        Parameters:
        :   - **axis** (Literal[‘X’, ‘Y’, ‘XY’, ‘XZ’, ‘YZ’] | [`Vector`](#mathutils.Vector "mathutils.Vector")) – An axis string,
              where a single axis is for a 2D matrix.
              Or a vector for an arbitrary axis
            - **size** (*int*) – The size of the projection matrix to construct [2, 4].

        Returns:
        :   A new projection matrix.

        Return type:
        :   [`Matrix`](#mathutils.Matrix "mathutils.Matrix")

    *classmethod* Rotation(*angle*, *size*, *axis*, */*)
    :   Create a matrix representing a rotation.

        Parameters:
        :   - **angle** (*float*) – The angle of rotation desired, in radians.
            - **size** (*int*) – The size of the rotation matrix to construct [2, 4].
            - **axis** (Literal[‘X’, ‘Y’, ‘Z’] | [`Vector`](#mathutils.Vector "mathutils.Vector")) – an axis string or a 3D Vector Object
              (optional when size is 2).

        Returns:
        :   A new rotation matrix.

        Return type:
        :   [`Matrix`](#mathutils.Matrix "mathutils.Matrix")

    *classmethod* Scale(*factor*, *size*, *axis*, */*)
    :   Create a matrix representing a scaling.

        Parameters:
        :   - **factor** (*float*) – The factor of scaling to apply.
            - **size** (*int*) – The size of the scale matrix to construct [2, 4].
            - **axis** ([`Vector`](#mathutils.Vector "mathutils.Vector")) – Direction to influence scale. (optional).

        Returns:
        :   A new scale matrix.

        Return type:
        :   [`Matrix`](#mathutils.Matrix "mathutils.Matrix")

    *classmethod* Shear(*plane*, *size*, *factor*, */*)
    :   Create a matrix to represent a shear transformation.

        Parameters:
        :   - **plane** (*Literal**[**'X'**,* *'Y'**,* *'XY'**,* *'XZ'**,* *'YZ'**]*) – An axis string,
              where a single axis is for a 2D matrix only.
            - **size** (*int*) – The size of the shear matrix to construct [2, 4].
            - **factor** (*float* *|* *Sequence**[**float**]*) – The factor of shear to apply. For a 2 *size* matrix use a single float. For a 3 or 4 *size* matrix pass a pair of floats corresponding with the *plane* axis.

        Returns:
        :   A new shear matrix.

        Return type:
        :   [`Matrix`](#mathutils.Matrix "mathutils.Matrix")

    *classmethod* Translation(*vector*, */*)
    :   Create a matrix representing a translation.

        Parameters:
        :   **vector** ([`Vector`](#mathutils.Vector "mathutils.Vector")) – The translation vector.

        Returns:
        :   An identity matrix with a translation.

        Return type:
        :   [`Matrix`](#mathutils.Matrix "mathutils.Matrix")

    adjugate()
    :   Set the matrix to its adjugate.

        Raises:
        :   **ValueError** – if the matrix cannot be adjugated.

    adjugated()
    :   Return an adjugated copy of the matrix.

        Returns:
        :   the adjugated matrix.

        Return type:
        :   [`Matrix`](#mathutils.Matrix "mathutils.Matrix")

        Raises:
        :   **ValueError** – if the matrix cannot be adjugated

    copy()
    :   Returns a copy of this matrix.

        Returns:
        :   an instance of itself

        Return type:
        :   [`Matrix`](#mathutils.Matrix "mathutils.Matrix")

    decompose()
    :   Return the translation, rotation, and scale components of this matrix.

        Returns:
        :   Tuple of translation, rotation, and scale.

        Return type:
        :   tuple[[`Vector`](#mathutils.Vector "mathutils.Vector"), [`Quaternion`](#mathutils.Quaternion "mathutils.Quaternion"), [`Vector`](#mathutils.Vector "mathutils.Vector")]

    determinant()
    :   Return the determinant of a matrix.

        Returns:
        :   Return the determinant of a matrix.

        Return type: