Process/Addons/Rigify/Generator

= Main Generator Engine =

This describes the main classes that manage the generation of a rig.

Generator
The rig generation process is managed by an instance of the Generator class. It duplicates the metarig, instantiates the rig objects, creates the root control bone, executes the generation stages, and manages some other global operations.

Fields
The generator instance has the following fields:


 * `context`
 * Blender context in which the generation was invoked.


 * `scene`
 * Current scene.


 * `view_layer`
 * Current view layer.


 * `layer_collection`
 * Current layer collection.


 * `collection`
 * Current collection.


 * `metarig`
 * The original metarig object.


 * `obj`
 * The rig object being generated.


 * `stage`
 * The name of the current stage being executed.


 * `script`
 * The ScriptGenerator object that manages generation of the UI script.


 * `rig_id`
 * The random identifier string for the rig being generated.


 * `rig_list`
 * A list of all rig instances.


 * `root_rigs`
 * A list of all rig instances without a parent rig.


 * `bone_owners`
 * A map from bone names to the rig instance that owns them.


 * `derived_bones`
 * A map from bone names to sets of bones created by copying from them.

Methods
These are the public methods of the Generator class:


 * `generator.disable_auto_parent(bone_name)`
 * By default, all bones left without a parent are parented to the root control. This method excludes a bone from this function.


 * `generator.find_derived_bones(bone_name, *, by_owner=False, recursive=True)`
 * Returns a set of bones copied from the specified one. The `by_owner` option limits search to the owner rig of the bone. The `recursive` option enables walking through multiple chained copies.


 * `generator.set_layer_group_priority(bone_name, layers, priority)`
 * Assign a priority value used for choosing which layer to base the bone group choice on for the given bone. The value is set for the given layers.


 * `generator.rename_org_bone(old_name, new_name)`
 * May be used from `SubstitutionRig.substitute` to rename ORG bones.


 * `generator.find_rig_class(rig_type)`
 * Looks up a rig class by its ID string.


 * `generator.describe_rig(rig)`
 * Returns a string containing the rig class and base bone.

LegacyRig
Rigs that don't inherit from the `BaseRig` class are considered to use the legacy interface, and are wrapped in a `rigify.base_generate.LegacyRig` wrapper class. The wrapper itself inherits from `BaseRig`, and translates between the two API interfaces.

The old style `generate` method is invoked during the `generate_bones` stage, because that is the only stage that can create bones.

Fields:


 * `wrapped_rig`
 * The instance of the legacy rig wrapped by the class.

SubstitutionRig
In some special cases (mainly backward compatibility) it is necessary to present one or more different rig components as one, with the actual set of rigs depending on the structure and parameters of the rig.

This can be achieved by implementing a `Rig` class that inherits from `rigify.base_generate.SubstitutionRig`. Such classes are handled specially during the rig instantiation phase: instead of saving the newly created rig instance, the Generator immediately invokes its `substitute` method, and uses the list of rig instances returned from it instead.

Fields:


 * `generator`
 * The instance of Generator.


 * `obj`
 * The rig being generated.


 * `base_bone`
 * The name of the main bone that instantiated the rig.


 * `params`
 * The parameters attached to the main bone.


 * `params_copy`
 * Snapshot of the parameters attached to the main bone.

Methods:


 * `rig.substitute` callback
 * Invoked immediately after instantiation and expected to return a list of rig instances.
 * If it is necessary, this method may temporarily switch to edit mode to modify bone parenting and/or orientations.


 * `rig.get_params(bone_name)`
 * Returns the parameters container for the given bone.


 * `rig.assign_params(bone_name, param_dict=None, ...)`
 * Assigns values into the parameter container of the given bone. Parameter values may be supplied as a dictionary, or directly as named parameters. If both are supplied, the named parameters have precedence.


 * `rig.instantiate_rig(rig_class, bone_name)`
 * Creates a rig instance of the given type (specified as a class, or an ID string) for the specified bone.

GeneratorPlugin
Some functionality within the generation process isn't naturally tied to any specific rig component, and is instead equally shared between all of them. The generation of the UI script is one such example.

Such features can be conveniently implemented via classes that inherit from `rigify.base_generate.GeneratorPlugin`. Due to the metaclass and base classes used by GeneratorPlugin, such classes become parameterized singletons, which can have the same stage callbacks as regular rig classes.

Fields

 * `priority` static
 * Stage callbacks of the generator plugin instances are invoked after all of the rig callbacks are completed, in the order of decreasing priority.


 * `generator`
 * The Generator instance.


 * `obj`
 * The rig being generated.

Methods

 * `rig.__init__(generator)`
 * Initializes the plugin instance. As a parameterized singleton, every unique set of constructor parameter values creates a separate class instance, while passing the same values result in the same object.