simview 3.4__tar.gz → 3.5__tar.gz

simview-3.5/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: simview
+Version: 3.5
+Summary: THREE.js-based simulation visualization tool
+Author-email: Jan Vlk <vlkjan6@fel.cvut.cz>, Ales Kucera <kuceral4@fel.cvut.cz>, David Korcak <david.korcak@gmail.com>
+License-Expression: BSD-3-Clause
+Project-URL: Homepage, https://vlk-jan.github.io/simview/
+Project-URL: Repository, https://github.com/vlk-jan/simview
+Project-URL: Issues, https://github.com/vlk-jan/simview/issues
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Science/Research
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering :: Visualization
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.135.3
+Requires-Dist: httptools>=0.7.1; sys_platform != "win32"
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: orjson>=3.11.8
+Requires-Dist: uvicorn>=0.44.0
+Requires-Dist: uvloop>=0.22.1; sys_platform != "win32"
+Provides-Extra: authoring
+Requires-Dist: torch; extra == "authoring"
+Requires-Dist: einops; extra == "authoring"
+Requires-Dist: numpy; extra == "authoring"
+Provides-Extra: render
+Requires-Dist: playwright>=1.40; extra == "render"
+Dynamic: license-file
+
+# SimView Visualizer
+
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://vlk-jan.github.io/simview/)
+[![Live Demo](https://img.shields.io/badge/demo-live-brightgreen.svg)](https://vlk-jan.github.io/assets/demos/simview/)
+
+**SimView** is a powerful and interactive tool for visualizing 3D models and terrain data in simulations. It enables you to explore and analyze multiple simulation scenarios (batches) within a shared environment, all defined through an intuitive JSON format or a Python API.
+
+Whether you're simulating physical objects or comparing different runs, SimView provides a flexible and efficient way to bring your data to life using a web-based interface powered by Three.js.
+
+---
+
+## Documentation
+
+Full documentation — usage guides, CLI reference, the JSON format specification,
+the API reference, and developer/architecture docs — is available at:
+
+**[https://vlk-jan.github.io/simview/](https://vlk-jan.github.io/simview/)**
+
+Want to try it without installing anything? There's a
+[live browser demo](https://vlk-jan.github.io/assets/demos/simview/)
+(static snapshot, no backend needed).
+
+---
+
+## Features
+
+- **Batched Simulations**: Visualize multiple simulation instances side-by-side.
+- **Shared Terrain**: Efficient rendering with shared terrain across all batches.
+- **Interactive UI**: Web-based controls for playback, camera, and data inspection.
+- **Python API**: Easy-to-use API for generating scenes and launching the visualizer directly from your code.
+- **JSON Support**: Load and save simulation data using a portable JSON format.
+
+---
+
+## Quick Start
+
+The easiest way to get started is to run the provided example script:
+
+```bash
+python example.py
+```
+
+This script demonstrates how to use the Python API to create a simulation with wavy terrain, dynamic bodies, and time-series data.
+
+The Python authoring API (`simview.scene`, `simview.state`, `simview.model`) depends on
+`torch` and `einops`. Install them with the optional `authoring` extra shown below.
+Only these are needed to *build* simulations; *viewing* an existing JSON file does not
+require `torch`.
+
+---
+
+## Installation
+
+Requires **Python 3.12+**.
+
+### From PyPI
+
+To only view existing simulation JSON files:
+
+```bash
+pip install simview
+```
+
+To also author simulations from Python (installs `torch` and `einops`):
+
+```bash
+pip install "simview[authoring]"
+```
+
+### From source
+
+For working on SimView itself (or to track an unreleased commit), install an
+editable checkout instead:
+
+```bash
+pip install -e .              # viewing only
+pip install -e ".[authoring]" # viewing + authoring
+```
+
+For independent use of this repository, use `venv` or `uv`:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[authoring]"
+```
+
+```bash
+uv sync --extra authoring
+source .venv/bin/activate
+```
+
+---
+
+## License
+
+SimView is distributed under the [BSD 3-Clause License](LICENSE). The web interface
+vendors [uPlot](https://github.com/leeoniya/uPlot), [three.js](https://github.com/mrdoob/three.js),
+and [chroma-js](https://github.com/gka/chroma.js) (all MIT licensed) under
+`simview/static/lib/` so the viewer works fully offline — see the
+[documentation](https://vlk-jan.github.io/simview/dev/architecture/#vendored-third-party-libraries)
+for details. All third-party libraries used by SimView are permissively licensed
+(MIT/BSD), so there are no licensing restrictions on commercial use.

simview-3.5/README.md

@@ -0,0 +1,103 @@
+# SimView Visualizer
+
+[![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://vlk-jan.github.io/simview/)
+[![Live Demo](https://img.shields.io/badge/demo-live-brightgreen.svg)](https://vlk-jan.github.io/assets/demos/simview/)
+
+**SimView** is a powerful and interactive tool for visualizing 3D models and terrain data in simulations. It enables you to explore and analyze multiple simulation scenarios (batches) within a shared environment, all defined through an intuitive JSON format or a Python API.
+
+Whether you're simulating physical objects or comparing different runs, SimView provides a flexible and efficient way to bring your data to life using a web-based interface powered by Three.js.
+
+---
+
+## Documentation
+
+Full documentation — usage guides, CLI reference, the JSON format specification,
+the API reference, and developer/architecture docs — is available at:
+
+**[https://vlk-jan.github.io/simview/](https://vlk-jan.github.io/simview/)**
+
+Want to try it without installing anything? There's a
+[live browser demo](https://vlk-jan.github.io/assets/demos/simview/)
+(static snapshot, no backend needed).
+
+---
+
+## Features
+
+- **Batched Simulations**: Visualize multiple simulation instances side-by-side.
+- **Shared Terrain**: Efficient rendering with shared terrain across all batches.
+- **Interactive UI**: Web-based controls for playback, camera, and data inspection.
+- **Python API**: Easy-to-use API for generating scenes and launching the visualizer directly from your code.
+- **JSON Support**: Load and save simulation data using a portable JSON format.
+
+---
+
+## Quick Start
+
+The easiest way to get started is to run the provided example script:
+
+```bash
+python example.py
+```
+
+This script demonstrates how to use the Python API to create a simulation with wavy terrain, dynamic bodies, and time-series data.
+
+The Python authoring API (`simview.scene`, `simview.state`, `simview.model`) depends on
+`torch` and `einops`. Install them with the optional `authoring` extra shown below.
+Only these are needed to *build* simulations; *viewing* an existing JSON file does not
+require `torch`.
+
+---
+
+## Installation
+
+Requires **Python 3.12+**.
+
+### From PyPI
+
+To only view existing simulation JSON files:
+
+```bash
+pip install simview
+```
+
+To also author simulations from Python (installs `torch` and `einops`):
+
+```bash
+pip install "simview[authoring]"
+```
+
+### From source
+
+For working on SimView itself (or to track an unreleased commit), install an
+editable checkout instead:
+
+```bash
+pip install -e .              # viewing only
+pip install -e ".[authoring]" # viewing + authoring
+```
+
+For independent use of this repository, use `venv` or `uv`:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[authoring]"
+```
+
+```bash
+uv sync --extra authoring
+source .venv/bin/activate
+```
+
+---
+
+## License
+
+SimView is distributed under the [BSD 3-Clause License](LICENSE). The web interface
+vendors [uPlot](https://github.com/leeoniya/uPlot), [three.js](https://github.com/mrdoob/three.js),
+and [chroma-js](https://github.com/gka/chroma.js) (all MIT licensed) under
+`simview/static/lib/` so the viewer works fully offline — see the
+[documentation](https://vlk-jan.github.io/simview/dev/architecture/#vendored-third-party-libraries)
+for details. All third-party libraries used by SimView are permissively licensed
+(MIT/BSD), so there are no licensing restrictions on commercial use.

{simview-3.4 → simview-3.5}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simview"
-version = "3.4"
+version = "3.5"
 readme = "README.md"
 requires-python = ">=3.12"
 license = "BSD-3-Clause"
@@ -34,7 +34,7 @@ dependencies = [
 ]
 
 [project.urls]
-Homepage = "https://github.com/vlk-jan/simview"
+Homepage = "https://vlk-jan.github.io/simview/"
 Repository = "https://github.com/vlk-jan/simview"
 Issues = "https://github.com/vlk-jan/simview/issues"
 
@@ -42,6 +42,10 @@ Issues = "https://github.com/vlk-jan/simview/issues"
 # Needed only to author simulations via the Python API (simview.scene / state / model).
 # Viewing an existing JSON file does not require these.
 authoring = ["torch", "einops", "numpy"]
+# Needed only for `simview render` (headless PNG screenshots, e.g. from a
+# SLURM job with no display). Also requires a one-time `playwright install
+# chromium` to fetch the browser binary itself.
+render = ["playwright>=1.40"]
 
 [project.scripts]
 simview = "simview.__main__:main"
@@ -61,6 +65,7 @@ dev = [
     "pyright>=1.1.411",
     "websockets>=16.1",
 ]
+docs = ["mkdocs>=1.6", "mkdocs-material>=9.5", "mkdocstrings[python]>=0.27"]
 
 [tool.ruff]
 target-version = "py312"

{simview-3.4 → simview-3.5}/simview/__main__.py

@@ -178,6 +178,7 @@ def run_diff(path: Path, args: argparse.Namespace) -> None:
             every=args.every,
             pos_threshold=args.pos_threshold,
             rot_threshold_deg=args.rot_threshold_deg,
+            per_axis=args.per_axis,
         )
         text = diff_mod.format_diff_text(result)
         csv_text = diff_mod.format_diff_csv(result)
@@ -193,6 +194,36 @@ def run_diff(path: Path, args: argparse.Namespace) -> None:
         print(text)
 
 
+def run_render(path: Path, args: argparse.Namespace) -> None:
+    """Headlessly render one PNG screenshot of the scene JSON at `path`, for
+    generating figures from a display-less environment (e.g. a SLURM job)."""
+    from simview.render import render_screenshot
+
+    if args.output is None:
+        logger.error(
+            "Error: 'simview render' requires --output, e.g. 'simview render "
+            "scene.json --output frame.png'."
+        )
+        sys.exit(1)
+
+    try:
+        render_screenshot(
+            path,
+            args.output,
+            host=args.host,
+            port=args.port,
+            view=args.view,
+            width=args.width,
+            height=args.height,
+        )
+    except ImportError as e:
+        logger.error("Error: %s", e)
+        sys.exit(1)
+    except (RuntimeError, TimeoutError) as e:
+        logger.error("Error: 'simview render' failed: %s", e)
+        sys.exit(1)
+
+
 def save_merged(paths: list[Path], out_path: Path) -> None:
     """Merge `paths` (must be >= 2) and write the result to `out_path`, gzipped
     if it ends in .gz, without starting the server."""
@@ -219,10 +250,11 @@ def build_parser() -> argparse.ArgumentParser:
             "Path(s) to simulation JSON file(s) to visualize, 'clear' to clear "
             "cache, 'info <file>' to print a structural summary of one scene "
             "file, 'terrain <file>' to query terrain values at a point or over "
-            "an area, or 'diff <file>' to compare two batches' trajectories. "
-            "Multiple visualize-mode files are merged into one scene, each "
-            "file's batches appended as extra batches (e.g. a real-world "
-            "recording plus a simulated rerun)."
+            "an area, 'diff <file>' to compare two batches' trajectories, or "
+            "'render <file>' to headlessly save a PNG screenshot (needs the "
+            "'render' extra). Multiple visualize-mode files are merged into "
+            "one scene, each file's batches appended as extra batches (e.g. a "
+            "real-world recording plus a simulated rerun)."
         ),
     )
     parser.add_argument(
@@ -345,6 +377,15 @@ def build_parser() -> argparse.ArgumentParser:
             "orientation error exceeds this many degrees."
         ),
     )
+    parser.add_argument(
+        "--per-axis",
+        action="store_true",
+        help=(
+            "With 'simview diff <file>', also report signed per-axis "
+            "(err_x/err_y/err_z = batch_a - batch_b) position error, matching "
+            "the browser Error Metrics panel's per-axis toggle."
+        ),
+    )
     parser.add_argument(
         "--host",
         type=str,
@@ -365,6 +406,37 @@ def build_parser() -> argparse.ArgumentParser:
         action="store_true",
         help="Don't automatically open a browser tab once the server starts.",
     )
+    parser.add_argument(
+        "--output",
+        type=str,
+        default=None,
+        metavar="PATH",
+        help="With 'simview render <file>', PNG file path to save the screenshot to.",
+    )
+    parser.add_argument(
+        "--view",
+        type=str,
+        default=None,
+        metavar="HASH",
+        help=(
+            "With 'simview render <file>', a shareable view-link hash (from "
+            "the viewer's 'Copy view link' button, with or without the "
+            "leading '#') to set the camera/playback/terrain state before "
+            "capturing. Default: the viewer's startup state."
+        ),
+    )
+    parser.add_argument(
+        "--width",
+        type=int,
+        default=1280,
+        help="With 'simview render <file>', screenshot width in pixels (default: 1280).",
+    )
+    parser.add_argument(
+        "--height",
+        type=int,
+        default=720,
+        help="With 'simview render <file>', screenshot height in pixels (default: 720).",
+    )
     parser.add_argument(
         "--save-merged",
         type=str,
@@ -437,6 +509,21 @@ def main():
         run_diff(diff_path, args)
         return
 
+    if args.inputs and args.inputs[0] == "render":
+        render_args = args.inputs[1:]
+        if len(render_args) != 1:
+            logger.error(
+                "Error: 'simview render' requires exactly one file argument, "
+                "e.g. 'simview render scene.json --output frame.png'."
+            )
+            sys.exit(1)
+        render_path = Path(render_args[0])
+        if not (render_path.exists() and render_path.is_file()):
+            logger.error("Error: File '%s' not found or is not a file.", render_path)
+            sys.exit(1)
+        run_render(render_path, args)
+        return
+
     if args.inputs == ["clear"]:
         clear_cache()
         return

{simview-3.4 → simview-3.5}/simview/diff.py

@@ -180,19 +180,25 @@ def compute_trajectory_diff(
     every: int = 1,
     pos_threshold: float | None = None,
     rot_threshold_deg: float | None = None,
+    per_axis: bool = False,
 ) -> dict:
     """Per-frame positional/orientation divergence between batch `batch_a`
     and batch `batch_b`'s trajectories in `states_data`, for every body
     present in the states (or just `body` if given).
 
     Returns a JSON-serializable dict: `{"batch_a", "batch_b", "every",
-    "pos_threshold", "rot_threshold_deg", "bodies": {label: {"frame_indices",
-    "times", "position_error", "orientation_error_deg", "summary": {
-    "frame_count", "position_error": {"mean","max","final"},
+    "pos_threshold", "rot_threshold_deg", "per_axis", "bodies": {label:
+    {"frame_indices", "times", "position_error", "orientation_error_deg",
+    "summary": {"frame_count", "position_error": {"mean","max","final"},
     "orientation_error_deg": {...}, "first_frame_exceeding_pos_threshold",
-    "first_frame_exceeding_rot_threshold"}}}}`. Raises `ValueError` on
-    invalid batch indices, `every < 1`, an unmatched/ambiguous `body`, or a
-    scene with no diffable bodies.
+    "first_frame_exceeding_rot_threshold"}}}}`. When `per_axis` is set, each
+    body also gets `"err_x"`/`"err_y"`/`"err_z"` per-frame series (signed
+    `batch_a - batch_b`, matching the browser Error Metrics panel's
+    per-axis toggle -- see `static/js/utils/errorMath.js`'s
+    `positionAxisError`) and matching `"err_x"`/`"err_y"`/`"err_z"` entries
+    in `summary` (mean/max/final of the *signed* value, so directional bias
+    is visible). Raises `ValueError` on invalid batch indices, `every < 1`,
+    an unmatched/ambiguous `body`, or a scene with no diffable bodies.
     """
     batch_size = _resolve_batches(model_data, batch_a, batch_b)
     if every < 1:
@@ -223,6 +229,9 @@ def compute_trajectory_diff(
         times: list = []
         position_error: list[float] = []
         orientation_error_deg: list[float] = []
+        err_x: list[float] = []
+        err_y: list[float] = []
+        err_z: list[float] = []
 
         for idx, state in enumerate(states_data):
             if idx % every != 0:
@@ -245,24 +254,36 @@ def compute_trajectory_diff(
             times.append(state.get("time"))
             position_error.append(math.dist(row_a[:3], row_b[:3]))
             orientation_error_deg.append(_quat_angle_deg(row_a[3:], row_b[3:]))
-
+            if per_axis:
+                err_x.append(row_a[0] - row_b[0])
+                err_y.append(row_a[1] - row_b[1])
+                err_z.append(row_a[2] - row_b[2])
+
+        summary = {
+            "frame_count": len(frame_indices),
+            "position_error": _stats(position_error),
+            "orientation_error_deg": _stats(orientation_error_deg),
+            "first_frame_exceeding_pos_threshold": _first_exceeding(
+                frame_indices, position_error, pos_threshold
+            ),
+            "first_frame_exceeding_rot_threshold": _first_exceeding(
+                frame_indices, orientation_error_deg, rot_threshold_deg
+            ),
+        }
         bodies_out[label] = {
             "frame_indices": frame_indices,
             "times": times,
             "position_error": position_error,
             "orientation_error_deg": orientation_error_deg,
-            "summary": {
-                "frame_count": len(frame_indices),
-                "position_error": _stats(position_error),
-                "orientation_error_deg": _stats(orientation_error_deg),
-                "first_frame_exceeding_pos_threshold": _first_exceeding(
-                    frame_indices, position_error, pos_threshold
-                ),
-                "first_frame_exceeding_rot_threshold": _first_exceeding(
-                    frame_indices, orientation_error_deg, rot_threshold_deg
-                ),
-            },
+            "summary": summary,
         }
+        if per_axis:
+            bodies_out[label]["err_x"] = err_x
+            bodies_out[label]["err_y"] = err_y
+            bodies_out[label]["err_z"] = err_z
+            summary["err_x"] = _stats(err_x)
+            summary["err_y"] = _stats(err_y)
+            summary["err_z"] = _stats(err_z)
 
     return {
         "batch_a": batch_a,
@@ -270,6 +291,7 @@ def compute_trajectory_diff(
         "every": every,
         "pos_threshold": pos_threshold,
         "rot_threshold_deg": rot_threshold_deg,
+        "per_axis": per_axis,
         "bodies": bodies_out,
     }
 
@@ -306,6 +328,13 @@ def format_diff_text(result: dict) -> str:
             f"  rot_err (deg): mean={rot['mean']:.6g}  max={rot['max']:.6g}  "
             f"final={rot['final']:.6g}"
         )
+        if result.get("per_axis"):
+            for axis in ("err_x", "err_y", "err_z"):
+                a = summary[axis]
+                lines.append(
+                    f"  {axis} (m):      mean={a['mean']:.6g}  max={a['max']:.6g}  "
+                    f"final={a['final']:.6g}"
+                )
         if summary["first_frame_exceeding_pos_threshold"] is not None:
             lines.append(
                 "  first frame exceeding pos_threshold: "
@@ -344,17 +373,22 @@ def format_diff_csv(result: dict) -> str:
     (body, frame), full series (no truncation) -- CSV output is for scripts,
     matching the "just the numbers, in full" philosophy `--json` already
     uses everywhere in this CLI."""
+    per_axis = result.get("per_axis")
     buf = io.StringIO()
     writer = csv.writer(buf)
-    writer.writerow(
-        ["body", "frame", "time", "position_error", "orientation_error_deg"]
-    )
+    header = ["body", "frame", "time", "position_error", "orientation_error_deg"]
+    if per_axis:
+        header += ["err_x", "err_y", "err_z"]
+    writer.writerow(header)
     for label, body in result["bodies"].items():
-        for frame_idx, t, p, r in zip(
+        columns = [
             body["frame_indices"],
             body["times"],
             body["position_error"],
             body["orientation_error_deg"],
-        ):
-            writer.writerow([label, frame_idx, t, p, r])
+        ]
+        if per_axis:
+            columns += [body["err_x"], body["err_y"], body["err_z"]]
+        for row in zip(*columns):
+            writer.writerow([label, *row])
     return buf.getvalue()