simview 6.1.2__tar.gz → 6.2.0__tar.gz

{simview-6.1.2/simview.egg-info → simview-6.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simview
-Version: 6.1.2
+Version: 6.2.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

{simview-6.1.2 → simview-6.2.0}/pyproject.toml

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

{simview-6.1.2 → simview-6.2.0}/simview/__main__.py

@@ -14,9 +14,9 @@ logger = logging.getLogger("simview.cli")
 
 _logging_configured = False
 
-# Subcommands with their own scoped flags. "view" (bare `simview <file>...`)
-# has no keyword of its own -- see main()'s routing.
-_SUBCOMMANDS = ("info", "diff", "terrain", "render", "clear")
+# Subcommands with their own scoped flags. "view" also works bare
+# (`simview <file>...`) -- see main()'s routing.
+_SUBCOMMANDS = ("view", "info", "diff", "terrain", "render", "clear", "static-viewer")
 
 
 def _configure_logging() -> None:
@@ -71,6 +71,20 @@ def clear_cache():
     logger.info("Cache cleared.")
 
 
+def export_static_viewer(directory: Path) -> None:
+    """Copy the viewer page (`index.html` + `static/`) into `directory`, so a
+    site can host it next to `SimulationScene.save_static` bundles and open
+    `index.html#data=<bundle url>` with no SimView server. The page's asset
+    URLs are page-relative already, so the files are copied verbatim."""
+    from importlib.resources import files
+
+    package = files("simview")
+    directory.mkdir(parents=True, exist_ok=True)
+    shutil.copy(str(package / "templates" / "index.html"), directory / "index.html")
+    shutil.copytree(str(package / "static"), directory / "static", dirs_exist_ok=True)
+    logger.info("Static viewer written to %s", directory)
+
+
 def run_info(path: Path, as_json: bool) -> None:
     """Print a structural summary of the scene JSON at `path` to stdout."""
     from simview.info import format_text, summarize_scene
@@ -287,7 +301,13 @@ def save_merged(
     payload = json.dumps(merged).encode("utf-8")
     if out_path.suffix == ".gz":
         payload = gzip.compress(payload, compresslevel=1)
-    out_path.write_bytes(payload)
+    try:
+        # Like SimulationScene.save: create missing parent directories.
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_bytes(payload)
+    except OSError as e:
+        logger.error("Error: cannot write merged scene to '%s': %s", out_path, e)
+        sys.exit(1)
     logger.info("Merged scene written to %s", out_path)
 
 
@@ -618,6 +638,15 @@ def build_parser() -> argparse.ArgumentParser:
 
     sub.add_parser("clear", help="Remove simview's on-disk cache.")
 
+    static_viewer = sub.add_parser(
+        "static-viewer",
+        help=(
+            "Copy the viewer page (index.html + static/) to DIR, to host it "
+            "as plain files next to save_static() bundles (open with #data=)."
+        ),
+    )
+    static_viewer.add_argument("directory", type=Path, metavar="DIR")
+
     return parser
 
 
@@ -638,9 +667,9 @@ def main():
         parser.print_help()
         sys.exit(1)
 
-    # No subcommand keyword names the bare `simview <file>...` view form, so
-    # anything that isn't a known subcommand (or -h/--help, which the top-level
-    # parser should still handle itself) is routed to the hidden "view" one.
+    # The bare `simview <file>...` view form has no keyword, so anything that
+    # isn't a known subcommand (or -h/--help, which the top-level parser
+    # should still handle itself) is routed to "view".
     if argv[0] not in _SUBCOMMANDS and argv[0] not in ("-h", "--help"):
         argv = ["view", *argv]
 
@@ -664,6 +693,9 @@ def main():
     if args.command == "clear":
         clear_cache()
         return
+    if args.command == "static-viewer":
+        export_static_viewer(args.directory)
+        return
 
     single_file_commands = {
         "info": lambda path, args: run_info(path, as_json=args.json),

{simview-6.1.2 → simview-6.2.0}/simview/columnar.py

@@ -93,6 +93,10 @@ def blob_floats(value: Any) -> list[float]:
         if not value.startswith(BLOB_PREFIX):
             raise ValueError(f"expected a {BLOB_PREFIX} blob, got {value[:32]!r}")
         raw = blob_bytes(value)
+        if len(raw) % 4:
+            raise ValueError(
+                f"blob has {len(raw)} bytes, not a multiple of 4 (float32)"
+            )
         return list(struct.unpack(f"<{len(raw) // 4}f", raw))
 
     flat: list[float] = []
@@ -154,7 +158,12 @@ def _decode_state_field_rows(value, width: int, batch_size: int):
             raise StatesShapeMismatch(f"unexpected string value for field: {value!r}")
         flat = np.frombuffer(blob_bytes(value), dtype="<f4")
     else:
-        arr = np.asarray(value, dtype="<f4")
+        try:
+            arr = np.asarray(value, dtype="<f4")
+        except (ValueError, TypeError) as e:
+            # Ragged / non-numeric rows: not repackable, keep the legacy layout
+            # (as documented) rather than crash the server at load.
+            raise StatesShapeMismatch(f"field value is not a numeric array: {e}")
         if arr.ndim == 1:
             if batch_size != 1:
                 raise StatesShapeMismatch(
@@ -291,9 +300,12 @@ def columnarize_states(states_data: list, model_data: dict | None, register_blob
 
         T = len(states_data)
 
-        bodies_payload = []
+        # Stack everything first; register_blob only once nothing can still
+        # bail out, so a late mismatch doesn't leave orphaned blobs behind in
+        # the server (they're never referenced, never freed).
+        body_blobs: list[tuple[object, dict[str, bytes]]] = []
         for key in body_order:
-            fields_payload = {}
+            raw_fields = {}
             for field, per_frame_rows in body_rows[key].items():
                 if len(per_frame_rows) != T:
                     raise StatesShapeMismatch(
@@ -303,17 +315,17 @@ def columnarize_states(states_data: list, model_data: dict | None, register_blob
                 stacked = np.ascontiguousarray(
                     np.stack(per_frame_rows, axis=0), dtype="<f4"
                 )  # (T, B, k)
-                fields_payload[field] = register_blob(stacked.tobytes())
-            entry = {"name": body_name_value[key], "fields": fields_payload}
-            if key in any_contacts:
-                entry["contacts"] = body_contacts[key]
-            bodies_payload.append(entry)
+                raw_fields[field] = stacked.tobytes()
+            body_blobs.append((key, raw_fields))
 
-        scalars_payload = {}
+        scalar_blobs: dict[str, bytes] = {}
         for name in model_data.get("scalarNames") or []:
             per_frame = []
             for state in states_data:
-                row = np.asarray(state[name], dtype="<f4")
+                try:
+                    row = np.asarray(state[name], dtype="<f4")
+                except (ValueError, TypeError) as e:
+                    raise StatesShapeMismatch(f"scalar '{name}' is not numeric: {e}")
                 if row.ndim == 0:
                     row = row.reshape(1)
                 if row.shape != (batch_size,):
@@ -323,14 +335,7 @@ def columnarize_states(states_data: list, model_data: dict | None, register_blob
                     )
                 per_frame.append(row)
             stacked = np.ascontiguousarray(np.stack(per_frame, axis=0), dtype="<f4")
-            scalars_payload[name] = register_blob(stacked.tobytes())
-
-        return {
-            "version": COLUMNAR_VERSION,
-            "times": times,
-            "bodies": bodies_payload,
-            "scalars": scalars_payload,
-        }
+            scalar_blobs[name] = stacked.tobytes()
     except StatesShapeMismatch as e:
         logger.warning(
             "States data is not columnar-repackable, keeping the legacy "
@@ -339,6 +344,23 @@ def columnarize_states(states_data: list, model_data: dict | None, register_blob
         )
         return None
 
+    bodies_payload = []
+    for key, raw_fields in body_blobs:
+        entry = {
+            "name": body_name_value[key],
+            "fields": {f: register_blob(raw) for f, raw in raw_fields.items()},
+        }
+        if key in any_contacts:
+            entry["contacts"] = body_contacts[key]
+        bodies_payload.append(entry)
+
+    return {
+        "version": COLUMNAR_VERSION,
+        "times": times,
+        "bodies": bodies_payload,
+        "scalars": {n: register_blob(raw) for n, raw in scalar_blobs.items()},
+    }
+
 
 def expand_columnar_states(states_doc: Any, batch_size: int) -> list[dict]:
     """Inverse of `columnarize_states`: rebuild the legacy per-frame array.
@@ -441,6 +463,11 @@ def write_static_bundle(data: dict, directory) -> None:
             else:
                 externalize(v)
 
+    externalize(data["model"])
+    # 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"])
     for name in ("model", "states"):
-        externalize(data[name])
         (out / f"{name}.json").write_text(json.dumps(data[name]))

{simview-6.1.2 → simview-6.2.0}/simview/diff.py

@@ -162,14 +162,57 @@ def _resolve_frame(
     return resolved
 
 
+def pose_resolver(model_data: dict, states_data: list):
+    """`(all_names, resolve)` for walking `states_data` in world space:
+    `all_names` is every body name/name-group in the states plus any
+    rigidly-attached body (constant `localTransform`, never written into the
+    states) resolvable from them, and `resolve(state, batch_idx)` maps each
+    body name to its absolute-world `[x, y, z, w, qx, qy, qz]` row for that
+    frame (parent chains composed; bodies without a pose that frame are left
+    out). Shared by `simview diff` and `simview terrain --along-body`."""
+    batch_size = int(model_data.get("simBatches") or 1)
+    all_names = collect_body_names(states_data)
+    meta = _build_body_meta(model_data, all_names)
+    topo_order = _topo_sort_bodies(meta)
+    seen_keys = {body_key(name) for name in all_names}
+    for name in topo_order:
+        if meta[name]["localTransform"] is not None and body_key(name) not in seen_keys:
+            seen_keys.add(body_key(name))
+            all_names.append(name)
+
+    def resolve(state: dict, batch_idx: int) -> dict[str, list[float]]:
+        return _resolve_frame(
+            meta, topo_order, bodies_by_name(state.get("bodies")), batch_size, batch_idx
+        )
+
+    return all_names, resolve
+
+
 def _quat_angle_deg(qa: list[float], qb: list[float]) -> float:
     """Angular distance in degrees between two [w, x, y, z] quaternions,
-    robust to the double-cover ambiguity (q and -q are the same rotation)."""
+    robust to the double-cover ambiguity (q and -q are the same rotation).
+    NaN in either quaternion gives NaN, never a spurious 0."""
     dot = qa[0] * qb[0] + qa[1] * qb[1] + qa[2] * qb[2] + qa[3] * qb[3]
+    if math.isnan(dot):
+        return math.nan
     dot = max(-1.0, min(1.0, abs(dot)))
     return math.degrees(2 * math.acos(dot))
 
 
+def _nan_aware_stats(values: list[float]) -> dict:
+    """`series_stats` over the finite entries of `values` (NaN for all of
+    mean/min/max when every entry is NaN), with `final` the raw last value
+    and `nan_count` how many entries were NaN."""
+    finite = [v for v in values if not math.isnan(v)]
+    stats = series_stats(finite)
+    if values and not finite:
+        stats = {"mean": math.nan, "min": math.nan, "max": math.nan, "final": None}
+    if values:
+        stats["final"] = values[-1]
+    stats["nan_count"] = len(values) - len(finite)
+    return stats
+
+
 def _resolve_batches(model_data: dict, batch_a: int, batch_b: int) -> int:
     batch_size = int(model_data.get("simBatches") or 1)
     if batch_size < 2:
@@ -191,7 +234,9 @@ def _first_exceeding(
     if threshold is None:
         return None
     for frame_idx, value in zip(frame_indices, values):
-        if value > threshold:
+        # A NaN error (NaN pose in either batch) counts as exceeding: it's
+        # never "within threshold".
+        if value > threshold or math.isnan(value):
             return frame_idx
     return None
 
@@ -230,28 +275,20 @@ def compute_trajectory_diff(
     per-axis toggle -- see `static/js/utils/errorMath.js`'s
     `positionAxisError`) and matching `"err_x"`/`"err_y"`/`"err_z"` entries
     in `summary` (mean/max/final of the *signed* value, so directional bias
-    is visible). Raises `ValueError` on invalid batch indices, `every < 1`,
-    an unmatched/ambiguous `body`, or a scene with no diffable bodies.
+    is visible). A NaN pose yields a NaN error for that frame: summary
+    mean/min/max skip NaN entries (`nan_count` says how many), and a NaN
+    error counts as exceeding any threshold. Raises `ValueError` on invalid
+    batch indices, `every < 1`, an unmatched/ambiguous `body`, or a scene
+    with no diffable bodies.
     """
-    batch_size = _resolve_batches(model_data, batch_a, batch_b)
+    _resolve_batches(model_data, batch_a, batch_b)
     if every < 1:
         raise ValueError(f"every must be >= 1; got {every}")
 
-    all_names = collect_body_names(states_data)
-    seen_keys = {body_key(name) for name in all_names}
+    all_names, resolve = pose_resolver(model_data, states_data)
     if not all_names:
         raise ValueError("no bodies found in the scene's states to diff")
 
-    meta = _build_body_meta(model_data, all_names)
-    topo_order = _topo_sort_bodies(meta)
-    # Rigidly-attached children carry a constant localTransform and so never
-    # appear in the states at all -- they're only diffable now that poses are
-    # resolved through the parent chain.
-    for name in topo_order:
-        if meta[name]["localTransform"] is not None and body_key(name) not in seen_keys:
-            seen_keys.add(body_key(name))
-            all_names.append(name)
-
     target_names = resolve_body(all_names, body)
 
     # A grouped ("A+B") state entry shares one transform across its members, so
@@ -273,11 +310,10 @@ def compute_trajectory_diff(
     for idx, state in enumerate(states_data):
         if idx % every != 0:
             continue
-        raw_by_name = bodies_by_name(state.get("bodies"))
         # Resolved once per frame for the whole scene rather than per body:
         # a child's world pose needs its ancestors' poses anyway.
-        rows_a = _resolve_frame(meta, topo_order, raw_by_name, batch_size, batch_a)
-        rows_b = _resolve_frame(meta, topo_order, raw_by_name, batch_size, batch_b)
+        rows_a = resolve(state, batch_a)
+        rows_b = resolve(state, batch_b)
 
         for name in target_names:
             key = body_key(name)
@@ -302,8 +338,8 @@ def compute_trajectory_diff(
         frame_indices = out["frame_indices"]
         summary = {
             "frame_count": len(frame_indices),
-            "position_error": series_stats(out["position_error"]),
-            "orientation_error_deg": series_stats(out["orientation_error_deg"]),
+            "position_error": _nan_aware_stats(out["position_error"]),
+            "orientation_error_deg": _nan_aware_stats(out["orientation_error_deg"]),
             "first_frame_exceeding_pos_threshold": _first_exceeding(
                 frame_indices, out["position_error"], pos_threshold
             ),
@@ -323,7 +359,7 @@ def compute_trajectory_diff(
         body_out["summary"] = summary
         for axis in axes:
             body_out[axis] = out[axis]
-            summary[axis] = series_stats(out[axis])
+            summary[axis] = _nan_aware_stats(out[axis])
         bodies_out[body_label(name)] = body_out
 
     return {

{simview-6.1.2 → simview-6.2.0}/simview/info.py

@@ -38,9 +38,32 @@ def _blob_byte_length(value: Any) -> int | None:
 
 
 def _encoding_of(value: Any) -> str:
+    if value is None:
+        return "absent"
     return "blob" if is_blob(value) else "plain"
 
 
+def _field_shape_reason(value: Any, width: int, batch_size: int) -> str | None:
+    """Why `columnarize_states` would reject this per-body field value (its
+    float count must be `batch_size * width`; a flat list only for a
+    single batch), or None if it's fine. Counts floats without decoding
+    plain lists into arrays."""
+    if is_blob(value):
+        count = len(blob_bytes(value)) // 4
+    elif isinstance(value, list):
+        if value and not isinstance(value[0], list):
+            if batch_size != 1:
+                return "is a flat list but the scene has more than one batch"
+            count = len(value)
+        else:
+            count = sum(len(row) if isinstance(row, list) else 1 for row in value)
+    else:
+        return f"is a {type(value).__name__}, not a list or blob"
+    if count != batch_size * width:
+        return f"has {count} floats; expected {batch_size * width}"
+    return None
+
+
 def _summarize_terrain(terrain: dict) -> dict:
     dims = terrain.get("dimensions") or {}
     bounds = terrain.get("bounds") or {}
@@ -141,6 +164,12 @@ def _summarize_states(states, model: dict | None, warnings: list[str]) -> dict:
         except ValueError as e:
             warnings.append(f"columnar states document is malformed: {e}")
             states = []
+    elif not isinstance(states, list):
+        warnings.append(
+            "'states' is neither a per-frame array nor a columnar document "
+            f"(got {type(states).__name__})"
+        )
+        states = []
 
     frame_count = len(states)
     dt_from_model = model.get("dt") if model else None
@@ -221,6 +250,7 @@ def _summarize_states(states, model: dict | None, warnings: list[str]) -> dict:
     body_encodings_by_field: dict = {}
     body_frames_present: dict = {}
     body_contacts_frames: dict = {}
+    body_shape_reported: set = set()
 
     for idx, state in enumerate(states):
         bodies = state.get("bodies") or []
@@ -253,6 +283,16 @@ def _summarize_states(states, model: dict | None, warnings: list[str]) -> dict:
             for field in fields:
                 encodings = body_encodings_by_field[key].setdefault(field, set())
                 encodings.add(_encoding_of(body[field]))
+                # Same row-shape rule columnarize_states applies, checked
+                # cheaply (float counts only) so the verdict matches.
+                shape_reason = _field_shape_reason(
+                    body[field], STATE_FIELD_WIDTHS[field], batch_size
+                )
+                if shape_reason and (key, field) not in body_shape_reported:
+                    body_shape_reported.add((key, field))
+                    reasons.append(
+                        f"body '{name}' field '{field}' in frame {idx} {shape_reason}"
+                    )
 
             if "contacts" in body:
                 body_contacts_frames.setdefault(key, []).append(idx)
@@ -373,7 +413,7 @@ def summarize_scene(path: str | Path) -> dict:
         warnings.append("'states' key missing from file")
 
     size_bytes = path.stat().st_size
-    if size_bytes > _LARGE_FILE_BYTES:
+    if size_bytes > _LARGE_FILE_BYTES and not gzipped:
         warnings.append(
             f"file is large ({human_bytes(size_bytes)}); consider gzip compression"
         )

{simview-6.1.2 → simview-6.2.0}/simview/live.py

@@ -55,9 +55,14 @@ class LiveViewer:
                 "(e.g. terrain might be missing)."
             )
         self.scene = scene
+        scene.reconcile_available_attributes()
         self.server = SimViewServer(
             data={"model": scene.model.to_json(), "states": []}, live=True
         )
+        # Frames already in the scene are neither served nor buffered, but
+        # episode startIndex values index the full scene.states, so the live
+        # frame indices must start after them.
+        self.server.frames_pushed = len(scene.states)
 
         self._threaded = ViewerHandle(
             self.server.app,
@@ -101,8 +106,9 @@ class LiveViewer:
         self.scene.add_state(time, body_states, scalar_values=scalar_values)
         frame = self.scene.states[before]
 
-        self.server.frame_buffer.append(frame)
-        self._enqueue(frame)
+        index = self.server.frames_pushed
+        self.server.push_frame(frame)
+        self._enqueue((index, frame))
 
     def mark_episode(self, label: str | None = None, start_index: int | None = None):
         """Mark the start of an episode at the current point in the stream.
@@ -146,7 +152,7 @@ class LiveViewer:
         """
         return self._dropped_frames
 
-    def _enqueue(self, frame: dict) -> None:
+    def _enqueue(self, frame: tuple[int, dict]) -> None:
         """Queue one frame for the sender thread, decimating under backpressure.
 
         When the queue is full (a slow or hung browser tab), the *oldest*
@@ -187,12 +193,12 @@ class LiveViewer:
         happens, instead of in the caller's simulation loop.
         """
         while True:
-            frame = self._send_queue.get()
-            if frame is _STOP_SENTINEL:
+            item = self._send_queue.get()
+            if item is _STOP_SENTINEL:
                 return
-            self._broadcast(frame)
+            self._broadcast(*item)
 
-    def _broadcast(self, frame: dict) -> None:
+    def _broadcast(self, index: int, frame: dict) -> None:
         loop = self.server.loop
         if loop is None:
             # Startup blocks until uvicorn's Server.started is set, which
@@ -205,10 +211,15 @@ class LiveViewer:
             return
 
         future = asyncio.run_coroutine_threadsafe(
-            self.server.broadcast_frame(frame), loop
+            self.server.broadcast_frame(frame, index), loop
         )
         try:
             future.result(timeout=_BROADCAST_TIMEOUT)
+        except TimeoutError:
+            # Cancel it, or the stalled broadcast keeps running on the loop and
+            # interleaves with the next frame's (out-of-order delivery).
+            future.cancel()
+            logger.warning("Timed out broadcasting live state frame; skipped.")
         except Exception:
             logger.exception("Error broadcasting live state frame")