simview 3.4__tar.gz → 3.6__tar.gz

simview-3.6/PKG-INFO

@@ -0,0 +1,136 @@
+Metadata-Version: 2.4
+Name: simview
+Version: 3.6
+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.6/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.6}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simview"
-version = "3.4"
+version = "3.6"
 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.6}/simview/__main__.py

@@ -82,14 +82,18 @@ def run_info(path: Path, as_json: bool) -> None:
 
 
 def run_terrain(path: Path, args: argparse.Namespace) -> None:
-    """Print terrain value(s) at a point or over an area, from the scene JSON
-    at `path`, to stdout. With `--batches A B`, compares two batches instead
-    of querying a single one."""
+    """Print terrain value(s) at a point, over an area, or along a body's
+    trajectory, from the scene JSON at `path`, to stdout. With `--batches
+    A B`, compares two batches instead of querying a single one (for
+    `--along-body`, both batches' terrains are sampled along batch A's
+    trajectory -- see `query_along_body_diff`)."""
     from simview import terrain as terrain_mod
 
-    if (args.point is None) == (args.area is None):
+    mode_count = sum(v is not None for v in (args.point, args.area, args.along_body))
+    if mode_count != 1:
         logger.error(
-            "Error: 'simview terrain' requires exactly one of --point or --area."
+            "Error: 'simview terrain' requires exactly one of --point, --area, "
+            "or --along-body."
         )
         sys.exit(1)
     if args.area is not None and len(args.area) not in (0, 4):
@@ -106,40 +110,67 @@ def run_terrain(path: Path, args: argparse.Namespace) -> None:
     diff_mode = args.batches is not None
 
     try:
-        model_data = terrain_mod.load_scene_model(path)
-        if diff_mode:
-            batch_a, batch_b = args.batches
-            if args.point is not None:
-                result = terrain_mod.query_point_diff(
+        if args.along_body is not None:
+            model_data, states_data = terrain_mod.load_scene(path)
+            if diff_mode:
+                batch_a, batch_b = args.batches
+                result = terrain_mod.query_along_body_diff(
                     model_data,
-                    args.point[0],
-                    args.point[1],
+                    states_data,
+                    args.along_body,
                     batch_a,
                     batch_b,
                     args.layer,
+                    args.every,
                 )
-                text = terrain_mod.format_point_diff_text(result)
-                csv_text = terrain_mod.format_point_diff_csv(result)
+                text = terrain_mod.format_along_diff_text(result)
+                csv_text = terrain_mod.format_along_diff_csv(result)
             else:
-                bounds = tuple(args.area) if args.area else None
-                result = terrain_mod.query_area_diff(
-                    model_data, bounds, batch_a, batch_b, args.layer, args.stride
+                result = terrain_mod.query_along_body(
+                    model_data,
+                    states_data,
+                    args.along_body,
+                    args.layer,
+                    args.batch,
+                    args.every,
                 )
-                text = terrain_mod.format_area_diff_text(result)
-                csv_text = terrain_mod.format_area_diff_csv(result)
-        elif args.point is not None:
-            result = terrain_mod.query_point(
-                model_data, args.point[0], args.point[1], args.layer, args.batch
-            )
-            text = terrain_mod.format_point_text(result)
-            csv_text = terrain_mod.format_point_csv(result)
+                text = terrain_mod.format_along_text(result)
+                csv_text = terrain_mod.format_along_csv(result)
         else:
-            bounds = tuple(args.area) if args.area else None
-            result = terrain_mod.query_area(
-                model_data, bounds, args.layer, args.batch, args.stride
-            )
-            text = terrain_mod.format_area_text(result)
-            csv_text = terrain_mod.format_area_csv(result)
+            model_data = terrain_mod.load_scene_model(path)
+            if diff_mode:
+                batch_a, batch_b = args.batches
+                if args.point is not None:
+                    result = terrain_mod.query_point_diff(
+                        model_data,
+                        args.point[0],
+                        args.point[1],
+                        batch_a,
+                        batch_b,
+                        args.layer,
+                    )
+                    text = terrain_mod.format_point_diff_text(result)
+                    csv_text = terrain_mod.format_point_diff_csv(result)
+                else:
+                    bounds = tuple(args.area) if args.area else None
+                    result = terrain_mod.query_area_diff(
+                        model_data, bounds, batch_a, batch_b, args.layer, args.stride
+                    )
+                    text = terrain_mod.format_area_diff_text(result)
+                    csv_text = terrain_mod.format_area_diff_csv(result)
+            elif args.point is not None:
+                result = terrain_mod.query_point(
+                    model_data, args.point[0], args.point[1], args.layer, args.batch
+                )
+                text = terrain_mod.format_point_text(result)
+                csv_text = terrain_mod.format_point_csv(result)
+            else:
+                bounds = tuple(args.area) if args.area else None
+                result = terrain_mod.query_area(
+                    model_data, bounds, args.layer, args.batch, args.stride
+                )
+                text = terrain_mod.format_area_text(result)
+                csv_text = terrain_mod.format_area_csv(result)
     except (json.JSONDecodeError, ValueError, KeyError) as e:
         logger.error("Error: %s", e)
         sys.exit(1)
@@ -154,7 +185,10 @@ def run_terrain(path: Path, args: argparse.Namespace) -> None:
 
 def run_diff(path: Path, args: argparse.Namespace) -> None:
     """Print a trajectory divergence report between two batches of the scene
-    JSON at `path`, to stdout."""
+    JSON at `path`, to stdout. With `--fail-on-exceed`, additionally exits
+    with a non-zero code once printing is done: 0 = within thresholds, 1 =
+    usage/parse error, 2 = a threshold was exceeded (see `--fail-on-exceed`'s
+    help text)."""
     from simview import diff as diff_mod
 
     if args.batches is None:
@@ -166,6 +200,16 @@ def run_diff(path: Path, args: argparse.Namespace) -> None:
     if args.json and args.csv:
         logger.error("Error: --json and --csv are mutually exclusive.")
         sys.exit(1)
+    if (
+        args.fail_on_exceed
+        and args.pos_threshold is None
+        and args.rot_threshold_deg is None
+    ):
+        logger.error(
+            "Error: --fail-on-exceed requires --pos-threshold and/or "
+            "--rot-threshold-deg."
+        )
+        sys.exit(1)
 
     try:
         model_data, states_data = diff_mod.load_scene(path)
@@ -178,6 +222,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)
@@ -192,6 +237,45 @@ def run_diff(path: Path, args: argparse.Namespace) -> None:
     else:
         print(text)
 
+    if args.fail_on_exceed:
+        exceeded = any(
+            body["summary"]["first_frame_exceeding_pos_threshold"] is not None
+            or body["summary"]["first_frame_exceeding_rot_threshold"] is not None
+            for body in result["bodies"].values()
+        )
+        if exceeded:
+            sys.exit(2)
+
+
+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
@@ -218,11 +302,13 @@ def build_parser() -> argparse.ArgumentParser:
         help=(
             "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)."
+            "file, 'terrain <file>' to query terrain values at a point, over "
+            "an area, or along a body's trajectory, '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(
@@ -255,7 +341,7 @@ def build_parser() -> argparse.ArgumentParser:
         help=(
             "With 'simview terrain <file>', query terrain value(s) at a single "
             "(x, y) point (bilinear-interpolated). Mutually exclusive with "
-            "--area."
+            "--area and --along-body."
         ),
     )
     parser.add_argument(
@@ -267,7 +353,23 @@ def build_parser() -> argparse.ArgumentParser:
             "With 'simview terrain <file>', query terrain values over a "
             "rectangular area: pass no values for the whole terrain extent, "
             "or exactly 4 values 'XMIN XMAX YMIN YMAX' for a sub-box. Mutually "
-            "exclusive with --point."
+            "exclusive with --point and --along-body."
+        ),
+    )
+    parser.add_argument(
+        "--along-body",
+        type=str,
+        default=None,
+        metavar="BODY",
+        help=(
+            "With 'simview terrain <file>', sample terrain value(s) "
+            "bilinear-interpolated at BODY's (x, y) position in every "
+            "sampled state (e.g. friction/stiffness under a robot's driven "
+            "path). BODY is matched the same way as 'simview diff' --body "
+            "(full label, or any single name inside a rigidly-grouped body). "
+            "With --batches A B, samples both batches' terrains along batch "
+            "A's trajectory instead and reports the delta per layer. "
+            "Mutually exclusive with --point and --area."
         ),
     )
     parser.add_argument(
@@ -301,10 +403,11 @@ def build_parser() -> argparse.ArgumentParser:
         metavar=("A", "B"),
         help=(
             "Two batch indices to compare. Required by 'simview diff <file>'. "
-            "With 'simview terrain <file> --point|--area', switches into "
-            "cross-batch diff mode (value_a/value_b/delta per layer) instead "
-            "of a single-batch query, and takes precedence over --batch if "
-            "both are given."
+            "With 'simview terrain <file> --point|--area|--along-body', "
+            "switches into cross-batch diff mode (value_a/value_b/delta per "
+            "layer) instead of a single-batch query, and takes precedence "
+            "over --batch if both are given. For --along-body, both batches' "
+            "terrains are sampled along batch A's trajectory."
         ),
     )
     parser.add_argument(
@@ -323,7 +426,10 @@ def build_parser() -> argparse.ArgumentParser:
         "--every",
         type=int,
         default=1,
-        help="With 'simview diff <file>', sample every Nth frame (default: 1).",
+        help=(
+            "With 'simview diff <file>' or 'simview terrain <file> "
+            "--along-body', sample every Nth frame (default: 1)."
+        ),
     )
     parser.add_argument(
         "--pos-threshold",
@@ -345,6 +451,27 @@ 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(
+        "--fail-on-exceed",
+        action="store_true",
+        help=(
+            "With 'simview diff <file>', exit with code 2 (after printing the "
+            "normal output) if any diffed body's trajectory exceeds "
+            "--pos-threshold or --rot-threshold-deg; requires at least one of "
+            "them. Exit codes: 0 = within thresholds, 1 = usage/parse error, "
+            "2 = threshold exceeded -- lets scripts/CI tell divergence apart "
+            "from a broken invocation."
+        ),
+    )
     parser.add_argument(
         "--host",
         type=str,
@@ -365,6 +492,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 +595,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