simview 6.2.1__tar.gz → 6.2.3__tar.gz

{simview-6.2.1/simview.egg-info → simview-6.2.3}/PKG-INFO

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

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

{simview-6.2.1 → simview-6.2.3}/simview/__main__.py

@@ -1,3 +1,5 @@
+"""The `simview` command-line interface."""
+
 import argparse
 import gzip
 import json
@@ -436,8 +438,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 +656,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.1 → simview-6.2.3}/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:
 
@@ -12,10 +12,10 @@ same document; only how a blob is referenced differs:
   URL the browser fetches in parallel as a `Float32Array`.
 
 That symmetry is the whole point: a columnar file needs no repacking at all
-to be served, and `server.py`'s existing `extract_blobs` walker does the
+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
@@ -122,6 +122,29 @@ def encode_floats(flat) -> str:
     return inline_blob(struct.pack(f"<{len(flat)}f", *flat))
 
 
+def batch_rows(flat: list[float], per_row: int, batch_size: int) -> list | None:
+    """Split a decoded blob into `batch_size` rows of `per_row` floats: either
+    one row shared by every batch (replicated) or one row per batch. None if
+    `flat` is neither length -- callers raise their own error."""
+    if len(flat) == per_row:
+        return [flat] * batch_size
+    if len(flat) == batch_size * per_row:
+        return [flat[i : i + per_row] for i in range(0, len(flat), per_row)]
+    return None
+
+
+def rewrite_blobs(obj: Any, register_blob) -> None:
+    """Replace, in place, every inline ``__b64__`` blob string nested anywhere
+    in `obj` with `register_blob(raw_bytes)`."""
+    if not isinstance(obj, (dict, list)):
+        return
+    for k, v in obj.items() if isinstance(obj, dict) else enumerate(obj):
+        if is_blob(v):
+            obj[k] = register_blob(blob_bytes(v))
+        else:
+            rewrite_blobs(v, register_blob)
+
+
 def decode_transform_row(value: Any, batch_size: int, batch_idx: int) -> list[float]:
     """Decode one state's `bodyTransform` field value for a single batch into
     a flat 7-element `[x, y, z, w, qx, qy, qz]` row, without numpy.
@@ -134,8 +157,6 @@ def decode_transform_row(value: Any, batch_size: int, batch_idx: int) -> list[fl
     if len(flat) == batch_size * width:
         start = batch_idx * width
         return flat[start : start + width]
-    if len(flat) == width and batch_size == 1:
-        return flat
     raise ValueError(
         f"bodyTransform has {len(flat)} floats; expected {width} "
         f"(batch_size=1, flat) or {batch_size * width} "
@@ -150,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):
@@ -200,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
@@ -451,23 +473,17 @@ def write_static_bundle(data: dict, directory) -> None:
     (out / "blob").mkdir(parents=True, exist_ok=True)
     count = 0
 
-    def externalize(obj):
+    def write_blob(raw: bytes) -> str:
         nonlocal count
-        if not isinstance(obj, (dict, list)):
-            return
-        for k, v in obj.items() if isinstance(obj, dict) else enumerate(obj):
-            if is_blob(v):
-                (out / "blob" / str(count)).write_bytes(blob_bytes(v))
-                obj[k] = f"/blob/{count}"
-                count += 1
-            else:
-                externalize(v)
-
-    externalize(data["model"])
+        (out / "blob" / str(count)).write_bytes(raw)
+        count += 1
+        return f"/blob/{count - 1}"
+
+    rewrite_blobs(data["model"], write_blob)
     # The viewer only resolves /blob/ URLs in the model and a columnar states
     # object; a legacy per-frame array's inline __b64__ fields are decoded
     # in place, so they must stay inline.
     if is_columnar(data["states"]):
-        externalize(data["states"])
+        rewrite_blobs(data["states"], write_blob)
     for name in ("model", "states"):
         (out / f"{name}.json").write_text(json.dumps(data[name]))

{simview-6.2.1 → simview-6.2.3}/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.1 → simview-6.2.3}/simview/info.py

@@ -3,11 +3,10 @@ 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
+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.
 """
@@ -241,8 +240,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 = {}

{simview-6.2.1 → simview-6.2.3}/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.1 → simview-6.2.3}/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.1 → simview-6.2.3}/simview/merge.py

@@ -27,6 +27,7 @@ import orjson
 
 from .columnar import (
     STATE_FIELD_WIDTHS,
+    batch_rows,
     blob_floats,
     encode_floats,
     expand_columnar_states,
@@ -212,12 +213,8 @@ def _decode_per_batch(
         return value
     flat = blob_floats(value)
     per_row = resolution * (vector_width or 1)
-    if len(flat) == per_row:
-        # One shared row (deduplicated singleton terrain).
-        chunks = [list(flat)] * batch_size
-    elif len(flat) == batch_size * per_row:
-        chunks = [list(flat[i : i + per_row]) for i in range(0, len(flat), per_row)]
-    else:
+    chunks = batch_rows(flat, per_row, batch_size)
+    if chunks is None:
         raise ValueError(
             f"terrain blob has {len(flat)} floats; expected {per_row} (one "
             f"shared row) or {batch_size * per_row} ({batch_size} batches "
@@ -316,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
 
@@ -636,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)
 
@@ -679,15 +679,6 @@ def _nearest_index(sorted_times: list[float], t: float) -> int:
     return i - 1 if (t - before) <= (after - t) else i
 
 
-def _state_body_lookup(
-    states: list[dict], file_idx: int, state_idx: int, cache: dict
-) -> dict[str, dict]:
-    key = (file_idx, state_idx)
-    if key not in cache:
-        cache[key] = bodies_by_name(states[state_idx].get("bodies"))
-    return cache[key]
-
-
 def _merge_states(
     states_list: list[list[dict]],
     batch_sizes: list[int],
@@ -696,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))
@@ -731,7 +729,11 @@ def _merge_states(
                 zip(states_list, batch_sizes, selections)
             ):
                 state_idx = state_idx_by_file[file_idx]
-                lookup = _state_body_lookup(states, file_idx, state_idx, lookup_cache)
+                lookup = lookup_cache.get((file_idx, state_idx))
+                if lookup is None:
+                    lookup = lookup_cache[(file_idx, state_idx)] = bodies_by_name(
+                        states[state_idx].get("bodies")
+                    )
                 body_state = lookup.get(name)
                 if body_state is None:
                     raise ValueError(
@@ -934,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],
         )