maya.roles

Maya node roles and behaviors.

Submodules

Classes

Controller

Semantic wrapper for controller transforms in Maya.

Package Contents

class Controller(node)

Semantic wrapper for controller transforms in Maya.

A Controller is a Transform node that: - Is tagged as a controller - Manages NURBS curve shapes for visual representation - Provides a controller-centric API for shape and color management

add_shape(curve_data: dict, size=1.0)

Add a curve shape under the controller transform.

Args:
curve_data: Dictionary containing curve definition with keys:

  • ‘point’: List of (x, y, z) tuples for CV positions

  • ‘degree’: Curve degree (default: 3)

  • ‘periodic’: Whether curve is periodic (default: False)

  • ‘knot’: Optional knot vector

size: Scale multiplier applied to all points (default: 1.0).

clear_shapes()

Delete all shapes under the controller transform.

classmethod create(name, shape='Circle', size=1.0, color=None, **kwargs)

Create a new controller transform with specified shape and properties.

Args:

name: Name for the new controller. shape: Shape name from library or curve data dict (default: “Circle”). size: Scale multiplier for the shape (default: 1.0). color: Color to apply (int, tuple, or Color object). **kwargs: Additional arguments passed to Transform.create().

Returns:

Controller: The newly created controller instance.

classmethod from_node(node)

Create a Controller wrapper from an existing controller node.

Args:

node: Node name or wrapper that is tagged as a controller.

Returns:

Controller: Controller instance wrapping the node.

Raises:

RuntimeError: If the node is not tagged as a controller.

get_color(as_color=False)

Get the display color of the controller shapes.

Args:
as_color: If True, return as Color object when using RGB;

otherwise return raw value (default: False).

Returns:

int, tuple, Color, or None: The color value or None if no override is set.

classmethod is_controller(node) → bool

Check if a node is tagged as a controller.

Args:

node: Node name or wrapper to check.

Returns:

bool: True if the node is tagged as a controller, False otherwise.

replace_shape(shape, size=1.0, snap=True, transfer_color=True)

Replace existing controller shapes while preserving transformations.

Args:

shape: Shape name from library (str) or raw curve data (dict). size: Scale multiplier (default: 1.0). snap: Whether to match the position of the new shape (default: True). transfer_color: Whether to transfer color from the old shape (default: True).

set_color(color)

Set the display color of the controller shapes.

Args:
color: Color specification:

  • int: Maya index color (0-31)

  • tuple/list: RGB values (0.0-1.0)

  • Color: tik.core.Color object

  • None: Disable color override

set_shape(shape, size=1.0)

Replace controller shapes with a new shape.

Args:

shape: Shape name from library (str) or raw curve data (dict). size: Scale multiplier, shapes are normalized to 1.0 (default: 1.0).

Note:

This clears all existing shapes before adding the new one.

ROLE_ATTR = 'isController'
property color

Get or set the display color of the controller shapes.

Can be set to:

  • int: Maya index color (0-31)

  • tuple/list: RGB values (0.0-1.0)

  • Color: tik.core.Color object

node
property shapes: list

Return all shape nodes under the controller transform.

Returns:

list: List of shape node wrappers.

property transform: maya.types.transform.Transform

Pass-through to the underlying transform node.

Returns:

Transform: The wrapped transform node.