paya.lib.controls#

class ControlShapesLibrary(filepath)#

Inheritance

UserDict MutableMapping Mapping Collection Sized Iterable Container

Administers Paya control shapes. An instance of this class is available on paya.runtime as .controlShapes.

load()#

Loads the library content fromn paya/lib/controlshapes.json.

Returns

self

dump()#

Dumps the library content into paya/lib/controlshapes.json.

Returns

self

applyToControls(name, controls, replace=True, lineWidth=None)#

Adds shapes to the specified controls from the named library entry.

Parameters

  • name – the name of the library entry to retrieve

  • controls (list) – the controls to add shapes to

  • replace/rep (bool) – replace existing shapes on the controls; defaults to True

  • lineWidth/lw (float) – an override for the line width; defaults to None

Returns

The newly-generated control shape nodes.

Return type

list of Shape

addFromControl(control, name, normalize=True, includeShapeDetails=False)#

Captures shape macros from the specified control and adds them under a new entry in the library.

Warning

If the name already exists in the library, it will be overwritten.

Note

Changes are not saved into paya/lib/controlshapes.json until dump() is called.

Parameters

  • control (str, Transform) – the control to inspect

  • name (str) – the name for the new entry

  • normalize/nr (bool) – normalize points into a unit; defaults to True

  • includeShapeDetails (bool) – include information on override color and visibility inputs; defaults to False

Raises

NoControlShapesError – no control shapes were found under the control

Returns

self

dumpControlShapes(filePath, controls=None)#

Dumps an archive of control shapes to the specified JSON file path.

Parameters

  • controls ([Transform, str]) – a list of scene controls to work from; if omitted, getControls() is used

  • filePath (str) – The path to a JSON file.

loadControlShapes(filePath, controls=None)#

Loads an archive of control shapes from the specified JSON file path and applies them to controls in the scene.

Parameters

  • filePath (str) – The path to the JSON file.

  • controls – a list of scene controls to work from; if omitted, information in the template itself is used

createControl(worldMatrix=None, keyable=None, channelBox=None, rotateOrder='xyz', offsetGroups='offset', parent=None, pickWalkParent=None, shape='cube', lineWidth=None, shapeScale=1.0, color=None, asControl=True)#

Creates an animation control.

Parameters

  • worldMatrix/wm (list, tuple, Matrix) – the initial pose matrix; if omitted, defaults to the identity matrix

  • keyable/k – a list of channel names to make keyable on the control; defaults to None

  • channelBox/cb ([str]) – a list of channel names to make settable on the control; defaults to None

  • rotateOrder/ro (int, str) – the rotate order for the controls; defaults to 'xyz'

  • offsetGroups/og (str, [str]) – one or more basenames for offset groups; defaults to 'offset'

  • parent/p (Transform, str) – a destination parent for the topmost offset group (or the control itself, if no offset groups are requested); defaults to None

  • pickWalkParent/pwp (DependNode, str) – if omitted, defaults to parent, but only if parent is itself a control, otherwise None

  • shape/sh (str) – the name of a library shape to apply to the control; defaults to 'cube'

  • lineWidth/lw – an optonal override for the display curve thickness; defaults to None

  • shapeScale/ssc (float) – scaling factor for the control shape(s); defaults to 1.0

  • color/col – a color for the control; this can be an index value, or one of the shorthands supported by colorCtShapes(); defaults to None

  • asControl/ac (bool) – if this is False, a simple group will be created instead of a visible control; defaults to True

Returns

The animation control.

Return type

Transform

createControls(numControls=2, useLetters=True, insetScale=0.8, numberFromFirstInset=False, addVisibilitySwitches=True, worldMatrix=None, keyable=None, channelBox=None, rotateOrder='xyz', offsetGroups='offset', parent=None, pickWalkInsets=False, pickWalkParent=None, shape='cube', shapeScale=1.0, lineWidth=None, color=None, asControl=True)#

Creates one or more (stacked) animation controls.

Parameters

  • numControls/nc (int) – the number of controls to generate; defaults to 2

  • useLetters/let (bool) – number controls with letters, not numbers; if this is set to False, padding can be controlled via the padding keyword argument on Name; defaults to True

  • insetScale/iss (float) – scale shapes by this amount for every inset layer; defaults to 0.8

  • numberFromFirstInset/nfs (bool) – don’t apply a number to the topmost control; defaults to False

  • addVisibilitySwitches/avs (bool) – for each inset control, add a visibility option on the control above it; defaults to True

  • worldMatrix/wm (list, tuple, Matrix) – the initial pose matrix; if omitted, defaults to the identity matrix

  • keyable/k – a list of channel names to make keyable on the controls; defaults to None

  • channelBox/cb ([str]) – a list of channel names to make settable on the controls; defaults to None

  • rotateOrder/ro (int, str) – the rotate order for the controls; defaults to 'xyz'

  • offsetGroups/og (str, [str]) – one or more basenames for offset groups to add to the topmost control; defaults to 'offset'

  • parent/p (Transform, str) – a destination parent for the topmost offset group; defaults to None

  • pickWalkInsets/pwi (bool) – create a pick-walk hierarchy along the nested inset controls; defaults to False

  • pickWalkParent/pwp (DependNode, str) – a pick-walk parent for the topmost control; if omitted, defaults to parent, but only if parent is itself a control, otherwise None

  • shape/sh (str) – the name of a library shape to apply to the controls; defaults to 'cube'

  • lineWidth/lw – an optonal override for the display curve thickness; defaults to None

  • shapeScale/ssc (float) – overall shape scaling factor for the control system; defaults to 1.0

  • color/col – a color for the controls; this can be an index value, or one of the shorthands supported by colorCtShapes(); defaults to None

  • asControl/ac (bool) – if this is False, simple groups will be created instead of controls with shapes; defaults to True

Returns

All the generated controls in a list, outermost to innermost.

Return type

[Transform]

getControls()#
Returns

All controls in the scene.

Return type

[Transform]