-------------------------------------------------------------------------- ***** BEGIN GPL LICENSE BLOCK ***** Script copyright (C) Bassam Kurdali This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details. You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA 02111-1307, USA. ***** END GPL LICENCE BLOCK ***** -------------------------------------------------------------------------- copyright 2009 Bassam Kurdali thanks to Martin Poirier for code reviews, fixes and advice Rigamarule version 0.1 README file COMPONENTS This is the first preview release of an autorigging/templating system for blender, titled Rigamarule The concept is simple: *each bone is tagged with some data. This is done via the pyconstraint rule.py. The data consists of: 1- a priority. lower numbers are executed first. 2- a rule name. Applicable names currently describe methods in marulez.py example: a rule "copy" would execute method RULEcopy in marulez.py 3- rule arguments: self component: can be head, tail or roll (or blank) targets: none, one, two or three bones in the same armature target component: can be head, tail or roll (or blank) x,y,z: are typically floats used to describe an euler angle, or they can be used to describe an axis vector, depending on the rule. *the file marulez.py contains a bunch of methods (rules) with names/arguments like RULEfoo(self, component, targets, target_component, axis) where self is the bone itself, and the rest are as in the tags from rule.py. *running the script rigamarule.py with the armature selected (must be in pose or object mode) will iterate over the bones, find all the rules' and execute the appropriate method with the appropriate argument. The dictionary of rules is built dynamically, so rigger can add their own custom rules to marulez.py. some possiblities with the current rules: copy: copies the bone's head, tail, roll to the targets' (in addition, you can do head to tail and tail to head) align: aligns a bone to another bone, or to a user defined axis. offset: offsets a bone some distance defined by a vector, if a target is given it uses the coord system defined by that target. rotate: euler rotation by an angle in xyz enplane: aligns the role either putting the x, or the z axis in plane with triangle defined by a two bone chain in arguments; useful for fk/ik chains. *etchaton integration: *the py constraint boneid.py tags the bone with it's own name and the name of it's armature object. *drtaggert.py can automatically do this for all bones in the template. (it also has an option to remove names) *when you use etchaton to retarget a template, the names are mangled from &N.&S to e.g. 1.L. the rules' targets however, are not affected by etchaton. *after using etchaton, you can run rigamarule.py, but this time, activate "etchafix" this will cause the targets to be renamed from &N.&S to whatever the etchaton made (e.g. 1.L). however, you must use a number for &N, or this will fail. after this, rigamarule runs normally. *in addition there is a left right fix; running this causes mirrored left/right bones, to have their targets renamed appropriately. USAGE **File Placement** the files must be present in the user's .blend file however, both rigamarule.py and drtaggert.py can be placed in the scripts directory and executed from the object menu. **Initial Rig or Template** while rigging (either a template or a whole rig) the rigger should tag the bones with rules as above, to constrain the bones' edit mode position. best practice is to only use "Geometry" bones i.e. bones that define the joints and geometry of the character, as targets, and to keep those geometry bones on one layer alone. The Geometry bones themselves must have a lower priority i.e. priority zero to execute their own rules first (this is usually only enplane to fix the rolls). the other rules get priority 1 or higher. If etchaton is being used (i.e. the rigger is making a template), then she should also run drtaggert.py to tag her template when she is done. **Retarget** retarget only requires rigamarule.py. there are two options: 1- retarget the entire armature, by moving the geometry bones (that's why it's good to isolate them to one layer) only to the new mesh; you can use volume snap to make this very quick. Then run rigamarule, and the other bones (controls, helper bones, fan bones, etc) are appropriately placed and aligned based on rules. 2- use etchaton: in this case, it is the same, except instead of snaps you use etchaton to retarget from a template, then run rigamarule.py with etchafix enabled to demangle the names. In addition, when you flip all to the right (or left) side, use rigamarule with left/right fix, to fix the right side. FUTURE PLANS: 0- add more rules, move the 'base' rules out of marulez.py and into rigamarule.py, so that that file (marulez.py) will be ready for riggers to add their own rules. 1- port to blender 2.5 and python 3.1 2- extend to work on more than one armature, and to work with objects (hooks/curves/lattices) as well. 3- more rules for e.g. adjusting bone limits, or changing actions. 4- handle drivers and ipos (or drivers and fcurves) in the rig, potentially making copies. 5- perhaps more specific rules / features to handle facial rigs. 6- ship with some already useful templates (arms/legs/torso/fingers/whole body/etc). potentially, mancandy and rigamarule could ship together. 7- more user friendly interface (depends on blender 2.5) 8- begin to handle/bundle with scripts that handle weight paint/vgroups and shapes. 9- automatically add modifiers to target meshes. 10- potentially split interfaces to a suite of retargetting tools, and a 'fixed' autorigger, that uses a fixed template. 11- anything else?