user: Provide the full official documentation entry for Mathutils, preserving all code examples.

assistant: or from_srgb_to_scene_linear ( ) ¶ Convert from sRGB to scene linear color space. Returns : A color in scene linear color space. Return type : 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 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. See also Euler angles on Wikipedia. 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 ), &#39;XYZ&#39; ) # Rotate the euler. eul . rotate_axis ( &#39;Z&#39; , 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 = &#39;ZYX&#39; # 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 Note use this to get a copy of a wrapped euler with no reference to the original data. 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 ) – Other euler rotation. Note the rotation order is not taken into account for this function. rotate ( other , / ) ¶ Rotates the euler by another mathutils value. Parameters : other ( Euler | Quaternion | 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 to_quaternion ( ) ¶ Return a quaternion representation of the euler. Returns : Quaternion representation of the euler. Return type : 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 , &#39;X&#39; ) # 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 ) – The vector of values for the diagonal. Returns : A diagonal matrix. Return type : 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 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 | None) – The translation component. rotation ( Matrix | Quaternion | Euler | None) – The rotation component as a 3x3 matrix, quaternion, euler or None for no rotation. scale ( Vector | None) – The scale component. Returns : Combined transformation as a 4x4 matrix. Return type : Matrix # Compute local object transformation matrix: if obj . rotation_mode == &#39;QUATERNION&#39; : 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 ) – 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 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 ) – an axis string or a 3D Vector Object (optional when size is 2). Returns : A new rotation matrix. Return type : 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 ) – Direction to influence scale. (optional). Returns : A new scale matrix. Return type : 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 classmethod Translation ( vector , / ) ¶ Create a matrix representing a translation. Parameters : vector ( Vector ) – The translation vector. Returns : An identity matrix with a translation. Return type : Matrix adjugate ( ) ¶ Set the matrix to its adjugate. Raises : ValueError – if the matrix cannot be adjugated. See also Adjugate matrix on Wikipedia. adjugated ( ) ¶ Return an adjugated copy of the matrix. Returns : the adjugated matrix. Return type : Matrix Raises : ValueError – if the matrix cannot be adjugated copy ( ) ¶ Returns a copy of this matrix. Returns : an instance of itself Return type : Matrix decompose ( ) ¶ Return the translation, rotation, and scale components of this matrix. Returns : Tuple of translation, rotation, and scale. Return type : tuple[ Vector , Quaternion , Vector ] determinant ( ) ¶ Return the determinant of a matrix. Returns : Return the determinant of a matrix. Return type : float See also Determinant on Wikipedia. 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. Note An object with a location and rotation of zero, and a scale of one will have an identity matrix. See also Identity matrix on Wikipedia. invert ( fallback = None , / ) ¶ Set the matrix to its inverse. Parameters : fallback ( Matrix ) – Set the matrix to this value when the inverse cannot be calculated (instead of raising a ValueError exception). See also Inverse matrix on Wikipedia. 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. See also Inverse Matrix on Wikipedia. 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 | 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 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 ) – value to interpolate with. factor ( float ) – The interpolation value in [0.0, 1.0]. Returns : The interpolated matrix. Return type : Matrix normalize ( ) ¶ Normalize each of the matrix columns. Note for 4x4 matrices, the 4th column (translation) is left untouched. normalized ( ) ¶ Return a column normalized matrix Returns : a column normalized matrix Return type : Matrix Note for 4x4 matrices, the 4th column (translation) is left untouched. resize_4x4 ( ) ¶ Resize the matrix to 4x4. rotate ( other , / ) ¶ Rotates the matrix by another mathutils value. Parameters : other ( Euler | Quaternion | Matrix ) – rotation component of mathutils value Note If any of the columns are not unit length this may not have desired results. to_2x2 ( ) ¶ Return a 2x2 copy of this matrix. Returns : a new matrix. Return type : Matrix to_3x3 ( ) ¶ Return a 3x3 copy of this matrix. Returns : a new matrix. Return type : Matrix to_4x4 ( ) ¶ Return a 4x4 copy of this matrix. Returns : a new matrix. Return type : 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 ) – 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 to_quaternion ( ) ¶ Return a quaternion representation of the rotation matrix. Returns : Quaternion representation of the rotation matrix. Return type : Quaternion to_scale ( ) ¶ Return the scale part of a 3x3 or 4x4 matrix. Returns : Return the scale of a matrix. Return type : Vector Note This method does not return a negative scale on any axis because it is not possible to obtain this data from the matrix alone. to_translation ( ) ¶ Return the translation part of a 4 row matrix. Returns : Return the translation of a matrix. Return type : Vector transpose ( ) ¶ Set the matrix to its transpose. See also Transpose on Wikipedia. transposed ( ) ¶ Return a new, transposed matrix. Returns : a transposed matrix Return type : 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 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 ) – 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. See also to_exponential_map() ( axis, angle ) Create a quaternion representing a rotation of angle radians over axis . See also to_axis_angle() 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&#39;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 copy ( ) ¶ Returns a copy of this quaternion. Returns : A copy of the quaternion. Return type : Quaternion Note use this to get a copy of a wrapped quaternion with no reference to the original data. cross ( other , / ) ¶ Return the cross product of this quaternion and another. Parameters : other ( Quaternion ) – The other quaternion to perform the cross product with. Returns : The cross product. Return type : Quaternion dot ( other , / ) ¶ Return the dot product of this quaternion and another. Parameters : other ( 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 make_compatible ( other , / ) ¶ Make this quaternion compatible with another, so interpolating between them works as intended. Parameters : other ( 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 rotate ( other , / ) ¶ Rotates the quaternion by another mathutils value. Parameters : other ( Euler | Quaternion | Matrix ) –