simview 3.2__py3-none-any.whl

simview/__init__.py

@@ -0,0 +1,69 @@
+import logging
+from typing import TYPE_CHECKING
+
+CACHE_DIR = ".simview_cache"
+
+# Library best practice: attach a NullHandler to the package root logger so
+# `import simview` is silent by default for downstream users. Applications
+# (including simview's own CLI, in __main__.py) are responsible for adding
+# their own handler(s) if they want to see log output.
+logging.getLogger(__name__).addHandler(logging.NullHandler())
+
+# Public authoring API. These live in submodules that depend on the optional
+# `authoring` extra (torch, einops), so they are imported lazily: a viewing-only
+# install can still `import simview` without those dependencies, and only pays
+# the import cost (and dependency requirement) when an authoring symbol is used.
+_LAZY_EXPORTS = {
+    "SimulationScene": "simview.scene",
+    "ViewerHandle": "simview.scene",
+    "SimViewBody": "simview.model",
+    "SimViewStaticObject": "simview.model",
+    "SimViewTerrain": "simview.model",
+    "SimViewModel": "simview.model",
+    "BodyShapeType": "simview.model",
+    "OptionalBodyStateAttribute": "simview.model",
+    "SimViewBodyState": "simview.state",
+    "BodyTrajectory": "simview.state",
+    "LiveViewer": "simview.live",
+}
+
+if TYPE_CHECKING:
+    from simview.live import LiveViewer
+    from simview.model import (
+        BodyShapeType,
+        OptionalBodyStateAttribute,
+        SimViewBody,
+        SimViewModel,
+        SimViewStaticObject,
+        SimViewTerrain,
+    )
+    from simview.scene import SimulationScene, ViewerHandle
+    from simview.state import BodyTrajectory, SimViewBodyState
+
+__all__ = [
+    "CACHE_DIR",
+    "SimulationScene",
+    "ViewerHandle",
+    "SimViewBody",
+    "SimViewStaticObject",
+    "SimViewTerrain",
+    "SimViewModel",
+    "BodyShapeType",
+    "OptionalBodyStateAttribute",
+    "SimViewBodyState",
+    "BodyTrajectory",
+    "LiveViewer",
+]
+
+
+def __getattr__(name: str):
+    module_name = _LAZY_EXPORTS.get(name)
+    if module_name is None:
+        raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+    import importlib
+
+    return getattr(importlib.import_module(module_name), name)
+
+
+def __dir__():
+    return sorted(__all__)

simview/__main__.py

@@ -0,0 +1,174 @@
+import argparse
+import gzip
+import json
+import logging
+import shutil
+import sys
+import tempfile
+from importlib.metadata import PackageNotFoundError, version
+from pathlib import Path
+
+from simview import CACHE_DIR
+from simview.server import SimViewServer
+
+logger = logging.getLogger("simview.cli")
+
+_logging_configured = False
+
+
+def _configure_logging() -> None:
+    """CLI entry point default: INFO-level, message-only output on stderr.
+
+    Kept minimal (no timestamps/level names) since this is user-facing CLI
+    chatter, not application log output meant for parsing. Idempotent, so
+    calling `main()` more than once in the same process (e.g. across tests)
+    doesn't stack up duplicate handlers.
+    """
+    global _logging_configured
+    if _logging_configured:
+        return
+    handler = logging.StreamHandler(sys.stderr)
+    handler.setFormatter(logging.Formatter("%(message)s"))
+    root = logging.getLogger("simview")
+    root.addHandler(handler)
+    root.setLevel(logging.INFO)
+    _logging_configured = True
+
+
+def _package_version() -> str:
+    """The installed simview version, with a sensible fallback for editable
+    checkouts run without an installed distribution (e.g. `python -m simview`
+    from a source tree that was never `pip install -e`'d)."""
+    try:
+        return version("simview")
+    except PackageNotFoundError:
+        return "unknown (not installed)"
+
+
+def clear_cache():
+    # Legacy cache directories (kept for cleanup of older installs).
+    for cache_dir in (Path("/tmp") / CACHE_DIR, Path.home() / ".cache" / CACHE_DIR):
+        if cache_dir.exists():
+            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)
+
+    logger.info("Cache cleared.")
+
+
+def save_merged(paths: list[Path], out_path: Path) -> None:
+    """Merge `paths` (must be >= 2) and write the result to `out_path`, gzipped
+    if it ends in .gz, without starting the server."""
+    if len(paths) < 2:
+        logger.error("Error: --save-merged requires at least 2 input files to merge.")
+        sys.exit(1)
+
+    from simview.merge import merge_simulation_files
+
+    merged = merge_simulation_files(paths)
+    payload = json.dumps(merged).encode("utf-8")
+    if out_path.suffix == ".gz":
+        payload = gzip.compress(payload, compresslevel=1)
+    out_path.write_bytes(payload)
+    logger.info("Merged scene written to %s", out_path)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    parser = argparse.ArgumentParser(description="SimView CLI")
+    parser.add_argument(
+        "inputs",
+        nargs="*",
+        help=(
+            "Path(s) to simulation JSON file(s) to visualize, or 'clear' to clear "
+            "cache. Multiple files are merged into one scene, each file's batches "
+            "appended as extra batches (e.g. a real-world recording plus a "
+            "simulated rerun)."
+        ),
+    )
+    parser.add_argument(
+        "--version",
+        action="store_true",
+        help="Print the installed simview version and exit.",
+    )
+    parser.add_argument(
+        "--host",
+        type=str,
+        default="127.0.0.1",
+        help="Host/interface for the server to bind to (default: 127.0.0.1).",
+    )
+    parser.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."
+        ),
+    )
+    parser.add_argument(
+        "--no-browser",
+        action="store_true",
+        help="Don't automatically open a browser tab once the server starts.",
+    )
+    parser.add_argument(
+        "--save-merged",
+        type=str,
+        default=None,
+        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."
+        ),
+    )
+    return parser
+
+
+def main():
+    _configure_logging()
+    parser = build_parser()
+    args = parser.parse_args()
+
+    if args.version:
+        print(_package_version())
+        return
+
+    if not args.inputs:
+        parser.print_help()
+        sys.exit(1)
+
+    if args.inputs == ["clear"]:
+        clear_cache()
+        return
+
+    paths = [Path(p) for p in args.inputs]
+    for path in paths:
+        if not (path.exists() and path.is_file()):
+            logger.error("Error: File '%s' not found or is not a file.", path)
+            sys.exit(1)
+
+    if args.save_merged:
+        save_merged(paths, Path(args.save_merged))
+        return
+
+    SimViewServer.start(
+        sim_path=paths if len(paths) > 1 else paths[0],
+        host=args.host,
+        preferred_port=args.port,
+        open_browser=not args.no_browser,
+    )
+
+
+if __name__ == "__main__":
+    main()

simview/launcher.py

@@ -0,0 +1,109 @@
+import gc
+import logging
+from pathlib import Path
+
+from simview.server import SimViewServer
+from simview.utils import find_free_port
+
+from .scene import SimulationScene
+
+logger = logging.getLogger("simview.launcher")
+
+
+class SimViewLauncher:
+    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.
+        """
+        self._scene: SimulationScene | None = None
+        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
+            ):
+                raise ValueError(
+                    "Cannot initialize visualizer: The provided SimulationScene "
+                    "is incomplete, has no states, or has already been cleared."
+                )
+            self._scene = source
+        elif isinstance(source, (str, Path)):
+            self._sim_file_path = Path(source)
+            if not self._sim_file_path.exists():
+                raise FileNotFoundError(
+                    f"Simulation JSON file not found at: {self._sim_file_path}"
+                )
+            logger.info(
+                "SimViewLauncher: Using existing simulation file: %s",
+                self._sim_file_path,
+            )
+        else:
+            raise TypeError(
+                "Source for SimViewLauncher must be a SimulationScene object or a file path (str/Path)."
+            )
+
+    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).
+        """
+        try:
+            if self._scene is not None:
+                # Serialize the scene once and hand it to the server directly,
+                # avoiding a temp-file write + read-back round-trip.
+                logger.info("SimViewLauncher: Serving in-memory SimulationScene")
+                data = {
+                    "model": self._scene.model.to_json(),
+                    "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)
+            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.
+                assert self._sim_file_path is not None
+                SimViewServer.start(
+                    sim_path=self._sim_file_path,
+                    host=host,
+                    preferred_port=preferred_port,
+                )
+        except KeyboardInterrupt:
+            logger.info("SimView server stopped by user.")
+        except Exception:
+            logger.exception("Error starting SimView server")
+            raise
+        finally:
+            self.cleanup()
+
+    def cleanup(self) -> None:
+        """
+        Clears 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..."
+            )
+            self._scene._clear_internal_data()
+            self._scene = None
+            gc.collect()
+
+    def __enter__(self) -> "SimViewLauncher":
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.cleanup()

simview/live.py

@@ -0,0 +1,204 @@
+import asyncio
+import logging
+import threading
+import time
+
+import uvicorn
+
+from simview.scene import SimulationScene
+from simview.server import SimViewServer
+from simview.utils import find_free_port
+
+logger = logging.getLogger("simview.live")
+
+# How long to poll uvicorn's Server.started flag for in __init__ before giving
+# up -- binding a localhost socket and completing FastAPI startup is normally
+# well under this, so a timeout here almost always means something is wrong
+# (bad host, port stolen after find_free_port checked it, ...).
+_START_TIMEOUT = 10.0
+_START_POLL_INTERVAL = 0.02
+
+
+class _ThreadedServer:
+    """Runs a SimViewServer's uvicorn app on a background daemon thread.
+
+    Shared plumbing for anything that needs a non-blocking local server
+    (LiveViewer, SimulationScene.show): builds the uvicorn.Server, starts it
+    on a thread, blocks until the socket is actually bound (or raises if
+    startup fails/times out), and offers an idempotent `stop()`.
+    """
+
+    def __init__(
+        self,
+        app,
+        host: str = "127.0.0.1",
+        preferred_port: int = 5420,
+        thread_name: str = "simview-server",
+    ) -> None:
+        self.host = host
+        self.port = find_free_port(host, preferred_port)
+        if self.port != preferred_port:
+            logger.warning(
+                "Preferred port %s is not available. Using port %s instead.",
+                preferred_port,
+                self.port,
+            )
+
+        # uvloop/httptools are faster than the stdlib fallbacks but aren't
+        # available everywhere (uvloop doesn't support Windows). Use them
+        # opportunistically and fall back to uvicorn's "auto" detection.
+        try:
+            import uvloop  # noqa: F401
+
+            loop = "uvloop"
+        except ImportError:
+            loop = "auto"
+        try:
+            import httptools  # noqa: F401
+
+            http = "httptools"
+        except ImportError:
+            http = "auto"
+        config = uvicorn.Config(
+            app,
+            host=host,
+            port=self.port,
+            log_level="info",
+            loop=loop,
+            http=http,
+        )
+        self._uvicorn_server = uvicorn.Server(config)
+
+        self._thread = threading.Thread(
+            target=self._uvicorn_server.run, name=thread_name, daemon=True
+        )
+        self._thread.start()
+
+        # Block until the socket is actually bound, so a caller's very first
+        # action (push_state, an HTTP request, a browser opened right after
+        # construction, ...) never races server startup.
+        deadline = time.monotonic() + _START_TIMEOUT
+        while not self._uvicorn_server.started:
+            if not self._thread.is_alive():
+                raise RuntimeError("SimView server thread died during startup.")
+            if time.monotonic() > deadline:
+                raise TimeoutError(
+                    f"SimView server did not start within {_START_TIMEOUT}s."
+                )
+            time.sleep(_START_POLL_INTERVAL)
+
+    @property
+    def bind_host(self) -> str:
+        """Host to put in URLs -- 0.0.0.0/:: aren't dialable, so localhost
+        stands in for them."""
+        return "127.0.0.1" if self.host in ("0.0.0.0", "::") else self.host
+
+    def is_alive(self) -> bool:
+        return self._thread.is_alive()
+
+    def stop(self) -> None:
+        """Signal the server to exit and wait for its thread to finish.
+
+        Idempotent -- safe to call multiple times.
+        """
+        if not self._thread.is_alive():
+            return
+        self._uvicorn_server.should_exit = True
+        self._thread.join(timeout=5.0)
+
+
+class LiveViewer:
+    """Streams a running simulation to an already-open browser tab over
+    WebSocket, instead of the usual save-then-view flow.
+
+    ``scene`` should already have its complete model (terrain, bodies, ...) --
+    states are pushed incrementally afterwards via `push_state`, using the
+    same validation/encoding as `SimulationScene.add_state`. Because
+    `push_state` appends to `scene.states` exactly like `add_state` would, the
+    scene can still be `save()`d normally once streaming is done.
+    """
+
+    def __init__(
+        self,
+        scene: SimulationScene,
+        host: str = "127.0.0.1",
+        preferred_port: int = 5420,
+        open_browser: bool = False,
+    ) -> None:
+        if not scene.model.is_complete:
+            raise ValueError(
+                "Cannot start LiveViewer: the scene's model is not complete "
+                "(e.g. terrain might be missing)."
+            )
+        self.scene = scene
+        self.server = SimViewServer(
+            data={"model": scene.model.to_json(), "states": []}, live=True
+        )
+
+        self._threaded = _ThreadedServer(
+            self.server.app,
+            host=host,
+            preferred_port=preferred_port,
+            thread_name="simview-live-server",
+        )
+        self.host = host
+        self.port = self._threaded.port
+
+        logger.info(
+            "SimView live server running on http://%s:%s",
+            self._threaded.bind_host,
+            self.port,
+        )
+        if open_browser:
+            import webbrowser
+
+            webbrowser.open(f"http://{self._threaded.bind_host}:{self.port}")
+
+    def push_state(self, time, body_states, scalar_values=None) -> None:
+        """Append one frame and broadcast it to every connected viewer.
+
+        Runs on the caller's thread. Delegates to `scene.add_state` for the
+        same validation/encoding `SimulationScene` normally does (the frame
+        also lands in `self.scene.states`, so `scene.save()` still works after
+        streaming), then hands the just-appended frame to the server thread's
+        event loop for broadcast. Safe to call before any client has
+        connected -- the frame is simply buffered for the next connection's
+        catch-up message.
+        """
+        before = len(self.scene.states)
+        self.scene.add_state(time, body_states, scalar_values=scalar_values)
+        frame = self.scene.states[before]
+
+        self.server.frame_buffer.append(frame)
+
+        if self.server.loop is None:
+            # Startup blocks until uvicorn's Server.started is set, which
+            # happens after the lifespan startup hook that captures
+            # server.loop -- so in practice this is unreachable, but avoid
+            # raising into the caller's simulation loop if it somehow occurs.
+            logger.warning(
+                "SimView live server loop not ready yet; frame buffered only."
+            )
+            return
+
+        future = asyncio.run_coroutine_threadsafe(
+            self.server.broadcast_frame(frame), self.server.loop
+        )
+        try:
+            future.result(timeout=5.0)
+        except Exception:
+            logger.exception("Error broadcasting live state frame")
+
+    def stop(self) -> None:
+        """Signal the server to exit and wait for its thread to finish.
+
+        Idempotent -- safe to call multiple times (e.g. once explicitly and
+        once more via __exit__).
+        """
+        self._threaded.stop()
+
+    def __enter__(self) -> "LiveViewer":
+        return self
+
+    def __exit__(self, exc_type, exc_value, traceback) -> None:
+        self.stop()