paya.runtime.data.Matrix#

class Matrix(*args, **kwargs)#

Inheritance

Matrix MatrixN Array MMatrix

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

decompose(rotateOrder='xyz')#

Decomposes this matrix.

Parameters: rotateOrder/ro (str, int) – the rotate order to apply; defaults to ‘xyz’
Returns: dictionary of {channelName: Point, Vector or EulerRotation}
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 transform slaves.

Parameters

*slaves (Transform, str) – one or more transforms to pose
translate/t (bool) – apply translation
rotate/r (bool) – apply rotation
scale/s (bool) – apply scale
shear/sh (bool) – apply shear
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); defaults to False
worldSpace/ws (bool) – premultiply this matrix with the inverse of the transform’s parent matrix to negate the parent stack; defaults to False
maintainOffset/mo (bool) – this is here for parity with paya.runtime.plugs.Matrix.decomposeAndApply(); when True, the transform won’t be modified at all; defaults to False

Returns

self

Return type

Matrix

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

Poses one or more transforms by modifying their offsetParentMatrix attribute, with SRT channels compensated.

Parameters

*slaves (Transform, str) – one or more transforms to pose
worldSpace/ws (bool) – drive the transform in world-space; defaults to False
persistentCompensation/pc (bool) – unused; here for parity with paya.runtime.plugs.Matrix.applyViaOpm()
preserveInheritsTransform/pit – when worldSpace is requested, don’t edit the inheritsTransform attribute on the slave; instead, localise against the current parent; defaults to False
maintainOffset/mo (bool) – this is here for parity with paya.runtime.plugs.Matrix.applyViaOpm(); if set to True, no action will be taken, and self will be returned; defaults to False

Returns

self

Return type

Matrix

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

Poses one or more slaves using this matrix. (For the dynamic, true attachment, see paya.runtime.plugs.Matrix.attach.)

Parameters

*slaves (Transform, str) – one or more transforms to pose
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) – this is here for parity with paya.runtime.plugs.Matrix.attach(); if set to True, no action will be taken, and self will be returned; 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

__add__(other)#

Implements addition (+).

Overloads pymel.core.datatypes.Matrix.__add__() to add support for 16D plugs.

__radd__(other)#

Implements reflected addition (+).

Overloads pymel.core.datatypes.Matrix.__add__() to add support for 16D plugs.

__mul__(other)#

Implements multiplication (*).

Overloads pymel.core.datatypes.Matrix.__mul__() to add support for 16D plugs.

__rmul__(other)#

Implements reflected multiplication (*).

Overloads pymel.core.datatypes.Matrix.__rmul__() to add support for 3D and 16D plugs as well as simple types.

__rxor__(other)#: Uses the exclusive-or operator (^) to implement point-matrix multiplication for 3D values and plugs.

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, similar to Maya’s pickMatrix. If ‘default’ is used, and it’s a plug, the output will also be a plug.

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 or Matrix

classmethod asOffset()#: Implemented for parity with paya.runtime.plugs.Matrix.asOffset(). Returns an identity matrix.

getAxis(axis, normalize=False)#

Extracts the specified axis from this matrix as a vector or point value. Used to implement the following properties: x, y, z and translate/t. The property versions will always return non-normalized values.

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

Vector, Point

setAxis(axis, vals)#

Sets the values for the specified axis row. Used to implement the following properties: x, y, z and translate/t.

Parameters

axis (str) – the axis to extract, one of ‘x’, ‘y’, ‘z’, ‘-x’, ‘-y’, ‘-z’ or ‘translate’ / ‘t’.
vals (Vector, Point, list) – the values to assign to the row

getX(normalize=False)#: Equivalent to getAxis('x'). Getter for the x property.

setX(vals)#: Equivalent to setAxis('x'). Setter for the x property.

getY(normalize=False)#: Equivalent to getAxis('y'). Getter for the y property.

setY(vals)#: Equivalent to setAxis('y'). Setter for the y property.

getZ(normalize=False)#: Equivalent to getAxis('z'). Getter for the z property.

setZ(vals)#: Equivalent to setAxis('z'). Setter for the z property.

getTranslate(normalize=False)#: Equivalent to getAxis('translate'). Getter for the translate/t property.

setTranslate(vals)#: Equivalent to setAxis('translate'). Setter for the translate/t property.

closestAxisToVector(vector)#

Returns: The axis on this matrix that’s most closely aligned to the given reference vector, e.g. ‘-x’.
Return type: str