|
1 | 1 | Shifter User Documentation |
2 | 2 | ########################## |
3 | 3 |
|
4 | | -WIP section: Please visit: |
| 4 | +Please visit: |
5 | 5 | `mGear Youtube channel <https://www.youtube.com/c/mgearriggingframework/>`_ |
6 | 6 |
|
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 | | - |
15 | 7 | .. _shifter-guide-manager: |
16 | 8 |
|
17 | 9 | Shifter Guide Manager |
@@ -631,22 +623,252 @@ Custom steps are Python classes that inherit from ``customShifterMainStep``: |
631 | 623 | # Create organization group for custom objects |
632 | 624 | setup_root = self.get_or_create_setup_root() |
633 | 625 |
|
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:** |
635 | 857 |
|
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 |
643 | 863 |
|
644 | | -**Step Dictionary:** |
| 864 | +Step Dictionary |
| 865 | +^^^^^^^^^^^^^^^ |
645 | 866 |
|
646 | 867 | All steps share a common dictionary (``customStepDic``) that enables inter-step communication: |
647 | 868 |
|
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 |
650 | 872 | - Use this for passing complex data between steps |
651 | 873 |
|
652 | 874 | .. _custom-step-templates: |
|
0 commit comments