simview 6.2.2__tar.gz → 6.2.3__tar.gz

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

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

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

{simview-6.2.2 → 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.2 → 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:
 
@@ -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.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.2 → 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.2 → 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.2 → 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.2 → simview-6.2.3}/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],
         )

{simview-6.2.2 → simview-6.2.3}/simview/model.py

@@ -13,7 +13,7 @@ logger = logging.getLogger("simview.model")
 
 
 def _encode_blob(array) -> str:
-    """Encode a numpy array as an inline little-endian float32 `__b64__` blob."""
+    """Encode a numpy array as an inline little-endian float32 ``__b64__`` blob."""
     return inline_blob(array.astype("<f4").tobytes())
 
 
@@ -72,6 +72,8 @@ def _validated_visible_ranges(owner: str, ranges: Any) -> list[list[float]] | No
 
 
 class BodyShapeType(StrEnum):
+    """Shape kind of a body or static object (the wire `shape.type`)."""
+
     POINTCLOUD = "pointcloud"
     MESH = "mesh"
     BOX = "box"
@@ -80,6 +82,8 @@ class BodyShapeType(StrEnum):
 
 
 class OptionalBodyStateAttribute(StrEnum):
+    """Optional per-body state fields beyond `bodyTransform` (wire keys)."""
+
     CONTACTS = "contacts"
     VELOCITY = "velocity"
     ANGULAR_VELOCITY = "angularVelocity"
@@ -100,7 +104,7 @@ class TerrainProperty:
     """One arbitrary named per-cell scalar field over the terrain grid (e.g.
     friction, stiffness, or any other user-defined property), stored the same
     way as `SimViewTerrain.height_data` -- a plain nested list, or an opaque
-    `__b64__`-prefixed blob string for compactness."""
+    ``__b64__``-prefixed blob string for compactness."""
 
     data: list[list[float]] | str
     # Value range used by the viewer to normalize the color map (analogous to
@@ -118,6 +122,9 @@ class TerrainProperty:
 
 @dataclass
 class SimViewTerrain:
+    """Terrain heightmap (plus optional normals, named properties and
+    embeddings) over a regular x/y grid, shared or per batch."""
+
     extent_x: float
     extent_y: float
     shape_x: int
@@ -128,10 +135,9 @@ class SimViewTerrain:
     max_y: float
     min_z: float
     max_z: float
-    # These are plain nested lists when constructed directly, but `create()` (and
-    # deserialization from JSON) may instead store an opaque `__b64__`-prefixed
-    # base64 blob string for compactness; `to_json`/`from_dict` pass them through
-    # as-is either way.
+    # `create()` always stores an opaque ``__b64__``-prefixed base64 blob
+    # string; hand-built instances may use plain nested lists. `to_json`/
+    # `from_dict` pass either through as-is.
     height_data: list[list[float]] | str
     # None when the terrain was authored with `compute_normals=False`: the
     # viewer then shades from normals it computes itself, and the file is
@@ -140,9 +146,7 @@ class SimViewTerrain:
     is_singleton: bool
     # Arbitrary named per-cell scalar fields (e.g. "friction", "stiffness", or
     # any other user-defined property), keyed by name -- see `TerrainProperty`.
-    # Adding a new property never requires touching this class or the viewer:
-    # supply it by name in `create()`'s `properties` dict and it becomes
-    # selectable as a terrain color mode automatically.
+    # Any name passed in `create()`'s `properties` becomes a viewer color mode.
     properties: dict[str, TerrainProperty] = field(default_factory=dict)
     # Per-cell K-wide feature vector (e.g. a reduced-dim PCA projection of a
     # learned backbone's features), stored the same way as `normals` (width
@@ -185,7 +189,7 @@ class SimViewTerrain:
         """Reconstruct a SimViewTerrain from the dict produced by `to_json`.
 
         `heightData`/`normals`/each property's `data` are kept in whatever
-        form they were serialized in (plain nested lists or a `__b64__` blob
+        form they were serialized in (plain nested lists or a ``__b64__`` blob
         string) -- decode with `simview.columnar.blob_floats` if you need the
         flat float values back out.
         """
@@ -222,7 +226,7 @@ class SimViewTerrain:
 
     @staticmethod
     def create(
-        heightmap: torch.Tensor,  # ! remember the x,y indexing is assumed to follow torch's "xy" convention, so increasing column index is increasing x coordinate
+        heightmap: torch.Tensor,
         normals: torch.Tensor | None,
         x_lim: tuple[float, float],
         y_lim: tuple[float, float],
@@ -231,6 +235,17 @@ class SimViewTerrain:
         property_bounds: dict[str, tuple[float, float]] | None = None,
         embedding_map: torch.Tensor | None = None,
     ) -> "SimViewTerrain":
+        """Build a terrain from batched tensors, encoding each field as a blob.
+
+        `heightmap` is `(B, Dy, Dx)` with torch's "xy" indexing: the column
+        index increases with x. `normals` is `(B, 3, Dy, Dx)` or None,
+        `properties` maps names to `(B, Dy, Dx)` maps, and `embedding_map` is
+        `(B, K, Dy, Dx)`. `x_lim`/`y_lim` are the `(min, max)` world extents.
+        `property_bounds` optionally pins a property's color-scale range;
+        otherwise the map's own data range is used. Every grid must match
+        the heightmap's. Batch broadcasting is the caller's job (see
+        `SimulationScene.create_terrain`).
+        """
         if heightmap.ndim != 3:
             raise ValueError(
                 f"Heightmap must include a batch dimension (ndim=3); got ndim={heightmap.ndim}."
@@ -333,6 +348,9 @@ class SimViewTerrain:
 
 @dataclass
 class SimViewBody:
+    """A dynamic body: its shape, look, optional parent attachment and the
+    optional state attributes its states carry."""
+
     name: str
     shape: dict
     available_attributes: list[OptionalBodyStateAttribute] | None = None
@@ -382,6 +400,7 @@ class SimViewBody:
     def set_available_attributes(
         self, available_attributes: list[str | OptionalBodyStateAttribute]
     ) -> None:
+        """Set the optional attributes this body's states carry (once only)."""
         if self.available_attributes is not None:
             raise ValueError("Available attributes already set")
         self.available_attributes = [
@@ -393,7 +412,8 @@ class SimViewBody:
 
     @staticmethod
     def _create_shape_dict(body_type: BodyShapeType, **kwargs) -> dict:
-        """Helper to create the shape dictionary, converting tensors."""
+        """Build a shape dict, encoding multi-element tensors as blobs and
+        validating required primitive dimensions."""
         shape_dict: dict[str, Any] = {"type": body_type.value}
         for key, value in kwargs.items():
             if isinstance(value, torch.Tensor):
@@ -430,6 +450,10 @@ class SimViewBody:
         visible_ranges: list | None = None,
         **kwargs,
     ) -> "SimViewBody":
+        """Build a body of `body_type`; `**kwargs` are its shape parameters
+        (e.g. `hx`/`hy`/`hz` for a box, `radius` for a sphere, `radius`/
+        `height` for a cylinder, `vertices`/`faces` for a mesh). The other
+        parameters are as on `SimulationScene.create_body`."""
         shape_dict = SimViewBody._create_shape_dict(body_type, **kwargs)
         if local_transform is not None and hasattr(local_transform, "tolist"):
             local_transform = local_transform.tolist()
@@ -453,6 +477,7 @@ class SimViewBody:
     def create_box(
         name: str, hx: float, hy: float, hz: float, **kwargs
     ) -> "SimViewBody":
+        """Build a box body with half-extents `hx`/`hy`/`hz`."""
         return SimViewBody.create(
             name, BodyShapeType.BOX, hx=hx, hy=hy, hz=hz, **kwargs
         )
@@ -465,13 +490,15 @@ class SimViewBody:
         embedding: torch.Tensor | None = None,
         **kwargs,
     ) -> "SimViewBody":
-        """`color` (N, 3) in [0, 1] is an optional static per-point RGB color,
+        """Build a point-cloud body from `(N, 3)` `points`.
+
+        `color` (N, 3) in [0, 1] is an optional static per-point RGB color,
         used by the viewer for vertex-colored rendering. `embedding` (N, K) is
         an optional per-point K-wide feature vector (e.g. a reduced-dim PCA
         projection of a learned backbone's features) enabling the viewer's
         click-to-similarity color mode: cosine similarity to a clicked point,
-        computed entirely in-browser from this data. Both round-trip through
-        the existing generic `__b64__` blob mechanism -- no new wire format."""
+        computed entirely in-browser from this data. Both are stored as
+        ``__b64__`` blobs."""
         if points.ndim != 2 or points.shape[1] != 3:
             raise ValueError(
                 f"points must have shape (N, 3); got {tuple(points.shape)}."
@@ -504,6 +531,7 @@ class SimViewBody:
     def create_mesh(
         name: str, vertices: torch.Tensor, faces: torch.Tensor, **kwargs
     ) -> "SimViewBody":
+        """Build a mesh body from `vertices` `(V, 3)` and `faces` `(F, 3)`."""
         return SimViewBody.create(
             name, BodyShapeType.MESH, vertices=vertices, faces=faces, **kwargs
         )
@@ -554,6 +582,9 @@ class SimViewBody:
 
 @dataclass
 class SimViewStaticObject:
+    """A static (never-moving) object: one shape shared by every batch
+    (singleton) or one shape per batch."""
+
     name: str
     is_singleton: bool
     shape: dict | None = None  # Used if is_singleton is True
@@ -578,9 +609,9 @@ class SimViewStaticObject:
         visible_ranges: list | None = None,
         **kwargs,
     ) -> "SimViewStaticObject":
-        shape_dict = SimViewBody._create_shape_dict(
-            shape_type, **kwargs
-        )  # Reuse helper
+        """Build a static object shared by every batch; `**kwargs` are the
+        shape parameters, as on `SimViewBody.create`."""
+        shape_dict = SimViewBody._create_shape_dict(shape_type, **kwargs)
         return SimViewStaticObject(
             name=name,
             is_singleton=True,
@@ -595,16 +626,12 @@ class SimViewStaticObject:
         shapes_kwargs: list[dict[str, Any]],
         visible_ranges: list | None = None,
     ) -> "SimViewStaticObject":
-        """
-        Creates a batched static object where all instances share the same shape type.
-
-        Args:
-            name: The name of the static object group.
-            shape_type: The BodyShapeType common to all instances in the batch.
-            shapes_kwargs: A list of dictionaries, where each dictionary contains the
-                           keyword arguments for creating the shape of one instance
-                           in the batch (e.g., [{'hx': 0.1, 'hy': 0.1, 'hz': 0.1}, {'hx': 0.2, ...}]).
-                           The length of this list must match the batch size.
+        """Build a static object with one shape per batch, all of `shape_type`.
+
+        `name` names the group. `shapes_kwargs` holds one dict of shape
+        keyword arguments per batch instance (e.g. `[{"hx": 0.1, "hy": 0.1,
+        "hz": 0.1}, {"hx": 0.2, ...}]`); its length must match the model's
+        batch size.
         """
         shapes_list = []
         if not shapes_kwargs:
@@ -616,9 +643,7 @@ class SimViewStaticObject:
                 raise ValueError(
                     "Do not include 'type' in shapes_kwargs; use the shape_type argument."
                 )
-            shapes_list.append(
-                SimViewBody._create_shape_dict(shape_type, **kwargs)
-            )  # Reuse helper
+            shapes_list.append(SimViewBody._create_shape_dict(shape_type, **kwargs))
         return SimViewStaticObject(
             name=name,
             is_singleton=False,
@@ -658,7 +683,7 @@ class SimViewPolyline:
     """A world-space polyline: a fixed `points` list (a route), and/or a
     per-frame `frames` blob (a replanned local path) of shape
     `(T, B, max_vertices, 3)` float32, trailing NaN rows padding each frame
-    up to `max_vertices`. Model-level by design (no new states field), so it
+    up to `max_vertices`. Model-level by design (not a states field), so it
     rides the generic blob machinery; not supported in live mode."""
 
     name: str
@@ -723,6 +748,7 @@ class SimViewPolyline:
 
     @classmethod
     def from_dict(cls, d: dict) -> "SimViewPolyline":
+        """Reconstruct a SimViewPolyline from the dict produced by `to_json`."""
         try:
             name = d["name"]
         except KeyError as e:
@@ -774,6 +800,7 @@ class SimViewEpisode:
 
     @classmethod
     def from_dict(cls, d: dict) -> "SimViewEpisode":
+        """Reconstruct a SimViewEpisode from the dict produced by `to_json`."""
         try:
             start_index = d["startIndex"]
         except (KeyError, TypeError) as e:
@@ -815,6 +842,9 @@ def _validate_parent_ref(name: str, parent: str | None, known_bodies: dict) -> N
 
 @dataclass
 class SimViewModel:
+    """The static part of a scene: batch layout, terrain, bodies, static
+    objects, polylines and metadata (the wire `model` section)."""
+
     batch_size: int
     scalar_names: list[str]
     # None means "not known"; the viewer then infers it from consecutive
@@ -859,12 +889,15 @@ class SimViewModel:
         _validate_episodes(self.episodes)
 
     def add_body(self, body: SimViewBody) -> None:
+        """Add `body`; its name must be new and its parent already added."""
         if body.name in self.bodies:
             raise ValueError(f"Dynamic body {body.name} already exists")
         _validate_parent_ref(body.name, body.parent, self.bodies)
         self.bodies[body.name] = body
 
     def add_static_object(self, static_object: SimViewStaticObject) -> None:
+        """Add `static_object`; its name must be new and a batched one needs
+        one shape per batch."""
         if static_object.name in self.static_objects:
             raise ValueError(f"Static object {static_object.name} already exists")
         if not static_object.is_singleton:
@@ -880,6 +913,7 @@ class SimViewModel:
         self.static_objects[static_object.name] = static_object
 
     def add_polyline(self, polyline: SimViewPolyline) -> None:
+        """Add `polyline`; its name must be new."""
         if polyline.name in self.polylines:
             raise ValueError(f"Polyline {polyline.name} already exists")
         self.polylines[polyline.name] = polyline
@@ -914,9 +948,11 @@ class SimViewModel:
     def from_dict(cls, d: dict) -> "SimViewModel":
         """Reconstruct a SimViewModel from the dict produced by `to_json`.
 
-        Centralizes parsing of the wire format: terrain, bodies and static
-        objects are all rebuilt via their own `from_dict`, keyed by name so
-        `add_body`/`add_static_object`'s uniqueness checks stay meaningful.
+        Centralizes parsing of the wire format: each part is rebuilt via its
+        own `from_dict`. Bodies are checked for duplicate names and parent
+        references inline; static objects and polylines go through
+        `add_static_object`/`add_polyline`, so they're validated exactly as
+        when authoring.
         """
         try:
             batch_size = d["simBatches"]
@@ -962,4 +998,5 @@ class SimViewModel:
 
     @property
     def is_complete(self) -> bool:
+        """True once a terrain is set (required to save or show)."""
         return self.terrain is not None

{simview-6.2.2 → simview-6.2.3}/simview/remote.py

@@ -121,7 +121,7 @@ def is_remote_spec(spec: str) -> bool:
 
 
 def cache_dir() -> Path:
-    """Root of simview's on-disk cache, honouring XDG_CACHE_HOME."""
+    """Root of simview's on-disk cache, honoring XDG_CACHE_HOME."""
     base = os.environ.get("XDG_CACHE_HOME")
     root = Path(base) if base else Path.home() / ".cache"
     return root / CACHE_DIR