simview 5.1.1__tar.gz → 6.0.0__tar.gz

{simview-5.1.1/simview.egg-info → simview-6.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simview
-Version: 5.1.1
+Version: 6.0.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
@@ -128,8 +128,8 @@ source .venv/bin/activate
 ## License
 
 SimView is distributed under the [BSD 3-Clause License](LICENSE). The web interface
-vendors [uPlot](https://github.com/leeoniya/uPlot), [three.js](https://github.com/mrdoob/three.js),
-and [chroma-js](https://github.com/gka/chroma.js) (all MIT licensed) under
+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
 [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

{simview-5.1.1 → simview-6.0.0}/README.md

@@ -97,8 +97,8 @@ source .venv/bin/activate
 ## License
 
 SimView is distributed under the [BSD 3-Clause License](LICENSE). The web interface
-vendors [uPlot](https://github.com/leeoniya/uPlot), [three.js](https://github.com/mrdoob/three.js),
-and [chroma-js](https://github.com/gka/chroma.js) (all MIT licensed) under
+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
 [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

{simview-5.1.1 → simview-6.0.0}/pyproject.toml

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

{simview-5.1.1 → simview-6.0.0}/simview/__init__.py

@@ -24,7 +24,7 @@ logging.getLogger(__name__).addHandler(logging.NullHandler())
 # the import cost (and dependency requirement) when an authoring symbol is used.
 _LAZY_EXPORTS = {
     "SimulationScene": "simview.scene",
-    "ViewerHandle": "simview.scene",
+    "ViewerHandle": "simview.server",
     "SimViewBody": "simview.model",
     "SimViewStaticObject": "simview.model",
     "SimViewTerrain": "simview.model",
@@ -48,7 +48,8 @@ if TYPE_CHECKING:
         SimViewStaticObject,
         SimViewTerrain,
     )
-    from simview.scene import SimulationScene, ViewerHandle
+    from simview.scene import SimulationScene
+    from simview.server import ViewerHandle
     from simview.state import BodyTrajectory, SimViewBodyState
 
 __all__ = [

{simview-5.1.1 → simview-6.0.0}/simview/__main__.py

@@ -4,11 +4,11 @@ import json
 import logging
 import shutil
 import sys
-import tempfile
 from pathlib import Path
 
 from simview import CACHE_DIR, __version__, remote
 from simview.server import SimViewServer
+from simview.utils import human_bytes, load_scene, load_scene_model
 
 logger = logging.getLogger("simview.cli")
 
@@ -48,46 +48,25 @@ def _package_version() -> str:
 
 
 def _dir_size(path: Path) -> int:
-    total = 0
-    for entry in path.rglob("*"):
-        try:
-            if entry.is_file():
-                total += entry.stat().st_size
-        except OSError:
-            pass
-    return total
+    return sum(p.stat().st_size for p in path.rglob("*") if p.is_file())
 
 
 def clear_cache():
-    """Remove simview's on-disk cache: scene files fetched from remote hosts
-    (see `simview.remote`), plus locations left behind by older installs."""
+    """Remove simview's on-disk cache of scene files fetched from remote hosts
+    (see `simview.remote`), including the default location when
+    $XDG_CACHE_HOME points elsewhere."""
     freed = 0
-    seen: set[Path] = set()
-    for cache_dir in (
-        remote.cache_dir(),
-        Path("/tmp") / CACHE_DIR,
-        Path.home() / ".cache" / CACHE_DIR,
+    for cache_dir in dict.fromkeys(
+        (remote.cache_dir(), Path.home() / ".cache" / CACHE_DIR)
     ):
-        if cache_dir in seen or not cache_dir.is_dir():
+        if not cache_dir.is_dir():
             continue
-        seen.add(cache_dir)
         freed += _dir_size(cache_dir)
         logger.info("Removing %s", cache_dir)
         shutil.rmtree(cache_dir, ignore_errors=True)
 
-    # Temp scenes written by SimViewLauncher (tempfile.mkstemp with this prefix);
-    # these leak if a launched viewer is killed before cleanup runs.
-    removed = 0
-    for leftover in Path(tempfile.gettempdir()).glob("simview_viz_*.json"):
-        try:
-            leftover.unlink()
-            removed += 1
-        except OSError as e:
-            logger.warning("Could not remove %s: %s", leftover, e)
-    if removed:
-        logger.info("Removed %d leftover temporary scene file(s).", removed)
     if freed:
-        logger.info("Freed %s.", remote.human_bytes(freed))
+        logger.info("Freed %s.", human_bytes(freed))
 
     logger.info("Cache cleared.")
 
@@ -128,7 +107,7 @@ def run_terrain(path: Path, args: argparse.Namespace) -> None:
 
     try:
         if args.along_body is not None:
-            model_data, states_data = terrain_mod.load_scene(path)
+            model_data, states_data = load_scene(path)
             if diff_mode:
                 batch_a, batch_b = args.batches
                 result = terrain_mod.query_along_body_diff(
@@ -154,7 +133,7 @@ def run_terrain(path: Path, args: argparse.Namespace) -> None:
                 text_fn = terrain_mod.format_along_text
                 csv_fn = terrain_mod.format_along_csv
         else:
-            model_data = terrain_mod.load_scene_model(path)
+            model_data = load_scene_model(path)
             if diff_mode:
                 batch_a, batch_b = args.batches
                 if args.point is not None:
@@ -226,7 +205,7 @@ def run_diff(path: Path, args: argparse.Namespace) -> None:
         sys.exit(1)
 
     try:
-        model_data, states_data = diff_mod.load_scene(path)
+        model_data, states_data = load_scene(path)
         result = diff_mod.compute_trajectory_diff(
             model_data,
             states_data,
@@ -366,6 +345,24 @@ def _add_json_csv_flags(sp: argparse.ArgumentParser) -> None:
     fmt.add_argument("--csv", action="store_true", help="Print CSV instead of text.")
 
 
+def _add_host_port_flags(sp: argparse.ArgumentParser) -> None:
+    sp.add_argument(
+        "--host",
+        type=str,
+        default="127.0.0.1",
+        help="Host/interface for the server to bind to (default: 127.0.0.1).",
+    )
+    sp.add_argument(
+        "--port",
+        type=int,
+        default=5420,
+        help=(
+            "Port for the server to use (default: 5420). If it's already taken, "
+            "the next free port is used instead."
+        ),
+    )
+
+
 def _add_file_arg(sp: argparse.ArgumentParser) -> None:
     sp.add_argument(
         "file",
@@ -406,21 +403,7 @@ def build_parser() -> argparse.ArgumentParser:
         nargs="*",
         help="Path(s) to simulation JSON file(s) to visualize.",
     )
-    view.add_argument(
-        "--host",
-        type=str,
-        default="127.0.0.1",
-        help="Host/interface for the server to bind to (default: 127.0.0.1).",
-    )
-    view.add_argument(
-        "--port",
-        type=int,
-        default=5420,
-        help=(
-            "Port for the server to use (default: 5420). If it's already taken, "
-            "the next free port is used instead."
-        ),
-    )
+    _add_host_port_flags(view)
     view.add_argument(
         "--no-browser",
         action="store_true",
@@ -606,21 +589,7 @@ def build_parser() -> argparse.ArgumentParser:
         metavar="PATH",
         help="PNG file path to save the screenshot to. Required.",
     )
-    render.add_argument(
-        "--host",
-        type=str,
-        default="127.0.0.1",
-        help="Host/interface for the server to bind to (default: 127.0.0.1).",
-    )
-    render.add_argument(
-        "--port",
-        type=int,
-        default=5420,
-        help=(
-            "Port for the server to use (default: 5420). If it's already taken, "
-            "the next free port is used instead."
-        ),
-    )
+    _add_host_port_flags(render)
     render.add_argument(
         "--view",
         type=str,
@@ -696,24 +665,14 @@ def main():
         clear_cache()
         return
 
-    if args.command == "info":
-        path = _resolve_input(args.file, args)
-        run_info(path, as_json=args.json)
-        return
-
-    if args.command == "terrain":
-        path = _resolve_input(args.file, args)
-        run_terrain(path, args)
-        return
-
-    if args.command == "diff":
-        path = _resolve_input(args.file, args)
-        run_diff(path, args)
-        return
-
-    if args.command == "render":
-        path = _resolve_input(args.file, args)
-        run_render(path, args)
+    single_file_commands = {
+        "info": lambda path, args: run_info(path, as_json=args.json),
+        "terrain": run_terrain,
+        "diff": run_diff,
+        "render": run_render,
+    }
+    if args.command in single_file_commands:
+        single_file_commands[args.command](_resolve_input(args.file, args), args)
         return
 
     # view mode: launch the viewer (or --save-merged) over one or more inputs.

{simview-5.1.1 → simview-6.0.0}/simview/columnar.py

@@ -81,13 +81,18 @@ def inline_blob(raw: bytes) -> str:
     return BLOB_PREFIX + base64.b64encode(raw).decode()
 
 
+def blob_bytes(value: str) -> bytes:
+    """Raw bytes of one inline ``__b64__`` blob string."""
+    return base64.b64decode(value[len(BLOB_PREFIX) :])
+
+
 def blob_floats(value: Any) -> list[float]:
     """Decode one ``__b64__`` blob (or pass through an already-plain nested
     list, flattened) into a flat list of floats, without numpy."""
     if isinstance(value, str):
         if not value.startswith(BLOB_PREFIX):
             raise ValueError(f"expected a {BLOB_PREFIX} blob, got {value[:32]!r}")
-        raw = base64.b64decode(value[len(BLOB_PREFIX) :])
+        raw = blob_bytes(value)
         return list(struct.unpack(f"<{len(raw) // 4}f", raw))
 
     flat: list[float] = []
@@ -147,7 +152,7 @@ def _decode_state_field_rows(value, width: int, batch_size: int):
     if isinstance(value, str):
         if not value.startswith(BLOB_PREFIX):
             raise StatesShapeMismatch(f"unexpected string value for field: {value!r}")
-        flat = np.frombuffer(base64.b64decode(value[len(BLOB_PREFIX) :]), dtype="<f4")
+        flat = np.frombuffer(blob_bytes(value), dtype="<f4")
     else:
         arr = np.asarray(value, dtype="<f4")
         if arr.ndim == 1:
@@ -233,7 +238,7 @@ def columnarize_states(states_data: list, model_data: dict | None, register_blob
 
                 fields = sorted(k for k in body if k in STATE_FIELD_WIDTHS)
                 if key not in body_fields:
-                    if state_idx != 0 and body_rows.get(key) is None:
+                    if state_idx != 0:
                         # A body appearing for the first time after frame 0
                         # would leave earlier frames' rows undefined -- bail
                         # rather than guess a fill value.
@@ -396,7 +401,7 @@ def expand_columnar_states(states_doc: Any, batch_size: int) -> list[dict]:
             for field, (flat, width) in fields.items():
                 start = t * B * width
                 chunk = flat[start : start + B * width]
-                entry[field] = inline_blob(struct.pack(f"<{len(chunk)}f", *chunk))
+                entry[field] = encode_floats(chunk)
             if contacts is not None:
                 value = contacts[t] if t < len(contacts) else None
                 if value is not None:

{simview-5.1.1 → simview-6.0.0}/simview/diff.py

@@ -16,13 +16,19 @@ truncation) for scripts/coding agents to consume directly, with
 same data.
 """
 
-import csv
-import io
 import math
 
 from simview.columnar import body_key, decode_transform_row
-from simview.utils import body_label, cap, iter_names, resolve_body
-from simview.utils import load_scene as load_scene  # re-exported for __main__.py
+from simview.utils import (
+    bodies_by_name,
+    body_label,
+    cap,
+    collect_body_names,
+    iter_names,
+    resolve_body,
+    series_stats,
+    write_csv,
+)
 
 _MAX_SERIES_ROWS = 10
 
@@ -115,19 +121,6 @@ def _compose(parent_row: list[float], local_row: list[float]) -> list[float]:
     ]
 
 
-def _expand_raw_bodies(raw_bodies: list | None) -> dict:
-    """`name -> entry` for one state's `bodies`, expanding grouped (list) name
-    entries so each individual body name maps to the shared entry."""
-    expanded: dict = {}
-    for entry in raw_bodies or []:
-        name = entry.get("name")
-        if name is None:
-            continue
-        for single in iter_names(name):
-            expanded[single] = entry
-    return expanded
-
-
 def _resolve_frame(
     meta: dict[str, dict],
     topo_order: list[str],
@@ -192,12 +185,6 @@ def _resolve_batches(model_data: dict, batch_a: int, batch_b: int) -> int:
     return batch_size
 
 
-def _stats(values: list[float]) -> dict:
-    if not values:
-        return {"mean": None, "max": None, "final": None}
-    return {"mean": sum(values) / len(values), "max": max(values), "final": values[-1]}
-
-
 def _first_exceeding(
     frame_indices: list[int], values: list[float], threshold: float | None
 ) -> int | None:
@@ -250,18 +237,8 @@ def compute_trajectory_diff(
     if every < 1:
         raise ValueError(f"every must be >= 1; got {every}")
 
-    all_names: list = []
-    seen_keys = set()
-    for state in states_data:
-        for entry in state.get("bodies") or []:
-            name = entry.get("name")
-            if name is None:
-                continue
-            key = body_key(name)
-            if key not in seen_keys:
-                seen_keys.add(key)
-                all_names.append(name)
-
+    all_names = collect_body_names(states_data)
+    seen_keys = {body_key(name) for name in all_names}
     if not all_names:
         raise ValueError("no bodies found in the scene's states to diff")
 
@@ -296,7 +273,7 @@ def compute_trajectory_diff(
     for idx, state in enumerate(states_data):
         if idx % every != 0:
             continue
-        raw_by_name = _expand_raw_bodies(state.get("bodies"))
+        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)
@@ -318,41 +295,36 @@ def compute_trajectory_diff(
                 out["err_y"].append(row_a[1] - row_b[1])
                 out["err_z"].append(row_a[2] - row_b[2])
 
+    axes = ("err_x", "err_y", "err_z") if per_axis else ()
     bodies_out = {}
     for name in target_names:
         out = series[body_key(name)]
-        label = body_label(name)
         frame_indices = out["frame_indices"]
-        times = out["times"]
-        position_error = out["position_error"]
-        orientation_error_deg = out["orientation_error_deg"]
-        err_x, err_y, err_z = out["err_x"], out["err_y"], out["err_z"]
-
         summary = {
             "frame_count": len(frame_indices),
-            "position_error": _stats(position_error),
-            "orientation_error_deg": _stats(orientation_error_deg),
+            "position_error": series_stats(out["position_error"]),
+            "orientation_error_deg": series_stats(out["orientation_error_deg"]),
             "first_frame_exceeding_pos_threshold": _first_exceeding(
-                frame_indices, position_error, pos_threshold
+                frame_indices, out["position_error"], pos_threshold
             ),
             "first_frame_exceeding_rot_threshold": _first_exceeding(
-                frame_indices, orientation_error_deg, rot_threshold_deg
+                frame_indices, out["orientation_error_deg"], rot_threshold_deg
             ),
         }
-        bodies_out[label] = {
-            "frame_indices": frame_indices,
-            "times": times,
-            "position_error": position_error,
-            "orientation_error_deg": orientation_error_deg,
-            "summary": summary,
+        body_out = {
+            key: out[key]
+            for key in (
+                "frame_indices",
+                "times",
+                "position_error",
+                "orientation_error_deg",
+            )
         }
-        if per_axis:
-            bodies_out[label]["err_x"] = err_x
-            bodies_out[label]["err_y"] = err_y
-            bodies_out[label]["err_z"] = err_z
-            summary["err_x"] = _stats(err_x)
-            summary["err_y"] = _stats(err_y)
-            summary["err_z"] = _stats(err_z)
+        body_out["summary"] = summary
+        for axis in axes:
+            body_out[axis] = out[axis]
+            summary[axis] = series_stats(out[axis])
+        bodies_out[body_label(name)] = body_out
 
     return {
         "batch_a": batch_a,
@@ -438,22 +410,16 @@ def format_diff_csv(result: dict) -> str:
     (body, frame), full series (no truncation) -- CSV output is for scripts,
     matching the "just the numbers, in full" philosophy `--json` already
     uses everywhere in this CLI."""
-    per_axis = result.get("per_axis")
-    buf = io.StringIO()
-    writer = csv.writer(buf)
+    keys = ["frame_indices", "times", "position_error", "orientation_error_deg"]
     header = ["body", "frame", "time", "position_error", "orientation_error_deg"]
-    if per_axis:
+    if result.get("per_axis"):
+        keys += ["err_x", "err_y", "err_z"]
         header += ["err_x", "err_y", "err_z"]
-    writer.writerow(header)
-    for label, body in result["bodies"].items():
-        columns = [
-            body["frame_indices"],
-            body["times"],
-            body["position_error"],
-            body["orientation_error_deg"],
-        ]
-        if per_axis:
-            columns += [body["err_x"], body["err_y"], body["err_z"]]
-        for row in zip(*columns):
-            writer.writerow([label, *row])
-    return buf.getvalue()
+    return write_csv(
+        header,
+        (
+            [label, *row]
+            for label, body in result["bodies"].items()
+            for row in zip(*(body[k] for k in keys))
+        ),
+    )

{simview-5.1.1 → simview-6.0.0}/simview/info.py

@@ -12,14 +12,14 @@ inspection tool. Shares its blob-decoding/body-label helpers with
 which are stdlib-only on this read path.
 """
 
-import base64
 import json
 from pathlib import Path
 from typing import Any
 
 from simview.columnar import (
-    BLOB_PREFIX,
     STATE_FIELD_WIDTHS,
+    blob_bytes,
+    body_key,
     expand_columnar_states,
     is_blob,
     is_columnar,
@@ -33,7 +33,7 @@ _LARGE_FILE_BYTES = 100_000_000
 def _blob_byte_length(value: Any) -> int | None:
     """Decoded byte length if `value` is a `__b64__` blob string, else None."""
     if is_blob(value):
-        return len(base64.b64decode(value[len(BLOB_PREFIX) :]))
+        return len(blob_bytes(value))
     return None
 
 
@@ -230,7 +230,7 @@ def _summarize_states(states, model: dict | None, warnings: list[str]) -> dict:
                 reasons.append(f"state {idx} has a body entry missing 'name'")
                 continue
             name = body["name"]
-            key = tuple(name) if isinstance(name, list) else name
+            key = body_key(name)
             if key in seen_keys:
                 reasons.append(f"state {idx} lists body '{name}' more than once")
             seen_keys.add(key)

{simview-5.1.1 → simview-6.0.0}/simview/launcher.py

@@ -25,14 +25,10 @@ class SimViewLauncher:
         self._sim_file_path: Path | None = None
 
         if isinstance(source, SimulationScene):
-            if (
-                source.model is None
-                or not source.model.is_complete
-                or source.states is None
-            ):
+            if not source.model.is_complete:
                 raise ValueError(
                     "Cannot initialize visualizer: The provided SimulationScene "
-                    "is incomplete, has no states, or has already been cleared."
+                    "is incomplete (e.g. terrain might be missing)."
                 )
             self._scene = source
         elif isinstance(source, (str, Path)):
@@ -64,14 +60,7 @@ class SimViewLauncher:
                     "states": self._scene.states,
                 }
                 server = SimViewServer(data=data)
-                port = find_free_port(host, preferred_port)
-                if port != preferred_port:
-                    logger.warning(
-                        "Preferred port %s is not available. Using port %s instead.",
-                        preferred_port,
-                        port,
-                    )
-                server.run(host=host, port=port)
+                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,