Skip to content

Commit 5e3abef

Browse files
committed
updating documentation #601
1 parent fbbe35f commit 5e3abef

1 file changed

Lines changed: 242 additions & 20 deletions

File tree

‎docs/source/shifterUserDocumentation.rst‎

Lines changed: 242 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,17 +1,9 @@
11
Shifter User Documentation
22
##########################
33

4-
WIP section: Please visit:
4+
Please visit:
55
`mGear Youtube channel <https://www.youtube.com/c/mgearriggingframework/>`_
66

7-
* components
8-
* creating new components
9-
* guides templates and basic rig building
10-
* stepped rig building
11-
* scalability and reusability
12-
* gotchas
13-
* tips
14-
157
.. _shifter-guide-manager:
168

179
Shifter Guide Manager
@@ -631,22 +623,252 @@ Custom steps are Python classes that inherit from ``customShifterMainStep``:
631623
# Create organization group for custom objects
632624
setup_root = self.get_or_create_setup_root()
633625
634-
**Available Methods in Custom Steps:**
626+
Available Properties
627+
^^^^^^^^^^^^^^^^^^^^
628+
629+
**self.rig**
630+
631+
Alias for ``self.mgear_run`` providing intuitive access to the Shifter rig object. Use this to access rig-wide data and controls.
632+
633+
.. code-block:: python
634+
635+
def run(self):
636+
# Access the global control
637+
global_ctl = self.rig.global_ctl
638+
639+
# Access the rig's setup group
640+
setup_grp = self.rig.setupWS
641+
642+
# Get all components
643+
all_components = self.rig.components
644+
645+
**self.guide**
646+
647+
Access to the guide object from the rig build (if available).
648+
649+
.. code-block:: python
650+
651+
def run(self):
652+
if self.guide:
653+
# Access guide data
654+
guide_model = self.guide.model
655+
656+
Available Methods
657+
^^^^^^^^^^^^^^^^^
658+
659+
**self.component(name)**
660+
661+
Get a component by its full name (e.g., "arm_L0"). Raises ``KeyError`` if the component is not found.
662+
663+
.. code-block:: python
664+
665+
def run(self):
666+
# Get a specific component
667+
arm = self.component("arm_L0")
668+
669+
# Access component controls
670+
fk_ctl = arm.fk_ctl
671+
ik_ctl = arm.ik_ctl
672+
673+
**self.has_component(name)**
674+
675+
Check if a component exists without raising an error. Returns ``True`` if the component exists, ``False`` otherwise.
676+
677+
.. code-block:: python
678+
679+
def run(self):
680+
# Safely check for optional components
681+
if self.has_component("tail_C0"):
682+
tail = self.component("tail_C0")
683+
self.log("Found tail component")
684+
else:
685+
self.log("No tail component in this rig", level="warning")
686+
687+
**self.components_by_type(comp_type)**
688+
689+
Get all components of a specific type. Returns a list of matching components.
690+
691+
.. code-block:: python
692+
693+
def run(self):
694+
# Get all control_01 components
695+
all_controls = self.components_by_type("control_01")
696+
for ctrl in all_controls:
697+
self.log("Found control: {}".format(ctrl.fullName))
698+
699+
# Process all arm components
700+
arms = self.components_by_type("EPIC_arm_01")
701+
for arm in arms:
702+
# Apply custom setup to each arm
703+
self.setup_arm_spaces(arm)
704+
705+
**self.custom_step(name)**
706+
707+
Access a custom step that has already been executed. Raises ``KeyError`` if the step hasn't run yet.
708+
709+
.. code-block:: python
710+
711+
def run(self):
712+
# Access data from a previous step
713+
color_step = self.custom_step("apply_colors")
714+
colors_used = color_step.color_palette
715+
716+
**self.has_custom_step(name)**
717+
718+
Check if a custom step has been executed without raising an error.
719+
720+
.. code-block:: python
721+
722+
def run(self):
723+
# Check for optional dependency
724+
if self.has_custom_step("proxy_setup"):
725+
proxy = self.custom_step("proxy_setup")
726+
# Use proxy data
727+
else:
728+
self.log("Proxy setup not available", level="warning")
729+
730+
**self.get_or_create_setup_root(name)**
731+
732+
Get or create a setup root group for organizing custom step objects. The group is automatically parented under the rig's setup group.
733+
734+
.. code-block:: python
735+
736+
def run(self):
737+
# Create a setup group for this step's objects
738+
setup_grp = self.get_or_create_setup_root()
739+
740+
# Create custom objects and parent them
741+
my_locator = pm.spaceLocator(name="custom_loc")
742+
pm.parent(my_locator, setup_grp)
743+
744+
# Use a custom name for the setup root
745+
custom_grp = self.get_or_create_setup_root("my_custom_setup")
746+
747+
**self.log(message, level)**
748+
749+
Log a message with the step name as a prefix. The ``level`` parameter can be "info" (default), "warning", or "error".
750+
751+
.. code-block:: python
752+
753+
def run(self):
754+
self.log("Starting custom step processing")
755+
# Output: [my_custom_step] Starting custom step processing
756+
757+
self.log("Missing optional attribute", level="warning")
758+
# Displays as Maya warning
759+
760+
self.log("Critical error occurred", level="error")
761+
# Displays as Maya error
762+
763+
Running Sub-Steps
764+
^^^^^^^^^^^^^^^^^
765+
766+
**self.run_sub_step(module_name, step_path)**
767+
768+
Load and run another custom step from an external module. This powerful method enables modular step design by allowing you to break complex operations into smaller, reusable steps.
769+
770+
The sub-step will have access to the same step dictionary, components, and rig context as the parent step.
771+
772+
**Parameters:**
773+
774+
- ``module_name``: The name of the Python module/file without the ``.py`` extension
775+
- ``step_path`` (optional): The directory path where the module is located. If not provided, checks the ``MGEAR_SHIFTER_CUSTOMSTEP_PATH`` environment variable
776+
777+
**Basic Usage:**
778+
779+
.. code-block:: python
780+
781+
def run(self):
782+
# Run a sub-step from a specific path
783+
self.run_sub_step("apply_colors", "W:/my_steps")
784+
785+
# Run a sub-step using MGEAR_SHIFTER_CUSTOMSTEP_PATH env var
786+
self.run_sub_step("setup_spaces")
787+
788+
# Run a sub-step that's already in Python's path
789+
self.run_sub_step("mirror_controls")
790+
791+
**Accessing Sub-Step Data:**
792+
793+
.. code-block:: python
794+
795+
def run(self):
796+
# Run the sub-step and get immediate access
797+
color_step = self.run_sub_step("apply_colors", "W:/my_steps")
798+
self.log("Colors applied: {}".format(color_step.colors_applied))
799+
800+
# Or access it later via custom_step()
801+
self.run_sub_step("setup_proxies", "W:/my_steps")
802+
# ... other code ...
803+
proxy_step = self.custom_step("setup_proxies")
804+
805+
**Modular Step Architecture Example:**
806+
807+
Main step file (``main_setup.py``):
808+
809+
.. code-block:: python
810+
811+
from mgear.shifter.custom_step import customShifterMainStep
812+
813+
class CustomShifterStep(customShifterMainStep):
814+
815+
def setup(self):
816+
self.name = "main_setup"
817+
818+
def run(self):
819+
self.log("Running main setup...")
820+
821+
# Run color application
822+
self.run_sub_step("apply_colors", "W:/steps")
823+
824+
# Run space switching setup
825+
self.run_sub_step("setup_spaces", "W:/steps")
826+
827+
# Run selection sets creation
828+
self.run_sub_step("create_sets", "W:/steps")
829+
830+
self.log("Main setup complete!")
831+
832+
Sub-step file (``apply_colors.py``):
833+
834+
.. code-block:: python
835+
836+
from mgear.shifter.custom_step import customShifterMainStep
837+
838+
class CustomShifterStep(customShifterMainStep):
839+
840+
def setup(self):
841+
self.name = "apply_colors"
842+
self.colors_applied = []
843+
844+
def run(self):
845+
self.log("Applying control colors...")
846+
847+
# Get all arm components and apply colors
848+
arms = self.components_by_type("EPIC_arm_01")
849+
for arm in arms:
850+
# Apply color logic
851+
self.colors_applied.append(arm.fullName)
852+
853+
self.log("Applied colors to {} components".format(
854+
len(self.colors_applied)))
855+
856+
**Benefits of Sub-Steps:**
635857

636-
- ``self.rig``: Access to the Shifter rig object
637-
- ``self.guide``: Access to guide data
638-
- ``self.component(name)``: Get a component by name (e.g., "arm_L0")
639-
- ``self.components_by_type(type)``: Get all components of a specific type
640-
- ``self.custom_step(name)``: Access previously executed custom steps
641-
- ``self.run_sub_step(module_name, step_path)``: Execute nested steps
642-
- ``self.get_or_create_setup_root()``: Create an organization group for step objects
858+
- **Modularity**: Break complex setups into focused, single-purpose steps
859+
- **Reusability**: Share common operations across multiple rigs
860+
- **Maintainability**: Update individual sub-steps without modifying the main step
861+
- **Testing**: Test sub-steps independently before integrating
862+
- **Team Collaboration**: Different team members can work on different sub-steps
643863

644-
**Step Dictionary:**
864+
Step Dictionary
865+
^^^^^^^^^^^^^^^
645866

646867
All steps share a common dictionary (``customStepDic``) that enables inter-step communication:
647868

648-
- Each executed step is stored in this dictionary
649-
- Steps can access data set by previous steps
869+
- Each executed step is stored in this dictionary using its name as the key
870+
- Steps can access data set by previous steps via ``self.custom_step(name)``
871+
- Sub-steps are automatically registered in this dictionary
650872
- Use this for passing complex data between steps
651873

652874
.. _custom-step-templates:

0 commit comments

Comments
 (0)