openrig.conventions.conventions module

Rigging conventions loader for OpenRig.

Reads conventions/config.json, validates the values, and exposes load_conventions() for file-based loading and RiggingConventions for direct programmatic construction.

Exported symbols (consumed by __init__.py):

ConventionsError: raised on any load or validation failure.
RiggingConventions: frozen dataclass holding the active defaults.
load_conventions(path): reads a JSON file and returns an instance.

exception openrig.conventions.conventions.ConventionsError[source]

Bases: Exception

Raised when rigging conventions cannot be loaded or are invalid.

class openrig.conventions.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.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.