user: How do I use Math Types & Utilities (mathutils) in Blender? Include parameters, examples, warnings and best practices.

assistant:         :   float

    freeze()
    :   Make this object immutable.

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

        Returns:
        :   An instance of this object.

    identity()
    :   Set the matrix to the identity matrix.

    invert(*fallback=None*, */*)
    :   Set the matrix to its inverse.

        Parameters:
        :   **fallback** ([`Matrix`](#mathutils.Matrix "mathutils.Matrix")) – Set the matrix to this value when the inverse cannot be calculated
            (instead of raising a `ValueError` exception).

    invert_safe()
    :   Set the matrix to its inverse, will never error.
        If degenerated (e.g. zero scale on an axis), add some epsilon to its diagonal, to get an invertible one.
        If tweaked matrix is still degenerated, set to the identity matrix instead.

    inverted(*fallback=None*, */*)
    :   Return an inverted copy of the matrix.

        Parameters:
        :   **fallback** (*Any*) – return this when the inverse can’t be calculated
            (instead of raising a `ValueError`).

        Returns:
        :   The inverted matrix or fallback when given.

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

    inverted_safe()
    :   Return an inverted copy of the matrix, will never error.
        If degenerated (e.g. zero scale on an axis), add some epsilon to its diagonal, to get an invertible one.
        If tweaked matrix is still degenerated, return the identity matrix instead.

        Returns:
        :   the inverted matrix.

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

    lerp(*other*, *factor*, */*)
    :   Returns the interpolation of two matrices. Uses polar decomposition, see “Matrix Animation and Polar Decomposition”, Shoemake and Duff, 1992.

        Parameters:
        :   - **other** ([`Matrix`](#mathutils.Matrix "mathutils.Matrix")) – value to interpolate with.
            - **factor** (*float*) – The interpolation value in [0.0, 1.0].

        Returns:
        :   The interpolated matrix.

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

    normalize()
    :   Normalize each of the matrix columns.

    normalized()
    :   Return a column normalized matrix

        Returns:
        :   a column normalized matrix

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

    resize_4x4()
    :   Resize the matrix to 4x4.

    rotate(*other*, */*)
    :   Rotates the matrix 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

    to_2x2()
    :   Return a 2x2 copy of this matrix.

        Returns:
        :   a new matrix.

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

    to_3x3()
    :   Return a 3x3 copy of this matrix.

        Returns:
        :   a new matrix.

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

    to_4x4()
    :   Return a 4x4 copy of this matrix.

        Returns:
        :   a new matrix.

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

    to_euler(*order='XYZ'*, *euler_compat=None*, */*)
    :   Return an Euler representation of the rotation matrix
        (3x3 or 4x4 matrix only).

        Parameters:
        :   - **order** – A rotation order string. :type order: Literal[‘XYZ’, ‘XZY’, ‘YXZ’, ‘YZX’, ‘ZXY’, ‘ZYX’]
            - **euler_compat** ([`Euler`](#mathutils.Euler "mathutils.Euler")) – Optional euler argument the new euler will be made
              compatible with (no axis flipping between them).
              Useful for converting a series of matrices to animation curves.

        Returns:
        :   Euler representation of the matrix.

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

    to_quaternion()
    :   Return a quaternion representation of the rotation matrix.

        Returns:
        :   Quaternion representation of the rotation matrix.

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

    to_scale()
    :   Return the scale part of a 3x3 or 4x4 matrix.

        Returns:
        :   Return the scale of a matrix.

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

    to_translation()
    :   Return the translation part of a 4 row matrix.

        Returns:
        :   Return the translation of a matrix.

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

    transpose()
    :   Set the matrix to its transpose.

    transposed()
    :   Return a new, transposed matrix.

        Returns:
        :   a transposed matrix

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

    zero()
    :   Set all the matrix values to zero.

    col
    :   Access the matrix by columns, 3x3 and 4x4 only, (read-only).

        Type:
        :   Matrix Access

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

        Type:
        :   bool

    is_identity
    :   True if this is an identity matrix (read-only).

        Type:
        :   bool

    is_negative
    :   True if this matrix results in a negative scale, 3x3 and 4x4 only, (read-only).

        Type:
        :   bool

    is_orthogonal
    :   True if this matrix is orthogonal, 3x3 and 4x4 only, (read-only).

        Type:
        :   bool

    is_orthogonal_axis_vectors
    :   True if this matrix has got orthogonal axis vectors, 3x3 and 4x4 only, (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

    median_scale
    :   The average scale applied to each axis (read-only).

        Type:
        :   float

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

    row
    :   Access the matrix by rows (default), (read-only).

        Type:
        :   Matrix Access

    translation
    :   The translation component of the matrix.

        Type:
        :   [`Vector`](#mathutils.Vector "mathutils.Vector")

*class* mathutils.Quaternion(*seq=(1.0, 0.0, 0.0, 0.0)*, *angle=0.0*, */*)
:   This object gives access to Quaternions in Blender.

    Parameters:
    :   - **seq** ([`Vector`](#mathutils.Vector "mathutils.Vector")) – size 3 or 4
        - **angle** (*float*) – rotation angle, in radians

    The constructor takes arguments in various forms:

    (), *no args*
    :   Create an identity quaternion

    (*wxyz*)
    :   Create a quaternion from a `(w, x, y, z)` vector.

    (*exponential_map*)
    :   Create a quaternion from a 3d exponential map vector.

    (*axis, angle*)
    :   Create a quaternion representing a rotation of *angle* radians over *axis*.

    ```
    import mathutils
    import math

    # A new rotation 90 degrees about the Y axis.
    quat_a = mathutils.Quaternion((0.7071068, 0.0, 0.7071068, 0.0))

    # Passing values to Quaternion's directly can be confusing so axis, angle
    # is supported for initializing too.
    quat_b = mathutils.Quaternion((0.0, 1.0, 0.0), math.radians(90.0))

    print("Check quaternions match", quat_a == quat_b)

    # Like matrices, quaternions can be multiplied to accumulate rotational values.
    quat_a = mathutils.Quaternion((0.0, 1.0, 0.0), math.radians(90.0))
    quat_b = mathutils.Quaternion((0.0, 0.0, 1.0), math.radians(45.0))
    quat_out = quat_a @ quat_b

    # Print the quaternion, euler degrees for mere mortals and (axis, angle).
    print("Final Rotation:")
    print(quat_out)
    print("{:.2f}, {:.2f}, {:.2f}".format(*(math.degrees(a) for a in quat_out.to_euler())))
    print("({:.2f}, {:.2f}, {:.2f}), {:.2f}".format(*quat_out.axis, math.degrees(quat_out.angle)))

    # Multiple rotations can be interpolated using the exponential map.
    quat_c = mathutils.Quaternion((1.0, 0.0, 0.0), math.radians(15.0))
    exp_avg = (quat_a.to_exponential_map() +
               quat_b.to_exponential_map() +
               quat_c.to_exponential_map()) / 3.0
    quat_avg = mathutils.Quaternion(exp_avg)
    print("Average rotation:")
    print(quat_avg)

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

    conjugate()
    :   Set the quaternion to its conjugate (negate x, y, z).

    conjugated()
    :   Return a new conjugated quaternion.

        Returns:
        :   a new quaternion.

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

    copy()
    :   Returns a copy of this quaternion.

        Returns:
        :   A copy of the quaternion.

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

    cross(*other*, */*)
    :   Return the cross product of this quaternion and another.

        Parameters:
        :   **other** ([`Quaternion`](#mathutils.Quaternion "mathutils.Quaternion")) – The other quaternion to perform the cross product with.

        Returns:
        :   The cross product.

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

    dot(*other*, */*)
    :   Return the dot product of this quaternion and another.

        Parameters:
        :   **other** ([`Quaternion`](#mathutils.Quaternion "mathutils.Quaternion")) – The other quaternion to perform the dot product with.

        Returns:
        :   The dot product.

        Return type:
        :   float

    freeze()
    :   Make this object immutable.

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

        Returns:
        :   An instance of this object.

    identity()
    :   Set the quaternion to an identity quaternion.

    invert()
    :   Set the quaternion to its inverse.

    inverted()
    :   Return a new, inverted quaternion.

        Returns:
        :   the inverted value.

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

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

        Parameters:
        :   **other** ([`Quaternion`](#mathutils.Quaternion "mathutils.Quaternion")) – The other quaternion to make compatible with.

    negate()
    :   Set the quaternion to its negative.

    normalize()
    :   Normalize the quaternion.

    normalized()
    :   Return a new normalized quaternion.

        Returns:
        :   a normalized copy.

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

    rotate(*other*, */*)
    :   Rotates the quaternion 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

    rotation_difference(*other*, */*)
    :   Returns a quaternion representing the rotational difference.

        Parameters:
        :   **other** ([`Quaternion`](#mathutils.Quaternion "mathutils.Quaternion")) – second quaternion.

        Returns:
        :   the rotational difference between the two quat rotations.

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

    slerp(*other*, *factor*, */*)
    :   Returns the interpolation of two quaternions.

        Parameters:
        :   - **other** ([`Quaternion`](#mathutils.Quaternion "mathutils.Quaternion")) – value to interpolate with.
            - **factor** (*float*) – The interpolation value in [0.0, 1.0].

        Returns:
        :   The interpolated rotation.

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

    to_axis_angle()
    :   Return the axis, angle representation of the quaternion.

        Returns:
        :   Axis, angle.

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

    to_euler(*order='XYZ'*, *euler_compat=None*, */*)
    :   Return Euler representation of the quaternion.

        Parameters:
        :   - **order** (*Literal**[**'XYZ'**,* *'XZY'**,* *'YXZ'**,* *'YZX'**,* *'ZXY'**,* *'ZYX'**]*) – Rotation order.
            - **euler_compat** ([`Euler`](#mathutils.Euler "mathutils.Euler")) – Optional euler argument the new euler will be made
              compatible with (no axis flipping between them).
              Useful for converting a series of matrices to animation curves.

        Returns:
        :   Euler representation of the quaternion.

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

    to_exponential_map()
    :   Return the exponential map representation of the quaternion.

        This representation consist of the rotation axis multiplied by the rotation angle.
        Such a representation is useful for interpolation between multiple orientations.

        Returns:
        :   exponential map.

        Return type:
        :   [`Vector`](#mathutils.Vector "mathutils.Vector") of size 3

        To convert back to a quaternion, pass it to the [`Quaternion`](#mathutils.Quaternion "mathutils.Quaternion") constructor.

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

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

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

    to_swing_twist(*axis*, */*)
    :   Split the rotation into a swing quaternion with the specified
        axis fixed at zero, and the remaining twist rotation angle.

        Parameters:
        :   **axis** (*Literal**[**'X'**,* *'Y'**,* *'Z'**]*) – Twist axis as a string.

        Returns:
        :   Swing, twist angle.

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

    angle
    :   Angle of the quaternion.

        Type:
        :   float

    axis
    :   Quaternion axis as a vector.

        Type:
        :   [`Vector`](#mathutils.Vector "mathutils.Vector")

    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

    magnitude
    :   Size of the quaternion (read-only).

        Type:
        :   float

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

    w
    :   Quaternion axis value.

        Type:
        :   float

    x
    :   Quaternion axis value.

        Type:
        :   float

    y
    :   Quaternion axis value.

        Type:
        :   float

    z
    :   Quaternion axis value.

        Type:
        :   float

*class* mathutils.Vector(*seq=(0.0, 0.0, 0.0)*, */*)
:   This object gives access to Vectors in Blender.

    Parameters:
    :   **seq** (*Sequence**[**float**]*) – Components of the vector, must be a sequence of at least two.

    ```
    import mathutils

    # Zero length vector.
    vec = mathutils.Vector((0.0, 0.0, 1.0))

    # Unit length vector.
    vec_a = vec.normalized()

    vec_b = mathutils.Vector((0.0, 1.0, 2.0))

    vec2d = mathutils.Vector((1.0, 2.0))
    vec3d = mathutils.Vector((1.0, 0.0, 0.0))
    vec4d = vec_a.to_4d()

    # Other `mathutils` types.
    quat = mathutils.Quaternion()
    matrix = mathutils.Matrix()

    # Comparison operators can be done on Vector classes:

    # (In)equality operators == and != test component values, e.g. 1,2,3 != 3,2,1
    vec_a == vec_b
    vec_a != vec_b

    # Ordering operators >, >=, > and <= test vector length.
    vec_a > vec_b
    vec_a >= vec_b
    vec_a < vec_b
    vec_a <= vec_b

    # Math can be performed on Vector classes.
    vec_a + vec_b
    vec_a - vec_b
    vec_a @ vec_b
    vec_a * 10.0
    matrix @ vec_a
    quat @ vec_a
    -vec_a

    # You can access a vector object like a sequence.
    x = vec_a[0]
    len(vec)
    vec_a[:] = vec_b
    vec_a[:] = 1.0, 2.0, 3.0
    vec2d[:] = vec3d[:2]

    # Vectors support 'swizzle' operations.
    # See https://en.wikipedia.org/wiki/Swizzling_(computer_graphics)
    vec.xyz = vec.zyx
    vec.xy = vec4d.zw
    vec.xyz = vec4d.wzz
    vec4d.wxyz = vec.yxyx

    # Direct buffer access is supported.
    raw_data = memoryview(vec).tobytes()
    ```

    *classmethod* Fill(*size*, *fill=0.0*, */*)
    :   Create a vector of length size with all values set to fill.

        Parameters:
        :   - **size** (*int*) – The length of the vector to be created.
            - **fill** (*float*) – The value used to fill the vector.

    *classmethod* Linspace(*start*, *stop*, *size*, */*)
    :   Create a vector of the specified size which is filled with linearly spaced values between start and stop values.

        Parameters:
        :   - **start** (*int*) – The start of the range used to fill the vector.
            - **stop** (*int*) – The end of the range used to fill the vector.
            - **size** (*int*) – The size of the vector to be created.

    *classmethod* Range(*start*, *stop*, *step=1*, */*)
    :   Create a filled with a range of values.

        > This method can also be called with a single argument, in which case the argument is interpreted as `stop` and `start` defaults to 0.

        Parameters:
        :   - **start** (*int*) – The start of the range used to fill the vector.
            - **stop** (*int*) – The end of the range used to fill the vector.
            - **step** (*int*) – The s