Component

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

Bases: object

Base class for all rigging components in the Hive framework.

This class serves as the foundation for creating custom rigging components. It provides a complete lifecycle for component creation, from guide setup to final rig construction.

Note

This is an abstract base class that should be subclassed to create custom components. Implement the required build methods to define your component’s behavior.

The following methods define the component’s build process in order of execution:

Guide System:
Deformation System:
Rig System:
Naming and UI:
Mirroring:
Parameters:
  • rig (zoo.libs.hive.base.rig.Rig) – The rig instance that this component belongs to.

  • definition (zoo.libs.hive.base.definition.ComponentDefinition or dict) – The component definition used for building the guide and rig. Can be either a definition object or a dictionary.

  • metaNode (layers.HiveComponent) – The component’s meta node instance.

Variables:
  • creator (str) – The name of the developer who created the component type.

  • definitionName (str) – The name that links this component to its definition file.

  • uiData (dict) – Dictionary containing UI display information. Keys include ‘icon’, ‘iconColor’, and ‘displayName’.

  • icon (str) – Deprecated. Use uiData instead.

  • documentation (str) – Scene documentation for the component.

  • betaVersion (bool) – Flag indicating if this is a beta version of the component.

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

applyGuideScaleSettings()
betaVersion = False
property blackBox

Gets the blackbox state of the component’s container, if it exists.

Returns:

True if the component has a container and it is blackboxed, False otherwise

Return type:

bool

Note

A blackboxed container hides its internal nodes in the Maya outliner, providing a cleaner scene hierarchy. This property checks if the component’s container (if it exists) is currently blackboxed.

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

Get the component type name used for registry lookups.

This property returns the component’s type name, which is used to look up the component in the registry. If the component exists in the scene, it returns the type from the meta node; otherwise, it falls back to the class name.

Returns:

The component type name, either from the meta node or the class name.

Return type:

str

Note

The component type is used to identify the component’s definition in the component registry and is essential for proper serialization and deserialization.

connectables()
Returns:

Return type:

list[baseDef.ConnectableNode or baseDef.ConnectableAttribute]

container()

Retrieves the Maya container associated with this component.

This method returns the container node that encapsulates all the elements of this component in the Maya scene. The container is a Maya asset node that provides organization and encapsulation for the component’s nodes.

Returns:

The container asset instance if it exists, otherwise None.

Return type:

zoo.libs.maya.zapi.ContainerAsset or None

Note

  • The container is only available if the component has been built in the scene.

  • This method returns None if the component’s meta node doesn’t exist or if no container is associated with the component.

  • The container provides methods for managing the component’s nodes as a single unit.

controlPanel()

Returns the controlPanel from the rigLayer.

Returns:

The Control panel node from the scene.

Return type:

hnodes.SettingsNode or None

create(parent=None)

Creates and initializes the component’s scene representation.

This is the main method that sets up the component in the Maya scene. It creates the necessary meta nodes and initial data structures but does not create the actual guide or rig geometry. The method performs the following operations: - Creates the component’s meta node with appropriate attributes - Sets up naming based on the component’s definition - Initializes the component’s version and type information - Sets up connections to the parent component or rig if provided

Parameters:

parent (Layer.HiveRig or None) – The parent component or rig layer to connect to via meta node. This establishes the component’s position in the rig hierarchy.

Returns:

The newly created HiveComponent meta node instance.

Return type:

layers.HiveComponent

Note

  • This method is decorated with @profiling.fnTimer for performance monitoring.

  • The component’s definition must be properly set before calling this method.

  • This creates the component’s basic structure but not its guide or rig elements.

  • The component’s visibility is set to True by default.

  • The component is assigned a unique ID if one isn’t already set.

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.

The preset contains the naming rules and patterns used for generating node names within this component.

Returns:

The current naming preset for this component

Return type:

zoo.libs.hive.base.namingpresets.Preset

Note

The naming preset determines the specific naming rules applied to this component, allowing for different naming conventions to be used across different components or component types.

defaultMirrorFlipAxis = 0
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

deformationJointIds(deformLayer, deformJoints)

Returns all deform joint ids which will be skinned. Currently used for setting joint radius, colors and for setting up deform selection set.

Parameters:
  • deformLayer (layers.HiveDeformLayer)

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

Returns:

Return type:

list[hnodes.Joint], list[hnodes.Joint]

delete(deleteJoints=True)

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 component’s container and all its contents from the scene.

This method removes the Maya container associated with this component, including all nodes contained within it. This is a destructive operation that cannot be undone.

Returns:

True if the container was found and successfully deleted, False otherwise.

Return type:

bool

Note

  • This operation is irreversible and will permanently delete the container and its contents.

  • The component itself remains in the scene but loses its container association.

  • If the component doesn’t have a container, the method will return False.

  • This method only deletes the container, not the component’s meta node or definition.

deleteDeform(deleteJoints=True)

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

deprecated = False
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()

Determines if the component exists in the current Maya scene.

This method checks for the existence of the component by verifying that its associated meta node exists in the scene. The meta node stores all the component’s essential data and relationships.

Returns:

True if the component exists in the scene, False otherwise

Return type:

bool

Note

  • A component is considered to exist only if its meta node exists in the scene.

  • This method is safe to call even if the component has not been fully initialized.

  • This is different from isHidden(), which checks visibility rather than existence.

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

Checks if the component has an associated Maya container.

This method verifies whether the component is associated with a Maya container node. A container is a Maya asset that groups related nodes together for better organization and management in the scene.

Returns:

True if the component has an associated container, False otherwise.

Return type:

bool

Note

  • This is a lightweight check that only verifies the existence of a container.

  • The container might be empty if it was just created.

  • To get the actual container object, use the container() method.

  • Returns False if the component doesn’t exist in the scene.

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 in the Maya scene by setting its root transform’s visibility to off.

This method affects the visual representation of the component in the viewport without deleting any of its nodes. The hidden state is persistent and will be saved with the scene.

Returns:

True if the component was successfully hidden, False if the component doesn’t exist or is already hidden.

Return type:

bool

Note

  • This only affects the visibility in the viewport, not the component’s functionality.

  • To check the current visibility state, use the isHidden() method.

  • To make the component visible again, use the show() method.

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

implementMirroring(guides, ctrls, oppositeCtrls, ctrlIdMapping, mirrorPlaneObject, mirrorPlaneAxis)
inputLayer()

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

Return type:

layers.HiveInputLayer or None

property isBetaVersion

Check if this component is marked as a beta version.

This property indicates whether the component is in a beta state. Beta components may have incomplete features or be under active development and testing.

Returns:

True if the component is a beta version, False otherwise.

Return type:

bool

Note

The beta status is determined by the class-level betaVersion attribute, which should be set to True for beta components.

isHidden()

Determines if the component is currently hidden in the Maya scene.

This method checks the visibility state of the component by examining its root transform node. A component is considered hidden if either: - The component doesn’t exist in the scene - The root transform’s visibility attribute is set to False

Returns:

True if the component is hidden, False if it’s visible

Return type:

bool

Note

  • This is a read-only property that reflects the current visibility state.

  • To change the visibility, use the hide() or show() methods.

  • The visibility state is persistent and will be saved with the Maya scene.

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

mirrorData(translate=('x',), rotate=None)
name()

Retrieves the name of the component.

The name is a unique identifier for the component within its parent rig and is used for various operations including node naming and component lookup.

Returns:

The name of the component

Return type:

str

Note

  • The name is typically set during component creation and should be unique within the rig.

  • To change the name, update the component’s definition and call saveDefinition().

  • The name is used to generate node names and should be a valid Maya name.

namespace()

Returns the full namespace path for this component.

This method retrieves the complete namespace path under which this component’s nodes are organized in the Maya scene. The namespace helps organize and prevent naming conflicts between different components and their elements.

Returns:

The full namespace path, e.g. “:root:character:arm_L”

Return type:

str

Note

  • If the component has no meta node, it returns the current namespace plus the component name.

  • The returned path always includes the root namespace as the first element.

  • This is different from the component name, which is just the last part of the namespace.

namingConfiguration()

Returns the naming configuration for the current component instance.

The naming configuration is cached after the first access to improve performance.

Returns:

The naming configuration manager for this component

Return type:

naming.NameManager

Note

The naming configuration controls how nodes within this component are named, following the rig naming conventions. This includes patterns for different node types and their hierarchical relationships.

nodes()

Generator function which returns every node linked to this component.

Return type:

Iterable[zapi.DGNode or zapi.DagNode]

property originalDefinition

Returns the original definition object, this is the base definition without any modifications by the user. This data is useful for diffing changes and/or resetting to defaults.

Return type:

baseDef.ComponentDefinition

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

Retrieves the parent namespace of this component’s namespace.

This method navigates up one level in the namespace hierarchy from the component’s current namespace. This is useful for operations that need to reference or modify the parent container of this component.

Returns:

The parent namespace path, e.g. “:root:character” for a component in “:root:character:arm_L”

Return type:

str

Note

  • Returns the root namespace if the component is in the root namespace or if an error occurs.

  • The current namespace is temporarily changed during execution but is restored before returning.

  • This is different from namespace() which returns the component’s full namespace path.

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

postDeformDriverSetup(parentNode)

Internal use only and likely temporary until i find a better way of running driver setups.

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

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, me thod 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).

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 and updates all related data structures.

This method performs a comprehensive rename of the component, updating: - The component’s name in its definition - The meta node attributes - The component’s namespace - Any dependent nodes or references

The rename operation ensures that all aspects of the component remain consistent with the new name, including updating any space switching dependencies that reference this component.

Parameters:

name (str) – The new name for the component. Should be a valid Maya name.

Note

  • This operation updates both the component’s definition and its meta node.

  • The component’s namespace will be updated to match the new name.

  • Any space switching dependencies on this component will be updated.

  • This is a potentially expensive operation as it may update many nodes.

  • The name should follow the project’s naming conventions.

renameNamespace(namespace)

Renames the namespace associated with this component.

This method changes the namespace that contains all the nodes belonging to this component. The method ensures that the rename operation is performed safely by checking for existing namespaces and properly managing the current namespace state.

Parameters:

namespace (str) – The new namespace name to assign to this component. The namespace should be a valid Maya namespace identifier.

Note

  • The method will do nothing if the target namespace already exists.

  • If the component is in the root namespace, the method will return without making changes.

  • The current namespace will be restored after the operation, even if an error occurs.

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

Retrieves the root transform node of the component.

This method returns the top-level transform node that serves as the parent for all the component’s nodes in the scene hierarchy. The root transform is the primary transform node that represents the component’s position, rotation, and scale in 3D space.

Returns:

The root transform node of the component, or None if the component doesn’t exist in the scene.

Return type:

maya.api.OpenMaya.MObject or None

Note

  • The component must exist in the scene (self.exists() must be True).

  • This is different from the group() method, which returns the organizational group node, while this returns the actual transform node.

  • Returns None if the component doesn’t exist in the scene.

  • The root transform is typically named according to the component’s naming convention.

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:

baseDef.ComponentDefinition

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.

def setDeformNaming(self, namingConfig, modifier):
    compName, compSide = self.name(), self.side()
    for joint in self.deformLayer().iterJoints():
        name = namingConfig.resolve("deformName", {
            "componentName": compName,
            "side": compSide,
            "id": joint.id(),
            "type": "joint"
        })
        joint.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

setGuideNaming(namingConfig, modifier)

Updates the naming convention for guide nodes in the component.

This method is called during the component’s update process to ensure all guide nodes follow the current naming convention. It’s automatically called by updateNaming() when the guide layer is being processed.

Subclasses should override this method to implement custom naming logic for guide nodes. The default implementation names guides based on the component’s naming configuration.

Parameters:
  • namingConfig (zoo.libs.naming.naming.NameManager) – The naming configuration instance containing naming rules.

  • modifier (zapi.dgModifier) – The Maya DG modifier to use for renaming operations.

Note

  • This method is called after postSetupGuide() during component updates.

  • The modifier’s doIt() will be called by the caller, don’t call it here.

  • Only modify node names within the guide layer.

  • The method should handle both creation and update scenarios.

  • Use the provided namingConfig to resolve names consistently.

Example implementation:
def setGuideNaming(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)
setIsHistoricallyInteresting(state)

Sets the isHistoricallyInteresting state on the component.

Parameters:

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

setMetaNode(node)

Associates a Maya node as the component’s meta node.

This method sets the internal reference to the component’s meta node, which stores the component’s metadata. The meta node is a critical part of the component that maintains its state in the Maya scene.

Parameters:

node (MObject) – The Maya node object to be used as the component’s meta node. This should be a valid MObject representing a HiveComponent node.

Returns:

The created HiveComponent instance wrapping the provided node.

Return type:

layers.HiveComponent

Note

  • This is typically called internally during component creation or loading.

  • The node must be compatible with the HiveComponent type.

  • This method will override any existing meta node reference.

  • The component’s existence state will be updated based on the node’s state.

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.

setRigNaming(namingConfig, modifier)

Hook for implementing custom naming conventions for rig nodes in subclasses.

This method is called during the component’s update process to ensure all rig nodes follow the current naming convention. It’s automatically called by updateNaming() when processing the rig layer. Subclasses should override this method to implement custom naming logic for rig-specific nodes.

The default implementation does nothing, allowing components without special rig naming requirements to skip this step.

Parameters:
  • namingConfig (zoo.libs.naming.naming.NameManager) – The naming configuration instance containing naming rules.

  • modifier (zapi.dgModifier) – The Maya DG modifier to use for renaming operations.

Note

  • This method is called after postSetupRig() during component updates.

  • The modifier’s doIt() will be called by the caller, don’t call it here.

  • Only modify node names within the rig layer.

  • Use the provided namingConfig to resolve names consistently.

  • This is the place to implement custom naming for rig-specific nodes.

Example implementation:
def setRigNaming(self, namingConfig, modifier):
    compName, compSide = self.name(), self.side()
    for ctrl in self.rigLayer().iterControls():
        name = namingConfig.resolve("controlName", {
            "componentName": compName,
            "side": compSide,
            "id": ctrl.id(),
            "type": "control"
        })
        ctrl.rename(name, maintainNamespace=False, mod=modifier, apply=False)
setSide(side)

Updates the side designation of the component.

This method changes the side of the component and updates all related data structures, including the meta node and naming configuration. It handles the necessary updates to maintain consistency across the component’s nodes and naming conventions.

Parameters:

side (str) – The new side designation (e.g., ‘L’ for left, ‘R’ for right, ‘C’ for center)

Note

  • This method updates both the component’s definition and its meta node (if it exists).

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.

setupDrivers()

Method which sets up all drivers for this components, drivers are direct,sdk connections which come from external sources. Executed after all components have been built

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

setupMirroring(oppositeComponent, mirrorPlaneObject, mirrorPlaneAxis)
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.

show()

Makes the component visible in the Maya scene by enabling its root transform’s visibility.

This method restores the visual representation of a previously hidden component in the viewport. The visibility state is persistent and will be saved with the scene.

Returns:

True if the component was successfully shown, False if the component doesn’t exist or is already visible.

Return type:

bool

Note

  • This method is the counterpart to hide() and only affects viewport visibility.

  • To check the current visibility state, use the isHidden() method.

  • This will not affect the component’s functionality, only its visual representation.

side()

Retrieves the side designation of the component.

The side typically represents the location of the component on the character’s body (e.g., ‘L’ for left, ‘R’ for right, ‘C’ for center) and is used in naming conventions and component organization.

Returns:

The side designation of the component (e.g., ‘L’, ‘R’, ‘C’)

Return type:

str

Note

  • The side is typically set during component creation but can be modified later.

  • To change the side, use the setSide() method to ensure proper updates.

  • The side is used in node naming and should follow the project’s naming conventions.

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[str, :class:`basesybsystem.BaseSubsystem]`

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

updateComponentDefinition(original, definition, originalVersion, oldVersion)
Parameters:
  • original (baseDef.ComponentDefinition)

  • definition (baseDef.ComponentDefinition)

  • originalVersion (version.LooseVersion)

  • oldVersion

Type:

oldVersion: version.LooseVersion

updateDeformJointRadius(bindJoints, nonBindJoints, deformRadius=1.0, nonDeformRadius=1.0)
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)

Returns:

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

Return type:

dict

updateJointColours(deformJoints, nonDeformJoints, colour)
updateJointDrawMode(joints, drawMode=0)
updateNaming(layerTypes=('HiveGuideLayer', 'HiveDeformLayer'), modifier=None, apply=True)

Updates the names of all nodes in the component based on the current naming configuration.

This method refreshes the naming of all nodes within the specified layers of the component to ensure they match the current naming conventions defined in the component’s configuration. It handles different types of nodes including inputs, outputs, and deform layers.

Parameters:
  • layerTypes (tuple) – A tuple of layer types to update. Currently supports: - constants.GUIDE_LAYER_TYPE: For guide nodes - constants.DEFORM_LAYER_TYPE: For deform nodes - constants.INPUT_LAYER_TYPE: For input nodes - constants.OUTPUT_LAYER_TYPE: For output nodes

  • modifier (zoo.libs.maya.zooapi.DGModifier or None) – The Maya DG modifier to use for the operation. If None, a new one will be created.

  • apply (bool) – If True, the modifier will be applied immediately. Set to False to delay application.

Note

  • This method updates node names in-place and cannot be undone if applied.

  • The naming follows the component’s current naming configuration.

  • Only updates nodes in the specified layer types.

  • If modifier is not applied (apply=False), you must apply it manually later.

  • This is typically called after changing naming conventions or component properties.

Returns:

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

Return type:

zapi.dgModifier

uuid()

Returns the UUID (Universally Unique Identifier) for the component.

The UUID is a unique identifier that remains constant for the lifetime of the component, even if the component is renamed. It can be used to reliably reference the component across different sessions or when the component’s name changes.

Returns:

The UUID string in the format ‘xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx’

Return type:

str

Note

If the component’s meta node exists, the UUID is retrieved from it. Otherwise, the UUID is retrieved from the component’s definition data.

validateGuides(validationInfo)

Called by UI or api on demand to validate the current state of the guides. If the component finds the state as invalid, the validationInfo object should be updated with a user error/warning message appended to it.

class IdOrderGroup(group, entries)

Bases: object

Parameters:
  • group – The group name

  • entries – The entries in the group

Note:

if entry contains a “side” key this will be used in components which require a local mirror eg. mouth L/R corners

static findGroup(idOrderGroups, groupId)
Parameters:

idOrderGroups (list[IdOrderGroup])

disconnectJointTransforms(deformLayer)

Disconnect all transform attributes on joints that have incoming connections.

This function removes all constraints and disconnects transform-related attributes from the specified deformation layer’s joints. This is typically used during the rigging process to ensure clean joint hierarchies.

The following attributes are processed:
  • All local transform attributes (translate, rotate, scale)

  • offsetParentMatrix

  • worldMatrix

  • matrix

Parameters:

deformLayer (layers.HiveDeformLayer) – The deformation layer containing the joints to process.

resetJointTransforms(deformLayer, guideDefLayer, idMapping)

Reset all joints in the deformation layer to match their guide definitions.

This function resets the transforms of all joints in the specified deformation layer to match their corresponding guide definitions. This is typically used during the rigging process to ensure joints are properly aligned with their guide counterparts.

The function performs the following operations for each joint:
  • Looks up the corresponding guide definition using the ID mapping

  • Retrieves the world transformation matrix from the guide (excluding scale)

  • Resets the joint’s transform and offset parent matrix

  • Applies the guide’s world transformation to the joint

Parameters:
  • deformLayer (layers.HiveDeformLayer) – The deformation layer containing the joints to reset.

  • guideDefLayer (baseDef.GuideLayerDefinition) – The guide layer definition containing the target transforms.

  • idMapping (dict) – Dictionary mapping guide IDs to deformation joint IDs.