simview 6.2.2__tar.gz → 6.3.0__tar.gz

{simview-6.2.2/simview.egg-info → simview-6.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simview
-Version: 6.2.2
+Version: 6.3.0
 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
@@ -130,8 +130,8 @@ source .venv/bin/activate
 
 SimView is distributed under the [BSD 3-Clause License](LICENSE). The web interface
 vendors [uPlot](https://github.com/leeoniya/uPlot) and [three.js](https://github.com/mrdoob/three.js)
-(both MIT licensed) under
-`simview/static/lib/` so the viewer works fully offline — see the
+(both MIT licensed) under `simview/static/lib/`, and the matplotlib colour-map tables
+(`js-colormaps.js`) under `simview/static/js/vendor/`, 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-6.2.2 → simview-6.3.0}/README.md

@@ -99,8 +99,8 @@ source .venv/bin/activate
 
 SimView is distributed under the [BSD 3-Clause License](LICENSE). The web interface
 vendors [uPlot](https://github.com/leeoniya/uPlot) and [three.js](https://github.com/mrdoob/three.js)
-(both MIT licensed) under
-`simview/static/lib/` so the viewer works fully offline — see the
+(both MIT licensed) under `simview/static/lib/`, and the matplotlib colour-map tables
+(`js-colormaps.js`) under `simview/static/js/vendor/`, 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-6.2.2 → simview-6.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simview"
-version = "6.2.2"
+version = "6.3.0"
 readme = "README.md"
 requires-python = ">=3.12"
 license = "BSD-3-Clause"

{simview-6.2.2 → simview-6.3.0}/simview/__main__.py

@@ -1,3 +1,5 @@
+"""The `simview` command-line interface."""
+
 import argparse
 import gzip
 import json
@@ -295,9 +297,18 @@ def save_merged(
         logger.error("Error: --save-merged requires at least 2 input files to merge.")
         sys.exit(1)
 
+    from simview.columnar import columnarize_states, inline_blob
     from simview.merge import merge_simulation_files
 
     merged = merge_simulation_files(paths, selections)
+    # Pack the merged states the same way SimulationScene.save does: merge
+    # decodes every blob to plain lists, so dumping it directly would write
+    # the fat legacy per-frame layout. Falls back silently when numpy is
+    # unavailable or the states are too irregular (columnarize_states
+    # returns None).
+    columnar_states = columnarize_states(merged["states"], merged["model"], inline_blob)
+    if columnar_states is not None:
+        merged["states"] = columnar_states
     payload = json.dumps(merged).encode("utf-8")
     if out_path.suffix == ".gz":
         payload = gzip.compress(payload, compresslevel=1)
@@ -370,7 +381,12 @@ def _add_host_port_flags(sp: argparse.ArgumentParser) -> None:
         "--host",
         type=str,
         default="127.0.0.1",
-        help="Host/interface for the server to bind to (default: 127.0.0.1).",
+        help=(
+            "Host/interface for the server to bind to (default: 127.0.0.1). "
+            "Note: the server has no authentication, so binding to a "
+            "non-loopback address exposes the scene data to everyone who can "
+            "reach it."
+        ),
     )
     sp.add_argument(
         "--port",
@@ -436,8 +452,8 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="PATH",
         help=(
             "Merge the given input files and write the result to PATH instead of "
-            "launching the viewer. Requires at least 2 input files. Gzips the "
-            "output if PATH ends in .gz."
+            "launching the viewer. Requires at least 2 input files, or 1 with a "
+            "'#<batches>' selection. Gzips the output if PATH ends in .gz."
         ),
     )
     _add_remote_flags(view)
@@ -654,9 +670,8 @@ def main():
     _configure_logging()
     argv = sys.argv[1:]
 
-    # Checked first, and unconditionally, to match every other flag/subcommand
-    # combination -- mirrors the old flat parser, where --version short-circuited
-    # before any other validation ran.
+    # Checked before parsing so --version works alongside any other
+    # arguments, without tripping their validation.
     if "--version" in argv:
         print(_package_version())
         return

{simview-6.2.2 → simview-6.3.0}/simview/columnar.py

@@ -2,7 +2,7 @@
 covering a whole trajectory, instead of thousands of small per-frame objects.
 
 This is both a **wire** format (served by `simview/server.py`, consumed by
-`static/js/components/StateStore.js`) and, since it became first-class, an
+`static/js/components/StateStore.js`) and an
 **on-disk** format (`SimulationScene.save(columnar=True)`). The two are the
 same document; only how a blob is referenced differs:
 
@@ -15,7 +15,7 @@ That symmetry is the whole point: a columnar file needs no repacking at all
 to be served, and `columnar.rewrite_blobs` (shared by `server.py`) does the
 rewriting for free.
 
-Shape (see README.md "JSON Format Specification" for the authoritative spec)::
+Shape (see docs/dev/json-format.md for the authoritative spec)::
 
     {"version": 4,
      "times": [t0, t1, ...],                              # length T
@@ -171,7 +171,8 @@ def _decode_state_field_rows(value, width: int, batch_size: int):
     Mirrors the shapes SimViewBodyState.to_json()/add_trajectory produce: a
     ``__b64__`` blob is always batch_size rows of `width` floats; a plain list
     is either already nested (one row per batch) or, for a single-batch scene,
-    a flat list of `width` floats (see README "Authoring whole trajectories").
+    a flat list of `width` floats (see docs/dev/json-format.md "Authoring whole
+    trajectories").
     """
     assert np is not None
     if isinstance(value, str):
@@ -221,7 +222,7 @@ def columnarize_states(states_data: list, model_data: dict | None, register_blob
     Strict by design: this trades a bit of coverage (an inconsistent scene just
     doesn't get the win) for never risking a subtly wrong repack. The one
     deliberate exception is `contacts`, which may legitimately come and go per
-    frame (see README) without disqualifying the rest of the scene.
+    frame (see docs/dev/json-format.md) without disqualifying the rest of the scene.
     """
     if np is None or not states_data:
         return None

{simview-6.2.2 → simview-6.3.0}/simview/diff.py

@@ -3,9 +3,9 @@
 ground truth vs. prediction, baseline vs. post-adaptation) actually track
 each other.
 
-Deliberately dependency-free (stdlib only: json, base64, struct, math via
-its imports) so it works on a base install without the `authoring` extra
-(torch/numpy) -- see CLAUDE.md. Shares its blob-decoding and
+Deliberately dependency-free (stdlib only) so it works on a base install
+without the `authoring` extra (torch/numpy) -- see "Lazy imports" in
+docs/dev/architecture.md. Shares its blob-decoding and
 body-resolution helpers with `simview/terrain.py`/`simview/info.py` via
 `simview.columnar`/`simview.utils`, which are stdlib-only on this read path.
 
@@ -36,8 +36,8 @@ _MAX_SERIES_ROWS = 10
 def _build_body_meta(model_data: dict, state_names: list) -> dict[str, dict]:
     """`name -> {"parent", "localTransform"}` for every body, from the model's
     `bodies` section. Bodies that appear in the states but not in the model are
-    added as parentless roots, so a hand-edited or third-party file still
-    diffs exactly as it did before parent resolution existed."""
+    added as parentless roots, so a hand-edited or third-party file whose
+    model omits them still diffs."""
     meta: dict[str, dict] = {}
     for entry in model_data.get("bodies") or []:
         name = entry.get("name")
@@ -54,8 +54,8 @@ def _build_body_meta(model_data: dict, state_names: list) -> dict[str, dict]:
 
 def _topo_sort_bodies(meta: dict[str, dict]) -> list[str]:
     """Order body names so every parent precedes its children. Independent
-    stdlib port of `static/js/utils/bodyTransforms.js`'s `topoSortBodies` (see
-    module docstring on why these aren't shared); each body has at most one
+    stdlib port of `static/js/utils/bodyTransforms.js`'s `topoSortBodies` (the
+    viewer's JS can't be shared with the CLI); each body has at most one
     parent, so a DFS post-order walk suffices."""
     order: list[str] = []
     status: dict[str, str] = {}
@@ -374,6 +374,9 @@ def compute_trajectory_diff(
 
 
 def format_diff_text(result: dict) -> str:
+    """Render `compute_trajectory_diff`'s output as a skimmable text report,
+    capping each body's per-frame table (use `--json`/`--csv` for the full
+    series)."""
     lines = [
         f"Batches {result['batch_a']} vs {result['batch_b']}  every={result['every']}"
     ]

{simview-6.2.2 → simview-6.3.0}/simview/info.py

@@ -1,17 +1,16 @@
 """Structural summary of a scene JSON file, for `simview info` and for coding
 agents inspecting simview-generated data files.
 
-Deliberately dependency-free (stdlib only: json, gzip via
-`simview.utils.read_maybe_gzipped_bytes`, base64) so it works on a base
-install without the `authoring` extra (torch/numpy) -- see
-CLAUDE.md. Does not import `simview.model`/`simview.server`: the former
-pulls in torch at module scope, the latter fastapi/uvicorn just to
-reach a numpy-gated helper -- both wrong layering for a lightweight
-inspection tool. Shares its blob-decoding/body-label helpers with
+Deliberately dependency-free (stdlib only: json, gzip, base64) so it works on a base
+install without the `authoring` extra (torch/numpy) -- see "Lazy imports" in
+docs/dev/architecture.md. Does not import `simview.model`/`simview.server`:
+the former pulls in torch at module scope, the latter fastapi/uvicorn --
+both wrong layering for a lightweight inspection tool. Shares its blob-decoding/body-label helpers with
 `simview/terrain.py`/`simview/diff.py` via `simview.columnar`/`simview.utils`,
 which are stdlib-only on this read path.
 """
 
+import gzip
 import json
 from pathlib import Path
 from typing import Any
@@ -24,7 +23,7 @@ from simview.columnar import (
     is_blob,
     is_columnar,
 )
-from simview.utils import body_label, cap, human_bytes, read_maybe_gzipped_bytes
+from simview.utils import body_label, cap, human_bytes
 
 _MAX_DETAIL_ITEMS = 20
 _LARGE_FILE_BYTES = 100_000_000
@@ -219,9 +218,12 @@ def _summarize_states(states, model: dict | None, warnings: list[str]) -> dict:
 
     scalars_summary = {}
     for name in scalar_names:
-        missing = [i for i, s in enumerate(states) if name not in s]
+        # One pass per scalar: collect missing-frame indices and check
+        # lengths in the same walk.
+        missing = []
         for i, s in enumerate(states):
             if name not in s:
+                missing.append(i)
                 continue
             value = s[name]
             length = len(value) if isinstance(value, list) else 1
@@ -241,8 +243,8 @@ def _summarize_states(states, model: dict | None, warnings: list[str]) -> dict:
 
     # Per-body walk, mirroring columnar.py's columnarize_states structural
     # checks (field-set consistency, first-appearance-at-frame-0, no
-    # dropping out) but never decoding/shaping blob values -- see module
-    # docstring.
+    # dropping out) without numpy: blobs are decoded only to count their
+    # floats, never shaped into arrays.
     body_order: list = []
     body_first_frame: dict = {}
     body_name_value: dict = {}
@@ -396,7 +398,10 @@ def summarize_scene(path: str | Path) -> dict:
     path = Path(path)
     raw = path.read_bytes()
     gzipped = raw[:2] == b"\x1f\x8b"
-    data = json.loads(read_maybe_gzipped_bytes(path))
+    # Decompress from the bytes already in hand rather than calling
+    # read_maybe_gzipped_bytes(path), which would read the whole file a
+    # second time -- scene files are often hundreds of MB.
+    data = json.loads(gzip.decompress(raw) if gzipped else raw)
     if not isinstance(data, dict):
         raise ValueError(
             "scene file must contain a JSON object with 'model'/'states' keys"

{simview-6.2.2 → simview-6.3.0}/simview/launcher.py

@@ -1,3 +1,5 @@
+"""Blocking launch of the viewer for a scene object or a scene file."""
+
 import gc
 import logging
 from pathlib import Path
@@ -11,15 +13,19 @@ logger = logging.getLogger("simview.launcher")
 
 
 class SimViewLauncher:
+    """Serve a scene in the foreground until interrupted, then free it.
+
+    The blocking counterpart to `SimulationScene.show()`'s background viewer.
+    """
+
     def __init__(
         self,
         source: SimulationScene | str | Path,
     ) -> None:
-        """
-        Initializes the visualizer.
-        - If source is a SimulationScene: it is handed to the server in memory (no
-          temporary file), and its internal data is cleared after the server stops.
-        - If source is a path: it is used directly.
+        """Validate `source`, a `SimulationScene` or a path to a scene file.
+
+        A scene is handed to the server in memory (no temporary file) and its
+        internal data is cleared once the server stops; a path is served as is.
         """
         self._scene: SimulationScene | None = None
         self._sim_file_path: Path | None = None
@@ -47,9 +53,7 @@ class SimViewLauncher:
             )
 
     def launch(self, host: str = "127.0.0.1", preferred_port: int = 5420) -> None:
-        """
-        Launches the SimViewServer, then clears the in-memory scene (if any).
-        """
+        """Run the server until it stops, then clear the in-memory scene (if any)."""
         try:
             if self._scene is not None:
                 # Serialize the scene once and hand it to the server directly,
@@ -62,9 +66,7 @@ class SimViewLauncher:
                 server = SimViewServer(data=data)
                 server.run(host=host, port=find_free_port(host, preferred_port))
             else:
-                # __init__ guarantees exactly one of self._scene / self._sim_file_path
-                # is set (it raises otherwise), so if self._scene is None here,
-                # self._sim_file_path must have been set.
+                # __init__ sets exactly one of _scene / _sim_file_path.
                 assert self._sim_file_path is not None
                 SimViewServer.start(
                     sim_path=self._sim_file_path,
@@ -80,9 +82,7 @@ class SimViewLauncher:
             self.cleanup()
 
     def cleanup(self) -> None:
-        """
-        Clears the in-memory scene's data. Safe to call multiple times.
-        """
+        """Clear the in-memory scene's data. Safe to call multiple times."""
         if self._scene is not None:
             logger.info(
                 "SimViewLauncher: Clearing source SimulationScene internal data..."

{simview-6.2.2 → simview-6.3.0}/simview/live.py

@@ -1,3 +1,5 @@
+"""Stream a running simulation to the browser viewer over WebSocket."""
+
 import asyncio
 import logging
 import queue
@@ -89,6 +91,7 @@ class LiveViewer:
 
     @property
     def url(self) -> str:
+        """Base URL of the live viewer."""
         return self._threaded.url
 
     def push_state(self, time, body_states, scalar_values=None) -> None:

{simview-6.2.2 → simview-6.3.0}/simview/merge.py

@@ -313,11 +313,14 @@ def _validate_doc(doc: dict, label: str) -> None:
 def _expand_batched(
     values: list | str, is_singleton: bool, batch_size: int, field: str, label: str
 ) -> list | str:
-    # b64 blobs pass through untouched: _decode_per_batch resolves their row
-    # layout by length (one shared row for a deduplicated singleton terrain,
-    # or batch_size rows for per-batch / legacy broadcast-singleton data) and
-    # replicates the shared case itself. Only plain lists (where the row count
-    # is directly observable) may need broadcasting below.
+    """Broadcast a plain-list terrain field to `batch_size` rows.
+
+    ``__b64__`` blobs pass through untouched: `_decode_per_batch` resolves
+    their row layout by length (one shared row for a deduplicated singleton
+    terrain, or `batch_size` rows for per-batch / legacy broadcast-singleton
+    data) and replicates the shared case itself. Only plain lists, where the
+    row count is directly observable, may need broadcasting here.
+    """
     if is_blob(values):
         return values
 
@@ -633,8 +636,8 @@ def _merge_terrain(
             )
 
     def _bound(name: str, key: str, pick) -> float | None:
-        # A null bound means "unknown" (json-format.md), and one unknown
-        # makes the merged range unknown too.
+        # A null bound means "unknown", and one unknown makes the merged
+        # range unknown too.
         values = [t["properties"][name].get(key) for t in terrains]
         return None if any(v is None for v in values) else pick(values)
 
@@ -684,6 +687,13 @@ def _merge_states(
     labels: list[str],
     selections: list[list[int] | None],
 ) -> list[dict]:
+    """Build the merged per-frame states on the first file's timeline.
+
+    Every other file contributes its nearest-in-time frame (zero-order hold).
+    Per-body fields and scalars are concatenated in file order, keeping only
+    each file's selected batches; rigidly attached bodies are skipped, since
+    they never appear in states.
+    """
     ref_times = [s["time"] for s in states_list[0]]
     times_by_file = [[s["time"] for s in states] for states in states_list]
     total_batches = sum(_output_sizes(batch_sizes, selections))
@@ -926,7 +936,7 @@ def merge_simulation_files(
     if dropped:
         logger.warning(
             "Dropping episode boundaries from %s: they index their own "
-            "timeline, and the merged scene uses '%s'’s timeline.",
+            "timeline, and the merged scene uses '%s's timeline.",
             ", ".join(f"'{label}'" for label in dropped),
             labels[0],
         )