Component¶
- class Component(rig, definition=None, metaNode=None)¶
Bases:
objectBase 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:
idMapping()- Define the ID mapping for the componentpreSetupGuide()- Pre-guide setup logicsetupGuide()- Main guide creation methodpostSetupGuide()- Post-guide setup logicalignGuides()- Guide alignment logic
- Deformation System:
setupInputs()- Set up input connectionsdeformationJointIds()- Define deformation joint IDssetupOutputs()- Set up output connectionspostSetupDeform()- Post-deformation setup logic
- Rig System:
preSetupRig()- Pre-rig setup logicsetupRig()- Main rig creation methodpostSetupRig()- Post-rig setup logicprePolish()- Pre-polish operationspostPolish()- Post-polish operations
- Naming and UI:
createRigControllerTags()- Create controller tags for the rigcreateGuideControllerTags()- Create controller tags for guidessetupSelectionSet()- Set up selection setssetGuideNaming()- Configure guide namingsetDeformNaming()- Configure deformation namingsetRigNaming()- Configure rig naming
- Mirroring:
updateGuideSettings()- Update guide settingspreMirror()- Pre-mirror operationspostMirror()- Post-mirror operations
- Parameters:
rig (
zoo.libs.hive.base.rig.Rig) – The rig instance that this component belongs to.definition (
zoo.libs.hive.base.definition.ComponentDefinitionor 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
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:
- 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:
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.ComponentDoesntExistErrorif the component doesn’t exist.- Raises:
errors.BuildComponentGuideUnknownErrorif an unknown error occurs while building the guide system
- buildRig(parentNode=None)¶
Build the rig for the current component.
- Parameters:
parentNode (
zapi.DagNodeor None) – parent node for the rig to be parented to. If None, the rig will not be parented to anything.- Raises:
ComponentDoesntExistErrorif the current component doesn’t exist- Raises:
BuildComponentRigUnknownErrorif building the rig fails
- children(depthLimit=256)¶
Generator method which returns all component children instances.
- 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.Jointor None) – Default parent node when None exist.- Returns:
The parent components joint or the provided default via parentNode argument.
- Return type:
hnodes.Jointorhnodes.DagNodeor 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:
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.ConnectableNodeorbaseDef.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.ContainerAssetor 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.SettingsNodeor 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.HiveRigor 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.Plugor 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.Plugor 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:
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.HiveDeformLayeror 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:
- 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:
rigLayer
deformLayer
inputLayer
outputLayer
guideLayer
assetContainer
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:
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:
- deleteGuide()¶
This function deletes the guide system.
- Returns:
True if the guide system is successfully deleted
- Return type:
- 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:
- 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
- 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:
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.HiveGeometryLayeror None.
- group()¶
- guideLayer()¶
Returns the guide layer node from the component, retrieved from the components meta node
- Return type:
layers.HiveGuideLayeror 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:
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.
- 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:
- 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:
- 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:
- 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:
- 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:
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:
- 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.HiveInputLayeror 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:
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:
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:
- 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()andComponent.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:
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:
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.DGNodeorzapi.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.HiveOutputLayeror 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:
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:
- 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 (
Componentor 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:
- rigLayer()¶
Returns the rig layer node from the component, retrieved from the components meta node
- Return type:
layers.HiveRigLayeror 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.MObjector 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.ComponentDefinitionor 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:
- 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.Jointorzapi.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:
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:
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': ()}¶
- 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.
- 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.DGModifieror 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:
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.