mujoco-toolbox 0.2.0__tar.gz → 0.3.0__tar.gz

{mujoco_toolbox-0.2.0 → mujoco_toolbox-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: mujoco-toolbox
-Version: 0.2.0
+Version: 0.3.0
 Summary: A modern package to handle MuJoCo environments
 License: MIT
 Keywords: MuJoCo,robotics,simulation,toolbox,wrapper
@@ -10,11 +10,7 @@ Requires-Python: >=3.10
 Classifier: Development Status :: 3 - Alpha
 Classifier: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
-Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.10
-Classifier: Programming Language :: Python :: 3.11
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
 Classifier: Topic :: Software Development :: Libraries
 Requires-Dist: colorama
 Requires-Dist: ffmpeg
@@ -29,15 +25,16 @@ Requires-Dist: screeninfo
 Requires-Dist: tqdm
 Requires-Dist: trimesh
 Project-URL: Bug Tracker, https://github.com/MGross21/mujoco-toolbox/issues
-Project-URL: documentation, https://github.com/MGross21/mujoco-toolbox
-Project-URL: homepage, https://github.com/MGross21/mujoco-toolbox
-Project-URL: repository, https://github.com/MGross21/mujoco-toolbox
+Project-URL: Documentation, https://github.com/MGross21/mujoco-toolbox
+Project-URL: Homepage, https://github.com/MGross21/mujoco-toolbox
+Project-URL: Repository, https://github.com/MGross21/mujoco-toolbox
 Description-Content-Type: text/markdown
 
 ![Build](https://github.com/MGross21/mujoco-toolbox/actions/workflows/ci.yml/badge.svg)
 ![Python](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue)
 ![License](https://img.shields.io/github/license/MGross21/mujoco-toolbox)
 [![PyPI](https://github.com/MGross21/mujoco-toolbox/actions/workflows/publish.yml/badge.svg)](https://github.com/MGross21/mujoco-toolbox/actions/workflows/publish.yml)
+[![Docs](https://github.com/MGross21/mujoco-toolbox/actions/workflows/docs.yml/badge.svg)](https://github.com/MGross21/mujoco-toolbox/actions/workflows/docs.yml)
 
 # Mujoco Toolbox
 
@@ -96,28 +93,26 @@ ffmpeg -version
 
 </details>
 
-## To Run in Scripts
+## Example Script
+
+*Bare minimum to run MuJoCo simulation and display result*
 
 ```python
 import mujoco_toolbox as mjtb
 
-# Optional Global Variables
-mjtb.VERBOSITY = True # Additional Performance and Debugging Print Statements (Default=False)
-mjtb.CAPTURE_PARAMETERS = "all" # MjData Simulation Parameters (Default = ['time', 'qpos', 'qvel', 'act', 'qacc', 'xpos', 'xquat', 'xmat', 'ctrl', 'sensordata']) 
-
-# Example Code
-mjtb.Wrapper("path/to/your/xml").runSim(render=True).renderMedia()
+mjtb.Wrapper("path/to/your/xml").run(render=True).save()
 ```
 
 ## Pre-Made Controllers
 
 ```python
-from mujoco_toolbox import \
-sineController,\
-cosineController,\
-stepController,\
-randomController,\
-realTimeController
+from mujoco_toolbox.controller import (
+    cosine_controller,
+    random_controller,
+    live_controller,
+    sine_controller,
+    step_controller,
+)
 
 # Wrapper can use custom controllers as well!
 ```
@@ -131,3 +126,4 @@ realTimeController
 ### URDF
 
 ![UR5](assets/images/ur5_render_no_gui.png)
+

{mujoco_toolbox-0.2.0 → mujoco_toolbox-0.3.0}/README.md

@@ -2,6 +2,7 @@
 ![Python](https://img.shields.io/badge/python-3.10%20|%203.11%20|%203.12%20|%203.13-blue)
 ![License](https://img.shields.io/github/license/MGross21/mujoco-toolbox)
 [![PyPI](https://github.com/MGross21/mujoco-toolbox/actions/workflows/publish.yml/badge.svg)](https://github.com/MGross21/mujoco-toolbox/actions/workflows/publish.yml)
+[![Docs](https://github.com/MGross21/mujoco-toolbox/actions/workflows/docs.yml/badge.svg)](https://github.com/MGross21/mujoco-toolbox/actions/workflows/docs.yml)
 
 # Mujoco Toolbox
 
@@ -60,28 +61,26 @@ ffmpeg -version
 
 </details>
 
-## To Run in Scripts
+## Example Script
+
+*Bare minimum to run MuJoCo simulation and display result*
 
 ```python
 import mujoco_toolbox as mjtb
 
-# Optional Global Variables
-mjtb.VERBOSITY = True # Additional Performance and Debugging Print Statements (Default=False)
-mjtb.CAPTURE_PARAMETERS = "all" # MjData Simulation Parameters (Default = ['time', 'qpos', 'qvel', 'act', 'qacc', 'xpos', 'xquat', 'xmat', 'ctrl', 'sensordata']) 
-
-# Example Code
-mjtb.Wrapper("path/to/your/xml").runSim(render=True).renderMedia()
+mjtb.Wrapper("path/to/your/xml").run(render=True).save()
 ```
 
 ## Pre-Made Controllers
 
 ```python
-from mujoco_toolbox import \
-sineController,\
-cosineController,\
-stepController,\
-randomController,\
-realTimeController
+from mujoco_toolbox.controller import (
+    cosine_controller,
+    random_controller,
+    live_controller,
+    sine_controller,
+    step_controller,
+)
 
 # Wrapper can use custom controllers as well!
 ```
@@ -94,4 +93,4 @@ realTimeController
 
 ### URDF
 
-![UR5](assets/images/ur5_render_no_gui.png)
+![UR5](assets/images/ur5_render_no_gui.png)

mujoco_toolbox-0.3.0/mujoco_toolbox/__init__.py

@@ -0,0 +1,74 @@
+"""Mujoco Toolbox.
+==============
+A toolbox for working with MuJoCo simulations. This package provides various utilities and controllers to facilitate
+the simulation process.
+
+Modules:
+--------
+- `Wrapper`: Contains the Wrapper class for interfacing with MuJoCo.
+- `Controller`: Includes sineController, cosineController, and randomController for controlling simulations.
+- `Builder`: Contains the Builder class for creating and merging MuJoCo models.
+- `assets`: Contains pre-defined assets for building MuJoCo models.
+
+Constants:
+----------
+- CAPTURE_PARAMETERS: List of MjData fields to capture during simulation.
+
+Notes
+-----
+This package is still under development. Report any issues to https://github.com/MGross21/mujoco-toolbox/issues.
+
+"""
+
+from .assets import WORLD_ASSETS, glovebox
+from .builder import Builder
+from .controller import (
+    cosine_controller,
+    live_controller,
+    random_controller,
+    sine_controller,
+    step_controller,
+)
+from .utils import _Platform, print_warning
+from .wrapper import Wrapper
+
+__version__ = "0.3.0"
+__author__ = "Michael Gross"
+__github_repo__ = "mujoco-toolbox"
+__license__ = "MIT"
+__status__ = "Development"
+__all__ = [
+    "CAPTURE_PARAMETERS",
+    "COMPUTER",
+    "WORLD_ASSETS",
+    "Builder",
+    "Wrapper",
+    "cosine_controller",
+    "glovebox",
+    "live_controller",
+    "random_controller",
+    "sine_controller",
+    "step_controller",
+]
+
+COMPUTER = _Platform()  # Singleton Instance
+MAX_GEOM_SCALAR: int = 2  # Scalar value for mujoco.Renderer.max_geom
+CAPTURE_PARAMETERS = [  # MjData default fields to capture during simulation
+    "time",
+    "qpos",
+    "qvel",
+    "act",
+    "qacc",
+    "xpos",
+    "xquat",
+    "xmat",
+    "ctrl",
+    "sensordata",
+]
+
+if __version__.startswith("0"):
+    print_warning(
+        f"{__package__} (v{__version__}) is still under development.",
+        f"Report any issues to https://github.com/MGross21/{__github_repo__}/issues",
+    )
+del _Platform, print_warning

{mujoco_toolbox-0.2.0 → mujoco_toolbox-0.3.0}/mujoco_toolbox/assets.py

@@ -10,7 +10,7 @@ WORLD_ASSETS = """
   </asset>
 """
 
-def GloveBox(width=1.25, depth=0.75, height=1.0, glass_thickness=0.05):
+def glovebox(width=1.25, depth=0.75, height=1.0, glass_thickness=0.05) -> str:
     return f"""
 <mujoco>
     <asset>

{mujoco_toolbox-0.2.0 → mujoco_toolbox-0.3.0}/mujoco_toolbox/builder.py

@@ -3,14 +3,30 @@ import xml.etree.ElementTree as ET
 
 
 class Builder:
-    def __init__(self, xml_input: str):
-        """ Initialize with an XML string or a file path. Input is required."""
-        self.tree, self.root = self.load_model(xml_input)
+    def __init__(self, *args: str) -> None:
+        """Initialize with an XML string or a file path. Input is required."""
+        for arg in args:
+            if not isinstance(arg, str):
+                msg = "Input must be an XML string or a file path"
+                raise TypeError(msg)
+        if len(args) == 0:
+            msg = "Input is required to initialize the Builder"
+            raise ValueError(msg)
+        if len(args) > 1:
+            # Create a new Builder instance for each additional argument and merge them
+            self.tree, self.root = self.load_model(args[0])
+            for additional_arg in args[1:]:
+                additional_builder = Builder(additional_arg)
+                self.__add__(additional_builder)
+        else:
+            xml_input = args[0]
+            self.tree, self.root = self.load_model(xml_input)
 
     def load_model(self, xml_input):
-        """ Load a MuJoCo model from a file or XML string."""
+        """Load a MuJoCo model from a file or XML string."""
         if not isinstance(xml_input, str):
-            raise ValueError("Input must be either an XML string or a file path")
+            msg = "Input must be either an XML string or a file path"
+            raise ValueError(msg)
 
         # Check if input is an XML string
         if xml_input.strip().startswith("<"):
@@ -31,11 +47,13 @@ class Builder:
 
                 return tree, tree.getroot()
             except ET.ParseError:
-                raise ValueError("Invalid XML string provided")
+                msg = "Invalid XML string provided"
+                raise ValueError(msg)
         else:
             # Treat input as file path
             if not os.path.exists(xml_input):
-                raise FileNotFoundError(f"File not found: {xml_input}")
+                msg = f"File not found: {xml_input}"
+                raise FileNotFoundError(msg)
 
             # Handle URDF files
             if xml_input.lower().endswith(".urdf"):
@@ -54,11 +72,11 @@ class Builder:
 
                 return tree, tree.getroot()
             except ET.ParseError:
-                raise ValueError(f"Invalid XML file: {xml_input}")
+                msg = f"Invalid XML file: {xml_input}"
+                raise ValueError(msg)
 
     def wrap_urdf_in_mujoco(self, urdf_input):
-        """
-        Wrap a URDF inside <mujoco> tags for MuJoCo compatibility.
+        """Wrap a URDF inside <mujoco> tags for MuJoCo compatibility.
         Input can be a file path, ElementTree, or XML string.
         """
         # Handle string input (could be a file path or XML string)
@@ -69,18 +87,21 @@ class Builder:
                     root = ET.fromstring(urdf_input)
                     tree = ET.ElementTree(root)
                 except ET.ParseError:
-                    raise ValueError("Invalid URDF XML string provided")
+                    msg = "Invalid URDF XML string provided"
+                    raise ValueError(msg)
             else:
                 # It's a file path
                 try:
                     tree = ET.parse(urdf_input)
                 except:
-                    raise ValueError(f"Could not parse URDF file: {urdf_input}")
+                    msg = f"Could not parse URDF file: {urdf_input}"
+                    raise ValueError(msg)
         # Handle ElementTree input
         elif isinstance(urdf_input, ET.ElementTree):
             tree = urdf_input
         else:
-            raise TypeError("URDF input must be a string or ElementTree")
+            msg = "URDF input must be a string or ElementTree"
+            raise TypeError(msg)
 
         root = tree.getroot()
 
@@ -95,8 +116,8 @@ class Builder:
         # Create a new tree with the <mujoco> root
         return ET.ElementTree(mujoco_elem), mujoco_elem
 
-    def merge_tags(self, tag_name, root_1, root_2):
-        """ Merge a specific tag (e.g., worldbody, asset) from two models."""
+    def merge_tags(self, tag_name, root_1, root_2) -> None:
+        """Merge a specific tag (e.g., worldbody, asset) from two models."""
         section_1 = root_1.find(tag_name)
         section_2 = root_2.find(tag_name)
 
@@ -111,7 +132,7 @@ class Builder:
                 section_1.append(element)
 
     def __add__(self, other):
-        """ Implement the + operator for merging two models."""
+        """Implement the + operator for merging two models."""
         model_root = None
 
         if isinstance(other, Builder):
@@ -121,7 +142,8 @@ class Builder:
             # If the input is a string, load as XML
             _, model_root = self.load_model(other)
         else:
-            raise TypeError("Addition only supported between Builder objects or with XML strings/files")
+            msg = "Addition only supported between Builder objects or with XML strings/files"
+            raise TypeError(msg)
 
         # List of sections to merge
         sections_to_merge = ["asset", "worldbody", "camera", "light", "contact", "equality",
@@ -135,22 +157,24 @@ class Builder:
         return self
 
     def __radd__(self, other):
-        """ Implement the reverse + operator for merging two models."""
+        """Implement the reverse + operator for merging two models."""
         if other == 0:  # Handle sum() starting value
             return self
         return self.__add__(other)
 
-    def save(self, file_path):
-        """ Save the merged model to a file."""
+    def save(self, file_path) -> "os.path":
+        """Save the merged model to a file."""
         if self.tree is not None:
             # Format the XML with proper indentation before saving
             self._indent_xml(self.root)
             self.tree.write(file_path, encoding="utf-8", xml_declaration=True)
         else:
-            raise ValueError("No model loaded. Cannot save.")
+            msg = "No model loaded. Cannot save."
+            raise ValueError(msg)
+        return os.path.abspath(file_path)
 
-    def _indent_xml(self, elem, level=0):
-        """ Add proper indentation to make the XML file more readable."""
+    def _indent_xml(self, elem, level=0) -> None:
+        """Add proper indentation to make the XML file more readable."""
         i = "\n" + level * "  "
         if len(elem):
             if not elem.text or not elem.text.strip():
@@ -161,24 +185,27 @@ class Builder:
                 self._indent_xml(sub_elem, level + 1)
             if not elem[-1].tail or not elem[-1].tail.strip():
                 elem[-1].tail = i
-        else:
-            if level and (not elem.tail or not elem.tail.strip()):
-                elem.tail = i
+        elif level and (not elem.tail or not elem.tail.strip()):
+            elem.tail = i
 
-    def __str__(self):
-        """ Return the XML string of the model."""
+    def __str__(self) -> str:
+        """Return the XML string of the model."""
         if self.tree is not None:
             # Format the XML with proper indentation
             self._indent_xml(self.root)
             return ET.tostring(self.root, encoding="unicode", method="xml")
-        else:
-            raise ValueError("No model loaded. Cannot generate string.")
+        msg = "No model loaded. Cannot generate string."
+        raise ValueError(msg)
 
-    def __repr__(self):
-        """ Return the XML string of the model."""
+    def __repr__(self) -> str:
+        """Return the XML string of the model."""
         return self.__str__()
 
+    def __len__(self) -> int:
+        """Return the number of elements in the model."""
+        return len(self.root) if self.root is not None else 0
+
     @property
     def xml(self):
-        """ Property to quickly grab the XML string of the model."""
+        """Property to quickly grab the XML string of the model."""
         return str(self)

mujoco_toolbox-0.2.0/mujoco_toolbox/Controller.py → mujoco_toolbox-0.3.0/mujoco_toolbox/controller.py

@@ -1,7 +1,7 @@
 from numpy import cos, pi, random, sin
 
 
-def _apply_control(model, data, value, joint=None, axis=None, delay=0):
+def _apply_control(model, data, value, joint=None, axis=None, delay=0) -> None:
     """Common helper function for controller logic to reduce redundancy.
 
     Args:
@@ -11,6 +11,7 @@ def _apply_control(model, data, value, joint=None, axis=None, delay=0):
         joint (list[int], optional): Joints to apply control to.
         axis (int, optional): Axis to apply control to.
         delay (float, optional): Delay before applying control.
+
     """
     # Don't apply control until after delay
     if data.time < delay:
@@ -28,7 +29,7 @@ def _apply_control(model, data, value, joint=None, axis=None, delay=0):
         data.qpos[axis] = value
 
 
-def stepController(model, data, **kwargs):
+def step_controller(model, data, **kwargs) -> None:
     """A step controller for the simulation.
 
     Args:
@@ -39,21 +40,24 @@ def stepController(model, data, **kwargs):
 
     Returns:
         None
+
     """
     amplitude = kwargs.get("amplitude", 1)
-    joint = kwargs.get("joint", None)
-    axis = kwargs.get("axis", None)
+    joint = kwargs.get("joint")
+    axis = kwargs.get("axis")
     delay = kwargs.get("delay", 0)
 
     if delay < 0:
-        raise ValueError("Delay must be non-negative.")
+        msg = "Delay must be non-negative."
+        raise ValueError(msg)
     if joint is not None and axis is not None:
-        raise ValueError("Cannot specify both 'joint' and 'axis'.")
+        msg = "Cannot specify both 'joint' and 'axis'."
+        raise ValueError(msg)
 
     _apply_control(model, data, amplitude, joint=joint, axis=axis, delay=delay)
 
 
-def sineController(model, data, **kwargs):
+def sine_controller(model, data, **kwargs) -> None:
     """A simple sine wave controller for the simulation.
 
     Args:
@@ -65,21 +69,23 @@ def sineController(model, data, **kwargs):
 
     Returns:
         None
+
     """
     amplitude = kwargs.get("amplitude", 1)
     frequency = kwargs.get("frequency", 1)
     phase = kwargs.get("phase", 0)
-    joint = kwargs.get("joint", None)
+    joint = kwargs.get("joint")
     delay = kwargs.get("delay", 0)
 
     if delay < 0:
-        raise ValueError("Delay must be non-negative.")
+        msg = "Delay must be non-negative."
+        raise ValueError(msg)
 
     value = amplitude * sin(2 * pi * frequency * data.time + phase)
     _apply_control(model, data, value, joint=joint, delay=delay)
 
 
-def cosineController(model, data, **kwargs):
+def cosine_controller(model, data, **kwargs) -> None:
     """A simple cosine wave controller for the simulation.
 
     Args:
@@ -91,21 +97,23 @@ def cosineController(model, data, **kwargs):
 
     Returns:
         None
+
     """
     amplitude = kwargs.get("amplitude", 1)
     frequency = kwargs.get("frequency", 1)
     phase = kwargs.get("phase", 0)
-    joint = kwargs.get("joint", None)
+    joint = kwargs.get("joint")
     delay = kwargs.get("delay", 0)
 
     if delay < 0:
-        raise ValueError("Delay must be non-negative.")
+        msg = "Delay must be non-negative."
+        raise ValueError(msg)
 
     value = amplitude * cos(2 * pi * frequency * data.time + phase)
     _apply_control(model, data, value, joint=joint, delay=delay)
 
 
-def randomController(model, data, **kwargs):
+def random_controller(model, data, **kwargs) -> None:
     """A random controller for the simulation.
 
     Args:
@@ -116,21 +124,24 @@ def randomController(model, data, **kwargs):
 
     Returns:
         None
+
     """
     amplitude = kwargs.get("amplitude", 1)
-    joint = kwargs.get("joint", None)
-    axis = kwargs.get("axis", None)
+    joint = kwargs.get("joint")
+    axis = kwargs.get("axis")
     delay = kwargs.get("delay", 0)
 
     if delay < 0:
-        raise ValueError("Delay must be non-negative.")
+        msg = "Delay must be non-negative."
+        raise ValueError(msg)
     if joint is not None and axis is not None:
-        raise ValueError("Cannot specify both 'joint' and 'axis'.")
+        msg = "Cannot specify both 'joint' and 'axis'."
+        raise ValueError(msg)
 
     value = amplitude * random.rand()
     _apply_control(model, data, value, joint=joint, axis=axis, delay=delay)
 
-def realTimeController(model, data, **kwargs):
+def live_controller(model, data, **kwargs) -> None:
     """A real-time controller for the simulation.
 
     Args:
@@ -138,8 +149,9 @@ def realTimeController(model, data, **kwargs):
 
     Returns:
         None
+
     """
-    from .Utils import print_warning
+    from .utils import print_warning
     for key, value in kwargs.get("controller_params", {}).items():
         if hasattr(data, key):
             setattr(data, key, value)
@@ -150,4 +162,3 @@ def realTimeController(model, data, **kwargs):
     # if hasattr(data, 'control'):
     #     data.control = kwargs.get("control", data.control)
 
-    return

mujoco_toolbox-0.2.0/mujoco_toolbox/Utils.py → mujoco_toolbox-0.3.0/mujoco_toolbox/utils.py

@@ -15,21 +15,17 @@ def timer(func):
         result = func(*args, **kwargs)
         end_time = time()
         total_time = end_time - start_time
-
-        from . import VERBOSITY
-
-        if VERBOSITY:
-            print(f"Function '{func.__name__}' took {total_time:.4f} seconds")
+        print(f"Function {func.__name__} took {total_time:.4f} seconds to execute")
         return result
 
     return time_wrapper
 
 def print_warning(*args, prefix: bool = True) -> None:
-    """
-    Prints the first argument as an orange warning message and prints the other arguments in regular text, all on the same line.
+    """Prints the first argument as an orange warning message and prints the other arguments in regular text, all on the same line.
 
     Args:
         *args: First argument is printed as an orange warning, other arguments are printed normally.
+
     """
     if args:
         if prefix:
@@ -54,11 +50,11 @@ def print_warning(*args, prefix: bool = True) -> None:
             print(*args[1:])
 
 def print_success(*args, prefix: bool = True) -> None:
-    """
-    Prints the first argument as a green success message and prints the other arguments in regular text, all on the same line.
+    """Prints the first argument as a green success message and prints the other arguments in regular text, all on the same line.
 
     Args:
         *args: First argument is printed as a green success message, other arguments are printed normally.
+
     """
     if args:
         if prefix:
@@ -83,7 +79,7 @@ def print_success(*args, prefix: bool = True) -> None:
             print(*args[1:])
 
 class _Platform:
-    def __init__(self):
+    def __init__(self) -> None:
         self.OS = platform.system()
         self.PROCESSOR = platform.processor()
         self.MACHINE = platform.machine()
@@ -95,25 +91,25 @@ class _Platform:
         self.RESOLUTION, self.GUI_ENABLED = self.get_resolution()
         # self.NUM_MONITORS = get_monitors().__len__()
 
-    def __repr__(self):
+    def __repr__(self) -> str:
         return (
             f"Operating System: {self.OS}\n"
+            f"Architecture: {self.ARCHITECTURE}\n"
             f"Processor: {self.PROCESSOR}\n"
             f"Machine Type: {self.MACHINE}\n"
+            f"CPU Count: {self.CPU_COUNT}\n"
             f"Python Version: {self.PYTHON_VERSION}\n"
             f"IDE: {self.IDE}\n"
-            f"CPU Count: {self.CPU_COUNT}\n"
-            f"Architecture: {self.ARCHITECTURE}\n"
             f"Python Implementation: {self.PYTHON_IMPLEMENTATION}\n"
             f"Resolution (disp0): {self.RESOLUTION}\n"
             f"GUI Enabled: {self.GUI_ENABLED}"
         )
 
-    def __str__(self):
+    def __str__(self) -> str:
         return self.__repr__()
 
     @staticmethod
-    def get_developer_mode():
+    def get_developer_mode() -> str:
         if "ipykernel" in sys.modules and not sys.stdin.isatty():
             return "jupyter"
         return "terminal" if hasattr(sys, "ps1") else "script"