Examples

Add A Rig

# first initialise an empty rig instance
from zoo.libs.hive import api
char = api.Rig()
# now either create or initialise a pre-existing rig(searches by name)
char.startSession("characterName") # populates the rig instance for meta etc

Add a Component to a Rig

# createComponent but dont build guides or rig
godNode = char.createComponent("godnodecomponent", "godnode", "M")
arm = char.createComponent("vchaincomponent", "arm", "L")
# get the full component list from the registry
char.configuration.componentRegistry().components # dict()
# get the current attached rig components
char.components()
# or by name
char.component("arm", "L") # searches by name and side
# or use "." syntax
char.arm_L == godNode # False
char.godnode_M == godNode # True

Build Component Guides & Rig

# build component guides and rigs
char.buildGuides()
char.buildRigs()

# lets do some queries and see what we have
# get the guide controls
arm.guideLayer().iterGuides()
#get a certain guide by id(we always use the id  as it should never change(death is the punishment))
endGuide = arm.guideLayer().guide("end")# this is the wrist guide
endGuide.translation() # api.Vector
endGuide.rotation(space=api.kTransformSpace, asQuaternion=False)# api.EulerRotation
endGuide.rotation(space=api.kWorldSpace, asQuaternion=True) # api.Quaternion
endGuide.serializeFromScene() # get a dict() version of the guide which is necessary to recreate it
endGuide.parent() # Guide Parent instance

Query Controls from a component

# what about the rig?
# same  as the guides
arm.rigLayer().control("endfk")
endControl = arm.rigLayer().control("uprfk")
endControl.translation()
#what about special animation attributes?
# we use separate nodes to store anim for a number reasons but heres the code for the arm
arm.controlPanel().ikfk
#returns a api.Plug instance
# settings nodes can be on any layer but these dont show up to animators only
#controlPanel does. Well unless your component has custom overrides
rigLayer = arm.rigLayer()
rigLayer.settingsNodes() # [:class:`api.SettingsNode`]
# creation
settingInstance = rigLayer.createSettingsNode("myCustomSettings")
settingInstance.addAttribute("myHiddenSetting", value=10, default=0, Type=api.kMFnNumericFloat)
# skin joints?
# same stuff just different name
arm.deformLayer().joint("end").translation()

print(settingInstance)
# get the meta node instances
print(char.meta)
print(arm.meta)
print(rigLayer)
# get the root transform of the arm  component
print(arm.rootTransform())

Update guides transform to match existing Hive Joints

This example leverages the idMapping method on components to match guides to joints. This method provide access to ids which match between the guide layer and other layers on the component ie. guides->joints.

from zoo.libs.hive import api

for rig in api.iterSceneRigs():
    for comp in rig.iterComponents():
        mapping = comp.idMapping()
        deformLayer, guideLayer = comp.deformLayer(), comp.guideLayer()
        deformMap = mapping[api.constants.DEFORM_LAYER_TYPE]
        joints = deformLayer.findJoints(*deformMap.values())
        guides = guideLayer.findGuides(*deformMap.keys())

        for guide, joint in zip(guides, joints):
            transformMat = joint.transformationMatrix()
            transformMat.setScale(guide.scale(zapi.kTransformSpace), zapi.kTransformSpace)
            guide.setWorldMatrix(transformMat.asMatrix())

Create a guide programmatically.

# creation is just as easy but more information is needed if you don't want the defaults
#create a guide
data = {
            "name": "godnode",
            "translate": [
                0.0,
                10.0,
                0.0],
            "rotate": [   # rotation are in quaternions
                0.0,
                0.0,
                0.0,
                1.0],
            "rotationOrder": 0,
            "shape": "godnode", # can be a string for a shape in the library or a dict
            "id": "godnode",  # hive internal id to set
            "parent": arm.guideLayer().guide("mid"), # must be a hiveclass
            "children": [],
        }
arm.guideLayer().createGuide(**data)  # done, adds a new guide and all the meta data etc
# same with the rigLayer, deformLayer inputs and outputs all the same jazz

# lets now parent the two components the arm is driven by the godnode
arm.setParent(godNode, godNode.guideLayer().guide("godnode"))

Casting Scene Objects to Hive Objects.

from zoo.libs.maya import zapi
for i in zapi.selected():
    component = api.componentFromNode(i) # returns the attached component if any or None
    rig = api.rigFromNode(i)# same but grabs a rig instance instead

    print(component, rig)

Grouping components

char.createGroup("myGroup", components=ri.components())
# current group names
rig.groupNames()
# retrieve components of a group is a generate function
rig.iterComponentsForGroup("myGroup")
# delete a group
rig.removeGroup("myGroup")

Upgrading Rigs via the commandline or terminal.

This script shows how you could use a mayapy/batch session to upgrade a hive rig.

With the below Commandline script make sure you change the paths for your setup.:

set MAYA_MODULE_PATH=zootoolspro/install/core/extensions/maya;
set ZOO_LOG_LEVEL=DEBUG
mayapy.exe upgrade_hive_rig_cli.py --scene my_rig_scene.ma --outputPath my_rig_scene_upgraded.ma

upgrade_hive_rig_cli.py

import argparse
import contextlib


def parseArguments():
    parser = argparse.ArgumentParser("Hive",
                                     description="Provides a script to upgrade a hive rig which resides within maya "
                                                 "scene")
    parser.add_argument("--outputPath", type=str, required=True, help="Output path for the upgrade rig file.")
    parser.add_argument("--rigName", type=str, required=False, help="The name of the rig in the scene, defaults to "
                                                                    "finding the first rig in the scene.")
    parser.add_argument("--scene", type=str, required=True,
                        help="The Maya scene path to load")
    return parser.parse_args()


def upgradeRig(rig):
    """Does the actual labour of rebuilding the rig, relies on the current scenes cached rig definition.

    We always go back to the guides which updates the rig definition merging new updates from the base components
    before user modification. Before we delete the control rig(maintaining joints and deformation) then we polish
    the rig for final output.

    :param rig: The Hive rig instance to upgrade.
    :type rig: :class:`api.Rig`
    """
    rig.buildGuides()
    rig.deleteRigs()
    rig.polish()


def findRigInstance(name=None):
    """Find the first occurrence of a hive rig which matches the give rig name.

    :param name: The rig name to find in the scene.
    :type name: str
    :return:
    :rtype: :class:`api.Rig`
    """
    from zoo.libs.hive import api
    if name:
        rigInstance = api.rootByRigName(name)
        if rigInstance is not None:
            return rigInstance
        raise api.HiveError("No rig in the scene with name: {}".format(name))
    rigs = list(api.iterSceneRigs())
    if not rigs:
        raise api.HiveError("No rigs in scene")
    return rigs[0]


@contextlib.contextmanager
def initializeContext():
    from maya import standalone
    standalone.initialize(name="python")
    try:

        yield
    finally:
        standalone.uninitialize()


if __name__ == "__main__":
    args = parseArguments()
    rigName = args.rigName
    outputPath = args.outputPath
    sceneFile = args.scene

    with initializeContext():
        from maya import cmds

        cmds.loadPlugin("zootools.py")

        from zoo.libs.maya.utils import files

        cmds.file(sceneFile, force=True, options="v=0;", ignoreVersion=True, open=True)
        rigInstance = findRigInstance(rigName)
        upgradeRig(rigInstance)
        files.saveScene(outputPath)