Matrix3D

Canonical path: NemAll_Python_Geometry.Matrix3D

Representation of a 4x4 geometry transformation matrix.

This matrix is used to transform (translate, rotate and scale) 3D geometries and looks like:

\[ \begin{bmatrix} a_{11} & a_{12} & a_{13} & 0 \\ a_{21} & a_{22} & a_{23} & 0 \\ a_{31} & a_{32} & a_{33} & 0 \\ a_{41} & a_{42} & a_{43} & 1 \end{bmatrix} \]

The components \(a_{11}...a_{33}\) are responsible for the rotation and scaling.
The components \(a_{41}...a_{43}\) are responsible for the translation.

Examples:

Assuming, translation_1 is a Matrix3D that translates by 100 units in each X,Y and Z direction.

Use Transform() function to apply the matrix to a geometry:

>>> geometry = Point3D(1, 1, 1)
>>> Transform(Point3D(1, 1, 1), translation_1)
Point3D(101, 101, 101)

Some geometry objects allow to use multiplication operator *, like:

>>> geometry = Point3D(1, 1, 1)
>>> geometry * translation_1
Point3D(101, 101, 101)

Methods:

Determinant –

Calculate determinant
GaussInvert –

Invert the matrix using the Gauss elimination method.
GetScaleX –

Get the scaling factor in the X direction
GetScaleY –

Get the scaling factor in the Y direction
GetScaleZ –

Get the scaling factor in the Z direction
GetScaling –

Get the scaling factors in all directions
GetTranslationVector –

Get translation part of a matrix
GetVectorX –

Get vector X
GetVectorY –

Get vector Y
GetVectorZ –

Get vector Z
IsIdentity –

Check to identity matrix
LaplaceTransform –

Transformation matrix by Laplace
Multiply –

Multiply this matrix with another one, according to the formula:
ReduceZDimension –

Create a 2D matrix from this 3D matrix
Reflection –

Adds a reflection to the current matrix
Reverse –

Reverse the matrix
Rotation –

Adds a rotation to the current matrix
Scaling –

Adds a scaling to the current matrix
SetIdentity –

Set the matrix to identity
SetProjection –

Set the matrix to a projection matrix
SetReflection –

Set the matrix to a reflection matrix
SetRotation –

Overloaded function. See individual overloads.
SetScaling –

Initialize matrix only with scaling factors
SetTranslation –

Set the matrix to a translation matrix
SetValue –

Set a specific matrix component to a value
SetValues –

Sets each matrix-element
Translate –

Adds a translation to the current matrix
Transpose –

Transpose the matrix
__add__ –

Add two matrices, according to the formula:
__eq__ –

Comparison of matrices.
__getitem__ –

Get the matrix element at a specified position
__iadd__ –

Add two matrices in place, according to the formula:
__imul__ –

Multiply two matrices in place, according to the formula:
__init__ –

Overloaded function. See individual overloads.
__isub__ –

Subtract two matrices in place, according to the formula:
__mul__ –

Multiply two matrices, according to the formula:
__repr__ –

Convert to string
__sub__ –

Subtract two matrices, according to the formula:

Determinant

Determinant() -> float

Calculate determinant

Returns:

float –

Determinant.

GaussInvert

GaussInvert() -> bool

Invert the matrix using the Gauss elimination method.

Inverted matrix reverses the transformation applied by the original matrix.

Returns:

bool –

True when operation is successful, otherwise false.

GetScaleX

GetScaleX() -> float

Get the scaling factor in the X direction

Returns:

float –

Scaling factor in the X direction

Examples:

scale is a Matrix3D that scales by 2 in the X direction, 3 in the Y direction and 4 in the Z direction.

>>> scale.GetScaleX()
2.0

GetScaleY

GetScaleY() -> float

Get the scaling factor in the Y direction

Returns:

float –

Scaling factor in the Y direction

Examples:

scale is a Matrix3D that scales by 2 in the X direction, 3 in the Y direction and 4 in the Z direction.

>>> scale.GetScaleY()
3.0

GetScaleZ

GetScaleZ() -> float

Get the scaling factor in the Z direction

Returns:

float –

Scaling factor in the Z direction

Examples:

scale is a Matrix3D that scales by 2 in the X direction, 3 in the Y direction and 4 in the Z direction.

>>> scale.GetScaleZ()
4.0

GetScaling

GetScaling() -> tuple[float, float, float]

Get the scaling factors in all directions

Returns:

float –

Scaling factor in the X direction
float –

Scaling factor in the Y direction
float –

Scaling factor in the Z direction

Examples:

scale is a Matrix3D that scales by 2 in the X direction, 3 in the Y direction and 4 in the Z direction.

>>> scale
Matrix3D(
   2 0 0 0
   0 3 0 0
   0 0 4 0
   0 0 0 1)
>>> scale.GetScaling()
(2.0, 3.0, 4.0)

GetTranslationVector

GetTranslationVector() -> Vector3D

Get translation part of a matrix

Returns:

Vector3D –

The vector of translation

Examples:

translation_1 is a Matrix3D that translates by 100 units in each X,Y and Z direction.

>>> translation_1.GetTranslationVector()
Vector3D(100, 100, 100)

GetVectorX

GetVectorX() -> Vector3D

Get vector X

Returns:

Vector3D –

Vector X

Examples:

rotation_1 is a Matrix3D that rotates by 90° around the Z axis.

>>> rotation_1.GetVectorX()
Vector3D(0, 1, 0)

GetVectorY

GetVectorY() -> Vector3D

Get vector Y

Returns:

Vector3D –

Vector Y

Examples:

rotation_1 is a Matrix3D that rotates by 90° around the Z axis.

>>> rotation_1.GetVectorY()
Vector3D(-1, 0, 0)

GetVectorZ

GetVectorZ() -> Vector3D

Get vector Z

Returns:

Vector3D –

Vector Z

Examples:

rotation_2 is a Matrix3D that rotates by 90° around the X axis.

>>> rotation_2.GetVectorZ()
Vector3D(0, -1, 0)

IsIdentity

IsIdentity() -> bool

Check to identity matrix

Returns:

bool –

Return true when is matrix identity, otherwise false.

Examples:

By default, Matrix3D is an identity matrix:

>>> Matrix3D().IsIdentity()
True

LaplaceTransform

LaplaceTransform()

Transformation matrix by Laplace

Multiply

Multiply(matrix: Matrix3D) -> Matrix3D

Multiply this matrix with another one, according to the formula:

\[ A = A \cdot B \]

Where \(A\) is this matrix and \(B\) is the other matrix.

NOTE: This method is a mutator AND returns the result!

Parameters:

matrix (Matrix3D) –

B matrix

Returns:

Matrix3D –

Product of matrices

ReduceZDimension

ReduceZDimension() -> Matrix2D

Create a 2D matrix from this 3D matrix

Returns:

Matrix2D –

a 2D matrix from this 3D matrix

Examples:

rotation_1 is a Matrix3D that rotates by 90° around the Z axis. When Z dimension is reduced, it can also be applied on 2D geometries:

>>> rotation_1_2d = rotation_1.ReduceZDimension()
>>> Line2D(0, 0, 1, 1) * rotation_1_2d
Line2D(0, 0, -1, 1)

Reflection

Reflection(plane: Plane3D)

Adds a reflection to the current matrix

Parameters:

plane (Plane3D) –

Reflection plane

Examples:

A transformation consisting of translation and reflection can be defined like:

>>> translation_reflection = Matrix3D()
>>> translation_reflection.Translate(Vector3D(100, 100, 100))
>>> translation_reflection.Reflection(Plane3D(Point3D(0, 0, 0), Vector3D(1, 0, 0)))
>>> Point3D(2, 2, 2) * translation_reflection
Point3D(-102, 102, 102)

Reverse

Reverse() -> bool

Reverse the matrix

This method provide geometrical inverse matrix and can not be used with regular inverse 4x4 matrix calculations.

Geometrical representation:

\[ (\vec{P} \cdot A) \cdot A^{-1} = \vec{P} \]

Where \(\vec{P}\) is a point and \(A\) is this matrix.

Returns:

bool –

True when operation is successful, otherwise false.

Rotation

Rotation(line: Line3D, angle: Angle) -> bool

Adds a rotation to the current matrix

Parameters:

line (Line3D) –

Axis of rotation.
angle (Angle) –

Angle of rotation.

Returns:

bool –

True when successful, otherwise false.

Examples:

A transformation consisting of translation and rotation can be defined like:

>>> translation_rotation = Matrix3D()
>>> translation_rotation.Translate(Vector3D(100, 100, 100))
>>> translation_rotation.Rotation(Line3D(0, 0, 0, 1, 0, 0), Angle(pi/2))
True
>>> Point3D(2, 2, 2) * translation_rotation
Point3D(102, -102, 102)

Scaling

Scaling(scaleX: float, scaleY: float, scaleZ: float)

Adds a scaling to the current matrix

Parameters:

scaleX (float) –

Scale in X axis.
scaleY (float) –

Scale in Y axis.
scaleZ (float) –

Scale in Z axis.

Examples:

A transformation consisting of translation and scaling can be defined like:

>>> translation_scaling = Matrix3D()
>>> translation_scaling.Translate(Vector3D(100, 100, 100))
>>> translation_scaling.Scaling(2, 3, 4)
>>> Point3D(2, 2, 2) * translation_scaling
Point3D(204, 306, 408)

SetIdentity

SetIdentity()

Set the matrix to identity

SetProjection

SetProjection(proj: eProjectionMatrixType)

Set the matrix to a projection matrix

A projection matrix rotates the geometry, so that the desired side is facing upwards.

Parameters:

proj (eProjectionMatrixType) –

Projection type

Examples:

A projection matrix of type FRONT_2D rotates the geometry around X axis by -90°, so that the front side is facing upwards:

>>> front_projection = Matrix3D()
>>> front_projection.SetProjection(eProjectionMatrixType.FRONT_2D)
>>> front_projection.GetVectorX(), front_projection.GetVectorY(), front_projection.GetVectorZ()
(Vector3D(1, 0, 0), Vector3D(0, 0, -1), Vector3D(0, 1, 0))

The matrix only rotates the geometry. No translation or scaling is applied:

>>> front_projection.GetTranslationVector(), front_projection.GetScaling()
(Vector3D(0, 0, 0), (1.0, 1.0, 1.0))

SetReflection

SetReflection(plane: Plane3D)

Set the matrix to a reflection matrix

Parameters:

plane (Plane3D) –

Reflection plane

Examples:

A matrix reflecting geometries relative to YZ plane can be defined like:

>>> reflection = Matrix3D()
>>> reflection.SetReflection(Plane3D(Point3D(0, 0, 0), Vector3D(1, 0, 0)))
>>> Point3D(2, 2, 2) * reflection
Point3D(-2, 2, 2)

SetRotation `overloaded`

SetRotation(axis: Line3D, angle: Angle) -> bool

Set the matrix to a rotation matrix by axis and angle

Parameters:

axis (Line3D) –

Axis of rotation.
angle (Angle) –

Angle of rotation.

Returns:

bool –

True when successful, otherwise false.

Examples:

A matrix rotating geometries around X axis by 90° can be defined like:

>>> rotation = Matrix3D()
>>> rotation.SetRotation(Line3D(0, 0, 0, 1, 0, 0), Angle(pi/2))
True
>>> Point3D(2, 2, 2) * rotation
Point3D(2, -2, 2)

SetRotation(startDirection: Vector3D, endDirection: Vector3D) -> bool

Set the matrix to a rotation matrix by start and end vector

Parameters:

startDirection (Vector3D) –

direction vector for start of rotation.
endDirection (Vector3D) –

direction vector for end of rotation.

Returns:

bool –

True when successful, otherwise false.

Examples:

A matrix rotating geometries around X axis by 90° can be defined like:

>>> rotation = Matrix3D()
>>> rotation.SetRotation(Vector3D(0, 1, 0), Vector3D(0, 0, 1))
True
>>> Point3D(2, 2, 2) * rotation
Point3D(2, -2, 2)

SetScaling

SetScaling(scaleX: float, scaleY: float, scaleZ: float)

Initialize matrix only with scaling factors

Parameters:

scaleX (float) –

Scale in X axis.
scaleY (float) –

Scale in Y axis.
scaleZ (float) –

Scale in Z axis.

SetTranslation

SetTranslation(vec: Vector3D)

Set the matrix to a translation matrix

Parameters:

vec (Vector3D) –

Vector of translation.

Examples:

A matrix translating geometries by 100 units in each X,Y and Z direction can be defined like:

>>> translation = Matrix3D()
>>> translation.SetTranslation(Vector3D(100, 100, 100))
>>> Point3D(2, 2, 2) * translation
Point3D(102, 102, 102)

SetValue

SetValue(index: int, value: float) -> bool

Set a specific matrix component to a value

Parameters:

index (int) –

Position index <0..15>
value (float) –

Value to set

Returns:

bool –

True when operation successful (index is not out of range), otherwise false.

SetValues

SetValues(
    v00: float,
    v01: float,
    v02: float,
    v03: float,
    v10: float,
    v11: float,
    v12: float,
    v13: float,
    v20: float,
    v21: float,
    v22: float,
    v23: float,
    v30: float,
    v31: float,
    v32: float,
    v33: float,
)

Sets each matrix-element

Parameters:

v00 (float) –

first row, first element
v01 (float) –

first row, second element
v02 (float) –

first row, third element
v03 (float) –

first row, fourth element
v10 (float) –

second row, first element
v11 (float) –

second row, second element
v12 (float) –

second row, third element
v13 (float) –

second row, fourth element
v20 (float) –

third row, first element
v21 (float) –

third row, second element
v22 (float) –

third row, third element
v23 (float) –

third row, fourth element
v30 (float) –

fourth row, first element
v31 (float) –

fourth row, second element
v32 (float) –

fourth row, third element
v33 (float) –

fourth row, fourth element

Translate

Translate(vec: Vector3D)

Adds a translation to the current matrix

Parameters:

vec (Vector3D) –

Vector of translation.

Examples:

A transformation consisting of rotation and translation can be defined like:

>>> translation_rotation = Matrix3D()
>>> translation_rotation.Rotation(Line3D(0, 0, 0, 1, 0, 0), Angle(pi/2))
True
>>> translation_rotation.Translate(Vector3D(100, 100, 100))
>>> Point3D(2, 2, 2) * translation_rotation
Point3D(102, 98, 102)

Transpose

Transpose()

Transpose the matrix

All transform-services multiply transformation-matrix from the right side. If you need the result as it would be multiplication from the left side you need the transposed matrix.

The matrix is transposed like:

\[ \begin{bmatrix} a_{11} & a_{12} & a_{13} & 0 \\ a_{21} & a_{22} & a_{23} & 0 \\ a_{31} & a_{32} & a_{33} & 0 \\ a_{41} & a_{42} & a_{43} & 1 \end{bmatrix}^T = \begin{bmatrix} a_{11} & a_{21} & a_{31} & a_{41} \\ a_{12} & a_{22} & a_{32} & a_{42} \\ a_{13} & a_{23} & a_{33} & a_{43} \\ 0 & 0 & 0 & 1 \end{bmatrix} \]

add

__add__(matrix: Matrix3D) -> Matrix3D

Add two matrices, according to the formula:

\[ C = A + B \]

Where \(A\) is this matrix

Parameters:

matrix (Matrix3D) –

B matrix

Returns:

Matrix3D –

Addition of matrices

eq

__eq__(matrix: Matrix3D) -> bool

Comparison of matrices.

Be careful, this method work without tolerance!

Parameters:

matrix (Matrix3D) –

matrix to be compared.

Returns:

bool –

True when matrices are equal, otherwise false.

getitem

__getitem__(index: int) -> float

Get the matrix element at a specified position

This method is checked and throwing Geometry::Exception when index is out of range.

Parameters:

index (int) –

Position index <0..15>

Returns:

float –

Returns a matrix element at a specified position.

iadd

__iadd__(matrix: Matrix3D) -> Matrix3D

Add two matrices in place, according to the formula:

\[ A = A + B \]

Where \(A\) is this matrix

Parameters:

matrix (Matrix3D) –

B matrix

Returns:

Matrix3D –

Addition of matrices

imul

__imul__(matrix: Matrix3D) -> Matrix3D

Multiply two matrices in place, according to the formula:

\[ A = A \cdot B \]

Where \(A\) is this matrix

Parameters:

matrix (Matrix3D) –

B matrix

Returns:

Matrix3D –

Product of matrices

init `overloaded`

__init__()

Initialize

__init__(proj: eProjectionMatrixType)

Constructor

Create a matrix for the required projection.

Parameters:

proj (eProjectionMatrixType) –

The required projection

__init__(matrix: Matrix3D)

Copy constructor

Parameters:

matrix (Matrix3D) –

Matrix which will be copied.

__init__(
    v00: float,
    v01: float,
    v02: float,
    v03: float,
    v10: float,
    v11: float,
    v12: float,
    v13: float,
    v20: float,
    v21: float,
    v22: float,
    v23: float,
    v30: float,
    v31: float,
    v32: float,
    v33: float,
)

Constructor setting each matrix-element

Parameters:

v00 (float) –

first row, first element
v01 (float) –

first row, second element
v02 (float) –

first row, third element
v03 (float) –

first row, fourth element
v10 (float) –

second row, first element
v11 (float) –

second row, second element
v12 (float) –

second row, third element
v13 (float) –

second row, fourth element
v20 (float) –

third row, first element
v21 (float) –

third row, second element
v22 (float) –

third row, third element
v23 (float) –

third row, fourth element
v30 (float) –

fourth row, first element
v31 (float) –

fourth row, second element
v32 (float) –

fourth row, third element
v33 (float) –

fourth row, fourth element

__init__(valuesinrows: list)

Constructor

Parameters:

valuesinrows (list) –

matrix values by rows as Python list

isub

__isub__(matrix: Matrix3D) -> Matrix3D

Subtract two matrices in place, according to the formula:

\[ A = A - B \]

Where \(A\) is this matrix

Parameters:

matrix (Matrix3D) –

B matrix

Returns:

Matrix3D –

Addition of matrices

mul

__mul__(matrix: Matrix3D) -> Matrix3D

Multiply two matrices, according to the formula:

\[ C = A \cdot B \]

Where \(A\) is this matrix

Parameters:

matrix (Matrix3D) –

B matrix

Returns:

Matrix3D –

Product of matrices

Examples:

When:

rotation_1 is a Matrix3D that rotates by 90° around the Z axis.
rotation_2 is a Matrix3D that rotates by 90° around the X axis.
translation_1 is a Matrix3D that translates by 100 units in each X,Y and Z direction.

A matrix, that first rotates by 90° around the Z axis, then by 90° around the X axis and finally translates by 100 units in each X,Y and Z direction can be defined like:

>>> rotation_1 * rotation_2 * translation_1
Matrix3D(
   0 0 1 0
   -1 0 0 0
   0 -1 0 0
   100 100 100 1)

repr

__repr__() -> str

Convert to string

sub

__sub__(matrix: Matrix3D) -> Matrix3D

Subtract two matrices, according to the formula:

\[ C = A - B \]

Where \(A\) is this matrix

Parameters:

matrix (Matrix3D) –

B matrix

Returns:

Matrix3D –

Addition of matrices

Placeholder

Matrix3D

Determinant

GaussInvert

GetScaleX

GetScaleY

GetScaleZ

GetScaling

GetTranslationVector

GetVectorX

GetVectorY

GetVectorZ

IsIdentity

LaplaceTransform

Multiply

ReduceZDimension

Reflection

Reverse

Rotation

Scaling

SetIdentity

SetProjection

SetReflection

SetRotation overloaded

SetScaling

SetTranslation

SetValue

SetValues

Translate

Transpose

__add__

__eq__

__getitem__

__iadd__

__imul__

__init__ overloaded

__isub__

__mul__

__repr__

__sub__

SetRotation `overloaded`

add

eq

getitem

iadd

imul

init `overloaded`

isub

mul

repr

sub