Component

class Component(rig, definition=None, metaNode=None)

Bases: object

Component class that encapsulates a single rigging component, This is the class that would be overridden.

BuildSystem Methods:
Parameters:
  • rig (zoo.libs.hive.base.rig.Rig) – The rig instance attached to the component.

  • definition (zoo.libs.hive.base.definition.ComponentDefinition or dict) – The component definition which is used to build the guide and rig.

  • metaNode (layers.HiveComponent) – the component meta node isinstance.

alignGuides()

This Method handles guide alignment for the component. This method will be run automatically just before the deformation layer is built. However, it can also be run on demand via rigging tools.

Note

This method is intended to be overridden however the default behaviour will auto align all guides to the first child found.

When overriding this method it’s important to utilise or api to help reduce the amount of code needed and to produce consistency across components. This includes using user defined per guide autoAlign settings and our batching function which updates all guide matrices in one go.

Every guide in hive defines 3 primary attributes relating to alignment

  1. autoAlign - Determines whether the guide requires auto Alignment.

  2. autoAlignAimVector - Determines the primary Axis which to align on, the target is defined by the dev.

  3. autoAlignUpVector - Determines The local UpVector for the guide. World Up is defined either by the dev or by a separate guide.

To determine whether a guide has been set by the user to use autoAlign the below code can be used.

if not guide.autoAlign.value():
    continue

To calculate to align rotations and create a final output matrix which is always done in worldSpace.

# guide.autoAlignAimVector and autoAlignUpVector are attributes which to user
# can change
outRotation = mayamath.lookAt(sourcePosition=source,
                              aimPosition=target,
                              aimVector=zapi.Vector(guide.autoAlignAimVector.value()),
                              upVector=zapi.Vector(guide.autoAlignUpVector.value()),
                              worldUpVector=worldUpVector
                              )
transform = guide.transformationMatrix()
transform.setRotation(outRotation)

To set all guide transforms in batch, which is far more efficient than one at a time.

api.setGuidesWorldMatrix(guidesToAlign, matricesToSet, skipLockedTransforms=False)
Returns:

Whether auto aligning succeeded.

Return type:

bool

betaVersion = False
property blackBox

Convenience method, If this component has a container object then return the container.blackBox value

Return type:

bool

buildDeform(parentNode=None)

Internal Method used by the build system, shouldn’t be overridden by subclasses unless you want full control of every part of the deformation layer being built.

Parameters:

parentNode (zapi.DagNode) – The DeformLayer root transform node

buildGuide()

Builds the guide system for this component. This method is responsible for creating the guide system, and setting up the guide layer metadata.

Raises:

errors.ComponentDoesntExistError if the component doesn’t exist.

Raises:

errors.BuildComponentGuideUnknownError if an unknown error occurs while building the guide system

buildRig(parentNode=None)

Build the rig for the current component.

Parameters:

parentNode (zapi.DagNode or None) – parent node for the rig to be parented to. If None, the rig will not be parented to anything.

Raises:

ComponentDoesntExistError if the current component doesn’t exist

Raises:

BuildComponentRigUnknownError if building the rig fails

children(depthLimit=256)

Generator method which returns all component children instances.

Parameters:

depthLimit (int) – The depth limit which to search within the meta network before stopping.

Returns:

Generator where each element is a component instance

Return type:

list[Component]

componentParentGuide()

Returns the connected parent component guide node.

Returns:

Tuple for the parent component and the connected parent guide node.

Return type:

tuple[Component, hnodes.Guide] or tuple[None, None]

componentParentJoint(parentNode=None)

Returns the parent components connected joint.

This is mostly called by the build code.

Parameters:

parentNode (hnodes.Joint or None) – Default parent node when None exist.

Returns:

The parent components joint or the provided default via parentNode argument.

Return type:

hnodes.Joint or hnodes.DagNode or None

property componentType

Returns the component name which can be used do a lookup in the registry

Return type:

str

container()

Returns the container hive node which is retrieved from the meta node

Return type:

zoo.libs.maya.zapi.ContainerAsset or None

controlPanel()

Returns the controlPanel from the rigLayer.

Returns:

The Control panel node from the scene.

Return type:

hnodes.SettingNode or None

create(parent=None)

Main method that creates the component in the scene excludes the actual creation of the component guides or rig

Parameters:

parent (Layer.HiveRig) – The parent component or rig layer which component will connect to via meta node.

Returns:

The hive components meta node instance.

Return type:

layers.HiveComponent

createContainer()

Creates a new AssetContainer if it’s not already created and attaches it to this component instance.

Note:

This will not merge component nodes into the container.

Returns:

The newly created containerAsset instance.

Return type:

zapi.ContainerAsset

createGuideControllerTags(guides, visibilityPlug)

Creates and yields controller tags for the Guide layer.

Parameters:
  • guides (iterable[hnodes.Guide]) – The full list of Guides from the component in order of creation.

  • visibilityPlug (zapi.Plug or None) – The visibility plug from the Guide settings nodes if present.

Returns:

Iterable of kControllerNode as a zapi DGNode

Return type:

iterable[zapi.DGNode]

createRigControllerTags(controls, visibilityPlug)

Creates and yields controller tags for the Anim rig layer.

Parameters:
  • controls (iterable[hnodes.ControlNode]) – The full list of controls from the component in order of creation.

  • visibilityPlug (zapi.Plug or None) – The visibility plug from the control panel.

Returns:

Iterable of kControllerNode as a zapi DGNode

Return type:

iterable[zapi.DGNode]

createSubSystems()

Creates the subsystems for the current component and returns them in an OrderedDict.

Returns:

OrderedDict with keys of the subsystem names and values of the corresponding subsystem object

Return type:

OrderedDict

Example return value:

{
    "twists": :class:`zoo.libs.hive.library.subsystems.twistsubsystem.TwistSubSystem`,
    "bendy": :class:`zoo.libs.hive.library.subsystems.bendysubsystem.BendySubSystem`
}

creator = ''
currentNamingPreset()

Returns the current naming convention preset instance for this component.

Return type:

zoo.libs.hive.base.namingpresets.Preset

property definition

Returns the correct definition object, if the rig is built then we grab the definition from the meta node attribute ‘componentDefinition’

Return type:

baseDef.ComponentDefinition

definitionName = ''
deformLayer()

Returns the deform layer node from the component, retrieved from the components meta node

Return type:

layers.HiveDeformLayer or None

delete()

Deletes The entire component from the scene if this component has children Then those children’s meta node will be re-parented to the component Layer of the rig.

Order of deletion:

  1. rigLayer

  2. deformLayer

  3. inputLayer

  4. outputLayer

  5. guideLayer

  6. assetContainer

  7. metaNode

Returns:

Return type:

deleteContainer()

Deletes the container and all of its contents

Returns:

True if succeeded

Return type:

bool

deleteDeform()

This function deletes the deform system.

Returns:

Whether the deform system is successfully deleted.

Return type:

bool

deleteGuide()

This function deletes the guide system.

Returns:

True if the guide system is successfully deleted

Return type:

bool

Raises:

ValueError – if the container is not valid

deleteRig()

Deletes the current rig for the component if it exists, this includes the rigLayer, inputs, outputs and deform layer.

Returns:

True if successful

Return type:

bool

deserializeComponentConnections(layerType='HiveGuideLayer')
disconnect(component)

Disconnects the specified component from the current component.

Parameters:

component (Component) – The component to disconnect.

disconnectAll()

Disconnects all guides by deleting incoming constraints on all guides and disconnects the meta data.

disconnectAllChildren()

Disconnects all child components from the current component.

disconnectComponentContext()

A context manager to pin and unpin this component and all its children

documentation = ''
duplicate(name, side)

Duplicates the current component and renames it to the new name, This is done by serializing the current component then creating a new instance of the class

Parameters:
  • name (str) – the new name for the component

  • side (str) – The mirrored component side.

Return type:

Component

exists()

Returns whether this component exists in the scene, this is determined by the existence of the meta node and the root transform node.

Return type:

bool

findLayer(layerType)

Finds and returns the components layer instance.

Parameters:

layerType (str) – The layer type ie. constants.GUIDE_LAYER_TYPES

Returns:

The Hive layer meta node instance.

Return type:

layers.HiveLayer

geometryLayer()

Returns the geometry layer node from the component, retrieved from the components meta node.

Return type:

layers.HiveGeometryLayer or None.

group()
guideLayer()

Returns the guide layer node from the component, retrieved from the components meta node

Return type:

layers.HiveGuideLayer or None

hasContainer()

Determines if this component has a container

Return type:

bool

hasGuide()

Determines if the guide for this component is already been built.

Return type:

bool

hasGuideControls()

Determines if the guide controls for this component is already been built.

Returns:

the value is returned from the meta.hasGuideControls attribute which is set by zoocommands

Return type:

bool

hasParent()

Whether this component has a parent component.

Return type:

bool

hasPolished()

Determines if this component has polished

Returns:

the value is returned from the meta.hasPolished attribute which is set at build time

Return type:

bool

hasRig()

Determines if this component has built the rig

Returns:

the value is returned from the meta.hasRig attribute which is set at build time

Return type:

bool

hasSkeleton()

Determines if this component has built the rig

Returns:

the value is returned from the meta.hasRig attribute which is set at build time

Return type:

bool

hide()

Hides the component by turning off the visibility on the root transform

Returns:

Success

Return type:

bool

icon = 'hive'
idMapping()

Returns the guide ID -> layer node ID mapping acting as a lookup table.

When live linking the joints with the guides this table is used to link the correct guide transform to the deform joint. This table is also used when determining which deformJoints should be deleted from the scene if the guide doesn’t exist anymore. Among other aspects of the build system.

Note

This method can be overridden in subclasses, by default it maps the guide.id as a 1-1

Note

If there’s no joint for the guide then it should have an empty string

def idMapping():
    id = {"pelvis": "pelvis",
            "gimbal": "",
            "hips": "",
            "fk01": "bind01"}
    return {constants.DEFORM_LAYER_TYPE: ids,
            constants.INPUT_LAYER_TYPE: ids,
            constants.OUTPUT_LAYER_TYPE: ids,
            constants.RIG_LAYER_TYPE: ids
    }
Returns:

The guideId mapped to the ids for each layer

Return type:

dict

inputLayer()

Returns the Input layer node from the component, retrieved from the components meta node

Return type:

layers.HiveInputLayer or None

property isBetaVersion

Returns whether this component is in beta.

Return type:

bool

isHidden()

Determines if the component is hidden in the scene.

This is determined by both the existence of the component and the root transform visibility attribute.

Return type:

bool

property meta

Component meta node

Returns:

Hive component meta node

Return type:

zoo.libs.hive.base.hivenodes.layers.HiveComponent

mirror(translate=('x',), rotate='yz', parent=MockExt.OpenMaya.MObject.kNullObj)

Method to override how the mirroring of component guides are performed.

By Default all guides,guideShapes and all srts are mirror with translation and rotation(if mirror attribute is True).

Note:

Unless you need complete control over the math and all mirror behaviour it is recommended to use Component.preMirror() and Component.postMirror() instead.

Parameters:
  • translate (tuple) – The axis to mirror on ,default is (“x”,).

  • rotate (str) – The mirror plane to mirror rotations on, supports “xy”, “yz”, “xz”, defaults to “yz”.

  • parent (om2.MObject) – the parent object to use as the mirror space, default is kNullObj making mirroring happen based on world (0, 0, 0).

Returns:

A list of tuples with the first element of each tuple the hiveNode and the second element the original world Matrix.

Return type:

list(tuple(zapi.DagNode, om2.MMatrix))

name()

returns the name of the component, if the meta node exists pull it from there else the definition

Returns:

the component name

Return type:

str

namespace()

Returns the namespace for this node. eg. “:namespace:nodeName”

Return type:

str

namingConfiguration()

Returns the naming configuration for the current component instance.

Return type:

naming.NameManager

nodes()

Generator function which returns every node linked to this component.

Return type:

Iterable[zapi.DGNode or zapi.DagNode]

outputLayer()

Returns the output layer node from the component, retrieved from the components meta node

Return type:

layers.HiveOutputLayer or None

parent()

Returns the parent component object.

Return type:

Component or None

parentNamespace()

Returns the parent namespace of this components namespace.

Returns:

the parent namespace, eg. “:parent”

Return type:

str

pin()

Pins the current component in place.

This works by serializing all upstream connections on the guideLayer meta then we disconnect while maintaining parenting(metadata) then in Component.unpin() We reapply the stored connections

polish()

Cleanup operation of a component, used to publish attributes from the controlPanel to the container interface and to publish all controls to the container

postMirror(translate=('x',), rotate='yz', parent=MockExt.OpenMaya.MObject.kNullObj)

Method to override to handle post-mirror operations, this is used in mirror() and in the apply symmetry command.Useful for reapplying any state to the guides eg.locking attributes.

Parameters:
  • translate (tuple) – The axis to mirror on ,default is (“x”,).

  • rotate (str) – The mirror plane to mirror rotations on, supports “xy”, “yz”, “xz”, defaults to “yz”.

  • parent (om2.MObject) – the parent object to use as the mirror space, default is kNullObj making mirroring happen based on world (0, 0, 0).

Returns:

A list of tuples with the first element of each tuple the hiveNode and the second element the original world Matrix.

Return type:

list(tuple(zapi.DagNode, om2.MMatrix))

postPolish()

Post publish method is the final operation done to complete a component build. This is useful for cleaning up the rig, locking off attributes/nodes etc.

postSetupDeform(parentJoint)
postSetupGuide()

Called directly after the guides have been created

Return type:

None

postSetupRig(parentNode)

Post rig build, method to take all control panel attributes and publish them to the container interface, control nodes are published and all nodes connected to the meta node of this component is added to the container but not published

preMirror(translate=('x',), rotate='yz', parent=MockExt.OpenMaya.MObject.kNullObj)

Method to override to handle pre-mirror operations, this is used in mirror() and in the apply symmetry command.Useful for unlocking attributes, deleting any constraint or any live interactions with the guide system.

Parameters:
  • translate (tuple) – The axis to mirror on ,default is (“x”,).

  • rotate (str) – The mirror plane to mirror rotations on, supports “xy”, “yz”, “xz”, defaults to “yz”.

  • parent (om2.MObject) – the parent object to use as the mirror space, default is kNullObj making mirroring happen based on world (0, 0, 0).

Returns:

A list of tuples with the first element of each tuple the hiveNode and the second element the original world Matrix.

Return type:

list(tuple(zapi.DagNode, om2.MMatrix))

prePolish()

First stage of the publishing is to remove Guide structure if it exists.

preSetupDeformLayer()

This function sets up the deform layer in the definition.

For each guide in the guide layer definition, it checks if a corresponding deform joint exists in the deform layer definition. If it does, it sets the translate, rotateOrder, and rotate attributes of the deform joint to the values of the corresponding guide. If no corresponding deform joint exists, it continues to the next guide.

preSetupGuide()

The pre setup guide is run before the buildGuide() function is run internally, hive will auto generate the guide structure using the definition data. You can override this method, but you’ll either need to handle the guide and all of its settings yourself or call the super class first.

preSetupRig(parentNode)

Same logic as guides, inputs outputs and animation attributes are auto generated from the definition.

removeAllParents()

Removes all parent components from the current component.

removeNamespace()

Removes the namespace of the this component and moves all children to the root namespace

Return type:

bool

removeParent(parentComponent=None)

Remove parent relationship between this component and the parent component.

Parameters:

parentComponent (:class:Component or None) – If None then remove all parents.

removeUpstreamAnnotations(parentComponent=None)

Removes upstream annotations from this component’s guide layer

Parameters:

parentComponent (Component or None) – The parent component to remove the annotations from. If None, all annotations will be removed.

rename(name)

Renames the component by setting the meta and definition name attribute as well the namespace

Parameters:

name (str) – the new name fpr the component

renameNamespace(namespace)

Renames the namespace which acts as the component name

Parameters:

namespace (str) – the new namespace

property rig

Returns the current rig instance.

Returns:

The rig class instance

Return type:

zoo.libs.hive.base.rig.Rig

rigLayer()

Returns the rig layer node from the component, retrieved from the components meta node

Return type:

layers.HiveRigLayer or None

rootTransform()

Returns The root transform node of the component i.e. the HRC

Return type:

zapi.DagNode

saveDefinition(value)

Saves the provided value as the definition cache and bakes the definition into the components meta node.

Parameters:

value (baseDef.ComponentDefinition or dict) – The new definition instance to bake.

serializeComponentGuideConnections()

Serializes the connection for this component to the parent. There’s only ever one parent but we may have multiple constraintTypes bound

serializeFromScene(layerIds=None)

Serializes the component from the root transform down using the individual layers, each layer has its own logic so see those classes for information.

Parameters:

layerIds (iterable[str]) – An iterable of Hive layer id types which should be serialized

Returns:

Return type:

serializedTokenKey()

Returns the serialized data key for this component. This result is the joined name, side with “:” as the separator

Returns:

the name and side of the component in the format of “name:side”

Return type:

str

setDeformNaming(namingConfig, modifier)

Provided for subclassed components to update the naming convention for the deformLayer, inputLayer and outputLayer.

Note

This method is run after postSetupDeform method.

# example of implementation

def setDeformNaming(self, namingConfig, modifier):
    compName, compSide = self.name(), self.side()
    for jnt in self.deformLayer().iterJoints():
        jntName = namingConfig.resolve("skinJointName", {"componentName": compName,
                                                         "side": compSide,
                                                         "id": jnt.id(),
                                                         "type": "joint"})
        jnt.rename(jntName, maintainNamespace=False, mod=modifier, apply=False)
Parameters:
  • namingConfig (zoo.libs.naming.naming.NameManager) – The naming configuration instance for this component.

  • modifier (zapi.dgModifier) – The DGModifier instance to use when renaming a node

setGuideNaming(namingConfig, modifier)

Provided for subclassed components to update the naming convention for the GuideLayer.

Note

This method is run after postSetupGuide method.

Note

Calling doIt() on the modifier is not required and will be handled by the caller.

# example of implementation

def setDeformNaming(self, namingConfig, modifier):
    compName, compSide = self.name(), self.side()
    for guide in self.guideLayer().iterGuides():
        name = namingConfig.resolve("guideName", {"componentName": compName,
                                                     "side": compSide,
                                                     "id": guide.id(),
                                                     "type": "guide"})
        guide.rename(name, maintainNamespace=False, mod=modifier, apply=False)
Parameters:
  • namingConfig (zoo.libs.naming.naming.NameManager) – The naming configuration instance for this component.

  • modifier (zapi.dgModifier) – The DGModifier instance to use when renaming a node

setIsHistoricallyInteresting(state)

Sets the isHistoricallyInteresting state on the component.

Parameters:

state (bool) – Whether the component is historically interesting.

setMetaNode(node)

Sets the component meta node

Parameters:

node (MObject) – the node

setParent(parentComponent, driver=None)

Sets the parent component for the current component.

Parameters:
  • parentComponent (:class:Component) – The parent component to set.

  • driver (:class:Guide) – The driver guide.

setSide(side)

This set’s the components side name

Parameters:

side (str) – the side

setupDeformLayer(parentNode=None)

Sets up the Deform layer for the component.

Parameters:

parentNode (api.Joint or zapi.DagNode) – The parent joint or the node which the joints will be parented too. Could be the deformLayer Root.

setupGuide()

Main Build method for the guide, do all your main logic here.

Returns:

shouldn’t return anything

Return type:

None

setupInputs()

Sets up the input layer for the component.

Raises:

errors.InvalidInputNodeMetaData

setupOutputs(parentNode)

Sets up the output layer for the component.

Parameters:

parentNode (zapi.DagNode) – Parent joint for the output layer.

Raises:

errors.InvalidOutputNodeMetaData

setupRig(parentNode)

Main method to build the rig. You should never access the guides directly as that would limit the flexibility for the building processing over the farm or without a physical guide in the scene. Always access rig nodes through the component class(self) never access the hive node class directly as internal method does extra setup for internal metadata etc.

:rtype:None

setupRigSettings()

Sets up rig settings for the animation Rig.

setupSelectionSet(deformLayer, deformJoints)

Responsible for adding joints to the deform selection set.

Parameters:
  • deformLayer (layers.HiveDeformLayer) – The deformLayer instance

  • deformJoints (dict[str, hnodes.Joint]) – The joint id to joint map.

setupSpaceSwitches()

Method to setup space switches from the definition data, this method is called after the rig is built

show()

Shows the component by turning on the visibility on the root transform

Returns:

Success

Return type:

bool

side()

Returns the side name of the component, if the meta node exists pull it from there else the definition

Returns:

the component side name

Return type:

str

spaceSwitchUIData()

Returns the available space Switch driven and driver settings for this component. Drivers marked as internal will force a non-editable driver state in the UI driver column and only displayed in the “driver component” column.

Below is an example function implementation.

def spaceSwitchUiData(self)
    driven = [api.SpaceSwitchUIDriven(id_="myControlId", label="User DisplayLabel")]
    drivers = [api.SpaceSwitchUIDriver(id_="myControlId", label="User DisplayLabel", internal=True)]
    return {"driven": driven,
            "drivers": drivers}
Return type:

dict

subsystems()

Returns the subsystems for the current component, if the subsystems have already been created, the cached version is returned.

Returns:

OrderedDict with keys of the subsystem names and values of the corresponding subsystem object

Return type:

OrderedDict

Example return value:

{
    "twists": :class:`zoo.libs.hive.library.subsystems.twistsubsystem.TwistSubSystem`,
    "bendy": :class:`zoo.libs.hive.library.subsystems.bendysubsystem.BendySubSystem`
}
uiData = {'displayName': '', 'icon': 'hive', 'iconColor': ()}
unPin()

Unpins the component.

Returns:

Whether the unpin was successful.

Return type:

bool

updateGuideSettings(settings)

Method that allows overloading updates of the guides settings of the definition which will be change the state of the scene if the guides are present.

It’s useful the overload this where changing a certain setting requires other per component updates ie. rebuilds.

Parameters:

settings (dict[name: value]) –

Returns:

The Original guide settings in the same format as settings, this will be used in zoo commands for handling undo.

Return type:

dict[name: value]

updateNaming(layerTypes=('HiveGuideLayer', 'HiveDeformLayer'), modifier=None, apply=True)

Runs the update process to update any node names on the component from the current naming configuration instance.

Parameters:
  • layerTypes (tuple[str]) – A tuple of layer types ie. (constants.GUIDE_LAYER_TYPE,) at this stage only GUIDE_LAYER_TYPE and DEFORM_LAYER_TYPE is supported.

  • modifier (zapi.dgModifier) – The DGModifier instance to use when renaming a node

  • apply (bool) – Whether doIt should be run on the modifier.

Returns:

The modifier instance used, if none provided then the one created will be returned

Return type:

zapi.dgModifier

uuid()

Returns the UUID value for the component

Returns:

the uuid4 value

Return type:

str

class SpaceSwitchUIDriven(id_, label)

Bases: object

SpaceSwitch UI Driven control data.

Parameters:
  • id (str) – The Internal component rigLayer control id to link too.

  • label (str) – The Display label for the control id

serialize()

Serialize the object’s attributes into a dictionary.

Returns:

a dictionary with the keys id_ and label, and values equal to the id and label attributes of the object, respectively.

Return type:

dict

class SpaceSwitchUIDriver(id_, label, internal=False)

Bases: object

SpaceSwitch UI Driver control data.

Parameters:
  • id (str) – The Internal component rigLayer control id to link too.

  • label (str) – The Display label for the control id

  • internal (bool) – Whether this control id is internally linked i.e. to the inputLayer.

serialize()

Serialize the object’s attributes into a dictionary.

Returns:

a dictionary with the keys id_, label, and internal, and values equal to the id, label, and internal attributes of the object, respectively.

Return type:

dict

disconnectJointTransforms(deformLayer)

Disconnects all joint transform attribute which have a incoming connection.

Parameters:

deformLayer (layers.HiveDeformLayer) – The component deformLayer instance

resetJointTransforms(deformLayer, guideDefLayer, idMapping)

Resets all joints on the deformLayer to match the guide definition.

Parameters:
  • deformLayer (layers.HiveDeformLayer) – The component deformLayer instance

  • guideDefLayer (baseDef.GuideLayerDefinition) – The component definition guideLayer instance.

  • idMapping