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.

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.

creator: str = ''¶: The name of the developer who created the component type

definitionName: str = ''¶: The Name of the definition which is used to link this component to the definition file. this is the “name” key within the definition.

icon: str = 'hive'¶: the Icon to use for component anytime we need GUI display

documentation = ''¶

betaVersion = False¶

isBuildingGuide: bool¶: True only while we are constructing the guide system for this component

isBuildingRig: bool¶: True only while we are constructing the anim system for this component

isBuildingSkeleton: bool¶: True only while we are constructing the skeleton/deform system for this component

applicationVersion: str¶: application version(maya)

logger¶: The python logging instance for this component

property meta¶

Component meta node

Returns:: Hive component meta node
Return type:: zoo.libs.hive.base.hivenodes.layers.HiveComponent

property componentType¶

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

Return type:: str

property isBetaVersion¶

Returns whether this component is in beta.

Return type:: bool

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

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.

property rig¶

Returns the current rig instance.

Returns:: The rig class instance
Return type:: zoo.libs.hive.base.rig.Rig

property blackBox¶

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

Return type:: bool

namingConfiguration()¶

Returns the naming configuration for the current component instance.

Return type:: naming.NameManager

currentNamingPreset()¶

Returns the current naming convention preset instance for this component.

Return type:: zoo.libs.hive.base.namingpresets.Preset

container()¶

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

Return type:: zoo.libs.maya.zapi.ContainerAsset or None

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

hide()¶

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

Returns:: Success
Return type:: bool

show()¶

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

Returns:: Success
Return type:: bool

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

deleteContainer()¶

Deletes the container and all of its contents

Returns:: True if succeeded
Return type:: bool

hasContainer()¶

Determines if this component has a container

Return type:: bool

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

rootTransform()¶

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

Return type:: zapi.DagNode

group()¶

setMetaNode(node)¶

Sets the component meta node

Parameters:: node (MObject) – the node

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

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

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

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

setSide(side)¶

This set’s the components side name

Parameters:: side (str) – the side

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

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

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

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

uuid()¶

Returns the UUID value for the component

Returns:: the uuid4 value
Return type:: str

renameNamespace(namespace)¶

Renames the namespace which acts as the component name

Parameters:: namespace (str) – the new namespace

namespace()¶

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

Return type:: str

parentNamespace()¶

Returns the parent namespace of this components namespace.

Returns:: the parent namespace, eg. “:parent”
Return type:: str

removeNamespace()¶

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

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

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

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

parent()¶

Returns the parent component object.

Return type:: Component or None

hasParent()¶

Whether this component has a parent component.

Return type:: bool

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]

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.

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.

removeAllParents()¶: Removes all parent components from the current component.

disconnectAllChildren()¶: Disconnects all child components from the current component.

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.

disconnectComponentContext()¶: A context manager to pin and unpin this component and all its children

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.

inputLayer()¶

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

Return type:: layers.HiveInputLayer or None

outputLayer()¶

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

Return type:: layers.HiveOutputLayer or None

deformLayer()¶

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

Return type:: layers.HiveDeformLayer or None

rigLayer()¶

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

Return type:: layers.HiveRigLayer or None

geometryLayer()¶

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

Return type:: layers.HiveGeometryLayer or None.

guideLayer()¶

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

Return type:: layers.HiveGuideLayer or None

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

controlPanel()¶

Returns the controlPanel from the rigLayer.

Returns:: The Control panel node from the scene.
Return type:: hnodes.SettingNode or None

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

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).

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))

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

unPin()¶

Unpins the component.

Returns:: Whether the unpin was successful.
Return type:: bool

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:

nodes()¶

Generator function which returns every node linked to this component.

Return type:: Iterable[zapi.DGNode or zapi.DagNode]

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 provide default via parentNode argument.
Return type:: hnodes.Joint or hnodes.DagNode

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`
}

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`
}

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

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

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

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

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.

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]

setupGuide()¶

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

Returns:: shouldn’t return anything
Return type:: None

postSetupGuide()¶

Called directly after the guides have been created

Return type:: None

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

autoAlign - Determines whether the guide requires auto Alignment.

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

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

setupRigSettings()¶: Sets up rig settings for the animation Rig.

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

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.

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.

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.

postSetupDeform(parentJoint)¶

preSetupRig(parentNode)¶: Same logic as guides, inputs outputs and animation attributes are auto generated from the definition.

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

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

setupSpaceSwitches()¶: Method to setup space switches from the definition data, this method is called after the rig is built

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]

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]

prePolish()¶: First stage of the publishing is to remove Guide structure if it exists.

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

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.

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

deleteDeform()¶

This function deletes the deform system.

Returns:: Whether the deform system is successfully deleted.
Return type:: bool

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

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:

rigLayer

deformLayer

inputLayer

outputLayer

guideLayer

assetContainer

metaNode

Returns:
Return type:

deserializeComponentConnections(layerType='HiveGuideLayer')¶

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

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 –

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

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