paya.lib.mathops#

flipAxis(axis)#

Flips an axis letter, for example from -x to x.

Parameters: axis (str) – the axis to flip (e.g. y or -z)
Returns: The flipped axis letter.
Return type: str

absAxis(axis)#

Equivalent to:

axis.strip('-')

Parameters: axis (str) – the axis to strip
Returns: The stripped axis.
Return type: str

missingAxis(*axes)#

Given two axes (lowercase), returns the missing one. Negative signs are stripped / ignored.

Parameters: *axes (str, list [str]) – the two available axes
Returns: The missing axis.
Return type: str

inventRotateOrder(downAxis, upAxis)#

Returns an ‘optimal’ rotate order based on the given down and up axes.

Parameters

downAxis (str) – the down axis, e.g. 'y'
upAxis (str) – the up axis, e.g. 'x'

Returns

The rotate order, e.g. 'yxz'.

Return type

:class:str

degToUI(val)#

Parameters: val (float) – An angle value in degrees.
Returns: If the UI is set to radians, val converted to radians; otherwise, the original val.
Return type: float

getUIAngleUnit()#

Returns: The current angle unit. Note that this will be returned in a format that can be passed along to the data type constructors (e.g. ‘degrees’) rather than how it’s returned by currentUnit() (e.g. ‘deg’).
Return type: str

getUIDistanceUnit()#

Returns: The current distance unit. Note that this will be returned in a format that can be passed along to the data type constructors (e.g. ‘centimeters’) rather than how it’s returned by currentUnit() (e.g. ‘cm’).
Return type: str

getUITimeUnit()#

Returns: The current time unit. Note that this will be returned in a format that can be passed along to the data type constructors (e.g. ‘24FPS’) rather than how it’s returned by currentUnit() (e.g. ‘film’).
Return type: str

onRadians()#

Returns: True if the UI is set to radians, otherwise False.
Return type: bool

mathInfo(item)#

Deprecated; here for backward compatibility.

Equivalent to:

values = list(info(item).values())
return [values[0], values[1], values[3]]

info(item, defaultUnitType=None, quiet=False)#

Returns a dict with the following keys (ordered):

'item': The item, conformed to the most specific Paya type possible.
'dimension': One of 1, 2, 3, 4 or 16.
'unitType': One of 'angle', 'distance', 'time' or None.
'isPlug': True or False.

Value conforming is performed in the following way:

If item is a bool, it’s returned as-is.
If item is a float or int, it’s returned as-is unless a defaultUnitType is specified, in which case a Angle, Distance or Time instance is returned. UI units are used in every case.
If item is a list of floats or ints, then:
- If its dimension is 3 then, if defaultUnitType is set to 'angle', it’s instantiated as EulerRotation; otherwise, as Vector.
- If its dimension is 4, then it’s always returned as a Quaternion.
- If its dimension is 16, then it’s always returned as a Matrix.
- In all other cases, it’s returned as a list with members intact.

Plugs are returned as Attribute instances, with the subtype / unit strictly based on MPlug analysis performed by paya.pluginfo.

Parameters

item – The item to inspect and conform.
defaultUnitType/dut (str, None) – one of 'angle', 'distance', 'time' or None.
quiet (bool) – don’t throw an error if item can’t be conformed to a math type, just pass-through the incomplete dictionary with the 'item' field populated with the original item

Returns

The dictionary.

Return type

dict

floatRange(start, end, numValues)#

A variant of Python’s range for floats and float plugs.

Parameters

start (float, Math1D) – the minimum value
end (float, Math1D) – the maximum value
numValues (int) – the number of values to generate

Returns

A list of float values between start and end, inclusively.

Return type

[float | Math1D]

class LinearInterpolator(*args, **kwargs)#

Inheritance

UserDict MutableMapping Mapping Collection Sized Iterable Container

Simple, dict-like interpolator implementation, similar to a linear animation curve in Maya. Works with any value type that can be handled by pymel.util.arrays.blend(), but types should not be mixed.

Example

interp = LinearInterpolator()
interp[10] = 30
interp[20] = 40
print(interp[11])
# Result: 31.0

chaseNones(source)#

Resolves None members in an iterable by filling in with neighbouring values. If the first member is None, the next defined value is used. If any internal member is None, the last resolved value is used.

Parameters: source – the iterable to fill-in
Returns: A list with no None members.
Return type: list

blendNones(source, ratios=None)#

A blending version of chaseNones().

Parameters

source – the iterable to fill-in
ratios – if provided, it should be a list of ratios from 0.0 to 1.0 (one per member) to bias the blending; if omitted, it will be autogenerated using floatRange(); defaults to None

Returns

A list with no None members.

Return type

list

blendScalars(scalarA, scalarB, weight=0.5)#

Blends between two scalar values or plugs.

Parameters

scalarA (float, str, Math1D) – the first scalar
scalarB (float, str, Math1D) – the second scalar
weight/w (float, str, Math1D) – the weight; when this is at 1.0, scalarB will have fully taken over; defaults to 0.t

Returns

multMatrices(*matrices)#

Performs efficient multiplication of any combination of matrix values or plugs. Consecutive values are reduced and consecutive plugs are grouped into multMatrix nodes.

If any of the matrices are plugs, the return will also be a plug. Otherwise, it will be a value.

Parameters: *matrices (Matrix, Matrix, list or str) – the matrices to multiply (unpacked)
Returns: The matrix product.
Return type: paya.runtime.data.Matrix or paya.runtime.plugs.Matrix

createMatrix(*rowHints, manageScale=True, preserveSecondLength=False, thirdLength=None, translate=None, plug=None)#

Constructs static or dynamic transformation matrices.

Shorthand

cm

Parameters

*rowHints –
If provided, this must comprise exactly four or five arguments, in both cases passed as unpacked pairs of row identifier: vector input or value.

If four arguments are passed, they will be used to construct an orthogonal matrix, with the first vector as the ‘aim’ and the second as the ‘up’, for example:
```
matrix = r.createMatrix('y', loc1.t, 'x', loc2.t)
```
If six arguments are passed, they will be used to directly populate the matrix rows. This may result in a non-orthornormal (shear) matrix.
```
matrix = r.createMatrix('y', loc1.t, 'x', loc2.t, 'z', loc3.t)
```
If this argument is omitted, an identity matrix will be returned.
translate/t (str, list, tuple, Vector, Point, Math3D) – A translate component for the matrix; this can be a point value or plug; defaults to None
manageScale/ms (bool) – set this to False to allow scale to be defined by incidental operations; useful when you intend to discard scale later anyway; defaults to True
preserveSecondLength/psl (bool) – ignored if six arguments were passed; preserve the second vector’s length when performing orthogonal construction; defaults to True
thirdLength/tl (None, float, int, Math1D, str) – ignored is six arguments were passed; if provided, defines the third (derived) vector’s length; defaults to None
plug/p (bool) – if you already know whether the passed arguments contain plugs, specify it here to avoid extraneous checks; if no arguments have been passed, this will specify whether the returned identity matrix is a plug or value; defaults to None

Returns

The constructed matrix.

Return type

paya.runtime.plugs.Matrix or paya.runtime.data.Matrix, depending on inputs.

createScaleMatrix(*args)#

Quick(er) method to create static or dynamic scale matrices. Takes one, three or six arguments.

Shorthand

csm

Parameters

*args –

If one argument is passed, the same scaling factor will be applied to the XYZ base vectors.

If three arguments are passed, they will each be applied to the XYZ base vectors.

If six arguments are passed then they will be interpreted as axis: scalar pairs.

Returns

The scale matrix.

Return type

paya.runtime.data.Matrix or paya.runtime.plugs.Matrix.

deflipVectors(vectors)#

Returns a list where each vector is flipped if that would bring it closer to the preceding one. This is a value-only method.

Parameters: vectors ([tuple, list, Vector]) – the source vectors (values)
Returns: The deflipped vectors.
Return type: [Vector]

getAimVectors(points)#

Parameters: points ([list, tuple, Point, Vector]) – the points
Raises: ValueError – Fewer than two points were provided.
Returns: Aiming vectors derived from the input points. The output list will always be one member shorter than the input list.

pointsIntoUnitCube(points)#

Parameters: points ([tuple, list, Point]) – the points to normalize
Returns: The points, fit inside a unit cube.
Return type: [Point]

getFramedAimAndUpVectors(points, upVector, tolerance=1e-07)#

Value-only method.

Returns paired lists of aim and up vectors based on points and upVector, which can be a single vector or one vector per point.

The final up vectors are derived using cross products, and biased towards the provided hints. Where the points are in-line, cross products are either blended from neighbours or swapped out for the user up vectors.

Parameters

points ([tuple, list, Point]) – the starting points
upVector (tuple, list, Vector) – one up hint vector, or one vector per point
tolerance/tol (bool) – any cross products below this length will be interpolated from neighbours; defaults to 1e-7

Returns

A list of aim vectors and a list of up vectors.

Return type

([Vector], [Vector])

getChainedAimMatrices(points, aimAxis, upAxis, upVector, squashStretch=False, globalScale=None, framed=False, tolerance=1e-07)#

Parameters

points – the starting points
aimAxis – the matrix axes to align to the aiming vectors, for example ‘-y’.
upAxis – the matrix axes to align to the resolved up vectors, for example ‘x’
upVector – either one up vector hint, or a list of up vectors (one per point)
squashStretch (bool) – allow squash-and-stretch on the aiming vectors; defaults to False
globalScale/gs – an optional plug for the scale component; defaults to None
framed/fra (bool) – if there are no plugs in the passed parameters, perform cross product framing via getFramedAimAndUpVectors() (recommended when drawing chains with triads, for example legs); defaults to False
tolerance/tol (float) – if framed is on, any cross products below this length will be interpolated from neighbours; defaults to 1e-7

Type

tuple, list, Vector, Vector, [tuple, list, Vector, Vector]

Raises

NotImplementedError – framed was requested but some of the arguments were plugs

Returns

Chained-aiming matrices, suitable for drawing or driving chains or control hierarchies.

Return type

[Matrix]

parallelTransport(normal, tangents, fromEnd=False)#

Implements parallel transport as described in the Houdini demonstration by Manuel Casasola Merkle based on the paper by Hanson and Ma.

If any of the arguments are plugs, the outputs will be plugs as well. The first output normal is a pass-through of the normal argument.

Parameters

normal (list, tuple, Vector, Vector) – the starting normal (or up vector)
tangents ([list, tuple, Vector, Vector]) – the tangent samples along the curve
fromEnd/fe (bool) – indicate that normal is at the end, not the start, of the sequence, and solve accordingly; defaults to False

Returns

The resolved normals / up vectors.

Return type

[paya.runtime.data.Vector], [paya.runtime.plugs.Vector]

blendCurveNormalSets(normalsA, normalsB, tangents, ratios=None, unwindSwitch=0)#

Blends between two sets of normals along a curve. The number of tangents, normalsA, normalsB and ratios must be the same. If any inputs are plugs then the outputs will also be plugs.

Parameters

normalsA ([list, tuple, Vector, Vector]) – the first set of normals
normalsB ([list, tuple, Vector, Vector]) – the first set of normals
tangents ([list, tuple, Vector, Vector]) – the curve tangents around which to rotate the normals
ratios/rat (None, [float, Math1D]) – per-normal blend ratios; if omitted, a uniform range of floats will be generated automatically; defaults to None
unwindSwitch/uws (int, Math1D) –
an integer value or attribute to pick between:
- 0 for shortest angle unwinding (the default)
- 1 for positive angle unwinding
- 2 for negative angle unwinding

Raises

ValueError – Unequal argument lengths.

Returns

The blended set of curve normals.

Return type

Vector, Vector

bidirectionalParallelTransport(startNormal, endNormal, tangents, ratios=None, unwindSwitch=0)#

Blends between a forward and backward parallel-transport solution. If either startNormal or endNormal are None, the solution will only be performed in one direction and returned on its own.

Parameters

startNormal (list, tuple, Vector, Vector) – the normal at the start of the blend range
endNormal – list, tuple, Vector, Vector
tangents – tangents along the blend range; one normal will be generated per tangent; the more tangents, the higher the accurace of the parallel transport solve
ratios (None, [float, Math1D]) – if provided, should be a list of float values or plugs (one per tangent); if omitted, a uniform float range will be generated automatically; defaults to None
unwindSwitch/uws (int, Math1D) –
an integer value or attribute to pick between:
- 0 for shortest angle unwinding (the default)
- 1 for positive angle unwinding
- 2 for negative angle unwinding

Raises

ValueError –

One of:

Unequal numbers of tangents and ratios (if provided)
Both startNormal and endNormal are None

Returns

The normals.

Return type

[Vector]

bevelTriadPoints(points, bevelLength)#

Given three point values or plugs, returns four points, to include a ‘bevel’ cutoff of the specified length.

Warning

Beta; does not guard against reversals.

Parameters

points (list [list [float], str, Point, Vector]) – three points
bevelLength (float, Math1D) – the length of the bevel side

Returns

Four points.

Return type

[Point, Point]

unbevelTriadPoints(points)#

Reverses the result of bevelTriadPoints().

Warning

Beta; does not guard against reversals.

Parameters: points (list [list [float], str, Point, Vector]) – four points
Returns: Three points.
Return type: [Point, Point,

getBevelVector(v1, v2, upVector, forceUpVector=False)#

Parameters

v1 – the first vector
v2 – the second vector
upVector – a fallback up vector to use when the two vectors are aligned.

Returns

Returns the ‘connecting’ (bevel) vector from v1 to v2. The vector will be normalized.