c4d.Matrix

class c4d.Matrix

A type to represent a transform.

See also

Matrix Manual

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__()

Initializes a new Matrix.

Matrix.__str__()

Returns a string representation of the Matrix object.

Matrix.__add__()

Adds two matrices.

Matrix.__sub__()

Subtracts two matrices.

Matrix.__mul__()

Computes the product of the Matrix and another type.

Matrix.__rmul__()

Computes the product of another type and the Matrix.

Matrix.__div__()

Divides each element in the matrix by a scalar.

Matrix.__rdiv__()

Not implemented.

Matrix.__invert__()

Inverts the matrix.

Matrix.__eq__()

Checks if two matrices are equal.

Matrix.__ne__()

Checks if two matrices are not equal.

Matrix.__ge__()

raise NotImplemented.

Matrix.__gt__()

raise NotImplemented.

Matrix.__le__()

raise NotImplemented.

Matrix.__lt__()

raise NotImplemented.

Matrix.Normalize()

Normalizes the frame of the instance.

Matrix.GetNormalized()

Returns the normalized matrix for the instance.

Matrix.Mul()

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

Matrix.MulV()

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

Matrix.GetTensorMatrix()

Returns the matrix’ tensor.

Matrix.Scale()

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

Matrix.GetScale()

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