mujoco-toolbox 0.1.8__tar.gz

mujoco_toolbox-0.1.8/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Michael Gross
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

mujoco_toolbox-0.1.8/PKG-INFO

@@ -0,0 +1,186 @@
+Metadata-Version: 2.3
+Name: mujoco-toolbox
+Version: 0.1.8
+Summary: A modern package to handle MuJoCo environments
+License: MIT
+Keywords: MuJoCo,robotics,simulation,toolbox,wrapper
+Author: MGross21
+Author-email: MGross21@TODO.com
+Requires-Python: >=3.10
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Topic :: Software Development :: Libraries
+Provides-Extra: dev
+Requires-Dist: ffmpeg
+Requires-Dist: ipywidgets
+Requires-Dist: matplotlib
+Requires-Dist: mediapy
+Requires-Dist: mujoco
+Requires-Dist: mypy ; extra == "dev"
+Requires-Dist: numpy
+Requires-Dist: pytest ; extra == "dev"
+Requires-Dist: pyyaml
+Requires-Dist: ruff ; extra == "dev"
+Requires-Dist: scipy
+Requires-Dist: screeninfo
+Requires-Dist: tqdm
+Requires-Dist: trimesh
+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: bug-tracker, https://github.com/MGross21/mujoco-toolbox/issues
+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)
+
+# Mujoco Toolbox
+
+Streamlines the MuJoCo Physics Simulator
+
+## PyPI Package
+
+```bash
+pip install -U mujoco-toolbox
+```
+
+## For Local Install
+
+*Navigate to the Directory that you wish to place the package*
+
+<details>
+<summary><b>JUPYTER NOTEBOOK</b></summary>
+</br>
+*Place Commands Inside Cell*
+
+One-Time Install:
+
+```python
+!git clone https://github.com/MGross21/mujoco-toolbox
+!pip install -U ./mujoco-toolbox
+```
+
+Check for Updates:
+
+```python
+!git pull origin main
+```
+
+Install/Check for Updates:
+
+```python
+folder = "mujoco-toolbox"
+repo_url = f"https://github.com/MGross21/{folder}"
+
+!if [ -d "{folder}" ]; then cd {folder} && git pull && cd ..; else git clone {repo_url}; fi
+!pip install -U ./{folder}
+```
+
+</details>
+</br>
+
+<details>
+<summary><b>BASH WINDOW</b></summary>
+</br>
+One-Time Install:
+
+```bash
+git clone https://github.com/MGross21/mujoco-toolbox
+pip install -U ./mujoco-toolbox
+```
+
+Check for Updates:
+```bash
+git pull origin main
+```
+
+Install/Check for Updates:
+
+```bash
+REPO_DIR="mujoco-toolbox"
+REPO_URL="https://github.com/MGross21/mujoco-toolbox"
+
+if [ -d "$REPO_DIR" ]; then
+  cd "$REPO_DIR" && git fetch origin && git pull origin main
+else
+  git clone $REPO_URL
+  cd "$REPO_DIR"
+fi
+
+pip install -U ./mujoco-toolbox
+```
+
+</details>
+
+## Extra Packages
+
+<details>
+<summary><b>FFMPEG</b></summary>
+
+</br>
+
+*Required for [mediapy](https://google.github.io/mediapy/mediapy.html) dependency*
+
+**Windows**
+
+```bash
+winget install ffmpeg
+ffmpeg -version
+```
+
+**Linux**
+
+```bash
+sudo apt update && sudo apt install ffmpeg
+ffmpeg -version
+```
+
+**MacOS**
+
+*Using Homebrew*
+
+```bash
+brew install ffmpeg
+ffmpeg -version
+```
+
+*Using MacPorts*
+
+```bash
+sudo port install ffmpeg
+ffmpeg -version
+```
+
+</details>
+
+## To Run in Scripts
+
+```python
+import mujoco_toolbox as mjtb
+from mujoco_toolbox import Wrapper
+
+# 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
+Wrapper("path/to/your/xml").runSim(render=True).renderMedia()
+```
+
+## Pre-Made Controllers
+
+```python
+import mujoco_toolbox as mjtb
+
+mjtb.sineController(m,d,**kwargs)
+mjtb.cosineController(m,d,**kwargs)
+mjtb.stepController(m,d,**kwargs)
+mjtb.randomController(m,d,**kwargs)
+
+# Wrapper can use custom controllers as well!
+```
+

mujoco_toolbox-0.1.8/README.md

@@ -0,0 +1,150 @@
+![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)
+
+# Mujoco Toolbox
+
+Streamlines the MuJoCo Physics Simulator
+
+## PyPI Package
+
+```bash
+pip install -U mujoco-toolbox
+```
+
+## For Local Install
+
+*Navigate to the Directory that you wish to place the package*
+
+<details>
+<summary><b>JUPYTER NOTEBOOK</b></summary>
+</br>
+*Place Commands Inside Cell*
+
+One-Time Install:
+
+```python
+!git clone https://github.com/MGross21/mujoco-toolbox
+!pip install -U ./mujoco-toolbox
+```
+
+Check for Updates:
+
+```python
+!git pull origin main
+```
+
+Install/Check for Updates:
+
+```python
+folder = "mujoco-toolbox"
+repo_url = f"https://github.com/MGross21/{folder}"
+
+!if [ -d "{folder}" ]; then cd {folder} && git pull && cd ..; else git clone {repo_url}; fi
+!pip install -U ./{folder}
+```
+
+</details>
+</br>
+
+<details>
+<summary><b>BASH WINDOW</b></summary>
+</br>
+One-Time Install:
+
+```bash
+git clone https://github.com/MGross21/mujoco-toolbox
+pip install -U ./mujoco-toolbox
+```
+
+Check for Updates:
+```bash
+git pull origin main
+```
+
+Install/Check for Updates:
+
+```bash
+REPO_DIR="mujoco-toolbox"
+REPO_URL="https://github.com/MGross21/mujoco-toolbox"
+
+if [ -d "$REPO_DIR" ]; then
+  cd "$REPO_DIR" && git fetch origin && git pull origin main
+else
+  git clone $REPO_URL
+  cd "$REPO_DIR"
+fi
+
+pip install -U ./mujoco-toolbox
+```
+
+</details>
+
+## Extra Packages
+
+<details>
+<summary><b>FFMPEG</b></summary>
+
+</br>
+
+*Required for [mediapy](https://google.github.io/mediapy/mediapy.html) dependency*
+
+**Windows**
+
+```bash
+winget install ffmpeg
+ffmpeg -version
+```
+
+**Linux**
+
+```bash
+sudo apt update && sudo apt install ffmpeg
+ffmpeg -version
+```
+
+**MacOS**
+
+*Using Homebrew*
+
+```bash
+brew install ffmpeg
+ffmpeg -version
+```
+
+*Using MacPorts*
+
+```bash
+sudo port install ffmpeg
+ffmpeg -version
+```
+
+</details>
+
+## To Run in Scripts
+
+```python
+import mujoco_toolbox as mjtb
+from mujoco_toolbox import Wrapper
+
+# 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
+Wrapper("path/to/your/xml").runSim(render=True).renderMedia()
+```
+
+## Pre-Made Controllers
+
+```python
+import mujoco_toolbox as mjtb
+
+mjtb.sineController(m,d,**kwargs)
+mjtb.cosineController(m,d,**kwargs)
+mjtb.stepController(m,d,**kwargs)
+mjtb.randomController(m,d,**kwargs)
+
+# Wrapper can use custom controllers as well!
+```

mujoco_toolbox-0.1.8/mujoco_toolbox/Controller.py

@@ -0,0 +1,131 @@
+from numpy import cos, pi, random, sin
+
+
+def _apply_control(model, data, value, joint=None, axis=None, delay=0):
+    """Common helper function for controller logic to reduce redundancy.
+
+    Args:
+        model: MuJoCo model.
+        data: MuJoCo data.
+        value: Control value to apply.
+        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:
+        return
+
+    # Determine targets if not explicitly provided
+    if joint is None and axis is None:
+        joint = range(model.nu)
+
+    # Apply control to joints or specific axis
+    if joint is not None and model.nu > 0:
+        for j in joint:
+            data.ctrl[j] = value
+    elif axis is not None:
+        data.qpos[axis] = value
+
+
+def stepController(model, data, **kwargs):
+    """A step controller for the simulation.
+
+    Args:
+        amplitude (float): The amplitude of the step signal (default=1).
+        joint (list[int]): The joints to apply the step signal to (default=all).
+        axis (int): The axis to apply the step signal to (default=None).
+        delay (float): The delay before applying the step signal (default=0).
+
+    Returns:
+        None
+    """
+    amplitude = kwargs.get("amplitude", 1)
+    joint = kwargs.get("joint", None)
+    axis = kwargs.get("axis", None)
+    delay = kwargs.get("delay", 0)
+
+    if delay < 0:
+        raise ValueError("Delay must be non-negative.")
+    if joint is not None and axis is not None:
+        raise ValueError("Cannot specify both 'joint' and 'axis'.")
+
+    _apply_control(model, data, amplitude, joint=joint, axis=axis, delay=delay)
+
+
+def sineController(model, data, **kwargs):
+    """A simple sine wave controller for the simulation.
+
+    Args:
+        amplitude (float): The amplitude of the sine wave (default=1).
+        frequency (float): The frequency of the sine wave (default=1).
+        phase (float): The phase shift of the sine wave (default=0).
+        joint (list[int]): The joint to apply the sine wave to (default=all).
+        delay (float): The delay before applying the sine wave (default=0).
+
+    Returns:
+        None
+    """
+    amplitude = kwargs.get("amplitude", 1)
+    frequency = kwargs.get("frequency", 1)
+    phase = kwargs.get("phase", 0)
+    joint = kwargs.get("joint", None)
+    delay = kwargs.get("delay", 0)
+
+    if delay < 0:
+        raise ValueError("Delay must be non-negative.")
+
+    value = amplitude * sin(2 * pi * frequency * data.time + phase)
+    _apply_control(model, data, value, joint=joint, delay=delay)
+
+
+def cosineController(model, data, **kwargs):
+    """A simple cosine wave controller for the simulation.
+
+    Args:
+        amplitude (float): The amplitude of the cosine wave (default=1).
+        frequency (float): The frequency of the cosine wave (default=1).
+        phase (float): The phase shift of the cosine wave (default=0).
+        joint (list[int]): The joint to apply the cosine wave to (default=all).
+        delay (float): The delay before applying the cosine wave (default=0).
+
+    Returns:
+        None
+    """
+    amplitude = kwargs.get("amplitude", 1)
+    frequency = kwargs.get("frequency", 1)
+    phase = kwargs.get("phase", 0)
+    joint = kwargs.get("joint", None)
+    delay = kwargs.get("delay", 0)
+
+    if delay < 0:
+        raise ValueError("Delay must be non-negative.")
+
+    value = amplitude * cos(2 * pi * frequency * data.time + phase)
+    _apply_control(model, data, value, joint=joint, delay=delay)
+
+
+def randomController(model, data, **kwargs):
+    """A random controller for the simulation.
+
+    Args:
+        amplitude (float): The maximum amplitude of the random signal (default=1).
+        joint (list[int]): The joints to apply the random signal to (default=all).
+        axis (int): The axis to apply the random signal to (default=None).
+        delay (float): The delay before applying the random signal (default=0).
+
+    Returns:
+        None
+    """
+    amplitude = kwargs.get("amplitude", 1)
+    joint = kwargs.get("joint", None)
+    axis = kwargs.get("axis", None)
+    delay = kwargs.get("delay", 0)
+
+    if delay < 0:
+        raise ValueError("Delay must be non-negative.")
+    if joint is not None and axis is not None:
+        raise ValueError("Cannot specify both 'joint' and 'axis'.")
+
+    value = amplitude * random.rand()
+    _apply_control(model, data, value, joint=joint, axis=axis, delay=delay)

mujoco_toolbox-0.1.8/mujoco_toolbox/Utils.py

@@ -0,0 +1,53 @@
+from functools import wraps
+from sys import platform
+from time import time
+
+
+def timer(func):
+    @wraps(func)
+    def time_wrapper(*args, **kwargs):
+        start_time = time()
+        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")
+        return result
+
+    return time_wrapper
+
+
+def print_warning(*args) -> None:
+    """
+    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:
+        # Make sure the first argument is printed with the 'WARNING:' prefix and in orange
+        message = f"WARNING: {args[0]}"
+
+        # Check if we're on Windows or a Unix-like system for color support
+        if platform.startswith("win"):
+            try:
+                from colorama import Fore, Style, init
+
+                init()  # Initialize colorama
+                print(
+                    f"{Fore.YELLOW}{message}{Style.RESET_ALL}", end=" "
+                )  # Yellow color for warning
+                print(
+                    *args[1:], end=""
+                )  # No newline, print all args separated by spaces
+            except ImportError:
+                # If colorama is not available, print without color
+                print(message, end=" ")
+                print(*args[1:], end="")
+        else:
+            # ANSI escape code for orange (for Unix-like systems)
+            print(f"\033[38;5;214m{message}\033[0m", end=" ")  # Orange ANSI escape code
+            print(*args[1:], end="")  # No newline, print all args separated by spaces