openrig.conventions package

Rigging conventions package for OpenRig.

Provides configurable rigging defaults (axis orientation, rotate order, default side) that can be adjusted per project via conventions/config.json or by constructing a RiggingConventions instance directly.

Public API:

  • get_conventions() -> RiggingConventions: returns the singleton instance.

  • load_conventions(path) -> RiggingConventions: loads from a custom path.

  • RiggingConventions: the conventions dataclass.

  • ConventionsError: raised on load or validation failures.

Example

>>> from openrig.conventions import get_conventions
>>> conv = get_conventions()
>>> conv.aim_axis
<Axis.X: 'X'>
>>> conv.default_rotate_order.as_string
'xyz'
exception openrig.conventions.ConventionsError[source]

Bases: Exception

Raised when rigging conventions cannot be loaded or are invalid.

class openrig.conventions.RiggingConventions(aim_axis: Axis, up_axis: Axis, side_axis: Axis, default_rotate_order: RotateOrder, default_side: Side)[source]

Bases: object

Active rigging conventions for a project.

Construct directly for programmatic configuration or testing. Use load_conventions() or get_conventions() for file-based loading.

aim_axis

The axis joints and controls aim along.

Type:

openrig.constants.Axis

up_axis

The axis used as the up vector.

Type:

openrig.constants.Axis

side_axis

The axis used for the side direction.

Type:

openrig.constants.Axis

default_rotate_order

The default rotate order for joints and controls.

Type:

openrig.constants.RotateOrder

default_side

The default side token when none is specified.

Type:

openrig.constants.Side

aim_axis: Axis
up_axis: Axis
side_axis: Axis
default_rotate_order: RotateOrder
default_side: Side
openrig.conventions.get_conventions() → RiggingConventions[source]

Returns the pre-configured singleton RiggingConventions instance.

Builds the instance on first call using the defaults defined in conventions/config.json. Subsequent calls return the same instance.

Returns:

The singleton RiggingConventions instance.

openrig.conventions.load_conventions(path: Path | str | None = None) → RiggingConventions[source]

Loads rigging conventions from a JSON file.

Falls back to the package-level default (conventions/config.json) when no path is provided.

Parameters:

path – Path to a JSON config file, or None to use the package default.

Returns:

A validated RiggingConventions instance.

Raises:

ConventionsError – If the file is missing, malformed, or contains invalid values.

Submodules