Process/Addons/Rigify/Utils/Naming

= Naming Utilities (rigify.utils.naming) =

This module provides utilities for manipulating bone names.

Name Decomposition
Rigify expects bone names to follow a certain structure, consisting of a prefix, base name, Z and X sides, and a number, e.g. `DEF-foo.T.L.001` (all but the base are optional). These utilities help with parsing and recombining the names.

NameParts Tuple
Decomposed names are represented as a named tuple with the following fields:


 * `prefix`
 * Optional prefix part (without the `-` delimiter) or None.


 * `base`
 * The base part of the name.


 * `side_z`
 * Optional vertical side tag, consisting of a `._-` delimiter and `TtBb` top or bottom side descriptor.


 * `side`
 * Optional horizontal side tag, consisting of a `._-` delimiter and `LlRr` left or right side descriptor.


 * `number`
 * Optional number tag without the `.` delimiter.

Functions

 * `split_name(name)`
 * Parses the name string into the `NameParts` tuple representation.


 * `combine_name(parts, *, prefix=None, base=None, side_z=None, side=None, number=None)`
 * Recombines the tuple into a name string, optionally replacing some of its parts. The `number` part may be specified as an int.

Name Mirroring
These utilities deal with name symmetry along X and Z axes.

Side Enum
The horizontal side can be represented as the `Side` IntEnum.


 * `Side.LEFT = -1`
 * Left side.


 * `Side.MIDDLE = 0`
 * Neutral.


 * `Side.RIGHT = +1`
 * Right side.

Functions:


 * `Side.from_parts(parts)`
 * Convert the side component of the name parts tuple to the enum value.


 * `Side.to_string(parts, side)`
 * Convert the side enum value to a name side component, matching the delimiter and case from the tuple.


 * `Side.to_name(parts, side)`
 * Replace the name side component using the side enum value.

SideZ Enum
The vertical side can be represented as the `SideZ` IntEnum.


 * `SideZ.TOP = +2`
 * Top side.


 * `SideZ.MIDDLE = 0`
 * Neutral.


 * `SideZ.BOTTOM = -2`
 * Bottom side.

Functions:


 * `SideZ.from_parts(parts)`
 * Convert the side_z component of the name parts tuple to the enum value.


 * `SideZ.to_string(parts, side)`
 * Convert the side enum value to a name side_z component, matching the delimiter and case from the tuple.


 * `SideZ.to_name(parts, side)`
 * Replace the name side_z component using the side enum value.

NameSides Tuple
Names can be decomposed into a neutral name and two side enum values, represented as a named tuple.


 * `base`
 * Name string with sides removed.


 * `side`
 * Horizontal `Side` value.


 * `side_z`
 * Vertical `SideZ` value.

Functions

 * `get_name_side(name)`
 * Extract the horizontal `Side` value from the name string.


 * `get_name_side_z(name)`
 * Extract the vertical `SideZ` value from the name string.


 * `get_name_base_and_sides(name)`
 * Split the name into a `NameSides` tuple of a neutral name and both side values.


 * `change_name_side(name, side=None, *, side_z=None)`
 * Replace the sides components of the name using the enum values.


 * `mirror_name(name)`
 * Mirror the name in the horizontal direction.


 * `mirror_name_z(name)`
 * Mirror the name in the vertical direction.

Utility Functions
General utilities, built on top of the above low-level functions:


 * `get_name(bone)`
 * Return the name of the bone, or None if bone is None.


 * `make_derived_name(name, subtype, suffix=None)`
 * Replaces the prefix with one appropriate to the subtype (one in `'org'`, `'def'`, `'mch'`, `'ctrl'`), and optionally adds a suffix to the base part.


 * `is_control_bone(name)`
 * Returns true if the name has no prefix component.


 * `strip_trailing_number(name)`
 * Removes the number component of the name.


 * `strip_prefix(name)`
 * Removes the prefix component of the name.


 * `strip_org(name)`
 * Removes only the ORG prefix from the name.


 * `strip_mch(name)`
 * Removes only the MCH prefix from the name.


 * `strip_def(name)`
 * Removes only the DEF prefix from the name.


 * `make_original_name(name)`, `org(name)`
 * Adds the ORG prefix to the name if not there.


 * `make_mechanism_name(name)`, `mch(name)`
 * Adds the MCH prefix to the name if not there.


 * `make_deformer_name(name)`, `deformer(name)`
 * Adds the DEF prefix to the name if not there.


 * `unique_name(collection, name)`
 * Find first prefix number that doesn't exist in the collection.


 * `random_id(length=8)`
 * Generate a random alphanumeric string.


 * `choose_derived_bone(generator, original_name, subtype, *, by_owner=True, recursive=True)`
 * Find a bone of the appropriate `make_derived_name` subtype that was generated based on the original bone.
 * `by_owner` limits search to the original's owner rig, and `recursive` walks through chained copies.