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 andTtBb
top or bottom side descriptor. side
- Optional horizontal side tag, consisting of a
._-
delimiter andLlRr
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, andrecursive
walks through chained copies.