maya.roles.controller
=====================

.. py:module:: maya.roles.controller

.. autoapi-nested-parse::

   Controller facade.

   A Controller is a semantic wrapper around a Transform node that:
   - is tagged as a controller in Maya
   - manages NURBS curve shapes under the transform
   - exposes a controller-centric API



Attributes
----------

.. autoapisummary::

   maya.roles.controller.LOG


Classes
-------

.. autoapisummary::

   maya.roles.controller.Controller


Functions
---------

.. autoapisummary::

   maya.roles.controller.replace_curve


Module Contents
---------------

.. py: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


   .. py:method:: 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).



   .. py:method:: clear_shapes()

      Delete all shapes under the controller transform.



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


      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.



   .. py:method:: from_node(node)
      :classmethod:


      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.



   .. py:method:: 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.



   .. py:method:: is_controller(node) -> bool
      :classmethod:


      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.



   .. py:method:: 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).



   .. py:method:: 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



   .. py:method:: 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.



   .. py:attribute:: ROLE_ATTR
      :value: 'isController'



   .. py: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



   .. py:attribute:: node


   .. py:property:: shapes
      :type: list


      Return all shape nodes under the controller transform.

      Returns:
          list: List of shape node wrappers.



   .. py:property:: transform
      :type: maya.types.transform.Transform


      Pass-through to the underlying transform node.

      Returns:
          Transform: The wrapped transform node.



.. py:function:: replace_curve(orig_curve, new_curve, snap=True, transfer_color=True)

   Replace curve shapes on a controller.

   Args:
       orig_curve: Name of the original nurbsCurve transform to replace.
       new_curve: Name of the new nurbsCurve transform to replace with.
       snap: Whether to match the position of the new curve to the original (default: True).
       transfer_color: Whether to transfer the color override from new to original (default: True).


.. py:data:: LOG