openrig.maya.core package

Core abstractions for the OpenRig solution system.

Public API:

from openrig.maya.core import (
    BuildContext,
    InputPort,
    NamingStrategy,
    OutputPort,
    SolutionBase,
    SolutionSettings,
)

class openrig.maya.core.BuildContext(namer: NamingStrategy, conventions: RiggingConventions)[source]

Bases: object

Shared state and services for the solution build pipeline.

Carries the naming strategy, rigging conventions, and the in-memory outputs registry. Solutions use this to register their outputs, resolve inputs from other solutions, and query guide positions in the scene.

Parameters:

namer – Naming strategy implementation used by all solutions.
conventions – Active rigging conventions (axes, rotate order, etc.).

get_output(solution_id: str, port_name: str) → str[source]

Return the Maya DAG path registered for an output port.

Parameters:

solution_id – Unique identifier of the source solution.
port_name – Name of the output port.

Returns:

The registered Maya DAG path string.

Raises:

KeyError – If the solution or port has not been registered yet.

set_output(solution_id: str, port_name: str, value: str) → None[source]

Register an output value produced by a built solution.

Called by solutions inside build() for each declared output port.

Parameters:

solution_id – Unique identifier of the solution setting the output.
port_name – Name of the output port being registered.
value – Maya DAG path of the output node.

resolve_input(solution: _SolutionLike, port_name: str) → str | None[source]

Resolve a declared input connection to a Maya DAG path.

Looks up the connection declaration for the given port and retrieves the corresponding output from the already-built outputs registry. Returns None if no connection was declared for the port (optional inputs).

Parameters:

solution – The solution requesting the input.
port_name – Name of the input port to resolve.

Returns:

The Maya DAG path of the connected output, or None if no connection was declared for this port.

Raises:

KeyError – If the referenced source solution or port has not been built yet.
ValueError – If the stored connection string has an invalid format.

get_guide(solution: _SolutionLike, guide_name: str) → tuple[float, float, float] | None[source]

Return the world position of a guide object if it exists in the scene.

Looks for a node named {solution_id}_guides_grp in the Maya scene and navigates to {guides_grp}|{guide_name}. Returns None if not found — the caller falls back to its settings values.

Parameters:

solution – The solution whose guides group is searched.
guide_name – Short name of the guide node within the guides group.

Returns:

World-space (x, y, z) position tuple, or None if no guide was found.

finalize(rig_root: str) → None[source]

Write rig-level and solution-level metadata to Maya nodes.

Called automatically by the build pipeline after all solutions have completed build(). Writes custom string attributes to the rig root and to each solution’s root node so the scene is self-describing.

Rig-level attributes (written to rig_root):

openrig_version
description_json
build_date

Solution-level attributes (written to each solution’s root node):

solution_type
solution_id
settings_json
outputs_json

Parameters:: rig_root – Maya DAG path of the rig root node.

class openrig.maya.core.InputPort(name: str, type: str, required: bool = True, description: str = '')[source]

Bases: object

Declares a value that a solution needs from another solution.

Parameters:

name – Unique port identifier within the solution.
type – Advisory type string (e.g. "node", "transform", "joint").
required – If True, the build fails before touching Maya when no connection is declared for this port.
description – Human-readable description of what this input expects.

name: str

type: str

required: bool = True

description: str = ''

class openrig.maya.core.NamingStrategy(*args, **kwargs)[source]

Bases: Protocol

Interface every naming convention implementation must satisfy.

Solutions call ctx.namer.build_name(...) — they never import get_manager() directly, keeping them agnostic to which naming convention is active.

build_name(**tokens: object) → str[source]: Build a validated name from token key/value pairs.

parse_name(name: str) → dict[str, str][source]: Parse a name string into its constituent token values.

class openrig.maya.core.OutputPort(name: str, type: str, description: str = '')[source]

Bases: object

Declares a value that a solution produces for other solutions.

Parameters:

name – Unique port identifier within the solution.
type – Advisory type string (e.g. "node", "transform", "joint").
description – Human-readable description of what this output provides.

name: str

type: str

description: str = ''

class openrig.maya.core.SolutionBase[source]

Bases: ABC

Contract every rig solution must implement.

Subclasses must define:

solution_type — class variable used as the JSON registry key.
settings — instance attribute holding a SolutionSettings subclass with all configuration for this solution.
build(ctx) — the main build method (abstract).

Subclasses are registered automatically when their module is imported. No manual registration is needed.

solution_type

Class-level type string used as the JSON key (e.g. "Arm"). Must be unique across all registered solutions.

Type:: ClassVar[str]

solution_id

Instance-level unique identifier within a rig build (e.g. "arm_l"). Set by the build pipeline before build() is called.

Type:: str

settings

Configuration for this solution instance. Each subclass defines its own SolutionSettings subclass with the fields it needs.

Type:: openrig.maya.core.settings.SolutionSettings

solution_type: ClassVar[str]

solution_id: str

settings: SolutionSettings

classmethod input_ports() → dict[str, InputPort][source]

Declare what this solution needs from other solutions.

Override to declare input ports. The default returns an empty dict (no inputs required).

Returns:: A dict mapping port name to InputPort descriptor.

classmethod output_ports() → dict[str, OutputPort][source]

Declare what this solution produces for other solutions.

Override to declare output ports. The default returns an empty dict (no outputs produced).

Returns:: A dict mapping port name to OutputPort descriptor.

create_guides(ctx: BuildContext) → None[source]

Create guide objects in Maya for interactive positioning.

Optional. The default implementation does nothing — the solution builds from settings alone. Override to place guide locators or geometry that the rigger can reposition before calling build().

Parameters:: ctx – The shared build context.

abstract build(ctx: BuildContext) → None[source]

Build the solution in the Maya scene.

Required. Called by the build pipeline in dependency order.

Implementations must:

Read guide positions via ctx.get_guide() when guides exist, falling back to self.settings when they do not.
Create all necessary Maya nodes.
Register every declared output port via ctx.set_output().

Parameters:: ctx – The shared build context.

post_build(ctx: BuildContext) → None[source]

Run connections that require all solutions to already exist.

Optional. The default implementation does nothing. Override to make cross-solution connections (e.g. parenting arm to spine) that can only be established after every solution has completed build().

Parameters:: ctx – The shared build context.

class openrig.maya.core.SolutionSettings(side: Side = Side.CENTER)[source]

Bases: object

Base settings shared by every solution.

Subclasses add solution-specific fields (naming tokens, joint counts, fallback positions, etc.). Only concepts that are universally meaningful across all solutions belong here.

side

Which side of the body this solution belongs to (left, right, center, or middle).

Type:: openrig.constants.Side

side: Side = 'c'

openrig.maya.core package

Submodules