Brush Assets Project #104846

Merged
Julian Eisel merged 32 commits from JulianEisel/blender-manual:temp-brush-assets into main 2024-07-08 18:45:49 +02:00
88 changed files with 2671 additions and 45 deletions
Showing only changes of commit ee02702e12 - Show all commits

View File

@ -27,4 +27,5 @@ Add-ons Category Listings
animation/index.rst
import_export/index.rst
node/index.rst
rigging/index.rst
system/index.rst

View File

@ -0,0 +1,11 @@
###########
Rigging
###########
These add-ons relate to rigging and armatures.
.. toctree::
:maxdepth: 1
rigify/index.rst

View File

@ -0,0 +1,276 @@
***********
Basic Usage
***********
.. _bpy.ops.pose.rigify_generate:
Basic Rig Generation
====================
#. Add a meta-rig structure from the :menuselection:`Add --> Armature` menu.
#. Edit the bone positions to match the character geometry.
#. In the armature properties click on the *Generate Rig* button to generate the rig.
Add a Predefined Meta-Rig
-------------------------
.. reference::
:Mode: Object Mode
:Menu: :menuselection:`Add --> Armature`
:Shortcut: :kbd:`Shift-A`
Rigify stores all the information required to generate complex rig controls and mechanism in
more simple armatures called "meta-rigs".
The predefined meta-rigs can be found in the *Add* menu.
Currently available meta-rig types are:
- Basic Human (doesn't include face and fingers)
- Basic Quadruped
- Human
- Cat
- Wolf
- Horse
- Shark
Edit Bone Positions
-------------------
To correctly match your character, meta-rig bones must be moved to correct positions.
This can be achieved in two different ways: Pose Mode or Edit Mode.
.. note::
Rigify assumes that 1 unit corresponds to 1 meter. So a human is about 2 units tall.
If your character is in a different scale and you are more familiar with modeling rather than rigging,
it is suggested to scale it to Rigify dimensions before positioning the meta-rig bones.
If you want to scale the character's geometry, we suggest you to first scale up the character in Object Mode,
then apply the geometry scale with the *Apply Scale* tool.
Rigify Human Alignment Tips
^^^^^^^^^^^^^^^^^^^^^^^^^^^
- Limbs: Keep the legs as straight as possible in the front view (Rigify human works better in predictable cases).
Give the knee and the elbow a slight bend angle (Rigify needs to know where your knee/elbow is pointing).
- Torso: Keep the spine as straight as possible in the front view (Rigify human works better in predictable cases).
The last bone of the spine is the head. By default the next two bones (top to bottom)
are considered the neck bones. It is suggested to keep the neck bones as aligned as possible while editing.
- Face: Positioning face bones can be tricky if you are not an expert in bone editing and
they are almost useless if you plan to make facial animation through shape keys.
Consider removing face features from your character if they aren't really needed.
If you don't need the face all the face bones can be deleted.
All the face bones are in the *Face* armature bone collection by default.
You can select them by displaying only that collection, selecting all of its content and
then deleting the bones in Edit Mode to correctly remove the face.
If you want to scale all the face bones at once, consider scaling the face master bone
in Pose Mode (see Pose Mode matching method).
The face master bone is placed in the same position of the head bone.
To select it easily, hide all other bone collections.
For more tips, see the :doc:`Positioning Guide </addons/rigging/rigify/bone_positioning>`.
Pose Mode Matching (Basic)
--------------------------
Enter the meta-rig Pose Mode. Rotate, scale, and translate the bones in the correct position.
When bones are in correct positions (always staying in Pose Mode)
use :menuselection:`Apply --> Apply Pose As Rest Pose`.
.. note::
Connected bones cannot be translated in Pose Mode.
You can scale the parent bones to match the general length and then refine child bones scale.
For more detailed information on armature modes please refer to
the :doc:`armatures section </animation/armatures/bones/editing/introduction>`.
Edit Mode Matching (Advanced)
-----------------------------
Some basic armature display setup is suggested before entering bone Edit Mode.
With the meta-rig selected, go in the Properties and click on the Object tab.
Scroll down to the display panel and enable X-ray and under *Maximum Draw Type* selector select *Wire*.
This way the bones will always be drawn in wireframe on top of your geometry.
Then, always in the Properties click on the Armatures tab and under display check the *Axis* checkbox.
This way you the bones rotation axes will be displayed during the edit process.
For more detailed information on armature display modes please refer to
the :doc:`Display panel page </animation/armatures/properties/display>`.
Generating the Rig
------------------
With the bones in the correct positions, jump back in Object Mode, go to the Armature tab,
scroll down to the bottom and click on the *Generate Rig* button to finalize the rig creation.
The generation process will take from few seconds to one minute depending on
rig complexity and hardware specifications of your machine.
If the generated rig needs tweaking, you can modify the meta-rig accordingly and
then click again on the generate button. If the rig already exists,
Rigify will simply overwrite it retaining all your modifiers and constraints and -- where possible --
all the previously generated features.
For information about additional generation options, see the `Advanced Rig Generation`_ section.
.. tip::
If the metarig uses the legacy :doc:`face rig <./rig_types/faces>`, you can use the
*Upgrade Face Rig* button that appears above *Generate Rig* to automatically upgrade
to the new modular face system.
The upgrade will preserve compatibility with existing skinning, but existing poses and
animations will likely not be compatible due to subtle changes in control behavior.
.. note::
To make the rig overwriting work as expected, you need to have **both** the rig and
the meta-rig visible before generating again. Rigify will try to unhide them in simple
cases, but will abort generation if that fails.
.. warning::
As with all Python add-ons, Blender interface cannot be updated until the Python script execution is over.
Wait until the rig appears to see the results.
.. warning::
Rigify is designed assuming a workflow where the meta-rig is kept available to allow re-generating
the main rig whenever it is necessary to make changes to it. Removing the meta-rig after generating
the main rig, or significantly modifying the generated rig is not advised: it will make it impossible
to introduce features added in later versions of Rigify, or easily adapt it to breaking changes in later
Blender versions. In general, automatic version update scripts will be provided for meta-rigs when necessary,
but not generated rigs.
Binding the Geometry to the Rig
-------------------------------
To bind the geometry to the rig you can use your preferred tools. Just few things you have to know:
- All the deforming bones are in the *DEF* bone collection.
- Eyes and Teeth bones of the legacy face are not deforming. You are supposed to bind the eyes and
teeth geometry through Child Of constraints.
- Usually armature deform with automatic weights do a really good job out of the box
if you correctly place your bones (and there is enough topology to work with!).
For more detailed information on bone collections, Armature modifier and weight painting refer to the Blender manual.
.. _bpy.types.Armature.rigify:
Advanced Rig Generation
=======================
Advanced Options Features
-------------------------
By using options in the Advanced sub-panel, it is possible to:
- Generate more than one rig per scene.
- Update/Override a specific rig.
- Force previously generated widget objects to be overwritten.
- Choose whether to use linked duplicates for left and right side widgets.
- Execute a script data-block after generation.
Advanced Options Sub-Panel
--------------------------
.. figure:: /images/addons_rigging_rigify_basics_advanced-panel.png
:align: right
:width: 300px
Advanced rig generation options are by default hidden in a sub-panel. Click on the *Advanced* line to open it.
Some of the options will be automatically set by Rigify if they have no value when a rig is generated,
while others are fully controlled by the user.
Rig Name
When a brand new rig is generated, as opposed to overwriting an existing one, the value of this option
is used to name it.
If this field is empty, the new object will be named based on the name of the metarig according
to the following rules:
* If the name contains ``META``, it is replaced with ``RIG``.
* If the name contains ``metarig``, it is replaced with ``rig``.
* Otherwise, ``RIG-`` is prepended to the name.
When overwriting an existing rig object specified by the *Target Rig* option, its name is not changed,
allowing it to be freely renamed without having to keep the value of this option in sync.
Target Rig :guilabel:`auto`
This option specifies the generated rig to overwrite when re-generating from this metarig.
If the option is not set, Rigify will generate a new rig object and store it in this option.
.. note::
When the option isn't set, Rigify will create a brand new rig object even if an object
with a matching name already exists.
Rig UI Script :guilabel:`auto`
This option specifies the generated script datablock to overwrite when re-generating, and
works in the same manner as *Target Rig*.
The script controls the UI in the 3D Viewport that allows conveniently switching visible
bone collections, changing custom properties, converting between IK and FK and so on.
Widgets Collection :guilabel:`auto`
This reference specifies the collection containing generated widgets, and
works in the same manner as *Target Rig*.
Overwrite Widget Meshes
If enabled, Rigify will generate new widgets every time the rig is re-generated. By default,
it tries to reuse the already generated widget objects that exist in the widget collection,
allowing them to be manually edited to fit the character better.
Mirror Widgets
When enabled, Rigify generates widgets for left and right side bones as
linked duplicates, using negative X scale to flip the right side version.
This enforces symmetry and reduces the number of meshes to adjust to
fit the character.
When reusing an already generated widget, Rigify detects if it was originally generated mirrored
by checking object scale to avoid flipping existing controls. Therefore switching to mirrored
widgets for an existing character requires deleting the right side widgets, or *Force Widget Update*.
Run Script
It is possible to configure Rigify to execute a Python script contained in a text data-block
after generation in order to apply user-defined customizations. The script is executed with
the generated rig active and selected in Object Mode.
The simplest use of this may be adjusting properties of generated constraints when Rigify rig types
don't have any relevant meta-rig settings. That can be done by using the *Copy Full Data Path*
context menu option on the property, pasting it into the script and making an assignment, e.g.::
import bpy
bpy.data.objects["rig"].pose.bones["MCH-spine.003"].constraints[0].influence = 0.6
Doing such changes via a script ensures they aren't lost if the rig is re-generated.
Users familiar with `Rigify scripting <https://developer.blender.org/docs/features/animation/rigify/>`__
can import Rigify utility modules, and access the generator instance through ``rigify.get_generator()``.
Yet note that, since generation is already finished, the only use of that is reading data created
in the generation process.
Library Linking
===============
When linking a rig into another file, you generally want to create a collection that includes
the generated rig and the character mesh. You do not need to include the meta-rig or the widget
object collection. You then link in the collection and run
:ref:`Make Library Override <bpy.ops.object.make_override_library>`.
The ``rig_ui_template.py`` text data-block responsible for the rig UI
will be automatically linked along with the rig, you don't need to link it separately.
However, the script will not run until you run it manually from the Text editor or save and restart Blender.

View File

@ -0,0 +1,220 @@
**********************
Bone Positioning Guide
**********************
Face Bones
==========
Start by identifying basic face landmarks to follow as guide for bones placement.
.. figure:: /images/addons_rigging_rigify_bone-positioning_face-landmarks.png
:align: center
Basic Face Landmarks.
- Orange lines represent bones that should be placed in closed loops.
- Yellow lines represent bones whose position depends on surrounding bone loops.
- Red lines represent outer edge bones.
- Purple lines represent bridging bones used to cover deforming flesh.
.. figure:: /images/addons_rigging_rigify_bone-positioning_face-eyes-nose-landmarks.png
:align: center
Eyes-Nose Landmarks.
The eyes-nose loop area is split in different parts identified by bone names. Follow the image to place the bones.
.. figure:: /images/addons_rigging_rigify_bone-positioning_face-eyes-nose-bones.png
:align: center
Eyes-Nose Bone Positions.
.. tip:: Brow Placement
Keeping aligned the mid bones in "brow", "brow.b", "lid.t", "lid.t" and
cheek will give better results after rig generation.
.. figure:: /images/addons_rigging_rigify_bone-positioning_face-jaw-ear-bones.png
:align: center
Jaw-Ear Bone Positions.
Also the jaw-ear area is split in different parts identified by bone names. Follow the image to place the bones.
.. tip:: Jaw Placement
Try to place "ear.L" bone covering the part of the ear attached to the mandible (lower jaw).
Do the same with temple bone trying to cover the part you don't want to move with the jaw,
this way you will also determine the jaw pivot position.
.. figure:: /images/addons_rigging_rigify_bone-positioning_face-lips-merge-point.png
:align: center
Lips Merge Point.
.. warning::
While moving the face bones it is necessary to preserve merge points, i.e. whenever heads
or tails of two or more bones overlap at the same point, they should still do so after
repositioning. Tearing a merge point apart may result in multiple controls being created
instead of one, or even the generation of errors.
.. figure:: /images/addons_rigging_rigify_bone-positioning_face-stretcher-bones.png
:align: center
Face Stretcher Bones.
After the main face bones are placed use the cheek bone to connect the eye-nose area to the jaw mouth area.
Then do the same with the brow area. This process will automatically define face muscles compression areas.
Position the eye bones in the eye pivot point facing right **toward** the face on the Y axis.
The length of the eye bones should correspond to the radius of the eye.
.. figure:: /images/addons_rigging_rigify_bone-positioning_face-eyes-pivot-position.png
:align: center
Eyes Pivot Position.
.. tip:: Eye Pivot
If your eye has a spherical shape you can define its pivot by entering Edit Mode.
Select two opposite vertices on the center meridian -- or the opposite poles -- and
snapping the cursor to selection by pressing :menuselection:`Snap --> Cursor To Selected`.
If your eye is a complete sphere and its location it's not applied, then you can just use its center of mass.
Finally position the teeth bones on your teeth geometry and the tongue bone chain as described in the figure.
.. figure:: /images/addons_rigging_rigify_bone-positioning_face-mouth-teeth-positions.png
:align: center
Mouth and Teeth Positions.
.. tip:: Tongue
The tongue will work better if the bones are aligned at the symmetry line.
Before generating the rig ensure the face master bone is facing upward.
Torso Bones
===========
Start by identifying on your character basic torso zones to follow as guide for bones placement.
Head, chest and pelvis are rigid zones, so they require less bones.
Having a good edge loop placement around zone boundaries on your model
will help in having correct deformation after armature binding.
.. figure:: /images/addons_rigging_rigify_bone-positioning_torso-landmarks.png
:align: center
Torso Landmarks.
Starting from the side view, place the main spine bones trying to use
one bone for the rigid areas and two for the flexible ones.
In addition to the main spine, the torso is provided with additional pelvis bones (to oppose the leg bending),
two breast controls and two shoulder bones.
Even if the pelvis bones will not appear in the final rig as controls, they will contribute to deformation.
.. figure:: /images/addons_rigging_rigify_bone-positioning_torso-bones.png
:align: center
Torso Bones Positioning.
.. tip:: Bone Placement
Try to keep the spine as centered as possible inside the mesh bounding volume,
just apply a slight offset toward the back. In a similar way, consider the shoulder bones as general deformers;
placing it too forward -- where the collar bone should be -- could cause undesired deformations.
Limbs Bones
===========
While placing the arm bones try to start having a straight line that goes from
the shoulder to the hand in both front and top view. After this is done just add a slight bend to the elbow.
This can be easily done by going in the top view, entering armature Edit Mode and
sliding the bone junction between forearm and upper_arm slightly toward the world's Y axis.
.. figure:: /images/addons_rigging_rigify_bone-positioning_limbs-arm-bones.png
:align: center
Arm Bones Positioning.
For the leg you can follow a similar process. Start by aligning the leg bones creating a straight line from
the hips to the ankle, then place the foot and the toe accordingly.
Remember to add a slight bend to the knee. This can be easily done by going in the side view,
entering armature Edit Mode and sliding the bone junction between thigh and shin slightly toward the world's Y axis.
.. figure:: /images/addons_rigging_rigify_bone-positioning_limbs-leg-bones.png
:align: center
Leg Bones Positioning.
Finally align the heel bone by going in the front view and placing the head and tail to
fill the foot size from side to side. Then, in the side view,
align the bone at the point where the heel just touches the ground floor.
.. note::
From version 0.5 and above there is no more need of manual bone rolls alignment.
The generate function will take care of that for you by evaluating it from bend axis;
just insert a slight bend in your limb and it's done!
If you need more control on the orientation, follow the guidelines described in Advanced Usage.
Fingers Bones
=============
Start by placing, finger by finger, all the knuckles in place.
.. tip:: Fingers Placement
An easy and effective method to do this operation is to select on the mesh
the corresponding edge loop in Edit Mode and use the *Cursor to Selection* snap.
Then you can snap the bone to the corresponding loop using the *Selection to Cursor* snap.
.. figure:: /images/addons_rigging_rigify_bone-positioning_fingers-edge-loops.png
:align: center
Knuckles Edge Loops and Cursor Snapping.
Finalize the positioning by taking care of bone rolls (the X axis is set as bend axis).
.. tip:: Bone Roll
Finger axis alignment can be easily be made consistent by selecting all the finger bones
and recalculating the bone rolls :menuselection:`Recalculate Roll --> Global -Z Axis`.
Thumb may require more tweaking depending on your character's mesh topology,
usually :menuselection:`Recalculate Roll --> Global +Y Axis` is a good starting point.
Once your bone rolls are consistent, try generating the rig and scaling the finger master controls.
This should cause the fingers to curl. If they are rotating on the wrong axis,
change the Bend Rotation Axis parameter on the first finger's parameters under Rigify Type.
.. figure:: /images/addons_rigging_rigify_bone-positioning_fingers-bend-axis.png
:align: center
Fingers Bend Axis.
When the fingers are in place proceed placing the palm bones.
.. figure:: /images/addons_rigging_rigify_bone-positioning_fingers-palm-alignment.png
:align: center
Palm Alignment.
.. tip:: Palm Placement
Try to keep palm bones' heads at a little distance between each other.
This distance is required for Rigify to define the palm controls hierarchy.
Palm axis alignment can be easily done by selecting all the palm bones and
recalculating the bone rolls :menuselection:`Recalculate Roll --> Global -Z Axis`.
.. seealso::
For more detailed information on bones and rolls refer to
the :doc:`Bone Structure </animation/armatures/bones/structure>` and :ref:`armature-bone-roll`.

View File

@ -0,0 +1,26 @@
************
Feature Sets
************
Rigify allows third party developers to implement sub-addons, called *Feature Sets*,
which can provide new :doc:`Meta-Rigs </addons/rigging/rigify/metarigs>` and
:doc:`Rig Types </addons/rigging/rigify/rig_types/index>`. Similar to regular add-ons,
they can be installed from zip-files through Rigify settings.
These are some examples of *Feature Sets* currently provided by past and current Rigify developers:
`Cessen's Rigify Extensions <https://github.com/cessen/cessen_rigify_ext>`__
This feature set provides the original Rigify rigs by Nathan Vegdahl, minimally ported
and repackaged to work without switching Rigify to legacy mode. Note that their names
were changed, so meta-rigs designed for legacy mode aren't directly compatible.
`Experimental Rigs by Alexander Gavrilov <https://github.com/angavrilov/angavrilov-rigs>`__
Rig experiments, some of which might be included in Rigify in the future. Examples include
limbs with an extra IK system based at knee/elbow, a spline based tentacle, and more.
You can install these packages by clicking :menuselection:`Clone --> Download ZIP`,
and then install the downloaded file through Rigify settings.
Developer documentation is available on the `Blender Developer Documentation
<https://developer.blender.org/docs/features/animation/rigify/>`__.

View File

@ -0,0 +1,53 @@
##########
Rigify
##########
Basics
======
.. toctree::
:maxdepth: 2
introduction.rst
basics.rst
bone_positioning.rst
rig_features.rst
Customization
=============
.. toctree::
:maxdepth: 1
metarigs.rst
rig_types/index.rst
Extensions
==========
.. toctree::
:maxdepth: 1
feature_sets.rst
Development
===========
Developer documentation is available on
the `Blender Developer Documentation <https://developer.blender.org/docs/features/animation/rigify/>`__.
.. reference::
:Category: Rigging
:Description: Automatic rigging from building-block components.
:Location: :menuselection:`Properties --> Armature, Bone`, :menuselection:`3D Viewport --> Tools panel`,
:menuselection:`3D Viewport --> Add menu --> Armature`
:File: rigify folder
:Author: Nathan Vegdahl, Lucio Rossi, Ivan Cappiello, Alexander Gavrilov
:License: GPL
:Note: This add-on is bundled with Blender.

View File

@ -0,0 +1,56 @@
************
Introduction
************
Rigify helps automate the creation of character rigs. It is based around a building-block approach,
where you build complete rigs out of smaller rig parts (e.g. arms, legs, spines, fingers...).
The rig parts are currently few in number, but as more rig parts are added to
Rigify it should become more and more capable of rigging a large variety of characters and creatures.
Rigify also operates on the principle that once a rig is created, that rig should no longer need Rigify.
This means you can always distribute rigs created with Rigify to people
who do not have it and the rigs will still function completely.
It is important to note that Rigify only automates the creation of the rig controls and bones.
It does not attach the rig to a mesh, so you still have to do skinning etc. yourself.
Main Features
=============
Modular rigging
Rigify build blocks can be mixed together to rig any character you want.
If you need to build a character with five arms and one leg,
Rigify can handle it for you creating all the required complex controls system
(FK, IK, and all the relative snapping tools and the UI) in few seconds.
Nondisruptive re-rig
If the generated rig doesn't fit all the features you need or, for example,
you decide to add something more to your character (like a sixth arm or a tail),
you can re-generate your rig without losing your previously generated features and your animation data.
Advanced and flexible feature set for character animation
The included rig samples (limbs, spines, tails, fingers, faces...) adds to all the stretchy FK/IK features
a direct deformation secondary layer that lets you flex, bend and deform the character as you like
through interactive Bendy Bones controls.
Shareable animation through all Rigify rigs
Since the control system is generated by Rigify, if you share a meta-rig through different characters
you will be able to share data between them even if they have different proportions.
Extendable feature set
You can save and encode your meta-rigs to a button to have them available at any time
without recreating it by hand or share your meta-rigs with other people.
Through Python scripting you can also extend Rigify with new Rigify-types or new rig samples
by implementing your own :doc:`feature set <./feature_sets>` package.
Ready to go
Once you generate your rig you won't need Rigify or any other add-on to use it.
Activation
==========
- Open Blender and go to Preferences then the Add-ons tab.
- Click Rigging then Rigify to enable the script.

View File

@ -0,0 +1,397 @@
******************
Creating Meta-rigs
******************
#. Add a single bone from the :menuselection:`Add --> Armature` menu.
#. Go in armature Edit Mode and build the meta rig by samples or Rigify-types.
#. Define the :ref:`Rigify bone collection UI <bpy.types.BoneCollection.rigify_ui_row>`,
:ref:`color sets <bpy.types.Armature.rigify_colors>`, and selection sets.
#. In the armature properties click on the *Generate* button to generate the rig.
How Rigify Works
================
Rigify Meta-Rigs are split in multiple Sub-Rigs
A meta-rig is an assembly of bone chains. A bone chain is identified by the *Connected* attribute.
Bone chains can be further connected together by parenting them without using the *Connected* attribute
(i.e. using the *Keep Offset* option while parenting).
A custom attribute is set on the first bone of the sub-rig chain
Each first bone of a bone chain has a custom attribute on it which is a Rigify custom property
that identifies the sub-rig type. At rig generation time Rigify will determine which controls and
deform bones will be created processing the meta-rig from the first bone to the last of each chain.
.. figure:: /images/addons_rigging_rigify_metarigs_split-samples.png
Human meta-rig split by samples.
New meta-rigs are created assembling sub-rigs samples
Since a meta-rig is just a collection of sub-rigs,
new meta-rigs can be built assembling sub-rigs in different ways.
This way an infinite number of meta-rigs can be built from the same rigging blocks.
.. figure:: /images/addons_rigging_rigify_metarigs_built-samples.png
Cat meta-rig built by samples.
All the mechanics, deformation bones and widget are created on a single click
The meta-rig contains more information than the visualized bones.
In fact at generation time Rigify will identify each sub-rig type and depending on
the selected options will create all the sophisticated controls, switches, and
deforming bones with a single click.
Creating a new Meta-rig
=======================
Add a new Armature Object
-------------------------
.. reference::
:Mode: Object Mode
:Menu: :menuselection:`Add --> Armature --> Single Bone`
:Shortcut: :kbd:`Shift-A`
Building your own meta-rig from scratch requires an armature object to work with.
Just add a single bone from the *Add* menu.
.. tip::
At this stage naming the newly added armature ``metarig`` is a good idea.
You can do it at any time (or not at all) but it's suggested to do it before going on
so it will always be clear on which armature you have to work when editing the meta-rig structure.
Editing the Armature
--------------------
Now that there is an armature object to work -- with the armature selected -- enter armature Edit Mode.
Building a meta-rig from scratch in Edit Mode can be done in two ways:
#. Adding rig samples.
#. Creating bone chains.
Adding Samples (Basic)
^^^^^^^^^^^^^^^^^^^^^^
Adding pre-defined samples in Edit Mode is a good way to start building a meta-rig.
This way you can become familiar with the available building blocks and how they are meant to be used.
To add a rig sample:
#. Go in the armature tab.
#. Scroll down to Rigify panel.
#. Select a sample from the list.
#. Click on the *Add sample* button.
#. Edit the bone positions to match your character.
For the list of available samples, see the :doc:`Rig Types </addons/rigging/rigify/rig_types/index>` page.
.. _bpy.types.PoseBone.rigify_type:
.. _bpy.types.RigifyParameters:
Using Rig Types (Advanced)
^^^^^^^^^^^^^^^^^^^^^^^^^^
.. figure:: /images/addons_rigging_rigify_metarigs_rigify-type-panel.png
:align: right
:width: 300px
For full control, you can use the Rigify Type panel of bone properties in Pose Mode to assign
any Rigify sub-rig type to any bone, as well as change its options.
For the list of available sub-rig types and their options, see the
:doc:`Rig Types </addons/rigging/rigify/rig_types/index>` page.
At the top of the panel you can find a field specifying the rig type for the active bone. The drop-down list
can be optionally filtered by the :doc:`Feature Set </addons/rigging/rigify/feature_sets>` it belongs to.
Below that you can change options relevant to the selected rig type, if it has any.
Bone Collection References
""""""""""""""""""""""""""
Some rig types that generate many control bones have options that reference
:ref:`Bone Collections <bpy.types.BoneCollection.rigify_ui_row>`. These reference lists have a standard UI with
the following features:
* A checkbox controlling whether the reference should be used.
* A button to copy the reference list contents from the active to all selected bones.
* A plus button to add a new reference to the list.
* A list of references, each entry with a field to specify the target collection,
and a button to remove the entry from the list.
.. note::
Each sub rig has a required number of bones as input. If you are unsure on how to use rig-types properties,
add a rig sample to your armature to see how it is supposed to be used.
Preserved Bone Properties
^^^^^^^^^^^^^^^^^^^^^^^^^
Certain properties of the metarig bones are often copied to the generated rig control, deform and mechanism bones.
The exact set depends on the sub-rig and the specific generated bone, and the sub-rig may override some properties
even when it preserves others from the same subset, but there are certain common patterns:
Parenting Settings
This subset consists of the parent ORG bone, Use Connect, Use Inherit Rotation, Use Local Location, and Inherit
Scale.
It is usually copied to deform bones, FK controls, and in other cases where the sub-rig doesn't have a reason
to completely override them.
Bendy Bone Settings (Edit Mode)
Consist of the segment count, Vertex Mapping Mode, Ease In/Out, Roll In/Out, Curve In/Out and Scale In/Out.
The segment count is often overridden via a sub-rig option, but other settings are usually copied to deform
bones as is.
Transformation Settings
Consist of the rotation mode, pose mode rotation values, and channel locks.
These settings are usually copied to FK controls.
Custom Properties
Usually copied to one of the controls generated based on the metarig bone (mainly FK). Intra-armature drivers
that access the property are retargeted to the copied instance.
Custom Widget
Usually copied to one of the controls generated based on the metarig bone (mainly FK), and suppresses automatic
generation of a widget for the bone if specified.
Custom Root Bone
^^^^^^^^^^^^^^^^
If the meta-rig contains a bone called ``root``, it is used as the root control bone instead of creating a new one.
This allows changing the rest position of the root bone, assigning a custom widget,
or adding custom properties to the bone.
The custom root bone must have no parent, and use the :ref:`basic.raw_copy <rigify.rigs.basic.raw_copy>` sub-rig
type or none.
.. _bpy.ops.Armature.rigify_apply_selection_colors:
.. _bpy.ops.Armature.rigify_add_bone_groups:
.. _bpy.types.Armature.rigify_colors:
.. _bpy.types.Armature.rigify_colors_lock:
.. _bpy.types.Armature.rigify_theme_to_add:
.. _bpy.types.Armature.rigify_colors_index:
.. _bpy.types.RigifySelectionColors:
.. _bpy.types.RigifyArmatureLayer:
Color Sets
==========
.. figure:: /images/addons_rigging_rigify_metarigs_color-sets-panel.png
:align: right
:width: 300px
The Color Sets panel is used to define the bone color scheme for the final rig. The colors from the list
can be associated with bone collections from the relevant panel.
The top two rows of the Color Sets panel are used to define the general behavior of the bone colors.
Usually color themes use a gradient of colors to define the different bone states: default, selected and active.
When multiple color themes are used in the same rig, identifying which bone is selected or
active can be tricky since each color will have its corresponding state.
To override this behavior Rigify unifies the active and selected states using the same color.
This is defined by two values:
Unified Selected/Active Colors
When this option is active adding a bone group in the list will always keep the colors consistent.
When a color scheme is added from a theme, the color scheme is loaded as is.
Click on the *Apply* button to force the system to unify selected and active colors.
Selected/Active Colors
This two color fields define respectively the *Selected* and *Active* colors.
By default Rigify reads these colors from the theme defined by the user in the Blender preferences.
This way the *Selected*/*Active* colors can always have a predictable and consistent behavior in the UI.
The colors can be customized by clicking on the relevant color field.
To reset them to the Blender current theme value just click on the button with the update icon.
Color Sets can be added and deleted by clicking on the ``+`` or ``-`` buttons.
All color sets can be deleted at once by clicking on the Specials menu.
To add the colors from the predefined Rigify default color scheme (as shown in the image) to the list click
the *Add Standard* button.
To add a specific theme with its own color scheme, select it from the list and click on the *Add From Theme* button.
.. _bpy.types.BoneCollection.rigify_ui_row:
Bone Collections UI
===================
.. figure:: /images/addons_rigging_rigify_metarigs_bone-collections-panel.png
:align: right
:width: 300px
:doc:`Bone Collections </animation/armatures/bones/bone_collections>` are used to group related bones together
so that they can be hidden or revealed together.
Rigify can take advantage of collections to generate extra features and the user interface for the final rig.
A panel named :ref:`Rig Layers <rigify.rig_ui_template.RigLayers>` is generated with buttons for hiding the
collections, arranged in an intuitive layout.
The Bone Collections UI panel allows configuring the layout of that generated panel, as well as specifying some
other settings for bone collections, such as the color set to use.
The top of the panel is occupied by a list that duplicates the main bone collection list, but displays additional
properties, such as the color set, whether the collection has a button, or whether it generates a selection set.
Validate Collection References
Some sub-rig types have :ref:`references <bpy.types.RigifyParameters>` to bone collections in their properties.
Rigify uses a referencing scheme that is robust to collection renames, but deleting collections or joining armatures
can still lead to broken references.
This button runs a scan that validates and normalizes all collection references, reporting any errors, and
reducing the chance of breakage being caused by subsequent user actions.
This scan is also performed automatically every time the rig is generated.
.. warning::
To avoid breakage this operation should be used both immediately before and after joining two metarig armatures.
More specifically, it must be always done between the actions of renaming any collections and joining.
Color Set
Specifies the :ref:`color set <bpy.types.Armature.rigify_colors>` to use for bones in this collection. If a bone
belongs to multiple collections, in general the collection located earlier in the list has priority.
Add Selection Set
Specifies whether a selection set should be generated for this collection.
UI Row
If nonzero, specifies which row of the :ref:`Rig Layers <rigify.rig_ui_template.RigLayers>` panel should contain the
button controlling the visibility of this collection. When zero, no button is generated, and the collection is
hidden.
UI Title
This field can be used to override the title used on the UI button to be distinct from the true collection name.
Unlike collection names, titles are not required to be unique, so this can be used to reduce clutter by relying
on contextual cues within the panel.
UI Layout sub-panel
-------------------
.. figure:: /images/addons_rigging_rigify_metarigs_bone-collections-layout-panel.png
:align: right
:width: 300px
The UI Layout sub-panel provides a WYSIWYG editor for the layout of the generated UI panel
(as defined by the UI Row and UI Title settings above).
Each row contains three buttons at the end:
Arrow
Moves the active collection button to this row.
Plus
Inserts a new row before the current one.
Minus
Removes the current row and shifts all buttons up.
To the left of the editing control buttons, rows display buttons corresponding to the collections, same as the final
UI, except that rather than hiding or unhiding, clicking these buttons selects the collection.
For the active collection the selection button is replaced with an input field for editing the UI Title, and an **X**
button to unassign the collection from the UI.
For any collections not assigned to the UI, their select buttons are displayed in a separate section at the bottom
of the sub-panel.
The ``Root`` collection will be added and/or assigned a UI button automatically if necessary when the rig is
generated. If desired, it is possible to manually assign UI buttons to the internal ``ORG``, ``DEF`` and ``MCH``
collections.
.. tip::
Blank rows appear much thinner in the final interface, since they don't have to contain editing buttons, and can be
used as logical separators.
Actions
=======
.. figure:: /images/addons_rigging_rigify_metarigs_actions-list-panel.png
:align: right
:width: 300px
The :doc:`Action </animation/constraints/relationship/action>` constraint allows applying poses defined
by an action to bones based on the transformation of another bone. This requires adding the constraint to every
bone affected by the action, which is very tedious. For this reason, Rigify includes a system to do this
automatically through the Actions panel.
The panel defines a list of actions to be applied to the generated rig bones. Each action must be listed only once.
The list entries show the name of the action, the trigger (a bone or a corrective action driven by two others), and
a checkbox that can be used to temporarily disable applying this action to the rig. The icon at the start of the entry
is changed from an action icon to a link icon to highlight corrective actions that depend on the active normal one,
or normal actions used by the active corrective action.
.. note::
The Action constraints are added to the bones in such an order as to exactly reproduce the intended deformation,
assuming the actions were created (posed and keyframed) in the order listed.
Normal Actions
--------------
.. figure:: /images/addons_rigging_rigify_metarigs_actions-normal-panel.png
:align: right
:width: 300px
Normal actions are applied based on the transformation of a specific control bone from the generated rig.
They have the following properties:
Control Bone
Specifies the bone that drives the action.
Symmetrical
If the control bone has a suffix that specifies that it belongs to the left or right side, this option can
be enabled to automatically apply symmetry.
When enabled, left-side bones keyframed in the action will be controlled by the left-side control, and right-side
bones by the right side control. Bones that don't have a a side suffix are assumed to belong to the center of the
character. They are rigged with two Action constraints with influence 0.5 that are controlled by each of the
control bones.
Frame Start & End
Specifies the frame range of the action that will be used by the created constraints.
Target Space, Transform Channel
Specifies the coordinate space and transformation channel of the target bone that should be used.
Min, Max
Specifies the range of the transformation channel values that is mapped to the specified action frame range.
Default Frame
Shows the frame within the action that maps to the neutral value (1 for scale and 0 otherwise)
of the transformation channel, as computed from the specified range values.
Corrective Actions
------------------
.. figure:: /images/addons_rigging_rigify_metarigs_actions-corrective-panel.png
:align: right
:width: 300px
Corrective actions are applied based on the progress of two other actions from the list, and are used to improve
the pose when they are used together.
Frame Start & End
Specifies the frame range of the action that will be used by the created constraints.
Trigger A & B
Specifies the two actions that control the correction. The interface rows contain buttons to show the settings
for that action, or jump to it in the list.
The progress of the corrective action from the start to the end frame is calculated as the product of the progress
values of the two trigger actions. Thus, the start frame is applied when either of the triggers is at the start frame,
and the end frame is used when both are at their end frame.
Corrective actions must be below their triggers in the list, which is enforced via an implicit reorder even if
violated.
.. tip::
Corrective actions behave in the most intuitive way when both triggers have the Default Frame equal to Start Frame.
To create a corrective action in such case:
* Create the two trigger actions, add them to the panel and generate the rig.
* Pose your controls so that both trigger actions are fully activated to the end frame.
* Pose and keyframe the necessary corrections in the end frame of the new action, while keying the start
frame to the neutral values.
* Add the newly created action to the end of the list in the panel and configure its settings.

View File

@ -0,0 +1,552 @@
**********************
Generated Rig Features
**********************
After human rig generation a new armature named ``rig`` will be added to your scene.
This is the character rig you have generated from the human meta-rig and will contain all the features.
Common Features
===============
.. _rigify.rig_ui_template.RigBakeSettings:
.. _rigify.rig_ui_template.RigUI:
.. _rigify.rig_ui_template.RigLayers:
Rig UI Panels
-------------
.. figure:: /images/addons_rigging_rigify_rig-features_rig-ui-panels.png
:align: right
:width: 200px
The generated rig is accompanied by a script that implements a set of panels that appear in the Item
tab of the 3D view sidebar when a bone belonging to the generated rig is active.
Rig Bake Settings
^^^^^^^^^^^^^^^^^
This panel is displayed if the armature has an active :doc:`Action </animation/actions>`, and
is used by operators that apply an operation to multiple keyframes.
Bake All Keyed Frames
When enabled, the operator computes and keyframes its result on every frame that has a key for any of the
bones, as opposed to just relevant ones.
Limit Frame Range
When enabled, the operator is limited to a certain frame range.
Start, End
Specify the frame range to process.
Get Frame Range
Sets the baking frame range from the scene frame range.
Rig Main Properties
^^^^^^^^^^^^^^^^^^^
This panel shows properties and operators that are relevant to the selected bones.
Rig Layers
^^^^^^^^^^
This panel contains buttons for toggling visibility of bone collections.
The layout and labels of the buttons are defined in the metarig
:ref:`Bone Collection UI <bpy.types.BoneCollection.rigify_ui_row>` panel.
Common Controls
---------------
Rigify rigs are built from standardized components called sub-rigs, which are linked together in a parent-child
hierarchy. Although the precise behavior of each sub-rig is determined by its implementation, there are certain
conventions that are followed by many of them.
Root Bone
^^^^^^^^^
Every Rigify rig has a bone called `root`, which serves as a parent for all bones of the rig.
It is assigned to a bone collection called `Root`. Unless the metarig has a custom bone
of that name, it is positioned at the origin of the rig object. Its widget looks like
a circle with four arrow shaped protrusions.
.. figure:: /images/addons_rigging_rigify_rig-features_arm-controls.png
:align: right
:width: 200px
Limb Master
^^^^^^^^^^^
Many limb-like sub-rigs have a gear-shaped bone at their base.
This bone can in some cases be used to transform the whole sub-rig as a rigid unit, and is also used as a container
for its custom properties that are displayed in the *Rig Main Properties* panel. If you are looking in the Graph
editor for the animated values of the properties, this is most likely the bone to look at.
As an exception, if multiple controls of the sub-rig need their own copy of conceptually the same property,
it may be placed on those controls directly instead.
Tweak Controls
^^^^^^^^^^^^^^
These controls look like blue spheres in the default color scheme, and are the final control layer above the
deformation bones themselves.
Tweaks are subordinate to the general IK or FK limb position but can be moved apart, twisted and scaled freely,
even reaching virtually impossible limb shapes.
Rubber Tweak
.. figure:: /images/addons_rigging_rigify_rig-features_rubber-tweak.png
:align: right
:width: 200px
Some sub-rigs provide a slider in their *Rig Main Properties* when tweaks are selected, which controls
the smoothness of the Bendy Bone joint at that position. When zero, the joint deforms with a sharp bend,
while setting it to 1 makes the transition smooth for a more rubber hose cartoon like appearance.
Custom Pivots
^^^^^^^^^^^^^
Some bones that can be freely moved in space (like IK controls) can be optionally accompanied by a custom pivot
control. These controls usually look like a plain axes empty with the axis lines capped with squares or crosses,
like the one in the image above. The control can be freely moved to change the location of the pivot, and then
rotated or scaled to transform the target bone around the pivot.
IK and FK Switching
^^^^^^^^^^^^^^^^^^^
.. figure:: /images/addons_rigging_rigify_rig-features_ik-fk-switch.png
:align: right
:width: 200px
A number of rig types provides both IK and FK controls (red for IK and green for FK in the image above),
with an ability to switch and snap between them.
Switching is controlled by a slider in *Rig Main Properties*, usually blending between full IK at 0 and full FK at 1.
Snapping one type of controls to the shape of the other is done via buttons, which form a group of three
in their complete set:
* The main button will snap on the current frame, and auto-key the result if enabled.
* The *Action* button will bake the change on multiple keyframes, according to *Rig Bake Settings*.
* The *Clear* button will delete keyframes on the corresponding controls within the bake interval.
Parent Switching
^^^^^^^^^^^^^^^^
.. figure:: /images/addons_rigging_rigify_rig-features_parent-switch.png
:align: right
:width: 200px
Some freely movable controls, e.g. usually the IK controls, can have a mechanism to switch their parent bone
between a set of choices, including the root bone, or none at all.
This mechanism is exposed in the *Rig Main Properties* panel through a row with three controls:
* A button that presents a dropdown menu, which allows switching the parent on the current frame while
preserving the bone position and orientation in the world space.
* A dropdown input field that directly exposes the switch property for keyframing and direct manipulation.
Changing the value can cause the bone position to jump.
* A button to apply the position preserving parent switch over the bake range of keyframes.
.. note::
When manually placing a Child Of constraint on the control bone, the built-in parent should be switched to none.
Limbs
=====
Limbs have a master bone and tweaks. Depending on the user defined meta-rig options,
multiple deform bone segments with tweaks will be created.
The IK control may have an optional custom pivot, as well as additional predefined pivots.
Rigify's limbs have the following controls in the Sidebar panel:
.. figure:: /images/addons_rigging_rigify_rig-features_limb-properties.png
:align: right
:width: 200px
FK Limb Follow :guilabel:`Slider`
When set to 1 the FK limb will not rotate with the torso and will retain is rotation
relative to the root bone instead.
IK-FK :guilabel:`Slider`
Controls whether the limb follows IK or FK controls, blending between full IK at 0 and full FK at 1.
IK<->FK Snapping :guilabel:`Buttons`
Snaps one type of controls to another.
IK Stretch :guilabel:`Slider`
Blends between the limb stretching freely at 1, or having its maximum length constrained at 0.
Toggle Pole :guilabel:`Switch`
When the toggle is Off, the IK limb will use the rotational pole vector (the arrow at the base of the limb).
Rotating/translating/scaling the arrow will control the IK limb base.
When the toggle is On, the classic pole vector will be displayed and used to orient the IK limb.
The arrow will continue to handle the scale and the location of the IK limb base.
Similar to *Parent Switching*, the row includes buttons to convert the current pose between types,
or bake the whole action.
IK Parent :guilabel:`Switch`
Switches the effective parent of the main IK control.
Pole Parent :guilabel:`Switch`
Switches the effective parent of the classic IK Pole control.
Arms
----
.. figure:: /images/addons_rigging_rigify_rig-features_hand-controls.png
:align: right
:width: 200px
:ref:`Arms <rigify.rigs.limbs.arm>` have the simplest control structure: the IK controls consist of the main IK
control, the optional custom pivot control, and the optional wrist control (the bent circle), which pivots around
the tail rather than the head of the hand bone.
There are no additional controls in the *Rig Main Properties* panel.
Legs
----
:ref:`Legs <rigify.rigs.limbs.leg>` have a more complicated setup, which has:
.. figure:: /images/addons_rigging_rigify_rig-features_foot-controls.png
:align: right
:width: 200px
IK & FK Toe :guilabel:`Optional`
Two separate IK and FK controls for the toe (this is on by default in the bundled metarigs,
and is recommended for stable IK<->FK snapping).
IK Heel
A heel control which can be rotated to command forward or backward roll, sideways rock, or yaw of the heel.
Toe Pivot :guilabel:`Optional`
An extra pivot control rotating around the base of the toe.
Custom Pivot :guilabel:`Optional`
A custom pivot control.
The properties panel has two additional features:
.. figure:: /images/addons_rigging_rigify_rig-features_foot-properties.png
:align: right
:width: 200px
IK->FK Snap With Roll :guilabel:`Buttons`
Standard IK to FK snapping resets the transformations of all IK controls other than the main one. This is
not convenient to use in an animation that involves the use of the heel control, because roll and rock would
be folded into the transformation of the main control.
This alternative snapping operator tries to deduce the rotation of the heel control so as to keep the main
IK control parallel to the ground plane inferred from the *current* orientation of the IK control. The operator
has options to specify which rotational axes to use for the heel control rotation.
Roll On Toe :guilabel:`Slider` :guilabel:`Optional`
If enabled in the sub-rig settings, this slider can be used to control whether the heel rotation (excluding
backward roll) is applied at the base or the tip of the toe.
Fingers & Tentacles
===================
Simple Tentacle
---------------
.. figure:: /images/addons_rigging_rigify_rig-features_simple-controls.png
The simplest type of rig for a finger or appendage in general is the
:ref:`simple tentacle <rigify.rigs.limbs.simple_tentacle>` sub-rig. It has only basic FK controls and tweaks,
with the only automation being the ability to copy certain axes of the local rotation of a FK control to the next one.
Advanced Finger
---------------
.. figure:: /images/addons_rigging_rigify_rig-features_finger-controls.png
For fingers specifically, Rigify has a dedicated :ref:`finger <rigify.rigs.limbs.super_finger>` sub-rig type,
which provides:
Master
A master control (orange), which can be used to rotate the finger as a whole, as well as to bend it via Y scaling.
FK Chain
FK control chain (green) that can also operate as semi-tweaks through allowing translation.
IK Control :guilabel:`Optional`
IK control for the tip (red).
.. note::
IK in this sub-rig is rudimentary and operates as an adjustment for FK. The intended way of use is to pose
the finger in FK, and then enable IK after using IK->FK snap if it is necessary to pin the tip of the finger
in place.
The properties panel has the following features:
.. figure:: /images/addons_rigging_rigify_rig-features_finger-properties.png
:align: right
:width: 200px
Finger IK :guilabel:`Slider` :guilabel:`Optional`
Slider controlling the influence of the IK.
FK<->IK Snapping :guilabel:`Buttons` :guilabel:`Optional`
Snaps the IK control to the end of the finger, or adjusts the FK controls to the result of the IK correction.
Curvature :guilabel:`Slider`
Has the same effect as *Rubber Tweak* on limbs, controlling the rubber hose cartoon effect.
Spline Tentacle
---------------
.. figure:: /images/addons_rigging_rigify_rig-features_spline-controls.png
Spline Tentacle (Stretch To Fit, Manual Squash & Stretch)
.. figure:: /images/addons_rigging_rigify_rig-features_spline-controls-tip.png
Spline Tentacle (Direct Tip Control)
The :ref:`spline tentacle <rigify.rigs.limbs.spline_tentacle>` is an advanced rig for a flexible appendage (tentacle)
based on the :doc:`Spline IK </animation/constraints/tracking/spline_ik>` constraint. The IK control bones manage
control points of a Bezier spline curve, which in turn is followed by the IK chain.
The tentacle can be generated in three major modes:
Stretch To Fit
In this simplest mode all bones of the sub-rig deform chain follow the curve and squash & stretch to match
its length.
Manual Squash & Stretch
This mode is almost the same, but the chain does not automatically scale to match the curve length.
Instead, it tries to cover as much as possible of the curve given its manually scaled length.
If the curve is too short, the chain will overhang it and straighten out, but this can result in jitter.
Direct Tip Control
This mode is more similar to the behavior of IK limbs: the final bone of the chain is directly controlled by
the tip IK control, while the other bones of the chain stretch and follow the curve to bridge the gap.
The tentacle sub-rig has the following control bones:
Master
The tentacle has the same gear master control as other limbs (seen as a line in the images).
IK Start
The IK control at the base of the tentacle, which can be used to control the base twist and sideways scale, and
is one of the potential switchable parents for other IK controls.
In the *Manual Squash & Stretch* mode it controls uniform scale of the tentacle in all directions.
IK Start (Extra) :guilabel:`Optional`
Extra start controls, optional and hidden by default. Switchable parents default to the *IK Start* control.
The scale of the control may optionally affect the thickness of the chain via the radius of the curve point.
IK Middle
Controls for the middle of the curve. The switchable parents default to *Master*, but may be set to
*IK Start* or *IK End* controls.
The scale of the control may optionally affect the thickness of the chain via the radius of the curve point.
IK End (Extra) :guilabel:`Optional`
Extra end controls, optional and hidden by default. Switchable parents default to the *IK End* control.
The scale of the control may optionally affect the thickness of the chain via the radius of the curve point.
The *Direct Tip Control* mode adds one more extra end control next to the middle ones that cannot be hidden.
IK End
Controls the last control point of the curve, and is one of the potential parents for the other chain controls.
In the *Direct Tip Control* mode also directly controls the last bone of the chain.
IK End Twist :guilabel:`Optional`
This control is visually attached to the last bone of the chain, and must use Euler rotation.
* *Stretch To Fit*: it controls the twist of the tip of the tentacle, interpolated to nothing at the base.
* *Manual Squash & Stretch*: it also controls the scaling of the tip of the tentacle.
* *Direct Tip Control*: the control does not exist.
FK Chain :guilabel:`Optional`
If enabled, the rig has an alternative fully FK control chain.
The properties panel has the following features:
.. figure:: /images/addons_rigging_rigify_rig-features_spline-properties.png
:align: right
:width: 200px
Start/End Controls :guilabel:`Optional`
If extra controls exist, this property controls how many of them are visible and active.
When a control is disabled, it is snapped to a position extremely close to the corresponding end control point,
thus effectively neutralizing its effect. Thus, changing the setting during an animation can cause jumps.
The plus and minus buttons can help with maintaining a continuous transition in an animation by keyframing the
change in the property value with Constant interpolation, and also snapping and keyframing the control itself
to its 'hidden' position.
End Twist Estimate :guilabel:`Optional`
In the *Direct Tip Control* mode the twist at the end of the tentacle is deduced from the free form orientation
of the tip control, rather than using a separate twist control with constrained Euler rotation. However, for
technical reasons, that can only give values within the 180 degrees range of neutral.
A long tentacle can accept more twist than 180 degrees, so a workaround is necessary. This property allows
specifying an approximate estimate of the twist value (effectively shifting the neutral position), and the
rig then applies the automatic correction within 180 degrees of this value.
IK-FK, IK<->FK Snapping :guilabel:`Optional`
If the FK controls are enabled, these provide standard IK-FK switching and snapping.
However, unlike other limbs, for this rig automatic IK to FK snapping can only be approximate and requires
manual tuning. For this reason, buttons for baking the snapping over a range of keyframes are not provided.
Parent Switch
Switches the parent of the selected IK control.
Spine, Head & Tail
==================
.. figure:: /images/addons_rigging_rigify_rig-features_spine-controls.png
:align: right
:width: 200px
Spine
-----
The :ref:`spine <rigify.rigs.spines.basic_spine>` sub-rig provides a cube shaped torso control with
switchable parent, and bent circle shaped hip and chest controls subordinate to it. For low level deformation
tweak controls are provided.
The torso control can optionally be accompanied with a custom pivot control. The rig can also optionally
provide a full set of FK controls that are subordinate to the normal simplified ones, but above tweaks.
The rig properties panel for the spine controls usually includes options for the head and/or tail as well.
.. figure:: /images/addons_rigging_rigify_rig-features_head-controls.png
:align: right
:width: 200px
Head
----
The :ref:`head <rigify.rigs.spines.super_head>` sub-rig attaches to the end of the spine, and provides
rotational controls for the head and neck, as well as tweaks for fine control of the neck.
If the neck is three or more bones long, an additonal tweak-like translational
neck bend control is provided (the widget looks like a circle with arrows).
The properties panel contains the following options:
Neck Follow :guilabel:`Slider`
.. figure:: /images/addons_rigging_rigify_rig-features_head-properties.png
:align: right
:width: 200px
This slider controls the rotations isolation for the neck bones.
The neck will follow the orientation of the Torso when set to 0, and the Chest when set to 1.
Head Follow :guilabel:`Slider`
.. figure:: /images/addons_rigging_rigify_rig-features_tail-controls.png
:align: right
:width: 200px
This slider controls the rotations isolation for the head.
The head will follow the orientation of the Torso when set to 0, and the Chest when set to 1.
Tail
----
The :ref:`tail <rigify.rigs.spines.basic_tail>` sub-rig attaches to the start of the spine, and provides
FK controls for the tail, as well as a master control that replicates its local rotation around certain axes
to all individual bones.
The properties panel contains the following options:
Tail Follow :guilabel:`Slider`
This slider controls the rotations isolation for the tail.
The tail will follow the orientation of the Torso when set to 0, and the Hips when set to 1.
Face
====
.. note::
This describes the new-style modular face produced by the Upgrade Face operator button.
Basic Concepts
--------------
Skin Bone Chains
^^^^^^^^^^^^^^^^
.. figure:: /images/addons_rigging_rigify_rig-features_face-chains.png
:align: right
:width: 300px
The foundation of the Rigify face is a network of Bendy Bone :ref:`chains <rigify.rigs.skin.basic_chain>` with
controls placed at every bone end. These controls affect all bones that meet at that specific point.
When the controls are merely translated, the B-Bone chains retain the normal automatic bezier handle behavior.
Local rotation and/or scaling of the controls are applied on top of that.
In case of :ref:`certain chains <rigify.rigs.skin.stretchy_chain>`, the transformation of the end and/or middle
controls is interpolated to other controls located between them. In such cases the controls often have different
colors and/or shapes.
Additionally, certain controls have :ref:`arbitrary constraints <rigify.rigs.skin.glue>` that partially copy
transformation from nearby control points.
Specialized Controllers
^^^^^^^^^^^^^^^^^^^^^^^
Certain areas of the face, like eyes or mouth, have additional specialized controllers that apply custom behavior
on top of the chains and their controllers within the relevant area.
Eyes
----
.. figure:: /images/addons_rigging_rigify_rig-features_eye-controls.png
:align: right
:width: 300px
The :ref:`eyes <rigify.rigs.face.skin_eye>` have the following controls in addition to the eyelid chains:
Master
This large circular control can be used to transform the whole eye as one unit.
Common Target
This large control enveloping all individual eye targets has a switchable parent and can
be used to specify the point that the eyes should look at.
Eye Target
These small circle controls within the common target control specify the point targeted by each
individual eye. Their local scale can also be used to affect the iris or pupil of the eye,
depending on how it was weight painted.
The rig properties panel contains the following options:
.. figure:: /images/addons_rigging_rigify_rig-features_eye-properties.png
:align: right
:width: 200px
Eyelids Follow :guilabel:`Slider`
Controls how much the rotation of the eyeball affects the eyelids. Depending on the sub-rig generation
options, this slider can be split to separately control the horizontal and vertical directions.
Eyelids Attached :guilabel:`Slider` :guilabel:`Optional`
If enabled in the sub-rig generation options, this slider can be used to disable the mechanism that
forces the eyelids to conform to the sphere of the eye.
Parent :guilabel:`Parent Switch`
Selects the parent for the common target control.
Mouth
-----
.. figure:: /images/addons_rigging_rigify_rig-features_mouth-controls.png
:align: right
:width: 300px
The :ref:`mouth <rigify.rigs.face.skin_jaw>` has the following controls:
Jaw Master
Controls rotation of the jaw, directly affecting the main jaw deform bone, as well
as chains fully belonging to the jaw. Chains forming the lip loop(s) are adjusted to
open the mouth as the jaw rotates or moves.
Mouth Master
This control uniformly transforms the lips without moving the jaw.
The rig properties panel contains the following options:
.. figure:: /images/addons_rigging_rigify_rig-features_mouth-properties.png
:align: right
:width: 200px
Mouth Lock :guilabel:`Slider`
This slider can be changed from 0 to 1 in order to suppress opening of the mouth
when the jaw rotates or moves.

View File

@ -0,0 +1,125 @@
*****
Basic
*****
These rig types are used to generate simple single-bone features,
and for custom rigging done directly in the meta-rig.
The single-bone rig types must be applied separately to every bone even within a connected chain,
and can have connected children controlled by a different rig type.
This is unlike chain-based rig types that usually consume the whole connected chain.
.. _rigify.rigs.basic.copy_chain:
basic.copy_chain
================
Copies the bone chain keeping all the parent relations within the chain untouched.
Useful as a utility rig type for custom rigs.
Requirement: A chain of at least two connected bones.
Control (Boolean)
When enabled control bones and widgets will be created.
Deform (Boolean)
When enabled deform bones will be created.
.. _rigify.rigs.basic.pivot:
basic.pivot
===========
Single-bone rig type that creates a 'custom pivot' control for rotating and scaling its child sub-rigs.
This type of control transforms its children when rotated or scaled, while moving it
merely changes the pivot point used by rotation or scaling.
Master Control
When enabled an extra parent control bone with a box widget is created to allow moving the rig.
It is also required by all other options besides *Deform Bone*.
Widget Type
Allows selecting one of the predefined widgets to generate for the master control instead of the default cube.
Switchable Parent
Generates a mechanism for switching the effective parent of the rig based on the value of a custom property.
Register Parent
Registers the rig as a potential parent scope for its child sub-rigs' parent switches.
Tags
Specifies additional comma-separated tag keywords for the registered parent scope.
They can be used by other rigs to filter parent choices, or for selecting the default parent.
Some of the existing tags that are useful here:
``injected`` (special)
The parent scope will be made available for all children of the *parent* sub-rig,
rather than just this rig's children.
``held_object``
A control for the object held in the character's hand. Preferred by finger IK.
The ``injected,held_object`` combination is perfect for such a control.
Pivot Control
Disabling this avoids generating the actual custom pivot control, effectively turning this rig type
into a version of `basic.super_copy`_ with parent switching support and a different widget.
Deform Bone
When enabled a deform bone will be created.
.. _rigify.rigs.basic.raw_copy:
basic.raw_copy
==============
Single-bone rig type that copies the bone without the ``ORG-`` name prefix.
Normally all bones copied from the meta-rig are prefixed with ``ORG-`` and placed on an invisible layer.
This precludes their use as controls or deforming bones, which makes it difficult to transfer complex
fully custom rigging verbatim from the meta-rig.
This rig type does not add the automatic prefix, thus allowing an appropriate ``ORG-``, ``MCH-`` or ``DEF-``
prefix to be manually included in the meta-rig bone name, or alternatively using no prefix to create
a control bone.
Relink Constraints
Allows retargeting constraints belonging to the bone to point at bones created in the process
of generating the rig, thus allowing custom rigging to integrate with generated bones.
To use this feature, add ``@`` and the intended target bone name to the constraint name, resulting
in the ``...@bone_name`` syntax. After all bones of the rig are generated, the constraint target
bone will be replaced. If the new bone name is just ``CTRL``, ``MCH`` or ``DEF``, this will just
replace the ``ORG`` prefix in the existing target bone name. For the Armature constraint you can add
a ``@`` suffix for each target, or just one ``@CTRL``, ``@MCH`` or ``@DEF`` suffix to update all.
Parent
If the field is not empty, applies the same name substitution logic to the parent of the bone.
When this feature is enabled, the bone will not be automatically parented to the root bone even
if it has no parent; enter ``root`` in the *Parent* field if that is necessary.
.. _rigify.rigs.basic.super_copy:
basic.super_copy
================
Single-bone rig type that simply copies the bone. Useful as utility rig type for
adding custom features or specific deform bones to your rigs.
Control (Boolean)
When enabled a control bone and widget will be created.
Widget (Boolean)
When enabled a widget will be created in replacement to the standard.
Widget Type (String):
Allows selecting one of the predefined widget types to generate instead of the default circle.
Deform (Boolean)
When enabled a deform bone will be created.
Relink Constraints
Works the same as in the `basic.raw_copy`_ rig. In addition, when enabled any constraints that have
names prefixed with ``CTRL:`` are moved to the control, and with ``DEF:`` to the deform bone.

View File

@ -0,0 +1,71 @@
****
Face
****
These rig types implement components of a modular face.
.. _rigify.rigs.face.basic_tongue:
face.basic_tongue
=================
Generates a simple tongue, extracted from the original PitchiPoy :ref:`super_face <rigify.rigs.faces.super_face>` rig.
B-Bone Segments (integer)
Defines the number of b-bone segments each tweak control will be split into.
Primary Control Layers
Optionally specifies bone collections for the main control.
.. _rigify.rigs.face.skin_eye:
face.skin_eye
=============
Implements a skin system :ref:`parent controller <rigify.rigs.skin.skin_parents>` that manages
two skin chains for the top and bottom eyelids in addition to generating the eye rotation mechanism.
The rig must have two child skin chains with names tagged with ``.T`` and ``.B`` symmetry
to mark the top and bottom eyelid, which are connected at their ends forming eye corners.
The chains are rigged to follow the surface of the eye and twist to its normal.
In addition, it creates target controls for aiming the eye, including a master control shared by
all eyes under the same parent rig. The eyelids are rigged to follow the movement of the eyeball
with adjustable influence.
Eyeball and Iris Deforms
Generates deform bones for the eyeball and the iris, the latter copying XZ scale from
the eye target control. The iris is located at the tail of the ORG bone.
Eyelid Detach Option
Generates a slider to disable the mechanism that keeps eyelid controls stuck to the surface of the eye.
Split Eyelid Follow Slider
Generates two separate sliders for controlling the influence of the eye rotation on X and Z eyelid motion.
Eyelids Follow Default
Depending on *Split Eyelid Follow Slider*, specifies the default values for the split follow sliders,
or fixed factors to be multiplied with the single common follow influence slider value.
.. _rigify.rigs.face.skin_jaw:
face.skin_jaw
=============
Implements a skin system :ref:`parent controller <rigify.rigs.skin.skin_parents>` that manages
one or more loops of mouth skin chains in response to the movement of jaw and mouth controls.
The rig must have one or more child chain loops, each formed by four skin chains tagged
with ``.T``/``.B`` and ``.L``/``.R`` symmetrical names.
The lip loops are sorted into layers based on the distance from corners to the common
center and rigged with blended influence of the jaw and the master mouth control.
Other child rigs become children of the jaw.
Bottom Lip Influence
Specifies the influence of the jaw on the inner bottom lip with mouth lock disabled.
Locked Influence
Specifies the influence of the jaw on both lips of locked mouth.
Secondary Influence Falloff
Specifies the factor by which influence fades away with each successive lip loop
(for bottom lip loops the blend moves away from inner bottom lip to full jaw influence).

View File

@ -0,0 +1,19 @@
*****
Faces
*****
.. _rigify.rigs.faces.super_face:
faces.super_face
================
Will create a face system based on the bones child to the parent that has the property set on it.
Requirement: All the face bones bundled in the ``faces.super_face`` sample had to be present and
child of the master bone that has the Rigify-type *face* property set.
.. note::
This rig type is being deprecated in favor of a new modular
:doc:`skin <skin>` and :doc:`face <face>` rigging system.

View File

@ -0,0 +1,23 @@
#############
Rig Types
#############
Rig types are components used by Rigify to process specific parts of the meta-rig when generating the armature.
They represent common character features, like the spine, limbs, fingers etc.
.. note::
The list of available rig types appears in the Bone properties tab when the bone is selected in Pose Mode.
Scroll down the Properties to find Rigify Type panel.
This documents rig types that are bundled with Rigify.
.. toctree::
:maxdepth: 2
basic.rst
spines.rst
limbs.rst
faces.rst
skin.rst
face.rst

View File

@ -0,0 +1,265 @@
*****
Limbs
*****
These rig types handle generation of different kind of limbs and their features, like fingers.
.. _rigify.rigs.limbs.simple_tentacle:
limbs.simple_tentacle
=====================
Will create a simple bendy and stretchy b-bones tentacle chain, which can optionally replicate local rotation
from preceeding bones to the subsequent ones for use in cases like fingers.
Requirement: A chain of at least two connected bones.
Automation Axis (X, Y, Z, None)
Enables the automation on the selected axis. Multiple axis or none can be selected holding :kbd:`Shift-LMB`.
When enabled the subsequent control bones will copy the local rotations from the previous ones.
The option is accessible in the controls of the final rig as a Copy Rotation constraint and
can be disabled even after rig is generated, or at animation time.
Assign Tweak Layers
If enabled, allows placing the Tweak controls in different bone collections from the main controls.
.. _rigify.rigs.limbs.super_finger:
limbs.super_finger
==================
Will create a bendy and stretchy finger chain with a master control bone that controls the rotation of
all joints through its scale.
Requirement: A chain of at least two connected bones.
Bend Rotation Axis (Automatic, X, Y, Z, -X, -Y, -Z)
Defines the automatic rotation axis to be linked to the scale of the master bone.
B-Bone Segments (integer)
Defines the number of b-bone segments each tweak control will be split into.
IK Control
Generates a very simple IK mechanism with only one control.
IK starts its work with the shape of the finger defined by FK controls and adjusts it
to make the fingertip touch the IK control. It is designed as a tool to temporarily keep
the fingertip locked to a surface it touches, rather than a fully featured posing system.
To improve performance, the switchable parent for the IK control contains only one option beside None.
Thus it is advised to add a 'held object' control using the :ref:`basic.raw_copy <rigify.rigs.basic.pivot>`
rig to act as the common parent for the fingers with a fully functional parent switch.
IK Local Location
Specifies the value of the Local Location option for IK controls, which decides if the location
channels are aligned to the local control orientation or world.
Assign Tweak Layers
If enabled, allows placing the Tweak controls in different bone collections from the main controls.
Assign Extra IK Layers
If enabled, allows placing the extra IK control in different bone collections from the main controls.
.. note::
Rotation Axis (Bend Rotation Axis in the case of `limbs.super_finger`_)
affects the :doc:`roll </animation/armatures/bones/editing/bone_roll>` of the generated bones.
Automatic mode recalculates the generated bones roll while
any of the Manual modes copy the roll of the meta-rig bones.
.. _rigify.rigs.limbs.super_limb:
limbs.super_limb
================
A backwards compatibility wrapper around `limbs.arm`_, `limbs.leg`_ and `limbs.paw`_.
.. _rigify.rigs.limbs.arm:
limbs.arm
=========
Will create a fully featured bendy and stretchy arm depending on the user-defined options.
Requirement: A chain of three connected bones (upper_arm, forearm, hand).
.. figure:: /images/addons_rigging_rigify_rig-types_limbs_arm-required.png
Arm required bones.
IK Wrist Pivot
Generates an extra child of the hand IK control that rotates around the tail of the hand bone.
Rotation Axis (Automatic, X, Z)
Defines the bend axis for the IK chain. FK chains will have a totally free degree of rotation on all axes.
Limb Segments (integer)
Defines the number of additional tweak controls each limb bone will have on the final rig.
B-Bone Segments (integer)
Defines the number of b-bone segments each tweak control will be split into.
Custom IK Pivot
Generates an extra control for the end of the IK limb that allows rotating it around an arbitrarily placed pivot.
Assign FK Layers
If enabled, allows placing the FK chain in different bone collections from the IK bones.
Assign Tweak Layers
If enabled, allows placing the Tweak controls in different bone collections from the IK bones.
.. _rigify.rigs.limbs.leg:
limbs.leg
=========
Will create a fully featured bendy and stretchy leg depending on the user-defined options.
Requirement: A chain of four connected bones (thigh, shin, foot, toe) with one unconnected
child of the foot to be used as the heel pivot.
.. figure:: /images/addons_rigging_rigify_rig-types_limbs_leg-required.png
Leg required bones.
Foot Pivot (Ankle, Toe, Ankle & Toe)
Specifies where to put the pivot location of the main IK control, or whether to generate an additional
pivot control at the base of the toe.
Separate IK Toe
Specifies that two separate toe controls should be generated for IK and FK instead of sharing one bone.
This is necessary to get fully correct IK-FK snapping in all possible poses.
Toe Tip Roll
Generates a slider to switch the heel control to pivot on the tip rather than the base of the toe
(for roll this obviously only applies on forward roll).
Rotation Axis (Automatic, X, Z)
Defines the bend axis for the IK chain. FK chains will have a totally free degree of rotation on all axes.
Limb Segments (integer)
Defines the number of additional tweak controls each limb bone will have on the final rig.
B-Bone Segments (integer)
Defines the number of b-bone segments each tweak control will be split into.
Custom IK Pivot
Generates an extra control for the end of the IK limb that allows rotating it around an arbitrarily placed pivot.
Assign FK Layers
If enabled, allows placing the FK chain in different bone collections from the IK bones.
Assign Tweak Layers
If enabled, allows placing the Tweak controls in different bone collections from the IK bones.
.. _rigify.rigs.limbs.paw:
limbs.paw
=========
Will create a fully featured bendy and stretchy paw depending on the user-defined options.
Requirement: A chain of four or five connected bones (thigh, shin, paw, *optional* digit, toe).
.. figure:: /images/addons_rigging_rigify_rig-types_limbs_paw-required.png
Front/Rear paw required bones.
Rotation Axis (Automatic, X, Z)
Defines the bend axis for the IK chain. FK chains will have a totally free degree of rotation on all axes.
Limb Segments (integer)
Defines the number of additional tweak controls each limb bone will have on the final rig.
B-Bone Segments (integer)
Defines the number of b-bone segments each tweak control will be split into.
Custom IK Pivot
Generates an extra control for the end of the IK limb that allows rotating it around an arbitrarily placed pivot.
Assign FK Layers
If enabled, allows placing the FK chain in different bone collections from the IK bones.
Assign Tweak Layers
If enabled, allows placing the Tweak controls in different bone collections from the IK bones.
.. _rigify.rigs.limbs.front_paw:
limbs.front_paw
===============
Derivative of `limbs.paw`_ with extended IK suitable for use in front paws.
The additional IK limits the degree of change in the angle between shin and
paw bones (2nd and 3rd) as the main IK control moves and rotates.
For best results, the shin bone should not be parallel to either thigh or paw in rest pose,
i.e. there should be some degree of bend in all joints of the paw.
Heel IK Influence
Influence of the extended IK. At full rotating the main IK control or digit bone would
not affect the rotation of the paw bone, while lower values provide some blending.
.. _rigify.rigs.limbs.rear_paw:
limbs.rear_paw
==============
Derivative of `limbs.paw`_ with extended IK suitable for use in rear paws.
The additional IK tries to maintain thigh and paw bones (1st and 3rd) in a nearly parallel orientation
as the main IK control moves and rotates.
For best results, thigh and paw bones should start nearly parallel in the rest pose.
.. _rigify.rigs.limbs.super_palm:
limbs.super_palm
================
Will create a palm system based on the distance between palm bones.
Requirement: At least two bones child of the same parent.
The property has to be set on the inner palm bones (think it as index's metacarpus),
the rig control will appear on the last palm bone (think it as pinky's metacarpus).
Both Sides
Generates controls on both sides of the palm, with influence on inner bones blended between them.
Primary Rotation Axis (X, Z)
Defines the automatic rotation axis to be used on the palm bones.
.. _rigify.rigs.limbs.spline_tentacle:
limbs.spline_tentacle
=====================
This rig type implements a flexible tentacle with an IK system using the Spline IK constraint. The control bones
define control points of a Bezier curve, and the bone chain follows the curve.
The curve control points are sorted into three groups: start, middle and end. The middle controls are always
visible and active, while the other two types can be shown and hidden dynamically using properties; when enabled
they appear next to the corresponding permanent start/end control and can be moved from there.
Extra Start Controls
Specifies the number of optional start controls to generate.
Middle Controls
Specifies the number of middle controls to generate.
Extra End Controls
Specifies the number of optional end controls to generate.
Tip Control:
Specifies how the curve stretching and the final control bone work:
Stretch To Fit
Stretches the whole bone chain to fit the length of the curve defined by the controls.
An end twist control is generated to control the twist along the chain.
Direct Tip Control
Generates an IK end control, which directly controls the final bone of the chain similar to how
regular IK works for limbs, as well as controlling the end of the bezier curve. The middle bones of
the chain stretch to follow the curve and cover the gap.
The rig automatically deduces twist of up to 180 degrees based on the orientation of the end control.
Higher amounts of twist have to be dialled in through an End Twist Estimate slider to avoid flipping.
Manual Squash & Stretch
This mode allows full manual control over the chain scaling, while the chain covers as much of the curve
as it can given its current length.
The start control of the chain manages its uniform squash & stretch scale, while the end twist control
manages both the twist of the chain, as well as its scale at the tip (blended gradually along the length).
Radius Scaling
Allows scaling the controls to control the thickness of the chain through the curve.
Maximum Radius
Specifies the maximum scale allowed by the Radius Scaling feature.
FK Controls
Generates an FK control chain and IK-FK snapping.
Assign FK Layers
If enabled, allows placing the FK chain in different bone collections from the IK bones.

View File

@ -0,0 +1,221 @@
.. todo: make permanent 'new', development
****
Skin
****
These rigs implement a flexible system for rigging skin using multiple interacting B-Bone chains.
This is developed as the base for a new modular Rigify face rig.
These are the main ideas of the system:
Generic B-Bone Chain
One core idea of the system is that most of the deformation should be implemented
using a standard powerful B-Bone chain rig. These chains support advanced behavior by
interacting with other rig components. This is in contrast to having multiple domain-specific rigs
that each generate their own deform chains.
The implementation provides two versions of the chain rig: `skin.basic_chain`_ merely
attaches B-Bones to the controls with no automation added to the controls themselves.
The `skin.stretchy_chain`_ rig in addition interpolates motion of the end (and an optional middle)
controls to the other controls of the chain.
Automatic Control Merging
The deformation part of the system consists of chains of one or more B-Bones connecting
control points (nodes). Whenever controls for two chains would completely overlap,
they are automatically merged.
For each merged control, one of the chains is selected as the owner, based on heuristic factors
like parent depth from root, presence of ``.T``/``.B`` ``.L``/``.R`` symmetry markers,
and even alphabetical order as the last resort. This can be overridden by an explicit priority setting
in cases when it guesses wrong.
The owner and its parents determine additional automation that is placed on the control.
As a special case, if a control is merged with its ``.T``/``.B`` ``.L``/``.R`` symmetry counterparts
(detected purely by naming), the automation from all of the symmetry siblings
of the owner is averaged.
.. _rigify.rigs.skin.skin_parents:
Parent Controllers
Rather than simply using the parent meta-rig bone (ORG) as parent for controls and chain mechanisms,
the new system includes an interface for parent rigs. It explicitly provide parent bones and generate control
parent automation mechanisms for their child chain controls by inheriting from the appropriate base
and overriding methods.
This allows implementing rigs that integrate and manage their child chains in intelligent ways in order
to add extra automation specific to certain areas. The base skin system includes one simple example
`skin.transform.basic`_ rig, which translates its child control points according to
its control bone transformation.
Custom Rigging
Finally, the new system provides ways to integrate with custom automation directly included in the meta-rig
via two extra rig components.
The `skin.anchor`_ rig generates a single control with inherited constraints etc., similar to
:ref:`basic.super_copy <rigify.rigs.basic.super_copy>`. However, it also integrates into the skin system
as a zero length chain with highest priority. This allows overriding the normal behavior by providing
a control point under full control of the user, which other chains would automatically attach to.
The `skin.glue`_ rig on the other hand will attach itself to the control that is generated at
its position (it is an error if there is none). It can be used to read the position of the control
from custom rigging in the meta-rig, or inject constraints into the control bone. It is possible to
also detect the control at the tail of the glue bone and use it as target in the constraints,
thus copying transformation between the controls.
.. _rigify.rigs.skin.basic_chain:
skin.basic_chain
================
This is the basic chain rig, which bridges controls with B-Bones but does not add
any automation to the controls themselves.
When controls are merely moved, the chains behave as if using standard
automatic handles, but rotating and optionally scaling the controls will adjust the result.
B-Bone Segments
Specifies the number of segments to use. Setting this to 1 disables
all advanced behavior and merely bridges the points with a Stretch To bone.
Merge Parent Rotation and Scale
This can be enabled to let the chain respond to rotation and scale induced by parents of
controls owned by other chains that this chain's control merged into.
Use Handle Scale
Enables using control scale to drive scale and/or easing of the B-Bone.
Connect With Mirror
Specifies whether the ends of the chain should smoothly connect when merging controls
with its ``.T``/``.B`` ``.L``/``.R`` symmetry counterpart. The relevant option must be enabled
on both chains to work.
Connect Matching Ends
Specifies whether the end of the chain should connect to the opposite end of a different chain
when merging controls. Thus forming a continuous smooth chain in the same direction.
The relevant options must be enabled on both chains.
Sharpen Corner
Specifies whether the rig should generate a mechanism to form a sharp corner at
the relevant connected end, depending on the angle formed by adjacent control locations.
When the control angle becomes sharper than the specified value, ease starts reducing from 1 to 0.
Orientation
Specifies that the controls should be oriented the same as the selected bone, rather than being
aligned to the chain.
Copy To Selected
Copy to selected rigs that have the same option. Thus allowing to indiscriminately selecting bones
without assigning unnecessary values.
Chain Priority
Allows overriding the heuristic used to select the primary owner when merging controls.
.. _rigify.rigs.skin.stretchy_chain:
skin.stretchy_chain
===================
This rig extends the basic chain with automation that propagates movement of the start and end,
and an optional middle control, to other controls. This results in stretching the whole chain
when moving one of the ends, rather than just the immediately adjacent B-Bones.
Middle Control Position
Specifies the position of the middle control within the chain; disabled when zero.
Falloff
Specifies the influence falloff curves of the start, middle and end controls.
Zero results in linear falloff, increasing widens the influence, and -10 disables
the influence propagation from that control completely.
Spherical Falloff
Toggle buttons to change the shape of the falloff curve from a power curve that at falloff 1 forms a parabola
:math:`1 - x^{2^f}` to a curve forming a circle :math:`(1 - x^{2^f})^{2^{-f}}`.
Falloff Along Chain Curve
Computes the falloff curve along the length of the chain, instead of projecting on the straight
line connecting its start and end points.
Propagate Twist
Specifies whether twist of the chain should be propagated to control points between main controls.
Propagate Scale
Specifies whether perpendicular scaling of the chain should be propagated to control points between main controls.
Propagate to Controls
Allows other chains to see propagated twist and scale via *Merge Parent Rotation and Scale* when their
controls are merged into this chain, instead of it being completely local to this chain.
Primary Control Layers
Optionally specifies bone collections for the end controls.
Secondary Control Layers
Optionally specifies bone collections for the middle control, falling back to *Primary Control Layers* if not set.
The main controls with active falloff have the effect of *Merge Parent Rotation and Scale*
automatically enabled just for them.
.. _rigify.rigs.skin.anchor:
skin.anchor
===========
This rig effectively acts as a zero-length chain with highest priority,
ensuring that it becomes the owner when merging controls with other chains.
And also allowing one to input custom automation influence into the skin system.
All constraints on the meta-rig bone are moved to the created control.
Generate Deform Bone
Creates a deformation bone parented to the control.
Suppress Control
Makes the control a hidden mechanism bone to hide it from the user.
Widget Type
Selects which widget to generate for the control.
Relink Constraints
Operates the same as in :ref:`basic.raw_copy <rigify.rigs.basic.raw_copy>`,
except all constraints are moved from ORG to the control bone.
Orientation
Specifies the bone used to orient the control, like for other chains.
.. _rigify.rigs.skin.glue:
skin.glue
=========
This rig is in concept similar to `skin.anchor`_, but instead of overriding controls,
it is used to read or adjust the state of controls generated by other rigs.
The head of the bone must overlap a control of another skin rig.
The rig sets up its ORG bone to read the state of the control,
while moving all constraints that were originally on the bone to the control.
Glue Mode
Specifies how the ORG bone is connected to the skin control.
Child Of Control
Makes the ORG bone a child of the control bone.
Mirror Of Control
Makes the ORG bone a sibling of the control with a Copy Transforms constraint from the control.
The resulting local space transformation is the same as control's local space.
Mirror With Parents
Parents the ORG bone to the parent automation a control owned by
the glue rig would have had, while making it follow the actual control.
This includes both direct and parent-induced motion of the control into
the local space transformation of the bone.
Deformation Bridge
Other than adding glue constraints to the control, the rig acts as a one segment basic deform chain.
This is convenient when a pair of controls need to be bridged both with glue and a deform bone.
Relink Constraints
Operates the same as in :ref:`basic.raw_copy <rigify.rigs.basic.raw_copy>`,
except all constraints are moved from ORG to the control bone.
Use Tail Target
Relinks ``TARGET`` or any constraints with an empty target bone and no relink specification
to reference the control located at the tail of the glue bone.
Target Local With Parents
Switches the tail target to operate similarly to *Mirror With Parents*.
Add Constraint
Allows to add a typical glue constraints with specific *Influence*, as if it were at
the start of the ORG bone constraint stack.
.. _rigify.rigs.skin.transform.basic:
skin.transform.basic
====================
This rig provides a simplistic :ref:`parent controller <rigify.rigs.skin.skin_parents>`, which uses regular
translation, rotation, or scale to modify locations but not orientations or scale of its child chain controls.
Generate Control
Specifies whether to generate a visible control, or use the transformation of the ORG bone
as a part of more complex and specific rig setup.

View File

@ -0,0 +1,92 @@
******
Spines
******
These rigs are used to generate spine structures, including the head and tail.
.. _rigify.rigs.spines.super_spine:
spines.super_spine
==================
Will create a complete bendy and stretchy b-bones spine system based on bone numbers of
your bone chain and user defined options.
This is a composite wrapper of `spines.basic_spine`_, `spines.super_head`_ and `spines.basic_tail`_.
Note that for the tail, the direction of the bones is reversed compared to the separate rig.
Requirement: A chain of at least three connected bones (base system).
.. figure:: /images/addons_rigging_rigify_rig-types_spines-required.png
Spine required bones.
Pivot Position (integer)
Defines the pivot position for torso and hips.
Head (Boolean)
When checked neck and head systems will be added to your spine rig.
Neck Position (integer)
Defines the bone where the neck system starts. The last bone will always be the head system.
If neck position is the last bone of the chain, then only the head system will be created ignoring the neck.
Tail (Boolean)
When checked tail system will be added to your spine rig.
Tail Position (integer)
Defines the bone where the tail system starts. The next bone will always be the hips system.
X, Y, Z (Boolean)
When generating a tail, specifies which local axis rotations should be replicated along the chain.
Assign Tweak Layers
If enabled, allows placing the Tweak controls in different bone collections from the IK bones.
.. figure:: /images/addons_rigging_rigify_rig-types_spines-default.png
Spine default bones.
.. figure:: /images/addons_rigging_rigify_rig-types_spines-example.png
Spine with tail bones.
.. _rigify.rigs.spines.basic_spine:
spines.basic_spine
==================
Defines a bendy and stretchy b-bones spine.
Pivot Position (integer)
Defines the pivot position for torso and hips.
Assign Tweak Layers
If enabled, allows placing the Tweak controls in different bone collections from the IK bones.
FK Controls
Specifies whether to generate an FK control chain.
Assign FK Layers
If enabled, allows placing the FK chain in different bone collections from the IK bones.
.. _rigify.rigs.spines.basic_tail:
spines.basic_tail
=================
Defines a bendy and stretchy b-bones tail.
X, Y, Z (Boolean)
Specifies which local axis rotations should be replicated along the chain from each control
bone to the following one.
Assign Tweak Layers
If enabled, allows placing the Tweak controls in different bone collections from the IK bones.
.. _rigify.rigs.spines.super_head:
spines.super_head
=================
Defines a head rig with follow torso controls.
Assign Tweak Layers
If enabled, allows placing the Tweak controls in different bone collections from the IK bones.

View File

@ -371,6 +371,9 @@ GPU Options
``--gpu-backend``
Force to use a specific GPU backend. Valid options: ``vulkan`` (experimental), ``metal``, ``opengl``.
``--gpu-compilation-subprocesses``
Override the Max Compilation Subprocesses setting (OpenGL only).
.. _command-line-args-misc-options:

View File

@ -238,6 +238,7 @@ usage::
blender --command extension build [-h] [--source-dir SOURCE_DIR]
[--output-dir OUTPUT_DIR]
[--output-filepath OUTPUT_FILEPATH]
[--valid-tags VALID_TAGS_JSON]
[--split-platforms] [--verbose]
Build a package in the current directory.
@ -256,6 +257,16 @@ options:
The package output filepath (should include a ``.zip`` extension).
Defaults to a name created using the ``id`` from the manifest.
--valid-tags VALID_TAGS_JSON
Reference a file path containing valid tags lists.
If you wish to reference custom tags a ``.json`` file can be used.
The contents must be a dictionary of lists where the ``key`` matches the extension type.
For example:
``{"add-ons": ["Example", "Another"], "theme": ["Other", "Tags"]}``
To disable validating tags, pass in an empty path ``--valid-tags=""``.
--split-platforms Build a separate package for each platform.
Adding the platform as a file name suffix (before the extension).
@ -270,18 +281,30 @@ Subcommand: ``validate``
usage::
blender --command extension validate [-h] [SOURCE_PATH]
blender --command extension validate [-h]
[--valid-tags VALID_TAGS_JSON]
[SOURCE_PATH]
Validate the package meta-data in the current directory.
positional arguments:
:SOURCE_PATH: The package source path (either directory containing package files or the package archive).
This path must containing a ``blender_manifest.toml`` manifest.
:SOURCE_PATH: The package source path (either directory containing package files or the package archive).
This path must containing a ``blender_manifest.toml`` manifest.
Defaults to the current directory.
Defaults to the current directory.
options:
-h, --help show this help message and exit
-h, --help show this help message and exit
--valid-tags VALID_TAGS_JSON
Reference a file path containing valid tags lists.
If you wish to reference custom tags a ``.json`` file can be used.
The contents must be a dictionary of lists where the ``key`` matches the extension type.
For example:
``{"add-ons": ["Example", "Another"], "theme": ["Other", "Tags"]}``
To disable validating tags, pass in an empty path ``--valid-tags=""``.
.. _command-line-args-extension-server-generate:

View File

@ -14,8 +14,8 @@ compatible extensions are listed:
- ``platform``
- ``blender_version``
This means that servers have the chance to handle these arguments to output a single entry per-extension on the
listing.
This means that servers have the chance to handle these arguments to output a single entry
per-extension on the listing.
These arguments are passed as parameters to the server via a query URL:

View File

@ -29,7 +29,12 @@ To test the generated repository, create a new "Remote" repository from the user
- **Extensions -> Repositories -> [+] -> Add Remote Repository**
- In the **URL** paste the location of the generated JSON.
So the example ``/path/to/packages`` would use the: ``file:///path/to/packages/index.json``.
So the example ``/path/to/packages`` would use the:
- ``file:///path/to/packages/index.json`` on Linux/macOS.
- ``file:///C:/path/to/packages/index.json`` on MS-Windows.
- ``file://HOST/share/path/to/packages/index.json`` network shares on MS-Windows.
You may wish to use a web browser to navigate to the file-system location and copy that URL into Blender.
@ -86,4 +91,6 @@ Expected format:
<version_max_exclusive>&platforms=<platform1,platform2,...>``
Example:
``https://extensions.blender.org/add-ons/amaranth-toolset/1.0.23/download/add-on-amaranth-toolset-v1.0.23.zip?repository=/api/v1/extensions/&blender_version_min=4.2.0&platforms=linux-x64,macos-x64``
``https://extensions.blender.org/add-ons/amaranth-toolset/1.0.23/download/add-on-amaranth-toolset-v1.0.23.zip?repository=%2Fapi%2Fv1%2Fextensions%2F&blender_version_min=4.2.0&platforms=linux-x64%2Cmacos-x64``
*Note that ``%2F`` and ``%2C`` are simply the url-encoded equivalent of ``/`` and ``,`` respectively.*

View File

@ -83,8 +83,3 @@ Viewer Region
which will become the next preview in the backdrop.
:kbd:`Ctrl-Alt-B` discards the region back to a full preview.
This is only a preview option, final compositing during a render ignores this region.
.. _bpy.types.SpaceNodeEditor.use_auto_render:
Auto Render
Re-render and composite changed layer when edits to the 3D scene are made.

View File

@ -167,7 +167,8 @@ Scene Statistics
Scene Duration
Shows the total amount of time of the playback along with the current frame number and total frame count.
The format of the duration text is determined by the :ref:`Timecode Style <bpy.types.PreferencesView.timecode_style>`.
The format of the duration text is determined by the
:ref:`Timecode Style <bpy.types.PreferencesView.timecode_style>`.
System Memory
Shows an estimate of Blender's RAM consumption. On a single-instance single-machine scenario,

View File

@ -72,8 +72,8 @@ Open Recent
Displays a list of recently opened blend-files.
Hovering over items will show a preview, and information about the blend-file.
Select any of the file names in the list to open that blend-file.
When :kbd:`RMB` on a listed item, a context menu will appear; One of the available options is *Open File Location*, which will open that
location in an OS file explorer or Finder window.
When :kbd:`RMB` on a listed item, a context menu will appear; One of the available options is *Open File Location*,
which will open that location in an OS file explorer or Finder window.
Clear Recent Files List
Removes all items from the list.

View File

@ -132,7 +132,7 @@ Light Intensity Scale
Scale for the intensity of imported lights.
Custom Properties
Behavior when importing USD attributes as :doc:`Custom Properties <files-data_blocks-custom-properties>`.
Behavior when importing USD attributes as :ref:`Custom Properties <files-data_blocks-custom-properties>`.
:None: Does not import USD custom attributes.
:User:
@ -329,7 +329,7 @@ Include
Blender Data
Custom Properties
Exports :doc:`Custom Properties <files-data_blocks-custom-properties>`
Exports :ref:`Custom Properties <files-data_blocks-custom-properties>`
as USD attributes in the ``userProperties`` namespace.
Blender Names
Author USD custom attributes containing the original Blender object and object data names.

View File

@ -8,5 +8,4 @@
:maxdepth: 2
link_append.rst
library_proxies.rst
library_overrides.rst

View File

@ -70,6 +70,47 @@ data-blocks of different hierarchies, like a parenting relationships between two
of a same character.
Animation & Overrides
=====================
Due to current design of animation data in Blender, what is editable in overrides' animations can
change greatly depending on whether animation data was already defined in the linked reference
data-block. Animation data is created for a datablock if it gets animated by keyframes, or
through drivers.
In general, an overrides can do much more with its animation data if no animation data exists
in its linked reference data-block.
**Keyframes (a.k.a. F-Curves)**
:doc:`Keyframed animation </animation/keyframes/introduction>` belongs to another data-block
(an Action one). So it is possible to assign a purely local Action data-block replacing
the one linked from the library. This will completely replace the keyframed animation
from the linked data though, and not override it in any way.
Overridden Action data-blocks only support a very limited amount of editing.
For example, an existing F-Curve can be muted, but its keyframes cannot be edited,
and no new F-Curve can be added.
**Drivers**
If the linked reference data has animation data, then its overrides only have
limited possibilities to edit the existing :doc:`drivers </animation/drivers/introduction>`.
For example, it will be possible to change the exisitng target of a driver,
but it won't be possible to add new drivers, or new targets to an existing driver.
If the linked reference data has no animation data, then its overrides will create a new one
when they get some drivers defined. Drivers can then be fully edited, added or removed,
just as with purely local data-blocks.
**NLA**
The :doc:`NLA editor </editors/nla/introduction>` data also belongs to the animation data
of a data-block. However, this data does support some greater level of edition in overrides,
including moving or resizing existing strips from the linked data,
and adding new local strips.
Resyncing Overrides
===================

View File

@ -1,13 +0,0 @@
*******
Proxies
*******
Proxies were the historical way in Blender to allow some local editing of linked data-blocks.
This was mostly aimed at character animation.
They are now fully deprecated as of Blender 3.0, replaced by the new
:doc:`Library Overrides </files/linked_libraries/library_overrides>`.
Existing proxies in older blend-files will be converted to library overrides when
opening it in Blender 3.2 and later.

View File

@ -29,7 +29,9 @@ Link
*Link* creates a reference to the data in the source file such that
changes made there will be reflected in the referencing file the next time it is reloaded.
But linked data is not editable (to some extent, see :doc:`/files/linked_libraries/library_proxies`).
But linked data is usually not editable.
:doc:`Library Overrides </files/linked_libraries/library_overrides>` can be created from
linked data to allow some level of local editing, animation, etc.
In the :doc:`File Browser </editors/file_browser>`,
navigate to the external source blend-file and select the data-block you want to reuse.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

Binary file not shown.

View File

@ -67,7 +67,8 @@ Scene Statistics
Scene Duration
Shows the total amount of time of the playback along with the current frame number and total frame count.
The format of the duration text is determined by the :ref:`Timecode Style <bpy.types.PreferencesView.timecode_style>`.
The format of the duration text is determined by the
:ref:`Timecode Style <bpy.types.PreferencesView.timecode_style>`.
System Memory
Shows an estimate of Blender's RAM consumption. On a single-instance single-machine scenario,

View File

@ -9,7 +9,8 @@ Set Instance Transform Node
:align: right
:alt: Set Instance Transform node.
The *Set Instance Transform* node :term:`Transforms <Transform>` geometry instances using a :term:`Transformation Matrix`.
The *Set Instance Transform* node :term:`Transforms <Transform>` geometry instances
using a :term:`Transformation Matrix`.
The :doc:`/modeling/geometry_nodes/instances` page contains more information about geometry instances.

View File

@ -53,7 +53,3 @@ Minimum Vertices
Minimum number of vertices a face must have to be triangulated.
For example, setting this value to 5, will prevent triangulation of :term:`Quads <Quad>`
and only triangulate :term:`N-gons <N-gon>`.
Keep Normals
When using :ref:`custom normals <modeling_meshes_normals_custom>`,
try to preserve the same shading as before triangulation.

View File

@ -1,4 +1,3 @@
************
Displacement
************
@ -66,10 +65,8 @@ as 8-bit images often can not represent all the necessary detail.
Displacement and Bump
=====================
:guilabel:`Cycles Only`
Both methods can be combined to use actual displacement for the bigger displacement and
bump for the finer details. This can provide a good balance to reduce memory usage.
Once you subdivide the mesh very finely, it is better to use only actual displacement.
Once you subdivide the mesh very finely, it is better to use only actual displacement in Cycles.
Keeping bump maps will then only increase memory usage and slow down renders.

View File

@ -17,7 +17,7 @@ Faces
Collection
This creates an instance of the collection with the transformation of the object.
Collection instancers can be animated using actions,
or can get a :doc:`Proxy </files/linked_libraries/library_proxies>`.
or can get a :doc:`Library Override </files/linked_libraries/library_overrides>`.
.. toctree::
:maxdepth: 2