maya.utils.control_shapes
=========================

.. py:module:: maya.utils.control_shapes


Attributes
----------

.. autoapisummary::

   maya.utils.control_shapes.CAMERA_POSITIONS
   maya.utils.control_shapes.CURRENT_PLATFORM
   maya.utils.control_shapes.LOG


Classes
-------

.. autoapisummary::

   maya.utils.control_shapes.ControlShapeLibrary


Functions
---------

.. autoapisummary::

   maya.utils.control_shapes.capture
   maya.utils.control_shapes.capture_thumbnail
   maya.utils.control_shapes.capture_to_disk
   maya.utils.control_shapes.get_home_dir
   maya.utils.control_shapes.save_to_disk


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

.. py:class:: ControlShapeLibrary

   Singleton manager for accessing and loading controller shape data.

   The library searches for shape definitions in multiple locations:
   1. Core path: Built-in shapes shipped with TikMaya
   2. User path: User-specific shapes in ~/TikWorks/user_control_shapes
   3. Environment paths: Additional paths from TIKMAYA_SHAPES_PATH env variable
   4. Custom paths: Paths added via API

   Later paths override earlier ones for shapes with the same name.


   .. py:method:: add_path(path)

      Add a custom search path with highest priority.

      Args:
          path: Path to add to the search paths.

      Note:
          Invalidates the cache, forcing a refresh on next access.



   .. py:method:: get_instance()
      :classmethod:


      Get or create the singleton instance of the library.

      Returns:
          ControlShapeLibrary: The singleton instance.



   .. py:method:: get_path(name)

      Get the file path for a shape by name.

      Args:
          name: Name of the shape.

      Returns:
          Path or None: Path to the shape's JSON file, or None if not found.



   .. py:method:: get_shape_data()

      Get cached shape metadata for all shapes.

      Returns:
          dict: Dictionary mapping shape names to metadata dicts with 'path' and 'category' keys.



   .. py:method:: list_shapes()

      Get a list of all available shape names.

      Returns:
          list: List of shape names (str).



   .. py:method:: load(name)

      Load and return the curve data dictionary for a shape.

      Args:
          name: Name of the shape to load.

      Returns:
          dict or None: The shape data dictionary, or None if not found or error occurs.



   .. py:method:: refresh()

      Scan all search paths and populate the shape cache.

      Shapes in later paths override those in earlier paths.



   .. py:method:: remove_path(path)

      Remove a custom search path.

      Args:
          path: Path to remove from the search paths.

      Note:
          Invalidates the cache, forcing a refresh on next access.



   .. py:property:: search_paths

      Get the list of paths searched for shapes, in resolution order.

      Resolution order (lowest to highest priority):
      1. Core path
      2. User path
      3. Environment paths (from TIKMAYA_SHAPES_PATH)
      4. Custom paths (added via API)

      Returns:
          list: List of Path objects that exist on disk.



   .. py:property:: user_path

      Get the user-specific shape library path.

      Returns:
          Path: Path to the user's shape library directory.



.. py:function:: capture(node_name, name=None, normalize=True)

   Scrape curve data from a transform.


.. py:function:: capture_thumbnail(node_name, name, folder_path, category=None, camera_position=None)

   Snapshot the thumbnail of the current viewport for the shape.


.. py:function:: capture_to_disk(node_name, name=None, folder_path=None, category=None, normalize=True, thumbnail=True)

   Capture shape data from a Maya node and save it to disk as JSON.

   Args:
       node_name: Name of the Maya transform node to capture.
       name: Optional name for the saved shape (defaults to node name).
       folder_path: Destination folder (defaults to user library path).
       category: Optional subfolder category for organization.
       normalize: Whether to normalize the shape to unit scale (default: True).
       thumbnail: Whether to capture a thumbnail image (default: True).

   Returns:
       Path or None: Path to the saved JSON file, or None on error.


.. py:function:: get_home_dir()

   Get the user home directory.

   Returns:
       str: Normalized path to the user's home directory.


.. py:function:: save_to_disk(data, name, folder_path, category=None)

   Save the given shape data to disk as JSON.


.. py:data:: CAMERA_POSITIONS

.. py:data:: CURRENT_PLATFORM

.. py:data:: LOG