paya.lib.skel#

class Chain(*joints)#

copy()#

Returns: A copy of this instance (no actual joints will be copied).
Return type: Chain

classmethod getFromStartEnd(startJoint, endJoint)#

Parameters

startJoint (str, Joint) – the root joint for the chain
endJoint (str, Joint) – the end (tip) joint for the chain

Returns

A chain from the start joint to the end joint, inclusively.

Return type

Chain

classmethod getFromRoot(rootJoint)#

Parameters: startJoint (str, Joint) – the root joint for the chain
Returns: A chain from the specified root joint. The chain will terminate before the first branch.
Return type: Chain

classmethod createFromMatrices(matrices, parent=None)#

Creates a chain from matrices. The joints will match the matrices exactly; no attempt is made to orient the chain.

Parameters

matrices – the matrices to use
parent/p – an optional parent for the chain; defaults to None

Returns

Chain

classmethod createFromPoints(points, upVector, downAxis=<undefined>, upAxis=<undefined>, parent=None, tolerance=1e-07, tipMatrix=None)#

Builds a chain from points. The side (‘up’) axis will be calculated using cross products, but those will be biased towards the reference up vector.

Parameters

points (list [list [float] | Point | Vector]) – a world position for each joint
downAxis (str) – the ‘bone’ axis; defaults to paya.config.downAxis
upAxis (str) – the axis to map to the up vector; defaults to paya.config.upAxis
upVector (tuple, list, Vector, [tuple, list, Vector]) – one up vector hint, or one vector per point
parent/p – an optional parent for the chain; defaults to None
tolerance/tol (float) – see paya.lib.mathops.getChainedAimMatrices()
tipMatrix/tm (None, list [float], Matrix) – an optional rotation matrix override for the tip (end) joint; if provided, only orientation information will be used; defaults to None

Returns

The constructed chain.

Return type

Chain

classmethod createFromCurve(curve, numberOrFractions, downAxis, upAxis, upVectorOrCurve, tolerance=1e-07)#

Draws a chain (once) along a curve. Either ‘aimCurve’ or ‘upVector’ must be provided.

Parameters

numberOrFractions – this can either be a list of length fractions, or a number
curve (str or PyNode) – the curve along which to distribute joints
downAxis (str) – the ‘bone’ axis
upAxis (str) – the axis to map to the up vector(s)
upVectorOrCurve (list, Vector, str, DagNode) – either an up vector, or an up curve
tolerance/tol (float) – see paya.lib.mathops.getChainedAimMatrices()

Returns

The constructed chain.

Return type

Chain

orient(downAxis, upAxis, upVector, tolerance=1e-07)#

Orients this chain.

Parameters

upVector (list, Vector) – a reference up vector
downAxis (str) – the aiming (bone) axis
upAxis (str) – the axis to map to the up vector
tolerance/tol (float) – see paya.lib.mathops.getChainedAimMatrices()

Returns

self

Return type

Chain

bones()#

Returns: One Bone instance per overlapping pair of joints.
Return type: list of Bone

points(plug=False)#

Parameters: plug/p (bool) – return attributes instead of values; defaults to False
Returns: A world position for each joint in this chain.
Return type: list of Point

vectors(plug=False)#

Parameters: plug/p (bool) – return attributes instead of values; defaults to False
Returns: A vector for each bone in this chain.
Return type: list of Vector or Vector

isContiguous()#

Returns: True if every member of this chain is a child of its predecessor, otherwise False.
Return type: bool

isInline()#

Returns: True if this chain is in-line (in any direction), otherwise False.
Return type: bool

roots()#

Returns: The first joint, and any member which is not a child of its predecessor.
Return type: list

length(plug=False)#

Parameters: plug/p (bool) – return an attribute instead of a value; defaults to False
Returns: The length of this chain.
Return type: float or Math1D

skinClusters()#

Returns: Any skinClusters associated with any joint in this chain, in no particular order.
Return type: list

downAxis()#

Returns: The ‘bone’ axis of this chain (e.g. ‘x’)
Return type: str

ratios()#

Returns: A length ratio for reach joint in this chain.
Return type: list of float

insertJoints(*numberOrRatios, perBone=False)#

Inserts joints into this chain. This is an in-place operation.

Parameters

*numberOrRatios (int, float, list, tuple) – this can be passed either as a single integer or one or more floats; if an integer is passed, this number of joints will be uniformly distributed along the length of this chain; if floats are passed, then joints will be inserted at those length ratios
perBone/pb (bool) – perform the operation per bone in the chain; defaults to False

Returns

The newly-generated joints.

Return type

list of Joint

subdivide(*iterations)#

Recursively inserts joints to ‘subdivide’ this chain. This is an in place operation. The chain will be edited and its membership updated.

Parameters: *iterations (int) – the number of times to subdivide; defaults to 1 if omitted
Returns: The newly-generated joints.
Return type: list of Joint

duplicate(startNumber=1)#

Duplicates this chain. Joints will be renamed with contextual. Use Name blocks to modify.

Parameters: startNumber/sn (int) – the starting number for the joint renumbering; defaults to 1
Returns: The duplicated chain.
Return type: Chain

rename(startNumber=1)#

Renames this chain contextually. Use Name blocks to modify.

Parameters: startNumber/sn (int) – the start number for the chain renumbering; defaults to 1
Returns: self
Return type: Chain

compose()#: Ensures that every member of this chain is a child of its predecessor.

explode()#: Reparents every joint under the parent of the first joint.

appendChain(otherChain, replaceTip=True)#

This is an in-place operation. Splices otherChain to the bottom of this chain and updates the membership.

Parameters

otherChain (list or Chain) – the chain to append to this one
replaceTip/rt (bool) – replace this chain’s tip joint; defaults to True

Returns

self

Return type

Chain

Return type

Chain

reset()#

Sets rotations on every joint of this chain to [0.0, 0.0, 0.0].

Returns: self

getPolePoint(distance=1.0)#

This method creates a temporary IK handle and samples its default poleVector value. For this reason it will be affected by any preferredAngle values.

Parameters: distance/d (float or int) – the pole point’s distance from the chain’s chord vector axis; defaults to 1.0
Returns: An inert world-position point target for a pole vector constraint or setPolePoint().
Return type: Point

ikHandles()#

Returns: IK handles affecting this chain.
Return type: list of IkHandle

createIkHandle(jitter=False, upVector=None, **kwargs)#

Creates an IK handle for this chain.

Parameters

jitter (bool) – if this chain is in-line, auto-configures preferred angles to prevent lockout; upAxis will be required for this; defaults to False
upVector – used by jitter; a reference up vector to indicate the wind direction of the jitter; defaults to None
**kwargs –
forwarded to paya.runtime.nodes.IkHandle.create() with the following modifications:
- startJoint and endJoint are overriden to the start and end joints of this chain, respectively
- Unless specified, the solver defaults to ikSCsolver if there are only two joints in this chain, and ikRPsolver otherwise

Returns

The IK handle.

Return type

IkHandle

autoPreferredAngle(upVector)#

If this chain is in-line, auto-configures a slight value in the preferred angle of the bending (‘up’) axis of the internal joints in anticipation of an IK handle.

Parameters: upVector (list [float], Vector) – a reference up vector to indicate the wind direction of the jitter
Returns: self
Return type: Chain

createIkHandles()#

Creates one IK handle per bone in this chain. The IK handles will all use a single-chain solver. The IK handles will be numbered. Prefixes and padding can be specified using a Name block.

Returns: The IK handles
Return type: list of IkHandle

getTwistMap(twistChain)#

Returns a list of sublists, where each sublist comprises:

bone on this chain, subdivided bone (chain) on twist chain

Parameters: twistChain (list, Chain) – a twist chain, derived from this one using insertJoints() or `subdivide
Returns: A list of sublists, where each sublist comprises bone on this chain, subdivided bone (chain) on twist chain
Type: list [Chain, Chain]

driveTwistChain(twistChain, upAxis, globalScale=1.0, downAxis=None, startUpMatrix=None, endUpMatrix=None, useOffsetParentMatrix=<undefined>, skipEnd=False, squashStretch=False)#

Drives a chain derived by duplicating this one and calling insertJoints() or subdivide() on the copy.

Parameters

twistChain (list | Chain) – the derived chain to drive
upAxis (str) – this chain’s ‘up’ axis, e.g. x
globalScale/gs (float, str, Attribute) – if this is a plug, it will be normalized; if it’s not a plug, it will be overriden to 1.0; defaults to 1.0
downAxis/da (str) – if you know this chain’s ‘down’ axis, specify if here to prevent extraneous checks; defaults to None
startUpMatrix/sum (str, Matrix) – an optional matrix to override the transformation of the vector at the very start of this chain; useful for things like shoulders etc.; defaults to None
endUpMatrix/eum (str, Matrix) – an optional matrix to override the transformation of the vector at the very end of this chain; defaults to None
useOffsetParentMatrix/uop (bool) – use offset parent matrix to drive the slave joints; defaults to the namesake configuration flag
skipEnd/ske (bool) – don’t drive the final joint; defaults to False
squashStretch/ss (bool) – apply bone scale; defaults to False

class Bone(*joints)#

Inheritance

Chain

bones()#

Returns: One Bone instance per overlapping pair of joints.
Return type: list of Bone

ratios()#

Returns: A length ratio for reach joint in this chain.
Return type: list of float

vector(plug=False)#

Parameters: plug/p (bool) – return an attribute instead of a value; defaults to False
Returns: The vector for this bone.
Return type: paya.runtime.data.Vector or paya.runtime.plugs.Vector