diff options
Diffstat (limited to 'rigify/README')
-rw-r--r-- | rigify/README | 250 |
1 files changed, 0 insertions, 250 deletions
diff --git a/rigify/README b/rigify/README deleted file mode 100644 index f8cb7656..00000000 --- a/rigify/README +++ /dev/null @@ -1,250 +0,0 @@ -INTRODUCTION ------------- -Rigify is an auto-rigging system based on a "building blocks" paradigm. The -user can create a rig by putting together any combination of rig types, in any -configuration that they want. - -A rig type is something like "biped arm" or "spine" or "finger". - -The input to the Rigify system is something called a "metarig". It is an -armature that contains data about how to construct the rig. In particular, it -contains bones in the basic configuration of the rig, with some bones tagged -to indicate the rig type. - -For example, a metarig might contain a chain of three bones, the root-most of -which is tagged as being a biped arm. When given as input to Rigify, Rigify -will then generate a fully-featured biped arm rig in the same position and -proportions as the 3-bone chain. - -One could also have another chain of bones, the root-most of which is tagged as -being a spine. And the root-most bone of the arm chain could be the child of -any of those spine bones. Then the rig that Rigify generates would be a -spine rig with an arm rig attached to it. - - -THE GUTS OF RIGIFY, SUMMARIZED ------------------------------- -The concept behind rigify is fairly simple. It recieves an armature as input -with some of the bones tagged as being certain rig types (arm, leg, etc.) - -When Rigify recieves that armature as input, the first thing it does is -duplicate the armature. From here on out, the original armature is totally -ignored. Only the duplicate is used. And this duplicate armature object will -become the generated rig. - -Rigify next prepends "ORG-" to all of the bones. These are the "original" -bones of the metarig, and they are used as the glue between rig types, as I -will explain later. - -Rigify then generates the rig in two passes. The first pass is the -"information gathering" stage. - -The information gathering stage doesn't modify the armature at all. It simply -gathers information about it. Or, rather, it lets the rig types gather -information about it. -It traverses the bones in a root-most to leaf-most order, and whenever it -stumbles upon a bone that has a rig type tagged on it, it creates a rig-type -python object (rig types will be explained further down) for that rig type, -and executes the resulting python object's information gathering code. - -At the end of the information gathering stage, Rigify has a collection of -python objects, each of which know all the information they need to generate -their own bit of the rig. - -The next stage is the rig generation stage. This part is pretty simple. All -Rigify does is it loops over all of the rig-type python objects that it created -in the previous stage (also in root-most to leaf-most order), and executes -their rig-generate code. All of the actual rig generation happens in the -rig-type python objects. - -And that's pretty much it. As you can see, most of the important code is -actually in the rig types themselves, not in Rigify. Rigify is pretty sparse -when it comes right down to it. - -There is one final stage to rig generation. Rigify checks all of the bones -for "DEF-", "MCH-", and "ORG-" prefixes, and moves those bones to their own -layers. It also sets all of the "DEF-" bones to deform, and sets all other -bones to _not_ deform. And finally, it looks for any bone that does not have -a parent, and sets the root bone (which Rigify creates) as their parent. - - -THE GUTS OF A RIG TYPE, BASIC ------------------------------ -A rig type is simply a python module containing a class named "Rig", and some -optional module functions. The Rig class has only two methods: -__init__() and generate() - -__init__() is the "information gathering" code for the rig type. When Rigify -loops through the bones and finds a tagged bone, it will create a python -object from the Rig class, executing this method. -In addition to the default "self" parameter, __init__() needs to take the -armature object, the name of the bone that was tagged, and a parameters object. - -A proper rig-type __init__() will look like this: - - def __init__(self, obj, bone_name, params): - # code goes here - -At the bare minimum, you are going to want to store the object and bone name -in the rig type object for later reference in the generate() method. So: - - def __init__(self, obj, bone_name, params): - self.obj = obj - self.org_bone = bone_name - -Most rig types involve more than just that one bone, though, so you will also -want to store the names of any other relevant bones. For example, maybe the -parent of the tagged bone is important to the rig type: - - def __init__(self, obj, bone_name, params): - self.obj = obj - self.org_bone = bone_name - self.org_parent = obj.data.bones[bone_name].parent.name - -It is important that you store the _names_ of the bones, and not direct -references. Due to the inner workings of Blender's armature system, direct -edit-bone and pose-bone references are lost when flipping in and out of -armature edit mode. (Arg...) - -Remember that it is critical that the information-gathering method does _not_ -modify the armature in any way. This way all of the rig type's info-gathering -methods can execute on a clean armature. Many rig types depend on traversing -parent-child relationships to figure out what bones are relevant to them, for -example. - - -Next is the generate() method. This is the method that Rigify calls to -actually generate the rig. It takes the form: - - def generate(self): - # code goes here - -It doesn't take any parameters beyond "self". So you have to store any -information you need with the __init__() method. - -generate() pretty much has free reign to do whatever it wants, with the exception -of two simple rules: -1. Other than the "ORG-" bones, do not touch anything that is not created by -the rig type (this prevents rig types from messing each other up). -2. Even with "ORG-" bones, the only thing you are allowed to do is add children -and add constraints. Do not rename them, do not remove children or -constraints, and especially do not change their parents. (Adding constraints -and adding children are encouraged, though. ;-)) This is because the "ORG-" -bones are the glue that holds everything together, and changing them beyond -adding children/constraints ruins the glue, so to speak. - -In short: with the exception of adding children/constraints to "ORG-" -bones, only mess with things that you yourself create. - -It is also generally a good idea (though not strictly required) that the rig -type add constraints to the "ORG-" bones it was generated from so that the -"ORG-" bones move with the animation controls. -For example, if I make a simple arm rig type, the controls that the animator -uses should also move the "ORG-" bones. That way, any other rig-types that are -children of those "ORG-" bones will move along with them. For example, any -fingers on the end of the arm. - -Also, any bones that the animator should not directly animate with should have -their names prefixed with "DEF-" or "MCH-". The former if it is a bone that -is intended to deform the mesh, the latter if it is not. -It should be obvious, then, that a bone cannot be both an animation control and -a deforming bone in Rigify. This is on purpose. - -Also note that there are convenience functions in utils.py for prepending -"DEF-" and "MCH-" to bone names: deformer() and mch() -There is also a convenience function for stripping "ORG-" from a bone name: -strip_org() -Which is useful for removing "ORG-" from bones you create by duplicating -the "ORG-" bones. -I recommend you use these functions instead of manually adding/stripping -these prefixes. That way if the prefixes are changed, it can be changed in -one place (those functions) and all the rig types will still work. - - -THE GUTS OF A RIG TYPE, ADVANCED --------------------------------- -If you look at any of the rig types included with Rigify, you'll note that they -have several functions outside of the Rig class. -THESE ADDITIONAL FUNCTIONS ARE _NOT_ REQUIRED for a rig type to function. But -they can add some nifty functionality to your rig. - -Here are the additional functions relevant to Rigify, with brief decriptions of -what they are for: - - -RIG PARAMETERS --------------- -For many rig types, it is handy for the user to be able to tweak how they are -generated. For example, the included biped arm rig allows the user to specify -the axis of rotation for the elbow. - -There are two functions necessary to give a rig type user-tweakable parameters: -add_parameters() -parameters_ui() - -add_parameters() takes an IDPropertyGroup as input, and adds its parameters -to that group as RNA properties. For example: - - def add_parameters(params): - params.toggle_param = bpy.props.BoolProperty(name="Test toggle:", default=False, description="Just a test, not really used for anything.") - -parameters_ui() recieves a Blender UILayout object and an IDPropertyGroup -containing the parameters added by add_parameters(). It creates a GUI in the -UILayout for the user to tweak those parameters. For example: - - def parameters_ui(layout, params): - r = layout.row() - r.prop(params, "toggle_param") - - -SAMPLE METARIG --------------- -It is a good idea for all rig types to have a sample metarig that the user can -add to their own metarig. This is what the create_sample() function is for. - -create_sample() takes the current armature object as input, and adds the bones -for its rig-type's metarig. For example: - - def create_sample(obj): - bpy.ops.object.mode_set(mode='EDIT') - arm = obj.data - - bone = arm.edit_bones.new('Bone') - bone.head[:] = 0.0000, 0.0000, 0.0000 - bone.tail[:] = 0.0000, 0.0000, 1.0000 - bone.roll = 0.0000 - bone.use_connect = False - - bpy.ops.object.mode_set(mode='OBJECT') - pbone = obj.pose.bones[bone] - pbone.rigify_type = 'copy' - pbone.rigify_parameters.add() - -Obviously, this isn't something that you generally want to hand-code, -especially with more complex samples. When in edit-mode on an armature, -there is a "Rigify Dev Tools" panel in the View3d tools panel containing a -button labeled "Encode Sample to Python". This button will generate the python -code for create_sample() from the armature you are editing. The generated code -appears in a text block called "metarig_sample.py" - -IMPLEMENTATION RIGS -------------------- -Starting from version 0.5 you can create a Rig class as an implementation of a wrapper class. -This happens for limb rigs for example, where super_limb is kind of a wrapper class for arm, leg and paws. -To declare a class as an implementation just declare an IMPLEMENTATION constant in the module and set it to True. -Implementation classes are shown in the metarig samples list and generate a sample if a proper create_sample function is implemented, but cannot be directly assigned as a rigify type. - -GENERATING A PYTHON UI ----------------------- -The generate() method can also, optionally, return python code as a single -string. This python code is added to the "rig properties" panel that gets -auto-generated along with the rig. This is useful for exposing things like -IK/FK switches in a nice way to the animator. - -The string must be returned in a list, e.g.: - -return ["my python code"] - -The reason it needs to be put in a list is to leave room for expanding the API -in the future, for returning additional information. - |