Merge pull request #200 from TrevisanGMW/dev

release <- dev (3.3.0)

Author: TrevisanGMW

README.md

@@ -30,15 +30,14 @@ variety of tools and utilities. This menu contains sub-menus that have been orga
 for example: modeling, rigging, utilities, etc…
 
 For help on how to use these scripts, click on the “Help” button at the top right of their window (within Maya) or
-check their documentation by going to the <a href="./docs">"docs"</a> folder. For changelog read the text at the top
-of the tool init file (just open the “.py” file using any text editor, such as notepad)
+check their documentation by going to the <a href="./docs">docs</a> folder. For changelog see the <a href="https://github.com/TrevisanGMW/gt-tools/releases">releases</a> page.
 
 All of these items are supplied as is. You alone are solely responsible for any issues. Use at your own risk.
 Hopefully these scripts are helpful to you as they are to me.
 
 Note: Python 2 is no longer supported. If you want to still use an older versions of Maya, make sure to use a GT-Tools version below "3.0.0" for compatibility.
 
-<p><b>Package tested using Autodesk Maya 2022, 2023 and 2024 (Windows 10)</b></p>
+<p><b>Package tested using Autodesk Maya 2022, 2023 and 2024 (Windows 11)</b></p>
 
 <h1>Organization</h1>
 <ul>

docs/README.md

@@ -53,6 +53,7 @@
   <li><a href="#gt-create-testing-keys">GT Create Testing Keys</a></li>
   <li><a href="#gt-make-ik-stretchy">GT Make IK Stretchy</a></li>
   <li><a href="#gt-add-sine-attributes">GT Add Sine Attributes</a></li>
+  <li><a href="#gt-ribbon-tool">GT Ribbon Tool</a></li>
 </ul>
 <h3><b>Utilities:</b></h3>
 <ul>
@@ -800,7 +801,7 @@ If painting the skin weights with "ngSkinTools" (third party plugin) you might h
 <p>
 <ul>
 	<li><b>Home Remedy - Animated Short Film:</b><br><a href="https://vimeo.com/579130303">vimeo.com/579130303</a></li>
-	<li><b>Art in the time of Corona:</b><br><a href="https://youtu.be/TtYRudIZBGQ?t=2023">youtu.be/TtYRudIZBGQ</a><br><a href="https://vimeo.com/564743576">vimeo.com/564743576</a></li>
+	<li><b>Art in the time of Corona:</b><br><a href="https://youtu.be/TtYRudIZBGQ?t=2023">youtu.be/TtYRudIZBGQ</a><br></li>
 	<li><b>Short Horror Animation:</b><br><a href="https://youtu.be/pH62aGjf9-Y?t=1198">youtu.be/pH62aGjf9-Y</a></li>
 </ul></p>
 
@@ -1286,13 +1287,54 @@ If painting the skin weights with "ngSkinTools" (third party plugin) you might h
 	<li><b>Output:</b> Result of the sine operation.</li>
 	<li><b>Abs Output:</b> Absolute output. (no negative values).</li>
 </ul>
-
+<p>
 Added attributes don't affect your attribute holder in any way, it's up to you do create necessary connections that will determine how these new values will be used.<br>For example, connecting "sideOutput" to "translateY" will case the object to move up and down according to the side curve.
 
 </p>
 
 <br><br>
 
+<!-- GT Ribbon Tool -->
+<div>
+<h1>GT Ribbon Tool</h1>
+
+<img src="./media/gt_ribbon_tool.jpg" align="right"
+     alt="GT Ribbon Tool GUI">
+
+<p>Tool for automating the process of creating ribbons. A ribbon is a commonly used setup in rigging that serves as a flexible surface for attaching joints and controls.
+
+Ribbon rigging is particularly useful for creating smooth and natural-looking deformations, especially in areas of the character where complex movements are required, such as the spine, limbs, or facial features. By attaching joints and control objects to the ribbon, animators can easily manipulate and pose the character, achieving realistic movement and expressions.</p>
+
+<ul>
+	<li><b>Prefix:</b> Multiplier for the time input (tick)</li>
+	<li><b>Source Mode:</b> What the ribbon should use as input data.<br>
+          <ul>
+               <li><b>No Source:</b> Creates a simple ribbon.</li>
+               <li><b>Surface:</b> Uses provided surface as input.</li>
+               <li><b>Transform List:</b> Creates ribbon using a provided transform list.</li>
+          </ul>  
+    </li>
+	<li><b>Number of Controls:</b> How many ribbon controls should be created.</li>
+	<li><b>Number of Joints:</b> How many skinned joints should be created.</li>
+	<li><b>Dropoff Rate:</b> Dropoff rate used for binding controls to ribbon surface. Similar to dropoff rate when binding joints to surfaces.</li>
+	<li><b>Span Multiplier:</b> If more than zero, it multiplies the number of spans on the target surface.</li>
+	<li><b>Equidistant:</b> Ensures equidistant calculation between the distance of every follicle.</li>
+	<li><b>Add FK:</b> Creates extra forward-kinematics controls to drive ribbon controls.</li>
+	<li><b>Parent Skin Joints:</b> Creates a hierarchy with the generated driven joints.</li>
+	<li><b>Constraint Source:</b> Constraint source transforms to follow the ribbon. (This skips joint creation)</li>
+	<li><b>Source Surface / Transform List:</b> Determines what should be used as source data. (Different data depending on source mode)
+          <ul>
+               <li><b>No Source:</b> Option is disabled as no source is needed. (Ribbon is a simple surface going from -12 to 12 in the grid)</li>
+               <li><b>Surface:</b> Expects the user to set an existing surface (nurbsSurface) to be used as ribbon.</li>
+               <li><b>Transform List:</b> Expects the user to set a list of objects to be used as reference for when creating the ribbon.<br>Surface is created using the position of the selected objects. Order is important and is used to create the flow of the ribbon.</li>
+          </ul> 
+    </li>
+    <li><b>Create Ribbon:</b> Creates a ribbon setup using the preferences above.</li>
+</ul>
+
+<br><br>
+
+
 </div>
 
 <!-- GT Utilities -->

docs/media/gt_ribbon_tool.jpg

@@ -1,7 +1,7 @@
 import sys
 
 # Package Variables
-__version_tuple__ = (3, 2, 3)
+__version_tuple__ = (3, 3, 0)
 __version_suffix__ = ''
 __version__ = '.'.join(str(n) for n in __version_tuple__) + __version_suffix__
 __authors__ = ['Guilherme Trevisan']

gt/__init__.py

@@ -14,20 +14,27 @@ def __init__(self):
     # General Keys and Attributes
     PROJECT_EXTENSION = "rig"
     FILE_FILTER = f"Rig Project (*.{PROJECT_EXTENSION});;"
-    # Attributes and Keys
-    JOINT_ATTR_UUID = "jointUUID"
-    PROXY_ATTR_UUID = "proxyUUID"
-    CONTROL_ATTR_UUID = "controlUUID"
-    PROXY_ATTR_SCALE = "locatorScale"
-    PROXY_META_PARENT = "metaParentUUID"  # Metadata key, may be different from actual parent (e.g. for lines)
-    PROXY_META_TYPE = "proxyType"  # Metadata key, used to recognize rigged proxies within modules
-    PROXY_CLR = "color"  # Metadata key, describes color to be used instead of side setup.
-    LINE_ATTR_CHILD_UUID = "lineProxySourceUUID"  # Used by the proxy lines to store source
-    LINE_ATTR_PARENT_UUID = "lineProxyTargetUUID"  # Used by the proxy lines to store target
-    JOINT_ATTR_DRIVEN_UUID = "jointDrivenUUID"
+    # System Attributes
+    ATTR_JOINT_UUID = "jointUUID"
+    ATTR_MODULE_UUID = "moduleUUID"
+    ATTR_PROXY_UUID = "proxyUUID"
+    ATTR_DRIVER_UUID = "driverUUID"
+    ATTR_JOINT_DRIVEN_UUID = "jointDrivenUUID"
+    # Misc Attributes
+    ATTR_PROXY_SCALE = "locatorScale"
+    ATTR_JOINT_PURPOSE = "jointPurpose"
+    ATTR_JOINT_DRIVERS = "jointDrivers"
+    ATTR_LINE_CHILD_UUID = "lineProxySourceUUID"  # Used by the proxy lines to store source
+    ATTR_LINE_PARENT_UUID = "lineProxyTargetUUID"  # Used by the proxy lines to store target
+    # Metadata Keys
+    META_PROXY_LINE_PARENT = "lineParentUUID"  # Metadata key, line parent. Actual parent is ignored when present.
+    META_PROXY_PURPOSE = "proxyPurpose"  # Metadata key, used to recognize proxy purpose within modules
+    META_PROXY_DRIVERS = "proxyDrivers"  # Metadata key, used to find drivers (aka controls) driving the created joint
+    META_PROXY_CLR = "color"  # Metadata key, describes color to be used instead of side setup.
     # Separator Attributes
-    SEPARATOR_STD_SUFFIX = "Options"  # Standard (Std) Separator attribute name (a.k.a. header attribute)
-    SEPARATOR_BEHAVIOR = "Behavior"
+    SEPARATOR_OPTIONS = "options"
+    SEPARATOR_BEHAVIOR = "behavior"
+    SEPARATOR_AUTOMATION = "automation"
     # Group Names
     GRP_RIG_NAME = f'rig_{NamingConstants.Suffix.GRP}'
     GRP_PROXY_NAME = f'rig_proxy_{NamingConstants.Suffix.GRP}'
@@ -37,16 +44,29 @@ def __init__(self):
     GRP_SETUP_NAME = f'setup_{NamingConstants.Suffix.GRP}'
     GRP_LINE_NAME = f'visualization_lines'
     # Reference Attributes
-    REF_ROOT_RIG_ATTR = "rootRigLookupAttr"
-    REF_ROOT_PROXY_ATTR = "rootProxyLookupAttr"
-    REF_ROOT_CONTROL_ATTR = "rootControlLookupAttr"
-    REF_DIR_CURVE_ATTR = "dirCrvLookupAttr"
-    REF_GEOMETRY_ATTR = "geometryGroupLookupAttr"
-    REF_SKELETON_ATTR = "skeletonGroupLookupAttr"
-    REF_CONTROL_ATTR = "controlGroupLookupAttr"
-    REF_SETUP_ATTR = "setupGroupLookupAttr"
-    REF_LINES_ATTR = "linesGroupLookupAttr"
+    REF_ATTR_ROOT_RIG = "rootRigLookupAttr"
+    REF_ATTR_ROOT_PROXY = "rootProxyLookupAttr"
+    REF_ATTR_ROOT_CONTROL = "rootControlLookupAttr"
+    REF_ATTR_DIR_CURVE = "dirCrvLookupAttr"
+    REF_ATTR_GEOMETRY = "geometryGroupLookupAttr"
+    REF_ATTR_SKELETON = "skeletonGroupLookupAttr"
+    REF_ATTR_CONTROL = "controlGroupLookupAttr"
+    REF_ATTR_SETUP = "setupGroupLookupAttr"
+    REF_ATTR_LINES = "linesGroupLookupAttr"
     # Multipliers
     LOC_RADIUS_MULTIPLIER_DRIVEN = .8
     LOC_RADIUS_MULTIPLIER_FK = .3
     LOC_RADIUS_MULTIPLIER_IK = .6
+    # Misc
+    ENUM_ROTATE_ORDER = 'xyz:yzx:zxy:xzy:yxz:zyx'
+
+
+class RiggerDriverTypes:
+    def __init__(self):
+        """
+        Driver Type Constant values used by the drivers and controls.
+        """
+    FK = "fk"
+    IK = "ik"
+    OFFSET = "offset"
+    COG = "cog"