manual/addons/index.rst

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

manual/addons/rigging/index.rst

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

manual/addons/rigging/rigify/basics.rst

@@ -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.

manual/addons/rigging/rigify/bone_positioning.rst

@@ -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`.

manual/addons/rigging/rigify/feature_sets.rst

@@ -0,0 +1,30 @@
+
+************
+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.
+
+`Cloud Rig <https://gitlab.com/blender/CloudRig>`__
+   This major conversion feature set by Demeter Dzadik implements the rig used by
+   the Blender Animation Studio using the Rigify framework.
+
+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/>`__.

manual/addons/rigging/rigify/index.rst

@@ -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.

manual/addons/rigging/rigify/introduction.rst

@@ -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.

manual/addons/rigging/rigify/metarigs.rst

@@ -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.

manual/addons/rigging/rigify/rig_features.rst

@@ -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.

manual/addons/rigging/rigify/rig_types/basic.rst

@@ -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.

manual/addons/rigging/rigify/rig_types/face.rst

@@ -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).

manual/addons/rigging/rigify/rig_types/faces.rst

@@ -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.

manual/addons/rigging/rigify/rig_types/index.rst

@@ -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

manual/addons/rigging/rigify/rig_types/limbs.rst

@@ -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.

manual/addons/rigging/rigify/rig_types/skin.rst

@@ -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.

manual/addons/rigging/rigify/rig_types/spines.rst

@@ -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.