simview 3.2__tar.gz → 3.4__tar.gz

{simview-3.2 → simview-3.4}/PKG-INFO

@@ -1,17 +1,18 @@
 Metadata-Version: 2.4
 Name: simview
-Version: 3.2
+Version: 3.4
 Summary: THREE.js-based simulation visualization tool
-Author-email: Ales Kucera <kuceral4@fel.cvut.cz>, David Korcak <david.korcak@gmail.com>, Jan Vlk <vlkjan6@fel.cvut.cz>
+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
 Project-URL: Homepage, https://github.com/vlk-jan/simview
 Project-URL: Repository, https://github.com/vlk-jan/simview
 Project-URL: Issues, https://github.com/vlk-jan/simview/issues
-Classifier: Development Status :: 4 - Beta
+Classifier: Development Status :: 5 - Production/Stable
 Classifier: Intended Audience :: Science/Research
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
 Classifier: Topic :: Scientific/Engineering :: Visualization
 Requires-Python: >=3.12
 Description-Content-Type: text/markdown
@@ -67,16 +68,28 @@ require `torch`.
 
 Requires **Python 3.12+**.
 
+### From PyPI
+
 To only view existing simulation JSON files:
 
 ```bash
-pip install -e .
+pip install simview
 ```
 
 To also author simulations from Python (installs `torch` and `einops`):
 
 ```bash
-pip install -e ".[authoring]"
+pip install "simview[authoring]"
+```
+
+### From source
+
+For working on SimView itself (or to track an unreleased commit), install an
+editable checkout instead:
+
+```bash
+pip install -e .              # viewing only
+pip install -e ".[authoring]" # viewing + authoring
 ```
 
 For independent use of this repository, use `venv` or `uv`:
@@ -107,6 +120,67 @@ all of this using the following command:
 simview clear
 ```
 
+### Inspecting a scene file
+
+To print a quick structural summary of a scene JSON file (body/terrain/state
+breakdown, plus consistency warnings) without opening the viewer:
+
+```bash
+simview info scene.json          # human-readable text
+simview info scene.json --json   # machine-readable JSON (for scripts/agents)
+```
+
+Works on gzip-compressed files automatically, and does not require the
+`authoring` extra.
+
+### Querying terrain data
+
+To read raw numeric terrain values (height, and friction/stiffness if present)
+at a single point or over an area, without opening the viewer:
+
+```bash
+simview terrain scene.json --point 1.5 -2.0        # bilinear-interpolated value(s) at (x, y)
+simview terrain scene.json --area                  # whole terrain extent
+simview terrain scene.json --area -5 5 -5 0        # xmin xmax ymin ymax sub-box
+simview terrain scene.json --area --json           # machine-readable JSON (for scripts/agents)
+simview terrain scene.json --area --csv            # CSV (for pandas/spreadsheets)
+```
+
+Add `--layer height|friction|stiffness` to restrict to one layer, `--batch N`
+to pick a batch (only matters when the terrain isn't a singleton), and
+`--stride N` to subsample an `--area` query. Like `simview info`, this works
+on gzip-compressed files and doesn't require the `authoring` extra.
+
+Pass `--batches A B` instead of `--batch N` to compare two batches directly
+(e.g. a ground-truth terrain vs. a recovered friction/stiffness estimate)
+instead of querying a single one — each layer then reports `value_a`,
+`value_b`, and their `delta`:
+
+```bash
+simview terrain scene.json --area --batches 0 1 --json   # ground truth vs. estimate, whole extent
+```
+
+### Comparing two batches' trajectories
+
+To check how far apart two batches' trajectories are — e.g. ground truth vs.
+a model's prediction, or baseline vs. post-adaptation — without opening the
+viewer:
+
+```bash
+simview diff scene.json --batches 0 1                 # every body, human-readable text
+simview diff scene.json --batches 0 1 --json           # machine-readable JSON (for scripts/agents)
+simview diff scene.json --batches 0 1 --csv            # CSV, one row per (body, frame)
+simview diff scene.json --batches 0 1 --body Box       # restrict to one body
+```
+
+For each body, this reports per-frame position error (meters) and
+orientation error (degrees, quaternion angular distance) between the two
+batches, plus mean/max/final summaries. Add `--every N` to subsample frames,
+and `--pos-threshold METERS`/`--rot-threshold-deg DEGREES` to report the
+first frame where a batch's trajectory diverges past a given tolerance. Like
+`simview info`/`simview terrain`, this works on gzip-compressed files and
+doesn't require the `authoring` extra.
+
 ### Visualization of exported simulations
 
 To visualize a simulation defined in a JSON file, run the following command, replacing `[path_to_json_file]` with the actual path to your JSON data:

simview-3.2/simview.egg-info/PKG-INFO → simview-3.4/README.md

@@ -1,33 +1,3 @@
-Metadata-Version: 2.4
-Name: simview
-Version: 3.2
-Summary: THREE.js-based simulation visualization tool
-Author-email: Ales Kucera <kuceral4@fel.cvut.cz>, David Korcak <david.korcak@gmail.com>, Jan Vlk <vlkjan6@fel.cvut.cz>
-License-Expression: BSD-3-Clause
-Project-URL: Homepage, https://github.com/vlk-jan/simview
-Project-URL: Repository, https://github.com/vlk-jan/simview
-Project-URL: Issues, https://github.com/vlk-jan/simview/issues
-Classifier: Development Status :: 4 - Beta
-Classifier: Intended Audience :: Science/Research
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Topic :: Scientific/Engineering :: Visualization
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: fastapi>=0.135.3
-Requires-Dist: httptools>=0.7.1; sys_platform != "win32"
-Requires-Dist: jinja2>=3.1.6
-Requires-Dist: orjson>=3.11.8
-Requires-Dist: uvicorn>=0.44.0
-Requires-Dist: uvloop>=0.22.1; sys_platform != "win32"
-Provides-Extra: authoring
-Requires-Dist: torch; extra == "authoring"
-Requires-Dist: einops; extra == "authoring"
-Requires-Dist: numpy; extra == "authoring"
-Dynamic: license-file
-
 # SimView Visualizer
 
 **SimView** is a powerful and interactive tool for visualizing 3D models and terrain data in simulations. It enables you to explore and analyze multiple simulation scenarios (batches) within a shared environment, all defined through an intuitive JSON format or a Python API.
@@ -67,16 +37,28 @@ require `torch`.
 
 Requires **Python 3.12+**.
 
+### From PyPI
+
 To only view existing simulation JSON files:
 
 ```bash
-pip install -e .
+pip install simview
 ```
 
 To also author simulations from Python (installs `torch` and `einops`):
 
 ```bash
-pip install -e ".[authoring]"
+pip install "simview[authoring]"
+```
+
+### From source
+
+For working on SimView itself (or to track an unreleased commit), install an
+editable checkout instead:
+
+```bash
+pip install -e .              # viewing only
+pip install -e ".[authoring]" # viewing + authoring
 ```
 
 For independent use of this repository, use `venv` or `uv`:
@@ -107,6 +89,67 @@ all of this using the following command:
 simview clear
 ```
 
+### Inspecting a scene file
+
+To print a quick structural summary of a scene JSON file (body/terrain/state
+breakdown, plus consistency warnings) without opening the viewer:
+
+```bash
+simview info scene.json          # human-readable text
+simview info scene.json --json   # machine-readable JSON (for scripts/agents)
+```
+
+Works on gzip-compressed files automatically, and does not require the
+`authoring` extra.
+
+### Querying terrain data
+
+To read raw numeric terrain values (height, and friction/stiffness if present)
+at a single point or over an area, without opening the viewer:
+
+```bash
+simview terrain scene.json --point 1.5 -2.0        # bilinear-interpolated value(s) at (x, y)
+simview terrain scene.json --area                  # whole terrain extent
+simview terrain scene.json --area -5 5 -5 0        # xmin xmax ymin ymax sub-box
+simview terrain scene.json --area --json           # machine-readable JSON (for scripts/agents)
+simview terrain scene.json --area --csv            # CSV (for pandas/spreadsheets)
+```
+
+Add `--layer height|friction|stiffness` to restrict to one layer, `--batch N`
+to pick a batch (only matters when the terrain isn't a singleton), and
+`--stride N` to subsample an `--area` query. Like `simview info`, this works
+on gzip-compressed files and doesn't require the `authoring` extra.
+
+Pass `--batches A B` instead of `--batch N` to compare two batches directly
+(e.g. a ground-truth terrain vs. a recovered friction/stiffness estimate)
+instead of querying a single one — each layer then reports `value_a`,
+`value_b`, and their `delta`:
+
+```bash
+simview terrain scene.json --area --batches 0 1 --json   # ground truth vs. estimate, whole extent
+```
+
+### Comparing two batches' trajectories
+
+To check how far apart two batches' trajectories are — e.g. ground truth vs.
+a model's prediction, or baseline vs. post-adaptation — without opening the
+viewer:
+
+```bash
+simview diff scene.json --batches 0 1                 # every body, human-readable text
+simview diff scene.json --batches 0 1 --json           # machine-readable JSON (for scripts/agents)
+simview diff scene.json --batches 0 1 --csv            # CSV, one row per (body, frame)
+simview diff scene.json --batches 0 1 --body Box       # restrict to one body
+```
+
+For each body, this reports per-frame position error (meters) and
+orientation error (degrees, quaternion angular distance) between the two
+batches, plus mean/max/final summaries. Add `--every N` to subsample frames,
+and `--pos-threshold METERS`/`--rot-threshold-deg DEGREES` to report the
+first frame where a batch's trajectory diverges past a given tolerance. Like
+`simview info`/`simview terrain`, this works on gzip-compressed files and
+doesn't require the `authoring` extra.
+
 ### Visualization of exported simulations
 
 To visualize a simulation defined in a JSON file, run the following command, replacing `[path_to_json_file]` with the actual path to your JSON data:

{simview-3.2 → simview-3.4}/pyproject.toml

@@ -4,23 +4,24 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "simview"
-version = "3.2"
+version = "3.4"
 readme = "README.md"
 requires-python = ">=3.12"
 license = "BSD-3-Clause"
 license-files = ["LICENSE"]
 authors = [
+    { name = "Jan Vlk", email = "vlkjan6@fel.cvut.cz" },
     { name = "Ales Kucera", email = "kuceral4@fel.cvut.cz" },
     { name = "David Korcak", email = "david.korcak@gmail.com" },
-    { name = "Jan Vlk", email = "vlkjan6@fel.cvut.cz" },
 ]
 description = "THREE.js-based simulation visualization tool"
 classifiers = [
-    "Development Status :: 4 - Beta",
+    "Development Status :: 5 - Production/Stable",
     "Intended Audience :: Science/Research",
     "Programming Language :: Python :: 3",
     "Programming Language :: Python :: 3.12",
     "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
     "Topic :: Scientific/Engineering :: Visualization",
 ]
 dependencies = [

{simview-3.2 → simview-3.4}/simview/__init__.py

@@ -1,8 +1,17 @@
 import logging
+from importlib.metadata import PackageNotFoundError
+from importlib.metadata import version as _version
 from typing import TYPE_CHECKING
 
 CACHE_DIR = ".simview_cache"
 
+try:
+    __version__ = _version("simview")
+except PackageNotFoundError:
+    # Editable/source checkout that was never installed as a distribution.
+    __version__ = "0.0.0.dev0"
+del _version, PackageNotFoundError
+
 # 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
@@ -41,6 +50,7 @@ if TYPE_CHECKING:
     from simview.state import BodyTrajectory, SimViewBodyState
 
 __all__ = [
+    "__version__",
     "CACHE_DIR",
     "SimulationScene",
     "ViewerHandle",