paya.runtime.plugs.Matrix#

class Matrix(*args, **kwargs)#

Inheritance

Math Attribute Attribute PyNode ProxyUnicode

createLocator(size=1.0, name=None)#

Creates a locator and drives its SRT channels using this matrix.

Shorthand

cl

Parameters

name/n (str) – an optional name for the locator transform; defaults to a contextual name
size/siz (float) – the locator display scale; defaults to 1.0

Returns

The locator.

Return type

Transform

__add__(other, swap=False)#

Implements addition (+).

Parameters: other – a 16D value or plug

__radd__(other)#: Implements reflected addition (+). See __add__().

mul(*others)#

Multiplies this matrix in a chained manner with *others.

Parameters: others (str, Matrix, Matrix, [list]) – the other matrices (unpacked list)
Returns: Matrix

__mul__(other, swap=False)#

Implements multiplication (*).

Parameters: other – a value or plug of dimension 3 (left only) or 16.

__rmul__(other)#: Implements reflected multiplication (*). See __mul__().

__rxor__(other)#

Uses the exclusive-or operator (^) to implement point-matrix multiplication (reflected only).

Parameters: other – a 3D value or plug

normal()#

Returns: A version of this matrix with all axis vectors normalized.
Return type: Matrix

pick(translate=None, rotate=None, scale=None, shear=None, default=None)#

Filters this matrix through one or more pickMatrix nodes, depending on combinations with ‘default’. Flags are defined by omission, Maya-style.

Shorthand

Parameters

translate/t (bool) – use translate
rotate/r (bool) – use rotate
scale/s (bool) – use scale
shear/sh – use shear
default (list, Matrix, str, Matrix) – take omitted fields from this matrix; can be a value or plug; defaults to None

Returns

The filtered matrix.

Return type

Matrix

inverse()#

Returns: The inverse of this matrix.
Return type: Matrix

asOffset()#

Inverts this matrix once, to create an offset matrix. Equivalent to:

self.get().inverse() * self

Returns: The offset matrix.
Return type: Matrix

getAxis(axis, normalize=False)#

Extracts the specified axis from this matrix as a vector output. If this is the output attribute of a fourByFourMatrix node, the method will defer to methods in FourByFourMatrix.

Used to implement the following properties: x, y, z and translate/t. The property versions will always return non-normalized outputs.

Parameters

axis (str) – the axis to extract, one of ‘x’, ‘y’, ‘z’, ‘-x’, ‘-y’, ‘-z’ or ‘translate’ / ‘t’.
normalize (bool) – normalize the extracted vector; defaults to False

Returns

Math3D

getX(normalize=False)#

Extracts the X vector. Used to implement the x property.

Parameters: normalize (bool) – normalize the output; defaults to False
Returns: the extracted vector
Return type: Vector

getY(normalize=False)#

Extracts the Y vector. Used to implement the y property.

Parameters: normalize (bool) – normalize the output; defaults to False
Returns: the extracted vector
Return type: Vector

getZ(normalize=False)#

Extracts the Z vector. Used to implement the z property.

Parameters: normalize (bool) – normalize the output; defaults to False
Returns: the extracted vector
Return type: Vector

getTranslate(normalize=False)#

Extracts the translation component. Used to implement the translate / t property.

Parameters: normalize (bool) – normalize the output; defaults to False
Returns: the extracted translation
Return type: Math3D

transpose()#

Returns: The transposition of this matrix.
Return type: Matrix

decompose(rotateOrder='xyz')#

Connects and configures a decomposeMatrix node.

Parameters: rotateOrder/ro (str, int, Math1D) – the rotate order to apply; defaults to ‘xyz’
Returns: dictionary of {channelName:decomposeMatrixOutput}
Return type: dict

decomposeAndApply(*slaves, translate=None, rotate=None, scale=None, shear=None, compensatePivots=False, compensateJointOrient=True, compensateRotateAxis=False, compensateJointScale=True, worldSpace=False, maintainOffset=False)#

Decomposes and applies this matrix to one or more slave transforms.

Parameters

*slaves (Transform, str) – one or more transforms to drive
translate/t (bool) – apply translation
rotate/r (bool) – apply rotation
scale/s (bool) – apply scale
shear/sh (bool) – apply shear
maintainOffset/mo (bool) – maintain relative pose; defaults to False
worldSpace/ws (bool) – premultiply this matrix with parentInverseMatrix on the transform to negate the parent stack; defaults to False
compensateJointScale/cjs (bool) – account for segmentScaleCompensate on joints; defaults to True
compensateJointOrient/cjo (bool) – account for jointOrient on joints; defaults to True
compensateRotateAxis/cra (bool) – account for rotateAxis; defaults to False
compensatePivots/cp (bool) – compensate for pivots (non-joint transforms only); this is expensive, so defaults to False

Returns

self

Return type

Matrix

applyViaOpm(*slaves, worldSpace=False, persistentCompensation=False, preserveInheritsTransform=False, maintainOffset=False)#

Uses this matrix to drive one or more transforms via connections into offsetParentMatrix, with compensations against the transforms’ SRT channels.

Warning

When worldSpace is combined with preserveInheritsTransform, the matrix will only be localised against the current parent. The solution will break if the transform is subsequently reparented.

Parameters

*slaves (Transform, str) – one or more transforms to drive
worldSpace/ws (bool) – drive the slaves in world-space; defaults to False
maintainOffset/mo (bool) – preserve relative pose on application; defaults to False
persistentCompensation/pc (bool) – compensate for the transform’s SRT channels persistently, so that the world pose will remain the same even if they change; defaults to False
preserveInheritsTransform/pit – when worldSpace is requested, don’t edit the inheritsTransform attribute on the transform; instead, localise against the current parent; defaults to False

Returns

self

Return type

Matrix

drive(*slaves, worldSpace=False, maintainOffset=False, useOffsetParentMatrix=<undefined>, preserveInheritsTransform=False)#

Drives one or more slaves using this matrix.

Parameters

*slaves (Transform, str) – one or more transforms to drive
worldSpace/ws (bool) – drive the slaves in world-space; defaults to False
preserveInheritsTransform/pit – when worldSpace is requested, don’t edit the inheritsTransform attribute on the slave; instead, localise against its current parent; defaults to False
maintainOffset/mo (bool) – preserve relative pose on application; defaults to False
useOffsetParentMatrix/uop (bool) – connect into offsetParentMatrix instead of decomposing into SRT channels; defaults to namesake configuration flag; it that’s omitted too, defaults to True if Maya >= 2022, otherwise False

Returns

self

Return type

Matrix

hold()#

Connects a holdMatrix node and returns its output.

This is useful in situations where a method such as pick() has nothing to do, but must return a new output to protect code branching.

Returns: The output of a holdMatrix node.
Return type: HoldMatrix

blend(other, weight=0.5)#

Blends this matrix towards other. When weight is at 1.0, other will take over completely.

Parameters

other (list [float], Matrix, Matrix) – the matrix towards which to blend.
weight/w (Math1D, float) – the blending weight; defaults to 0.5

Returns

The blended matrix.

Return type

Matrix

asEulerRotation(rotateOrder='xyz')#

Returns the euler decomposition of this matrix.

Parameters: rotateOrder/ro (int, str, Math1D) – The rotate order, defaults to 'xyz'
Returns: The Euler rotation output.
Return type: Math3D

asQuaternion()#

Returns a quaternion output for this matrix’s rotation.

Returns: The quaternion.
Return type: Quaternion