c4d.Matrix¶

class c4d.Matrix¶

A type to represent a transform.

See also

Warning

The Matrix type does not support the function copy.copy(), please use the Matrix copy constructor instead.

>>> import c4d
>>> import copy

>>> # An identity matrix and its Python object id.
>>> m = c4d.Matrix()
>>> id(m), m
(2671923600768, Matrix(v1: (1, 0, 0); v2: (0, 1, 0); v3: (0, 0, 1); off: (0, 0, 0)))

>>> # We are only creating a reference to the same object.
>>> ref = m
>>> id(ref), ref
(2671923600768, Matrix(v1: (1, 0, 0); v2: (0, 1, 0); v3: (0, 0, 1); off: (0, 0, 0)))

>>> # Cinema's types usually do not work with Python's copy module.
>>> copy.deepcopy(m)
...
TypeError: can't pickle c4d.Matrix objects.

>>> # But we can copy objects via copy constructors.
>>> copy = c4d.Matrix(m)
>>> id(copy), copy
(2671923600512, Matrix(v1: (1, 0, 0); v2: (0, 1, 0); v3: (0, 0, 1); off: (0, 0, 0)))

Attributes

Matrix.v1¶

The X axis of a left-handed coordinate system.

Type: Vector

Matrix.v2¶

The Y axis of a left-handed coordinate system.

Type: Vector

Matrix.v3¶

The Z axis of a left-handed coordinate system.

Type: Vector

Matrix.off¶

The translation vector.

Type: Vector

Methods Signatures

`Matrix.__init__(self[, off, v1, v2, v3])`	Initializes a new `Matrix`.
`Matrix.__str__(self)`	Returns a string representation of the Matrix object.
`Matrix.__add__(self, other)`	Adds two matrices.
`Matrix.__sub__(self, other)`	Subtracts two matrices.
`Matrix.__mul__(self, other)`	Computes the product of the `Matrix` and another type.
`Matrix.__rmul__(self, other)`	Computes the product of another type and the `Matrix`.
`Matrix.__div__(self, other)`	Divides each element in the matrix by a scalar.
`Matrix.__rdiv__(self, other)`	Not implemented.
`Matrix.__invert__(self)`	Inverts the matrix.
`Matrix.__eq__(self, other)`	Checks if two matrices are equal.
`Matrix.__ne__(self, other)`	Checks if two matrices are not equal.
`Matrix.__ge__(self, other)`	raise NotImplemented.
`Matrix.__gt__(self, other)`	raise NotImplemented.
`Matrix.__le__(self, other)`	raise NotImplemented.
`Matrix.__lt__(self, other)`	raise NotImplemented.

`Matrix.Normalize(self)`	Normalizes the frame of the instance.
`Matrix.GetNormalized(self)`	Returns the normalized matrix for the instance.
`Matrix.Mul(self, v)`	Multiply the vector by the matrix, this includes any translation in the matrix.
`Matrix.MulV(self, v)`	Multiply the vector by the matrix, this does not include any translation.
`Matrix.GetTensorMatrix(self)`	Returns the matrix’ tensor.
`Matrix.Scale(self, v)`	Performs uniform matrix scaling (float) or non-uniform matrix scaling (vector).
`Matrix.GetScale(self)`	Returns the scale stored by the matrix.

Methods Documentation

Matrix.__init__(self, off=Vector(0), v1=Vector(1, 0, 0), v2=Vector(0, 1, 0), v3=Vector(0, 0, 1))¶

Initializes a new Matrix.

A Matrix is the type to represent linear transforms in Cinema 4D. A Matrix has four components:

v1 is the x-axis or the basis vector i of the frame of the linear transform defined by an Matrix instance.
v2 is the y-axis or the basis vector j of the frame of the linear transform defined by an Matrix instance.
v3 is the z-axis or the basis vector k of the frame of the linear transform defined by an Matrix instance.
off is the additional translation component for an c4d.Matrix instance.

A matrix can be instantiated in multiple ways, since all its constructor arguments are optional:

>>> # The Matrix constructor with no arguments will give us the identity 
>>> # matrix with the zero vector as the offset.
>>> c4d.Matrix()
Matrix(v1: (1, 0, 0); v2: (0, 1, 0); v3: (0, 0, 1); off: (0, 0, 0)

>>> # Here we define only the frame of the Matrix in its arguments, it 
>>> # will rotate by 90° ccw on the z-axis.
>>> m = c4d.Matrix(v1=c4d.Vector( 0, 1, 0),
                   v2=c4d.Vector(-1, 0, 0),
                   v3=c4d.Vector( 0, 0, 1))
>>> m
Matrix(v1: (0, 1, 0); v2: (-1, 0, 0); v3: (0, 0, 1); off: (0, 0, 0))

>>> # We can also modify components of an instance. 
>>> m.off = c4d.Vector(100, 0, 0)
>>> m
Matrix(v1: (0, 1, 0); v2: (-1, 0, 0); v3: (0, 0, 1); off: (100, 0, 0))

Parameters

off (Optional[c4d.Vector]) – The translation vector.
v1 (Optional[c4d.Vector]) – The X axis of a left-handed coordinate system.
v2 (Optional[c4d.Vector]) – The Y axis of a left-handed coordinate system.
v3 (Optional[c4d.Vector]) – The Z axis of a left-handed coordinate system.

Matrix.__str__(self)¶

Returns a string representation of the Matrix object.

Called if str() is invoked on a Matrix object. See object.__str__() for more information on Python’s data model.

>>> m = c4d.Matrix(v1=c4d.Vector( 0, 1, 0),
                   v2=c4d.Vector(-1, 0, 0),
                   v3=c4d.Vector( 0, 0, 1))
>>> print(m)
Matrix(v1: (0, 1, 0); v2: (-1, 0, 0); v3: (0, 0, 1); off: (0, 0, 0))

Return type: str
Returns: The Vector as string.

Matrix.__add__(self, other)¶

Adds two matrices.

Parameters: other (c4d.Matrix) – The other matrix.
Return type: c4d.Matrix
Returns: The result matrix.

Matrix.__sub__(self, other)¶

Subtracts two matrices.

Parameters: other (c4d.Matrix) – The other matrix.
Return type: c4d.Matrix
Returns: The result matrix.

Matrix.__mul__(self, other)¶

Computes the product of the Matrix and another type.

If other is of type Matrix, it computes the matrix product self * other.
If other is of type Vector, it will return the transform of other by self, including the translation defined in self. 

>>> import math

>>> u = c4d.Vector(1, 0, 0)
>>> quarter_pi = math.pi * .25

>>> # A transform rotating by 90° ccw and translating by 100 units on v3.
M = c4d.Matrix(v1=c4d.Vector(0, 1, 0),
               v2=c4d.Vector(-1, 0, 0),
               v3=c4d.Vector(0, 0, 1),
               off=c4d.Vector(0, 0, 100))

>>> # Transforms u by M, including translations.
>>> M * u
Vector(0, 1, 100)

>>> # A transform rotating by 45° ccw on the x-axis.
>>> X = c4d.utils.MatrixRotX(quarter_pi)
>>> X
Matrix(v1: (1, 0, 0); v2: (0, 0.707, -0.707); v3: (0, 0.707, 0.707); off: (0, 0, 0))

>>> # A transform rotating by 45° cw on the y-axis.
>>> Y = c4d.utils.MatrixRotY(-quarter_pi)
>>> Y
Matrix(v1: (0.707, 0, -0.707); v2: (0, 1, 0); v3: (0.707, 0, 0.707); off: (0, 0, 0))

>>> # A transform rotating by 45° ccw on the z-axis.
>>> Z = c4d.utils.MatrixRotZ(quarter_pi)
>>> Z
Matrix(v1: (0.707, -0.707, 0); v2: (0.707, 0.707, 0); v3: (0, 0, 1); off: (0, 0, 0))

>>> # The product of the three matrices is a matrix rotating by 45° ccw on x, then 45° cw 
>>> # on y and finally by 45° ccw on z.
>>> X * Y * Z
Matrix(v1: (0.5, -0.854, 0.146); v2: (0.5, 0.146, -0.854); v3: (0.707, 0.5, 0.5); off: (0, 0, 0))

>>> # Due to matrix multiplication not being commutative, executing the transforms in a 
>>> # different order will yield another matrix product.
>>> Z * Y * X
Matrix(v1: (0.5, -0.5, -0.707); v2: (0.146, 0.854, -0.5); v3: (0.854, 0.146, 0.5); off: (0, 0, 0))

Parameters: other (Union[c4d.Matrix, c4d.Vector, int, float]) – The other operand.
Return type: Union[c4d.Matrix, c4d.Vector]
Returns: The resulting matrix or vector.

Matrix.__rmul__(self, other)¶

Computes the product of another type and the Matrix.

If other is of type Vector, it will return the transform of other by self, including the translation defined in self. 
If other is a numeric type, it will scale each basis vector in self with it.

>>> u = c4d.Vector(1, 0, 0)

>>> # A transform rotating by 90° ccw and translating by 100 units on v3.
>>> M = c4d.Matrix(v1=c4d.Vector( 0, 1, 0),
                   v2=c4d.Vector(-1, 0, 0),
                   v3=c4d.Vector( 0, 0, 1),
                   off=c4d.Vector(0, 0, 100))

>>> # Transforms u by M, including translations.
>>> u * M
Vector(0, 1, 100)

>>> # Scale each component of M by the factor of two.
>>> 2 * M
Matrix(v1: (0, 2, 0); v2: (-2, 0, 0); v3: (0, 0, 2); off: (0, 0, 200))

Parameters: other (Union[int, float, c4d.Vector]) – The other operand.
Return type: Union[c4d.Vector, c4d.Matrix]
Returns: The resulting matrix or vector.

Matrix.__div__(self, other)¶

Divides each element in the matrix by a scalar.

Parameters: other (float) – The scalar.
Return type: c4d.Matrix
Returns: The result matrix.

Matrix.__rdiv__(self, other)¶

Not implemented.

Raise: TypeError.

Matrix.__invert__(self)¶

Inverts the matrix.

>>> u = c4d.Vector(1, 0, 0)

>>> # A transform rotating by 90° ccw and translating by 100 units on v3.
>>> M = c4d.Matrix(v1=c4d.Vector(0, 1, 0),
                   v2=c4d.Vector(-1, 0, 0),
                   v3=c4d.Vector(0, 0, 1),
                   off=c4d.Vector(0, 0, 100))
>>> M
Matrix(v1: (0, 1, 0); v2: (-1, 0, 0); v3: (0, 0, 1); off: (0, 0, 100))

>>> The inverse of M is the inverse transform of M.
>>> ~M
Matrix(v1: (0, -1, 0); v2: (1, 0, 0); v3: (0, 0, 1); off: (0, 0, -100))

>>> Applying the inverse of M to the point u transformed by M will yield u again.
>>> v = u * M
>>> v
Vector(0, 1, 100)
>>> v * ~M
Vector(1, 0, 0)

Return type: c4d.Matrix
Returns: The inverted matrix.

Matrix.__eq__(self, other)¶

Checks if two matrices are equal.

Parameters: other (c4d.Matrix) – The other matrix.
Return type: bool
Returns: True if matrices are equal.

Matrix.__ne__(self, other)¶

Checks if two matrices are not equal.

Parameters: other (c4d.Matrix) – The other matrix.
Return type: bool
Returns: True if matrices are not equal.

Matrix.__ge__(self, other)¶: raise NotImplemented.

Matrix.__gt__(self, other)¶: raise NotImplemented.

Matrix.__le__(self, other)¶: raise NotImplemented.

Matrix.__lt__(self, other)¶: raise NotImplemented.

Matrix.Normalize(self)¶

Normalizes the frame of the instance.

>>> # A transform rotating by 90° ccw and translating by 100 units on v3.
>>> M = c4d.Matrix(v1=c4d.Vector( 0, 1, 0),
                   v2=c4d.Vector(-1, 0, 0),
                   v3=c4d.Vector( 0, 0, 1),
                   off=c4d.Vector(0, 0, 100))

>>> # Scale each component of M by the factor of two.
>>> N = 2 * M
>>> N
Matrix(v1: (0, 2, 0); v2: (-2, 0, 0); v3: (0, 0, 2); off: (0, 0, 200))

>>> # Normalize the three basis vectors of N, i.e., set them to a length of 1.
>>> N.Normalize()
>>> N
Matrix(v1: (0, 1, 0); v2: (-1, 0, 0); v3: (0, 0, 1); off: (0, 0, 200))

Matrix.GetNormalized(self)¶

Returns the normalized matrix for the instance.

>>> # A transform rotating by 90° ccw and translating by 100 units on v3.
>>> M = c4d.Matrix(v1=c4d.Vector( 0, 1, 0),
                   v2=c4d.Vector(-1, 0, 0),
                   v3=c4d.Vector( 0, 0, 1),
                   off=c4d.Vector(0, 0, 100))


>>> # Scale each component of M by the factor of two.
>>> N = 2 * M
>>> N
Matrix(v1: (0, 2, 0); v2: (-2, 0, 0); v3: (0, 0, 2); off: (0, 0, 200))

>>> # Returns the normalized form of N.
>>> N.GetNormalized()
Matrix(v1: (0, 1, 0); v2: (-1, 0, 0); v3: (0, 0, 1); off: (0, 0, 200))

Return type: c4d.Matrix
Returns: The normalized matrix.

Matrix.Mul(self, v)¶

Multiply the vector by the matrix, this includes any translation in the matrix.

Note

This is a verbose form of Vector.__mul__ <c4d.Vector.__mul__.

Parameters: v (c4d.Vector) – The vector to multiply.
Return type: c4d.Vector
Returns: The resulting vector.

Matrix.MulV(self, v)¶

Multiply the vector by the matrix, this does not include any translation.

Note

This is a verbose form of Vector.__xor__ <c4d.Vector.__xor__.

Parameters: v (c4d.Vector) – The vector to multiply.
Return type: c4d.Vector
Returns: The resulting vector.

Matrix.GetTensorMatrix(self)¶

Returns the matrix’ tensor.

Return type: c4d.Matrix
Returns: The tensor matrix.

Matrix.Scale(self, v)¶

Performs uniform matrix scaling (float) or non-uniform matrix scaling (vector).

Parameters: v (Union[c4d.Vector, float]) – The scaling scalar.

Matrix.GetScale(self)¶

Returns the scale stored by the matrix.

Returns: The scale.
Return type: c4d.Vector