Component¶
- class Component(rig, definition=None, metaNode=None)¶
Bases:
object
Component class that encapsulates a single rigging component, This is the class that would be overridden.
- BuildSystem Methods:
Component.spaceSwitchUiData()
- 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.
- 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.
- documentation = ''¶
- betaVersion = False¶
- isBuildingSkeleton: bool¶
True only while we are constructing the skeleton/deform system for this component
- logger¶
The python logging instance for this component
- property meta¶
Component meta node
- Returns:
Hive component meta node
- Return type:
- property componentType¶
Returns the component name which can be used do a lookup in the registry
- Return type:
- 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:
- property blackBox¶
Convenience method, If this component has a container object then return the container.blackBox value
- Return type:
- 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:
- 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:
- hide()¶
Hides the component by turning off the visibility on the root transform
- Returns:
Success
- Return type:
- show()¶
Shows the component by turning on the visibility on the root transform
- Returns:
Success
- Return type:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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:
- 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
- renameNamespace(namespace)¶
Renames the namespace which acts as the component name
- Parameters:
namespace (str) – the new namespace
- parentNamespace()¶
Returns the parent namespace of this components namespace.
- Returns:
the parent namespace, eg. “:parent”
- Return type:
- removeNamespace()¶
Removes the namespace of the this component and moves all children to the root namespace
- Return type:
- 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:
- 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:
- 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:
- children(depthLimit=256)¶
Generator method which returns all component children instances.
- 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
- 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
- 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
orzapi.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
orhnodes.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:
- 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:
- 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.
- 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:
- 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
orzapi.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 instancedeformJoints (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:
- 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:
- 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:
- 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 instanceguideDefLayer (
baseDef.GuideLayerDefinition
) – The component definition guideLayer instance.idMapping –
- class SpaceSwitchUIDriver(id_, label, internal=False)¶
Bases:
object
SpaceSwitch UI Driver control data.
- Parameters: