hou.Matrix4

A 4×4 matrix of floating point values.

4×4 matrices are typically used in Houdini to represent a 3D transformation (e.g. some combination of rotation, scaling, shearing, and translation). A single matrix compactly represents a transformation, and is much easier to deal with than multiple translate, rotate, scale, shear, transformation order, and rotation order values.

Note that Houdini’s matrices are stored in row-major format, and vectors that are multiplied with matrices are treated as row vectors. So, if p is a hou.Vector4 representing a point and M is a Matrix4, you write p*M, not M*p. Similarly, p*M1*M2 will first transform p by M1, and then transform it by M2.

Note

Most mathematical notations treat vectors and points as column vectors instead of row vectors. They will often use A*B*C (or simply ABC) to refer to a combined transform that first applies C's transform, then B's, and then applies A's. However, the convention is different in Houdini. To represent the equivalent matrix expression in Houdini, you need to concatenate the transforms in the reverse order. So, you would instead write C'*B'*A', where C', B', A' are the transpose of C, B, A respectively.

You can multiply Vector3s or Vector4s by Matrix4s. If you multiply a Vector3, it is the same as multiplying a Vector4 where the fourth component is 1 (see hou.Vector3.__mul__).

To transform a normal (as opposed to a point or vector), you need to multiply by the inverse transpose of the matrix. For example, suppose:

`p`	is a hou.Vector3 object representing a position (or a hou.Vector4 with `v[4]==1`)
`v`	is a hou.Vector4 object representing a vector (a direction with a length but no fixed location in space), with `v[3]==0`
`n`	is a hou.Vector4 object representing a normal, with `v[3]==0`
`m`	is a Matrix4 object representing a transform matrix

Then you would write:

p * m # to transform the point
v * m # to transform the vector
n * m.inverted().transposed() # to transform the normal
# (note that m.inverted().transposed() is mathematically equivalent to m.transposed().inverted())

Here is a concrete example:

>>> m = hou.hmath.buildTranslate((1, 1, 2))
>>> m
<hou.Matrix4 [[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [1, 1, 2, 1]]>
>>> p = hou.Vector3(1, 2, 3)
>>> p * m
<hou.Vector3 [2, 3, 5]>

Both VEX and the UT_DMatrix4 class in the Houdini Development Kit (HDK) also store matrices in row-major format.

Methods

__add__	Add two matrices by adding corresponding entries together and return a new matrix. This method lets you write m1 + m2, where m1 and m2 are Matrix4 objects.
__init__	Return a new Matrix4. You can pass no parameters (the result will contain all zeros), a float (the result’s diagonal values will contain that float and the rest is all zeros), a sequence of 16 floats, a sequence of sequences of 4 floats, or a hou.Matrix3.
__mul__	Multiply this matrix by another matrix or by a scalar, returning a new matrix. This method lets you write m1 * m2, where m1 and m2 are Matrix4 objects, or m1 * s, where s is a float.
__sub__	Subtract another matrix from this one, subtracting corresponding entries, and return a new matrix. This method lets you write m1 - m2, where m1 and m2 are Matrix4 objects.
asTuple	Return the contents of the matrix as a tuple of 16 floats.
asTupleOfTuples	Return the contents of the matrix as a tuple of tuples of 4 floats.
at	Return the value of the matrix at the given row and column.
determinant	Return the determinant of the matrix.
explode	Return a dictionary with keys 'rotate', 'scale', 'translate', and 'shear' whose values are hou.Vector3 objects. When applied in the specified order, the corresponding rotations, scales (and shears), and translations will give this matrix.
extractRotates	A shortcut for self.explode(transform_order, rotate_order, pivot)['rotate']. See hou.Matrix4.explode for more information.
extractScales	A shortcut for self.explode(transform_order, rotate_order, pivot)['scale']. See hou.Matrix4.explode for more information.
extractShears	A shortcut for self.explode(transform_order, rotate_order, pivot)['shear']. See hou.Matrix4.explode for more information.
extractTranslates	A shortcut for self.explode(transform_order)['translate']. See hou.Matrix4.explode for more information.
inverted	Return the inverse of this matrix.
isAlmostEqual	Return whether this matrix is equal to another, within a tolerance.
preMult	Returns matrix4 * self. Note that __mul__ returns self * matrix4, which is a different result because matrix multiplication is not commutative.
setAt	Set the value of the matrix at the given row and column.
setTo	Set this matrix’s contents. The sequence may contain either 16 floats or 4 sequences, each with 4 floats.
setToIdentity	Set this matrix to the multiplicative identity, having 1’s in the diagonal.
setToZero	Set this matrix to contain all zeros.
transposed	Return the transpose of this matrix. The result is such that self.at(i, j) == self.transposed().at(j, i) for 0 <= i,j <= 3.

__init__(self, values)

Return a new Matrix4. You can pass no parameters (the result will contain all zeros), a float (the result’s diagonal values will contain that float and the rest is all zeros), a sequence of 16 floats, a sequence of sequences of 4 floats, or a hou.Matrix3.

>>> hou.Matrix4()
<hou.Matrix4 [[0, 0, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0], [0, 0, 0, 0]]>

>>> hou.Matrix4(1)
<hou.Matrix4 [[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]]>

>>> hou.Matrix4((0, 1, 2, 3, 4, 5, 6, 7, 8, 9, 10, 11, 12, 13, 14, 15))
<hou.Matrix4 [[0, 1, 2, 3], [4, 5, 6, 7], [8, 9, 10, 11], [12, 13, 14, 15]]>

>>> hou.Matrix4(((0, 1, 2, 3), (4, 5, 6, 7), (8, 9, 10, 11), (12, 13, 14, 15)))
<hou.Matrix4 [[0, 1, 2, 3], [4, 5, 6, 7], [8, 9, 10, 11], [12, 13, 14, 15]]>

>>> matrix3 = hou.Matrix3((0, 1, 2, 3, 4, 5, 6, 7, 8))
>>> matrix3
<hou.Matrix3 [[0, 1, 2], [3, 4, 5], [6, 7, 8]]>
>>> hou.Matrix4(matrix3)
<hou.Matrix4 [[0, 1, 2, 0], [3, 4, 5, 0], [6, 7, 8, 0], [0, 0, 0, 1]]>

Note that Houdini’s matrices are stored in row-major order, so the matrix’s contents are grouped by row.

at(self, row, col) → float

Return the value of the matrix at the given row and column.

Raises IndexError if the row or column are not between 0 and 3, inclusive. Note that negative indices will not index from the end.

setAt(self, row, col, value)

Set the value of the matrix at the given row and column.

Raises IndexError if the row or column are not between 0 and 3, inclusive. Note that negative indices will not index from the end.

asTuple(self) → tuple of float

Return the contents of the matrix as a tuple of 16 floats.

asTupleOfTuples(self) → tuple of tuple of float

Return the contents of the matrix as a tuple of tuples of 4 floats.

setTo(self, sequence)

Set this matrix’s contents. The sequence may contain either 16 floats or 4 sequences, each with 4 floats.

See hou.Matrix4.__init__ for examples of suitable parameter values.

setToIdentity(self)

Set this matrix to the multiplicative identity, having 1’s in the diagonal.

The matrix will contain the values [[1, 0, 0, 0], [0, 1, 0, 0], [0, 0, 1, 0], [0, 0, 0, 1]]. Note that you can construct a new matrix with these values using hou.hmath.identityTransform or hou.Matrix4(1).

setToZero(self)

Set this matrix to contain all zeros.

Note that you can construct a new matrix with all zeros with hou.Matrix4().

__add__(self, matrix4) → hou.Matrix4

Add two matrices by adding corresponding entries together and return a new matrix. This method lets you write m1 + m2, where m1 and m2 are Matrix4 objects.

__sub__(self, matrix4) → hou.Matrix4

Subtract another matrix from this one, subtracting corresponding entries, and return a new matrix. This method lets you write m1 - m2, where m1 and m2 are Matrix4 objects.

__mul__(self, matrix4_or_scalar) → hou.Matrix4

Multiply this matrix by another matrix or by a scalar, returning a new matrix. This method lets you write m1 * m2, where m1 and m2 are Matrix4 objects, or m1 * s, where s is a float.

If m1 and m2 are transformation matrices and v is a vector, v * m1 * m2 will transform v by m1, and then transform it by m2. This ordering occurs because Houdini’s Matrices are stored in row-major format, and is opposite from the ordering used in traditional mathematical notation. Note that m1 * v is not a valid expression in Houdini

See the Matrix4 class documentation and hou.Vector3.__mul__ for more information. See Wikipedia’s matrix multiplication page for details on how each element in the result is computed.

preMult(self, matrix4) → hou.Matrix4

Returns matrix4 * self. Note that __mul__ returns self * matrix4, which is a different result because matrix multiplication is not commutative.

determinant(self) → float

Return the determinant of the matrix.

See Wikipedia’s determinant page.

explode(self, transform_order='srt', rotate_order='xyz', pivot=hou.Vector3()) → dict of str to hou.Vector3

Return a dictionary with keys 'rotate', 'scale', 'translate', and 'shear' whose values are hou.Vector3 objects. When applied in the specified order, the corresponding rotations, scales (and shears), and translations will give this matrix.

The rotation is returned as a set of Euler angles, in degrees. See Wikipedia’s Euler angles page for more information.

transform_order

A string containing a permutation of the letters s, r, and t. The rotate, scale, and translate results are dependent on the order in which you perform those operations, and this string specifies that order.

For example, imagine a transformation where you first translate in x by one unit, then you rotate in z by 45 degrees. With a transform order of 'trs' (translate, rotate, scale), the translate component is (1, 0, 0). However, this same transformation could be constructed, for example, by first scaling, then rotating, and then translating. For this transformation order, the translate component would be (1.0 / math.sqrt(2), 1.0 / math.sqrt(2), 0).

rotate_order

A string containing a permutation of the letters x, y, and z that determines the order in which rotations are performed about the coordinate axes.

pivot

A Vector3 containing a position about which rotations and scales are performed. By default, this parameter is set to the origin.

Raises hou.OperationFailed if the matrix does not represent a valid transform matrix (e.g. it is singular), the transform order is not a permutation of the string 'srt', or the rotate order is not a permutation of the string 'xyz'.

See hou.hmath.buildRotateAboutAxis for an example of how to convert Euler angles into an axis and rotation.

See hou.ObjNode.setParmTransform for an example. This method is the inverse of hou.hmath.buildTransform. See also the other functions in hou.hmath that build transformation matrices.

extractTranslates(self, transform_order='srt') → hou.Vector3

A shortcut for self.explode(transform_order)['translate']. See hou.Matrix4.explode for more information.

>>> matrix = hou.hmath.buildTranslate(1, 0, 0) * hou.hmath.buildRotate(0, 0, 45)
>>> matrix.extractTranslates('trs')
<hou.Vector3 [4, 0, 0]>
>>> matrix.extractTranslates('srt')
<hou.Vector3 [0.707107, 0.707107, 0]>

extractRotates(self, transform_order='srt', rotate_order='xyz', pivot=hou.Vector3()) → hou.Vector3

A shortcut for self.explode(transform_order, rotate_order, pivot)['rotate']. See hou.Matrix4.explode for more information.

extractScales(self, transform_order='srt', pivot=hou.Vector3()) → hou.Vector3

A shortcut for self.explode(transform_order, rotate_order, pivot)['scale']. See hou.Matrix4.explode for more information.

extractShears(self, transform_order='srt', pivot=hou.Vector3()) → hou.Vector3

A shortcut for self.explode(transform_order, rotate_order, pivot)['shear']. See hou.Matrix4.explode for more information.

inverted(self) → hou.Matrix4

Return the inverse of this matrix.

Raises hou.OperationFailed if the matrix is not invertible. Otherwise, (self * self.inverted()).isAlmostEqual(hou.hmath.identityTransform()) is True.

See Wikipedia’s invertible matrix page for more information.

transposed(self) → hou.Matrix4

Return the transpose of this matrix. The result is such that self.at(i, j) == self.transposed().at(j, i) for 0 <= i,j <= 3.

See Wikipedia’s transpose page for more information.

isAlmostEqual(self, matrix4, tolerance=0.00001) → bool

Return whether this matrix is equal to another, within a tolerance.

hou.Matrix4 class

Methods