mujoco-mojo 2.2.3__tar.gz → 2.3.0__tar.gz

{mujoco_mojo-2.2.3 → mujoco_mojo-2.3.0}/.github/workflows/docs.yml

@@ -24,7 +24,7 @@ jobs:
       - name: Install Python 3.13
         run: uv python install 3.13
       - name: Generate API reference pages
-        run: uv run --python 3.13 --group dev python mujoco-mojo/scripts/gen_ref_pages.py
+        run: uv run --python 3.13 --group dev python scripts/gen_ref_pages.py
       - run: uv run --python 3.13 --group dev zensical build --clean
       - uses: actions/upload-pages-artifact@v4
         with:

{mujoco_mojo-2.2.3 → mujoco_mojo-2.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: mujoco-mojo
-Version: 2.2.3
+Version: 2.3.0
 Summary: A complete MJCF lifecycle and trial orchestration suite for MuJoCo, powered by Pydantic v2.
 Project-URL: Homepage, https://github.com/Hydrowelder/mujoco-mojo
 Project-URL: Documentation, https://hydrowelder.github.io/mujoco-mojo/

{mujoco_mojo-2.2.3 → mujoco_mojo-2.3.0}/docs/user-guides/dojo.md

@@ -78,5 +78,18 @@ Dojo is split into two primary environments depending on your current needs:
 
 ---
 
+## Plot Notes
+
+The trial viewer supports freeform notes anchored to specific points on a plot.
+
+- **Add a note:** Middle-click anywhere on the plot area. The Notes panel opens with the cursor's data coordinates pre-filled.
+- **Edit or delete:** Open the Notes panel (the speech-bubble icon in the sidebar) and use the edit/delete controls next to each note.
+- **Jump to a note:** Click the note's coordinates in the list to zoom the plot to that location.
+- **Close the panel:** Left-click anywhere outside the Notes panel, or press ++esc++.
+
+Notes are persisted in the trial's saved configuration and are included when sharing a view via the share URL.
+
+---
+
 !!! success
     Dojo is now live! Now that you have the interface running, move on to the **Monitor** tool to learn how to track your job's progress in real-time.

{mujoco_mojo-2.2.3 → mujoco_mojo-2.3.0}/docs/user-guides/getting-started.md

@@ -283,23 +283,23 @@ MuJoCo does not currently ship first-party Python typing stubs. To enable proper
 
 > Thanks to the work by [@kevinzakka](https://github.com/google-deepmind/mujoco/issues/1292#issuecomment-1874138201) and [@mluogh-xdof](https://github.com/google-deepmind/mujoco/issues/1292#issuecomment-3208219200) for figuring all this out!
 
-1. In your terminal:
+1. From your project root, generate stubs into a local `typings/` directory:
 
     ```bash linenums="0"
-    pybind11-stubgen mujoco -o ~/typings/ --numpy-array-wrap-with-annotated
+    pybind11-stubgen mujoco -o typings/ --numpy-array-wrap-with-annotated
     ```
 
 2. Recent MuJoCo builds compiled with newer pybind11 versions correctly expose enums as `SupportsInt`. If you encounter Pyright enum type errors, apply the compatibility patch:
 
     ```bash linenums="0"
-    python ~/typings/patch_mujoco_enums.py ~/typings/mujoco/_enums.pyi
+    python typings/patch_mujoco_enums.py typings/mujoco/_enums.pyi
     ```
 
 3. Then in `pyproject.toml` (for me, VSCode already type hints correctly, but this should fix things if you use `pyright` with your pre-commit hooks):
 
     ```toml title="pyproject.toml"
     [tool.pyright]
-    stubPath = "~/typings"
+    stubPath = "typings"
     venvPath = "."
     venv = ".venv"
     ```
@@ -307,7 +307,7 @@ MuJoCo does not currently ship first-party Python typing stubs. To enable proper
 ---
 
 !!! tip "Tip: Scaffold a New Project"
-    Before diving into the generate script, run `mujoco-mojo init` in a new directory to get a working project skeleton — `simulation.py`, `run.sh`, and `reloaded.sh` — pre-wired and ready to edit.
+    Before diving into the generate script, run `mujoco-mojo init` in a new directory to get a working project skeleton (`simulation.py`, `run.sh`, and `reloaded.sh`) pre-wired and ready to edit.
 
     ```bash linenums="0"
     mujoco-mojo init

{mujoco_mojo-2.2.3 → mujoco_mojo-2.3.0}/docs/user-guides/mosaic.md

@@ -58,7 +58,7 @@ Adjust the visual style. Switch between Lines, Markers, or both. Change interpol
 
 ### Notes Editor
 
-Click anywhere on the plot to drop a persistent note. These are saved into the JSON config and help you flag specific events (like "Impact Start" or "Sensor Saturation"). The editor allows you to go back and edit the note's label. Typos happen!
+**Middle-click** anywhere on the plot to drop a persistent note at the exact data coordinates of your cursor. Notes are saved into the JSON config and help you flag specific events (like "Impact Start" or "Sensor Saturation"). The editor allows you to go back and edit the note's label. Press ++esc++ to cancel an in-progress note or close the panel.
 
 ???+ tip "Tip: Clickable Buttons"
     You can click on a note in the editor to "focus" on the note!
@@ -71,18 +71,38 @@ Click anywhere on the plot to drop a persistent note. These are saved into the J
 
 ### Shapes Editor
 
-Add various shapes to the plot. After selecting an option in the menu, your mouse becomes a placement tool. Clicking on the plot configures the placement of the shape.
+Add various shapes to the plot. After selecting an option in the menu, your mouse becomes a placement tool. Clicking on the plot configures the placement of the shape. Press ++esc++ at any time to cancel placement.
 
 - **V-Line:** Draws a vertical line on the plot. The abscissa of the mouse determines the abscissa of the line.
 - **H-Line:** Draws a horizontal line on the plot. The ordinate of the mouse determines the ordinate of the line.
 - **Rect:** Draws a rectangle on the plot. The abscissa and ordinate of the mouse determines one of the corners of the rectangle. Likewise, the second click determines the other corner.
 
+Each new shape is automatically assigned the next color in the preset palette so overlapping shapes remain visually distinct. The shape editor includes a full color picker (identical to the signal color picker) for precise color control.
+
 <figure align="center">
     <img src="../../assets/user-guides/light-shapes-editor.jpg#only-light" alt="Shapes editor menu" style="width: 60%; height: auto;">
     <img src="../../assets/user-guides/dark-shapes-editor.jpg#only-dark" alt="Shapes editor menu" style="width: 60%; height: auto;">
     <figcaption>The menu for <b>shapes editor</b> is active and in editing mode. A shape's label and color is being edited. The plot area shows a vertical (yellow) and horizontal (red) line and a rectangle (purple).</figcaption>
 </figure>
 
+### Saved Profiles
+
+Profiles save your complete plot configuration (selected signals, axes, display settings, zoom, annotations, and shapes) under a named key so you can restore a view instantly.
+
+Profiles are stored globally in `~/.mujoco-mojo/profiles/` and are available across all workdirs, making it easy to share a standard analysis setup between projects.
+
+**Creating a profile**
+
+Type a name in the save box and press **Save** or ++enter++. To organize profiles into folders use a `folder/name` path, for example `arm-reach/baseline`. Folders are created automatically and the input field offers Tab-completion for existing folder names.
+
+**Loading a profile**
+
+Click **Load** next to any profile in the list. If the profile references signals, axes, or reference frames that do not exist in the current trial it will be rejected with an error toast rather than silently applying an invalid configuration. Profiles that are incompatible with the current trial are marked with a warning icon in the list.
+
+**Searching profiles**
+
+A search box filters the profile list by name (including folder path) as you type.
+
 ### Undo/Redo
 
 Every change to the plot configuration is tracked. Use the standard shortcuts (++ctrl+z++ / ++ctrl+y++ or ++cmd+z++ / ++cmd+shift+z++) to step through your edits.

{mujoco_mojo-2.2.3 → mujoco_mojo-2.3.0}/docs/user-guides/runtime-script.md

@@ -49,7 +49,7 @@ Mojo provides high-level force abstractions like `PointToPointForce`, which auto
 
         ---
 
-        **6-DOF force and torque**. The "multi-tool" of loads—defines full spatial dynamics in either a relative frame or local to a site.
+        **6-DOF force and torque**. Defines full spatial dynamics in either a relative frame or local to a site.
 
         > Think of it as a `VectorForce` and `VectorTorque` combined into one robust plugin.
 

{mujoco_mojo-2.2.3 → mujoco_mojo-2.3.0}/mkdocs.yml

@@ -29,9 +29,7 @@ nav:
       - Optimization: user-guides/optimization.md
       - Reloaded: user-guides/reloaded.md
   - Code Reference:
-      - reference/index.md
       - mujoco_mojo:
-          - reference/mujoco_mojo/index.md
           - MojoModel: reference/mujoco_mojo/mojo_model.md
           - Base: reference/mujoco_mojo/base.md
           - Visualization: reference/mujoco_mojo/visualization.md

{mujoco_mojo-2.2.3 → mujoco_mojo-2.3.0}/scripts/gen_ref_pages.py

@@ -19,8 +19,6 @@ DOCS_REF = ROOT / "docs" / "reference"
 # Modules to document: (dotted identifier, output path relative to DOCS_REF)
 # ---------------------------------------------------------------------------
 MODULES: list[tuple[str, str]] = [
-    # top-level package
-    ("mujoco_mojo", "mujoco_mojo/index.md"),
     ("mujoco_mojo.mojo_model", "mujoco_mojo/mojo_model.md"),
     ("mujoco_mojo.base", "mujoco_mojo/base.md"),
     ("mujoco_mojo.visualization", "mujoco_mojo/visualization.md"),

mujoco_mojo-2.3.0/scripts/gen_ts_models.py

@@ -0,0 +1,176 @@
+"""
+Generate TypeScript types from Pydantic models in plot_config.py.
+
+Run from the repo root:
+
+    python scripts/gen_ts_models.py
+
+Writes:
+    src/mujoco_mojo/utils/layers/dojo/templates/static/ts/src/lib/plot-config.generated.ts
+"""
+
+from __future__ import annotations
+
+import sys
+import textwrap
+from pathlib import Path
+
+ROOT = Path(__file__).parent.parent
+TS_OUT = (
+    ROOT
+    / "src/mujoco_mojo/utils/layers/dojo/templates/static/ts/src/lib"
+    / "plot-config.generated.ts"
+)
+
+# ---------------------------------------------------------------------------
+# JSON Schema → TypeScript converter
+# ---------------------------------------------------------------------------
+
+
+def _ref_name(ref: str) -> str:
+    """'#/$defs/FooBar' → 'FooBar'"""
+    return ref.rsplit("/", 1)[-1]
+
+
+def _schema_to_ts(node: dict, defs: dict) -> str:
+    """Recursively convert a JSON Schema node to a TypeScript type string."""
+    if "$ref" in node:
+        return _ref_name(node["$ref"])
+
+    if "anyOf" in node:
+        parts = [_schema_to_ts(s, defs) for s in node["anyOf"]]
+        return " | ".join(parts)
+
+    if "enum" in node:
+        return " | ".join(f'"{v}"' for v in node["enum"])
+
+    t = node.get("type")
+
+    if t == "string":
+        return "string"
+    if t in ("number", "integer"):
+        return "number"
+    if t == "boolean":
+        return "boolean"
+    if t == "null":
+        return "null"
+
+    if t == "array":
+        if "prefixItems" in node:
+            items = [_schema_to_ts(s, defs) for s in node["prefixItems"]]
+            return f"[{', '.join(items)}]"
+        if "items" in node:
+            return f"{_schema_to_ts(node['items'], defs)}[]"
+        return "unknown[]"
+
+    if t == "object":
+        add_props = node.get("additionalProperties")
+        props = node.get("properties", {})
+        required = set(node.get("required", []))
+
+        if add_props and not props:
+            # Pure dict / Record
+            if add_props is True or add_props == {}:
+                return "Record<string, unknown>"
+            return f"Record<string, {_schema_to_ts(add_props, defs)}>"
+
+        # Inline object (rare — models surface as $defs, not inline)
+        lines = _props_to_ts_lines(props, required, defs)
+        if add_props is True:
+            lines.append("  [key: string]: unknown;")
+        body = "\n".join(lines)
+        return "{\n" + body + "\n}"
+
+    return "unknown"
+
+
+def _props_to_ts_lines(
+    props: dict,
+    required: set[str],
+    defs: dict,
+) -> list[str]:
+    """Return one '  field?: Type;' string per property."""
+    lines: list[str] = []
+    for name, schema in props.items():
+        ts_type = _schema_to_ts(schema, defs)
+        opt = "" if name in required else "?"
+        lines.append(f"  {name}{opt}: {ts_type};")
+    return lines
+
+
+# ---------------------------------------------------------------------------
+# $defs → top-level TypeScript declarations
+# ---------------------------------------------------------------------------
+
+
+def _def_to_ts(name: str, schema: dict, defs: dict) -> str:
+    """Convert one $defs entry to a TypeScript type or interface block."""
+    # StrEnum / Literal  →  export type Name = "a" | "b";
+    if "enum" in schema:
+        values = " | ".join(f'"{v}"' for v in schema["enum"])
+        return f"export type {name} = {values};\n"
+
+    # BaseModel  →  export interface Name { ... }
+    if schema.get("type") == "object":
+        props = schema.get("properties", {})
+        required = set(schema.get("required", []))
+        lines = _props_to_ts_lines(props, required, defs)
+        if schema.get("additionalProperties") is True:
+            lines.append("  [key: string]: unknown;")
+        body = "\n".join(lines) if lines else "  [key: string]: unknown;"
+        return f"export interface {name} {{\n{body}\n}}\n"
+
+    return f"// Unhandled $def: {name}\n"
+
+
+def _top_level_interface(schema: dict, defs: dict) -> str:
+    """Generate the top-level model (PlotConfig) as an interface."""
+    name = schema.get("title", "PlotConfig")
+    desc = schema.get("description", "")
+    props = schema.get("properties", {})
+    required = set(schema.get("required", []))
+    lines = _props_to_ts_lines(props, required, defs)
+    body = "\n".join(lines)
+    comment = f"/** {desc} */\n" if desc else ""
+    return f"{comment}export interface {name} {{\n{body}\n}}\n"
+
+
+# ---------------------------------------------------------------------------
+# Entry point
+# ---------------------------------------------------------------------------
+
+
+def main() -> None:
+    # Import inside main so sys.path manipulation is localised
+    sys.path.insert(0, str(ROOT / "src"))
+    from mujoco_mojo.utils.layers.dojo.plot_config import PlotConfig
+
+    schema = PlotConfig.model_json_schema()
+    defs: dict = schema.get("$defs", {})
+
+    blocks: list[str] = []
+
+    # Emit each $def in definition order
+    for def_name, def_schema in defs.items():
+        blocks.append(_def_to_ts(def_name, def_schema, defs))
+
+    # Emit the top-level PlotConfig interface
+    blocks.append(_top_level_interface(schema, defs))
+
+    header = textwrap.dedent("""\
+        // ============================================================
+        // AUTO-GENERATED - do not edit manually.
+        // Source: src/mujoco_mojo/utils/layers/dojo/plot_config.py
+        // Regenerate: python scripts/gen_ts_models.py
+        // ============================================================
+
+    """)
+
+    output = header + "\n".join(blocks)
+    TS_OUT.parent.mkdir(parents=True, exist_ok=True)
+    TS_OUT.write_text(output, encoding="utf-8")
+    print(f"Written → {TS_OUT.relative_to(ROOT)}")
+
+
+if __name__ == "__main__":
+    main()

{mujoco_mojo-2.2.3 → mujoco_mojo-2.3.0}/src/mujoco_mojo/__init__.py

@@ -2,6 +2,30 @@
 mujoco_mojo is a collection of Python objects built to make working with MuJoCo via Python easier.
 
 It provides vast bindings for all MJCF XML schema objects, tools to convert to XML, run MuJoCo simulations, and more.
+
+MuJoCo Type Stubs:
+------------------
+
+MuJoCo does not ship Python type stubs. Generate them once with pybind11-stubgen:
+
+.. code-block:: bash
+    pip install pybind11-stubgen
+    pybind11-stubgen mujoco -o typings/ --numpy-array-wrap-with-annotated
+
+Run this from the project root. The ``typings/`` directory is gitignored.
+Then add to pyproject.toml:
+
+.. code-block:: toml
+    [tool.pyright]
+    stubPath = "typings"
+    venvPath = "."
+    venv = ".venv"
+
+If you encounter Pyright enum errors on recent MuJoCo builds, apply the
+compatibility patch that ships alongside the stubs:
+
+.. code-block:: bash
+    python typings/patch_mujoco_enums.py typings/mujoco/_enums.pyi
 """
 
 from mujoco_mojo.__about__ import __version__  # noqa: F401

{mujoco_mojo-2.2.3 → mujoco_mojo-2.3.0}/src/mujoco_mojo/utils/dataframe.py

@@ -1,7 +1,10 @@
 from __future__ import annotations
 
 from pathlib import Path
-from typing import TYPE_CHECKING, Any, Protocol, TypedDict, cast
+from typing import TYPE_CHECKING, Any, TypedDict, cast
+
+if TYPE_CHECKING:
+    from typing import Self
 
 import polars as pl
 from scipy.spatial.transform import Rotation as R
@@ -28,13 +31,6 @@ from mujoco_mojo.utils.log import get_logger
 logger = get_logger(__name__)
 
 
-class MojoFrameProtocol(Protocol):
-    """Protocol to tell type checkers that .mojo is available on the DataFrame."""
-
-    @property
-    def mojo(self) -> MojoNamespace: ...
-
-
 class _MojoFrame(pl.DataFrame):
     """
     Internal implementation of MojoFrame to house static loaders.
@@ -78,10 +74,30 @@ class _MojoFrame(pl.DataFrame):
 
 if TYPE_CHECKING:
     # MojoFrame is seen by the IDE as the combination of:
-    # 1. Our loaders (_MojoFrame)
+    # 1. loaders (_MojoFrame)
     # 2. Polars methods (pl.DataFrame)
-    # 3. Our namespace (MojoFrameProtocol)
-    class MojoDataFrame(_MojoFrame, MojoFrameProtocol): ...
+    # 3. namespace (MojoFrameProtocol)
+    class MojoDataFrame(_MojoFrame):
+        @property
+        def mojo(self) -> MojoNamespace: ...
+
+        # override polars methods that return DataFrame so the type propagates
+        def select(self, *args: Any, **kwargs: Any) -> Self: ...
+        def filter(self, *args: Any, **kwargs: Any) -> Self: ...
+        def with_columns(self, *args: Any, **kwargs: Any) -> Self: ...
+        def sort(self, *args: Any, **kwargs: Any) -> Self: ...
+        def head(self, *args: Any, **kwargs: Any) -> Self: ...
+        def tail(self, *args: Any, **kwargs: Any) -> Self: ...
+        def limit(self, *args: Any, **kwargs: Any) -> Self: ...
+        def slice(self, *args: Any, **kwargs: Any) -> Self: ...
+        def rename(self, *args: Any, **kwargs: Any) -> Self: ...
+        def drop(self, *args: Any, **kwargs: Any) -> Self: ...
+        def drop_nulls(self, *args: Any, **kwargs: Any) -> Self: ...
+        def unique(self, *args: Any, **kwargs: Any) -> Self: ...
+        def sample(self, *args: Any, **kwargs: Any) -> Self: ...
+        def join(self, *args: Any, **kwargs: Any) -> Self: ...
+        def hstack(self, *args: Any, **kwargs: Any) -> Self: ...
+        def vstack(self, *args: Any, **kwargs: Any) -> Self: ...
 else:
     # At runtime, it's just our internal class
     MojoDataFrame = _MojoFrame
@@ -93,7 +109,6 @@ class ColumnManifest(TypedDict):
     available_quats: list[str]
 
 
-@pl.api.register_dataframe_namespace("mojo")
 class MojoNamespace:
     """
     Enhanced Polars DataFrame for MuJoCo Mojo telemetry.
@@ -216,18 +231,22 @@ class MojoNamespace:
             self._df.select(pl.col(rf"^{SignalCategory.DEFORMABLES}/{name}/.*$"))
         )
 
-    def _get_base_map(self) -> dict[str, set[str]]:
+    def _get_base_map(
+        self, extra_columns: list[str] | None = None
+    ) -> dict[str, set[str]]:
         """
         Internal helper to group suffixes by their common prefixes.
 
         Example:
-            'Bodies/racket:xvelr:x', 'Bodies/racket:xvelr:y' -> {'Bodies/racket:xvelr': {'x', 'y'}}
+            'Bodies/racket/xvelr:x', 'Bodies/racket/xvelr:y' -> {'Bodies/racket/xvelr': {'x', 'y'}}
+
+        extra_columns are included in discovery but are not expected to exist in self._df.
 
         """
         base_map: dict[str, set[str]] = {}
-        for c in self._df.columns:
+        for c in list(self._df.columns) + (extra_columns or []):
             if ":" in c:
-                prefix, suffix = c.rsplit(":")  # we may have :ke_trans, or ke_rot, etc.
+                prefix, suffix = c.rsplit(":", 1)
                 base_map.setdefault(prefix, set()).add(suffix)
         return base_map
 
@@ -265,12 +284,17 @@ class MojoNamespace:
             expanded.extend([f"{base}:w", f"{base}:x", f"{base}:y", f"{base}:z"])
         return expanded
 
-    def get_manifest(self) -> ColumnManifest:
-        """Returns the structured manifest used by the frontend."""
+    def get_manifest(self, extra_columns: list[str] | None = None) -> ColumnManifest:
+        """Returns the structured manifest used by the frontend. extra_columns are appended to 'all' and included in rotatable/quat discovery."""
+        bm = self._get_base_map(extra_columns)
         return {
-            "all": self._df.columns,
-            "rotatable_vectors": sorted(list(self.rotatable_bases)),
-            "available_quats": sorted(list(self.quaternion_bases)),
+            "all": list(self._df.columns) + (extra_columns or []),
+            "rotatable_vectors": sorted(
+                b for b, s in bm.items() if {"x", "y", "z"}.issubset(s) and "w" not in s
+            ),
+            "available_quats": sorted(
+                b for b, s in bm.items() if {"w", "x", "y", "z"}.issubset(s)
+            ),
         }
 
     def with_rotation(self, quat_base: str, invert: bool = True) -> MojoDataFrame:
@@ -370,3 +394,7 @@ class MojoNamespace:
         target_cols = columns or self._df.columns
         filter_map = {col: filters for col in target_cols}
         return self.with_filter_map(filter_map, omit_time=omit_time)
+
+
+if not TYPE_CHECKING:
+    pl.api.register_dataframe_namespace("mojo")(MojoNamespace)

{mujoco_mojo-2.2.3 → mujoco_mojo-2.3.0}/src/mujoco_mojo/utils/filters/__init__.py

@@ -2,18 +2,26 @@ from .filters import (
     AbsoluteValueFilter,
     AnyFilter,
     ClipFilter,
+    ComparisonFilter,
     DeadbandFilter,
     DerivativeFilter,
+    ExpFilter,
     FilterType,
     HighPassFilter,
     IntegralFilter,
+    LogFilter,
     LowPassFilter,
     MedianFilter,
     NormalizeFilter,
+    PowerFilter,
     RollingMeanFilter,
+    RotationFilter,
+    RoundFilter,
     SavitzkyGolayFilter,
     ScaleFilter,
+    SignFilter,
     TaringFilter,
+    TrigFilter,
     UnitFilter,
     WrapFilter,
     filter_adapter,
@@ -23,18 +31,26 @@ __all__ = [
     "AbsoluteValueFilter",
     "AnyFilter",
     "ClipFilter",
+    "ComparisonFilter",
     "DeadbandFilter",
     "DerivativeFilter",
+    "ExpFilter",
     "FilterType",
     "HighPassFilter",
     "IntegralFilter",
+    "LogFilter",
     "LowPassFilter",
     "MedianFilter",
     "NormalizeFilter",
+    "PowerFilter",
     "RollingMeanFilter",
+    "RotationFilter",
+    "RoundFilter",
     "SavitzkyGolayFilter",
     "ScaleFilter",
+    "SignFilter",
     "TaringFilter",
+    "TrigFilter",
     "UnitFilter",
     "WrapFilter",
     "filter_adapter",