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 p[3]==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 ¶
__init__(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(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(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()
→ tuple
of float
Return the contents of the matrix as a tuple of 16 floats.
asTupleOfTuples()
→ tuple
of tuple
of float
Return the contents of the matrix as a tuple of tuples of 4 floats.
setTo(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()
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()
Set this matrix to contain all zeros.
Note that you can construct a new matrix with all zeros with
hou.Matrix4().
__add__(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__(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__(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(matrix4)
→ hou.Matrix4
Returns matrix4 * self. Note that __mul__ returns self * matrix4,
which is a different result because matrix multiplication is not
commutative.
determinant()
→ float
Return the determinant of the matrix.
explode(transform_order='srt', rotate_order='xyz', pivot=hou.Vector3(), pivot_rotate=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.
pivot_rotate
A Vector3 containing the Euler angles about the x, y, and z axes,
in degrees, that specifies the base rotation about the pivot. These
angles are always processed in 'xyz' order.
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(transform_order='srt', pivot_rotate=hou.Vector3(), pivot=hou.Vector3())
→ hou.Vector3
A shortcut for self.explode(transform_order, hou.Vector3(), pivot, pivot_rotate)['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(transform_order='srt', rotate_order='xyz', pivot=hou.Vector3(), pivot_rotate=hou.Vector3())
→ hou.Vector3
A shortcut for
self.explode(transform_order, rotate_order, pivot, pivot_rotate)['rotate'].
See hou.Matrix4.explode for more information.
extractScales(transform_order='srt', pivot=hou.Vector3(), pivot_rotate=hou.Vector3())
→ hou.Vector3
A shortcut for
self.explode(transform_order, rotate_order, pivot, pivot_rotate)['scale'].
See hou.Matrix4.explode for more information.
extractShears(transform_order='srt', pivot=hou.Vector3(), pivot_rotate=hou.Vector3())
→ hou.Vector3
A shortcut for
self.explode(transform_order, rotate_order, pivot, pivot_rotate)['shear'].
See hou.Matrix4.explode for more information.
extractRotationMatrix3()
→ hou.Matrix3
Extracts the 3×3 rotation matrix from this matrix, assuming it is a transformation matrix. If it fails to extract the rotation, for example if scaling is zero on one axis, it returns the identity matrix instead.
inverted()
→ 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()
→ 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(matrix4, tolerance=0.00001)
→ bool
Return whether this matrix is equal to another, within a tolerance.
setToPerspective(zoom, image_aspect=1, pixel_aspect=1, clip_near=0, clip_far=1, window_xmin=0, window_xmax=1, window_ymin=0, window_ymax=1)
Set this matrix to a perspective projection matrix with the given parameters.
Sometimes the zoom is expressed in terms of focal and aperture. In this case: zoom = focal/aperture. Sometimes the image_aspect is expressed in terms of xres and yres. In this case: image_aspect = xres / yres.
setToOrthographic(zoom, orthowidth=1, image_aspect=1, pixel_aspect=1, clip_near=0, clip_far=1, window_xmin=0, window_xmax=1, window_ymin=0, window_ymax=1)
Set this matrix to an orthographic projection matrix with the given parameters.
Sometimes the zoom is expressed in terms of focal and aperture. In this case: zoom = focal/aperture. Sometimes the image_aspect is expressed in terms of xres and yres. In this case: image_aspect = xres / yres.
| See also |