simview 3.5__tar.gz → 4.0.0__tar.gz

{simview-3.5/simview.egg-info → simview-4.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simview
-Version: 3.5
+Version: 4.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
@@ -34,7 +34,7 @@ Dynamic: license-file
 # SimView Visualizer
 
 [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://vlk-jan.github.io/simview/)
-[![Live Demo](https://img.shields.io/badge/demo-live-brightgreen.svg)](https://vlk-jan.github.io/assets/demos/simview/)
+[![Live Demo](https://img.shields.io/badge/demo-live-brightgreen.svg)](https://vlk-jan.github.io/simview/demo/)
 
 **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.
 
@@ -50,8 +50,8 @@ the API reference, and developer/architecture docs — is available at:
 **[https://vlk-jan.github.io/simview/](https://vlk-jan.github.io/simview/)**
 
 Want to try it without installing anything? There's a
-[live browser demo](https://vlk-jan.github.io/assets/demos/simview/)
-(static snapshot, no backend needed).
+[live browser demo](https://vlk-jan.github.io/simview/demo/)
+(always up-to-date with the current code, no backend needed).
 
 ---
 

{simview-3.5 → simview-4.0.0}/README.md

@@ -1,7 +1,7 @@
 # SimView Visualizer
 
 [![Documentation](https://img.shields.io/badge/docs-GitHub%20Pages-blue.svg)](https://vlk-jan.github.io/simview/)
-[![Live Demo](https://img.shields.io/badge/demo-live-brightgreen.svg)](https://vlk-jan.github.io/assets/demos/simview/)
+[![Live Demo](https://img.shields.io/badge/demo-live-brightgreen.svg)](https://vlk-jan.github.io/simview/demo/)
 
 **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.
 
@@ -17,8 +17,8 @@ the API reference, and developer/architecture docs — is available at:
 **[https://vlk-jan.github.io/simview/](https://vlk-jan.github.io/simview/)**
 
 Want to try it without installing anything? There's a
-[live browser demo](https://vlk-jan.github.io/assets/demos/simview/)
-(static snapshot, no backend needed).
+[live browser demo](https://vlk-jan.github.io/simview/demo/)
+(always up-to-date with the current code, no backend needed).
 
 ---
 

{simview-3.5 → simview-4.0.0}/pyproject.toml

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

{simview-3.5 → simview-4.0.0}/simview/__main__.py

@@ -82,14 +82,18 @@ def run_info(path: Path, as_json: bool) -> None:
 
 
 def run_terrain(path: Path, args: argparse.Namespace) -> None:
-    """Print terrain value(s) at a point or over an area, from the scene JSON
-    at `path`, to stdout. With `--batches A B`, compares two batches instead
-    of querying a single one."""
+    """Print terrain value(s) at a point, over an area, or along a body's
+    trajectory, from the scene JSON at `path`, to stdout. With `--batches
+    A B`, compares two batches instead of querying a single one (for
+    `--along-body`, both batches' terrains are sampled along batch A's
+    trajectory -- see `query_along_body_diff`)."""
     from simview import terrain as terrain_mod
 
-    if (args.point is None) == (args.area is None):
+    mode_count = sum(v is not None for v in (args.point, args.area, args.along_body))
+    if mode_count != 1:
         logger.error(
-            "Error: 'simview terrain' requires exactly one of --point or --area."
+            "Error: 'simview terrain' requires exactly one of --point, --area, "
+            "or --along-body."
         )
         sys.exit(1)
     if args.area is not None and len(args.area) not in (0, 4):
@@ -106,40 +110,67 @@ def run_terrain(path: Path, args: argparse.Namespace) -> None:
     diff_mode = args.batches is not None
 
     try:
-        model_data = terrain_mod.load_scene_model(path)
-        if diff_mode:
-            batch_a, batch_b = args.batches
-            if args.point is not None:
-                result = terrain_mod.query_point_diff(
+        if args.along_body is not None:
+            model_data, states_data = terrain_mod.load_scene(path)
+            if diff_mode:
+                batch_a, batch_b = args.batches
+                result = terrain_mod.query_along_body_diff(
                     model_data,
-                    args.point[0],
-                    args.point[1],
+                    states_data,
+                    args.along_body,
                     batch_a,
                     batch_b,
                     args.layer,
+                    args.every,
                 )
-                text = terrain_mod.format_point_diff_text(result)
-                csv_text = terrain_mod.format_point_diff_csv(result)
+                text = terrain_mod.format_along_diff_text(result)
+                csv_text = terrain_mod.format_along_diff_csv(result)
             else:
-                bounds = tuple(args.area) if args.area else None
-                result = terrain_mod.query_area_diff(
-                    model_data, bounds, batch_a, batch_b, args.layer, args.stride
+                result = terrain_mod.query_along_body(
+                    model_data,
+                    states_data,
+                    args.along_body,
+                    args.layer,
+                    args.batch,
+                    args.every,
                 )
-                text = terrain_mod.format_area_diff_text(result)
-                csv_text = terrain_mod.format_area_diff_csv(result)
-        elif args.point is not None:
-            result = terrain_mod.query_point(
-                model_data, args.point[0], args.point[1], args.layer, args.batch
-            )
-            text = terrain_mod.format_point_text(result)
-            csv_text = terrain_mod.format_point_csv(result)
+                text = terrain_mod.format_along_text(result)
+                csv_text = terrain_mod.format_along_csv(result)
         else:
-            bounds = tuple(args.area) if args.area else None
-            result = terrain_mod.query_area(
-                model_data, bounds, args.layer, args.batch, args.stride
-            )
-            text = terrain_mod.format_area_text(result)
-            csv_text = terrain_mod.format_area_csv(result)
+            model_data = terrain_mod.load_scene_model(path)
+            if diff_mode:
+                batch_a, batch_b = args.batches
+                if args.point is not None:
+                    result = terrain_mod.query_point_diff(
+                        model_data,
+                        args.point[0],
+                        args.point[1],
+                        batch_a,
+                        batch_b,
+                        args.layer,
+                    )
+                    text = terrain_mod.format_point_diff_text(result)
+                    csv_text = terrain_mod.format_point_diff_csv(result)
+                else:
+                    bounds = tuple(args.area) if args.area else None
+                    result = terrain_mod.query_area_diff(
+                        model_data, bounds, batch_a, batch_b, args.layer, args.stride
+                    )
+                    text = terrain_mod.format_area_diff_text(result)
+                    csv_text = terrain_mod.format_area_diff_csv(result)
+            elif args.point is not None:
+                result = terrain_mod.query_point(
+                    model_data, args.point[0], args.point[1], args.layer, args.batch
+                )
+                text = terrain_mod.format_point_text(result)
+                csv_text = terrain_mod.format_point_csv(result)
+            else:
+                bounds = tuple(args.area) if args.area else None
+                result = terrain_mod.query_area(
+                    model_data, bounds, args.layer, args.batch, args.stride
+                )
+                text = terrain_mod.format_area_text(result)
+                csv_text = terrain_mod.format_area_csv(result)
     except (json.JSONDecodeError, ValueError, KeyError) as e:
         logger.error("Error: %s", e)
         sys.exit(1)
@@ -154,7 +185,10 @@ def run_terrain(path: Path, args: argparse.Namespace) -> None:
 
 def run_diff(path: Path, args: argparse.Namespace) -> None:
     """Print a trajectory divergence report between two batches of the scene
-    JSON at `path`, to stdout."""
+    JSON at `path`, to stdout. With `--fail-on-exceed`, additionally exits
+    with a non-zero code once printing is done: 0 = within thresholds, 1 =
+    usage/parse error, 2 = a threshold was exceeded (see `--fail-on-exceed`'s
+    help text)."""
     from simview import diff as diff_mod
 
     if args.batches is None:
@@ -166,6 +200,16 @@ def run_diff(path: Path, args: argparse.Namespace) -> None:
     if args.json and args.csv:
         logger.error("Error: --json and --csv are mutually exclusive.")
         sys.exit(1)
+    if (
+        args.fail_on_exceed
+        and args.pos_threshold is None
+        and args.rot_threshold_deg is None
+    ):
+        logger.error(
+            "Error: --fail-on-exceed requires --pos-threshold and/or "
+            "--rot-threshold-deg."
+        )
+        sys.exit(1)
 
     try:
         model_data, states_data = diff_mod.load_scene(path)
@@ -193,6 +237,15 @@ def run_diff(path: Path, args: argparse.Namespace) -> None:
     else:
         print(text)
 
+    if args.fail_on_exceed:
+        exceeded = any(
+            body["summary"]["first_frame_exceeding_pos_threshold"] is not None
+            or body["summary"]["first_frame_exceeding_rot_threshold"] is not None
+            for body in result["bodies"].values()
+        )
+        if exceeded:
+            sys.exit(2)
+
 
 def run_render(path: Path, args: argparse.Namespace) -> None:
     """Headlessly render one PNG screenshot of the scene JSON at `path`, for
@@ -249,12 +302,13 @@ def build_parser() -> argparse.ArgumentParser:
         help=(
             "Path(s) to simulation JSON file(s) to visualize, 'clear' to clear "
             "cache, 'info <file>' to print a structural summary of one scene "
-            "file, 'terrain <file>' to query terrain values at a point or over "
-            "an area, 'diff <file>' to compare two batches' trajectories, or "
-            "'render <file>' to headlessly save a PNG screenshot (needs the "
-            "'render' extra). Multiple visualize-mode files are merged into "
-            "one scene, each file's batches appended as extra batches (e.g. a "
-            "real-world recording plus a simulated rerun)."
+            "file, 'terrain <file>' to query terrain values at a point, over "
+            "an area, or along a body's trajectory, 'diff <file>' to compare "
+            "two batches' trajectories, or 'render <file>' to headlessly save "
+            "a PNG screenshot (needs the 'render' extra). Multiple "
+            "visualize-mode 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(
@@ -287,7 +341,7 @@ def build_parser() -> argparse.ArgumentParser:
         help=(
             "With 'simview terrain <file>', query terrain value(s) at a single "
             "(x, y) point (bilinear-interpolated). Mutually exclusive with "
-            "--area."
+            "--area and --along-body."
         ),
     )
     parser.add_argument(
@@ -299,16 +353,33 @@ def build_parser() -> argparse.ArgumentParser:
             "With 'simview terrain <file>', query terrain values over a "
             "rectangular area: pass no values for the whole terrain extent, "
             "or exactly 4 values 'XMIN XMAX YMIN YMAX' for a sub-box. Mutually "
-            "exclusive with --point."
+            "exclusive with --point and --along-body."
+        ),
+    )
+    parser.add_argument(
+        "--along-body",
+        type=str,
+        default=None,
+        metavar="BODY",
+        help=(
+            "With 'simview terrain <file>', sample terrain value(s) "
+            "bilinear-interpolated at BODY's (x, y) position in every "
+            "sampled state (e.g. friction/stiffness under a robot's driven "
+            "path). BODY is matched the same way as 'simview diff' --body "
+            "(full label, or any single name inside a rigidly-grouped body). "
+            "With --batches A B, samples both batches' terrains along batch "
+            "A's trajectory instead and reports the delta per layer. "
+            "Mutually exclusive with --point and --area."
         ),
     )
     parser.add_argument(
         "--layer",
-        choices=["height", "friction", "stiffness", "all"],
         default="all",
         help=(
-            "With 'simview terrain <file>', which terrain layer(s) to query "
-            "(default: all present)."
+            "With 'simview terrain <file>', which terrain layer to query: "
+            "'height', 'all' (default: all present), or the name of any "
+            "arbitrary property the terrain was authored with (e.g. "
+            "'friction', 'stiffness', or a custom name)."
         ),
     )
     parser.add_argument(
@@ -333,10 +404,11 @@ def build_parser() -> argparse.ArgumentParser:
         metavar=("A", "B"),
         help=(
             "Two batch indices to compare. Required by 'simview diff <file>'. "
-            "With 'simview terrain <file> --point|--area', switches into "
-            "cross-batch diff mode (value_a/value_b/delta per layer) instead "
-            "of a single-batch query, and takes precedence over --batch if "
-            "both are given."
+            "With 'simview terrain <file> --point|--area|--along-body', "
+            "switches into cross-batch diff mode (value_a/value_b/delta per "
+            "layer) instead of a single-batch query, and takes precedence "
+            "over --batch if both are given. For --along-body, both batches' "
+            "terrains are sampled along batch A's trajectory."
         ),
     )
     parser.add_argument(
@@ -355,7 +427,10 @@ def build_parser() -> argparse.ArgumentParser:
         "--every",
         type=int,
         default=1,
-        help="With 'simview diff <file>', sample every Nth frame (default: 1).",
+        help=(
+            "With 'simview diff <file>' or 'simview terrain <file> "
+            "--along-body', sample every Nth frame (default: 1)."
+        ),
     )
     parser.add_argument(
         "--pos-threshold",
@@ -386,6 +461,18 @@ def build_parser() -> argparse.ArgumentParser:
             "the browser Error Metrics panel's per-axis toggle."
         ),
     )
+    parser.add_argument(
+        "--fail-on-exceed",
+        action="store_true",
+        help=(
+            "With 'simview diff <file>', exit with code 2 (after printing the "
+            "normal output) if any diffed body's trajectory exceeds "
+            "--pos-threshold or --rot-threshold-deg; requires at least one of "
+            "them. Exit codes: 0 = within thresholds, 1 = usage/parse error, "
+            "2 = threshold exceeded -- lets scripts/CI tell divergence apart "
+            "from a broken invocation."
+        ),
+    )
     parser.add_argument(
         "--host",
         type=str,

{simview-3.5 → simview-4.0.0}/simview/info.py

@@ -69,8 +69,7 @@ def _summarize_terrain(terrain: dict) -> dict:
     bounds = terrain.get("bounds") or {}
     height = terrain.get("heightData")
     normals = terrain.get("normals")
-    friction = terrain.get("frictionData")
-    stiffness = terrain.get("stiffnessData")
+    properties = terrain.get("properties") or {}
     return {
         "extent": {"x": dims.get("sizeX"), "y": dims.get("sizeY")},
         "shape": {"x": dims.get("resolutionX"), "y": dims.get("resolutionY")},
@@ -83,28 +82,18 @@ def _summarize_terrain(terrain: dict) -> dict:
             "max_z": bounds.get("maxZ"),
         },
         "is_singleton": terrain.get("isSingleton"),
-        "has_friction": friction is not None,
-        "has_stiffness": stiffness is not None,
-        "friction_bounds": (
-            {"min": bounds.get("minFriction"), "max": bounds.get("maxFriction")}
-            if friction is not None
-            else None
-        ),
-        "stiffness_bounds": (
-            {"min": bounds.get("minStiffness"), "max": bounds.get("maxStiffness")}
-            if stiffness is not None
-            else None
-        ),
         "height_data_encoding": _encoding_of(height),
         "height_data_bytes": _blob_byte_length(height),
         "normals_encoding": _encoding_of(normals),
         "normals_bytes": _blob_byte_length(normals),
-        "friction_data_encoding": _encoding_of(friction)
-        if friction is not None
-        else None,
-        "stiffness_data_encoding": (
-            _encoding_of(stiffness) if stiffness is not None else None
-        ),
+        "properties": {
+            name: {
+                "bounds": {"min": prop.get("min"), "max": prop.get("max")},
+                "encoding": _encoding_of(prop.get("data")),
+                "bytes": _blob_byte_length(prop.get("data")),
+            }
+            for name, prop in properties.items()
+        },
     }
 
 
@@ -142,6 +131,7 @@ def _summarize_model(model: dict, warnings: list[str]) -> dict:
         "scalar_names": model.get("scalarNames") or [],
         "dt": model.get("dt"),
         "collapse": model.get("collapse"),
+        "metadata": model.get("metadata"),
         "terrain": _summarize_terrain(terrain) if terrain is not None else None,
         "bodies": {
             "count": len(bodies),
@@ -445,6 +435,12 @@ def format_text(summary: dict) -> str:
         lines.append(f"  Scalars: {', '.join(model['scalar_names']) or '(none)'}")
         lines.append(f"  dt: {model['dt']}   Collapse: {model['collapse']}")
 
+        metadata = model["metadata"]
+        if metadata:
+            lines.append("\nMetadata")
+            for key, value in metadata.items():
+                lines.append(f"  {key}: {value}")
+
         terrain = model["terrain"]
         if terrain is None:
             lines.append("\nTerrain: (none)")
@@ -459,9 +455,12 @@ def format_text(summary: dict) -> str:
                 f"  Bounds: x=[{b['min_x']},{b['max_x']}] "
                 f"y=[{b['min_y']},{b['max_y']}] z=[{b['min_z']},{b['max_z']}]"
             )
-            friction = "yes" if terrain["has_friction"] else "no"
-            stiffness = "yes" if terrain["has_stiffness"] else "no"
-            lines.append(f"  Friction data: {friction}   Stiffness data: {stiffness}")
+            props = terrain["properties"]
+            if props:
+                names = ", ".join(sorted(props))
+                lines.append(f"  Properties: {names}")
+            else:
+                lines.append("  Properties: (none)")
             h_bytes = terrain["height_data_bytes"]
             n_bytes = terrain["normals_bytes"]
             lines.append(

{simview-3.5 → simview-4.0.0}/simview/merge.py

@@ -64,13 +64,13 @@ def _decode_state_field(value, width: int):
 
 
 def _decode_per_batch(value: list | str, batch_size: int) -> list:
-    """Normalize a terrain data field (heightData/normals/frictionData/
-    stiffnessData) to a plain list of length `batch_size`, one entry per
-    batch, regardless of whether it's a binary ``__b64__`` blob (one flat
-    buffer covering all batches) or an already-batched plain list. Used so
-    that inputs mixing binary and plain-list encoding can still be
-    concatenated -- each file's field is decoded independently rather than
-    branching on a single file's encoding."""
+    """Normalize a terrain data field (heightData/normals/a named property's
+    data) to a plain list of length `batch_size`, one entry per batch,
+    regardless of whether it's a binary ``__b64__`` blob (one flat buffer
+    covering all batches) or an already-batched plain list. Used so that
+    inputs mixing binary and plain-list encoding can still be concatenated --
+    each file's field is decoded independently rather than branching on a
+    single file's encoding."""
     flat = _decode_b64_floats(value)
     if flat is None:
         # `_decode_b64_floats` only returns None for non-`__b64__` input, and
@@ -276,26 +276,28 @@ def _merge_terrain(
                 f"'{labels[0]}' dimensions {dims}."
             )
 
-    has_friction = all(
-        model["terrain"].get("frictionData") is not None for model in models
-    )
-    has_stiffness = all(
-        model["terrain"].get("stiffnessData") is not None for model in models
-    )
-    if not has_friction and any(
-        model["terrain"].get("frictionData") is not None for model in models
-    ):
-        logger.warning(
-            "Not all files provide terrain friction data; dropping "
-            "frictionData from the merged terrain."
-        )
-    if not has_stiffness and any(
-        model["terrain"].get("stiffnessData") is not None for model in models
-    ):
-        logger.warning(
-            "Not all files provide terrain stiffness data; dropping "
-            "stiffnessData from the merged terrain."
+    # Union of property names across all files, in first-seen order. A property
+    # present in every file is kept (concatenated + bounds merged); one present
+    # in only some is dropped with a warning, same all-or-nothing rule as
+    # heightData/normals require unconditionally.
+    property_names: list[str] = []
+    for model in models:
+        for name in model["terrain"].get("properties") or {}:
+            if name not in property_names:
+                property_names.append(name)
+    kept_properties = []
+    for name in property_names:
+        present_in_all = all(
+            name in (model["terrain"].get("properties") or {}) for model in models
         )
+        if present_in_all:
+            kept_properties.append(name)
+        else:
+            logger.warning(
+                "Not all files provide terrain property '%s'; dropping it "
+                "from the merged terrain.",
+                name,
+            )
 
     def _concat_lists_or_b64(items: list[tuple]) -> list | None:
         # Each item is decoded independently, keyed by its own batch_size (not
@@ -309,9 +311,12 @@ def _merge_terrain(
             merged.extend(_decode_per_batch(value, batch_size))
         return merged
 
-    height_data, normals, friction_data, stiffness_data = [], [], [], []
+    height_data, normals = [], []
+    property_data: dict[str, list] = {name: [] for name in kept_properties}
     min_z = max_z = None
-    min_friction = max_friction = min_stiffness = max_stiffness = None
+    property_min_max: dict[str, tuple[float | None, float | None]] = {
+        name: (None, None) for name in kept_properties
+    }
     for model, batch_size, label in zip(models, batch_sizes, labels):
         terrain = model["terrain"]
         singleton = terrain.get("isSingleton", False)
@@ -335,51 +340,18 @@ def _merge_terrain(
         bounds = terrain["bounds"]
         min_z = bounds["minZ"] if min_z is None else min(min_z, bounds["minZ"])
         max_z = bounds["maxZ"] if max_z is None else max(max_z, bounds["maxZ"])
-        if has_friction:
-            friction_data.append(
+        for name in kept_properties:
+            prop = terrain["properties"][name]
+            property_data[name].append(
                 (
-                    _expand_batched(
-                        terrain["frictionData"],
-                        singleton,
-                        batch_size,
-                        "frictionData",
-                        label,
-                    ),
+                    _expand_batched(prop["data"], singleton, batch_size, name, label),
                     batch_size,
                 )
             )
-            min_friction = (
-                bounds["minFriction"]
-                if min_friction is None
-                else min(min_friction, bounds["minFriction"])
-            )
-            max_friction = (
-                bounds["maxFriction"]
-                if max_friction is None
-                else max(max_friction, bounds["maxFriction"])
-            )
-        if has_stiffness:
-            stiffness_data.append(
-                (
-                    _expand_batched(
-                        terrain["stiffnessData"],
-                        singleton,
-                        batch_size,
-                        "stiffnessData",
-                        label,
-                    ),
-                    batch_size,
-                )
-            )
-            min_stiffness = (
-                bounds["minStiffness"]
-                if min_stiffness is None
-                else min(min_stiffness, bounds["minStiffness"])
-            )
-            max_stiffness = (
-                bounds["maxStiffness"]
-                if max_stiffness is None
-                else max(max_stiffness, bounds["maxStiffness"])
+            cur_min, cur_max = property_min_max[name]
+            property_min_max[name] = (
+                prop["min"] if cur_min is None else min(cur_min, prop["min"]),
+                prop["max"] if cur_max is None else max(cur_max, prop["max"]),
             )
 
     merged_bounds = {
@@ -390,12 +362,15 @@ def _merge_terrain(
         "minZ": min_z,
         "maxZ": max_z,
     }
-    if has_friction:
-        merged_bounds["minFriction"] = min_friction
-        merged_bounds["maxFriction"] = max_friction
-    if has_stiffness:
-        merged_bounds["minStiffness"] = min_stiffness
-        merged_bounds["maxStiffness"] = max_stiffness
+
+    merged_properties = {
+        name: {
+            "data": _concat_lists_or_b64(property_data[name]),
+            "min": property_min_max[name][0],
+            "max": property_min_max[name][1],
+        }
+        for name in kept_properties
+    }
 
     return {
         "dimensions": dims,
@@ -403,10 +378,7 @@ def _merge_terrain(
         "isSingleton": False,
         "heightData": _concat_lists_or_b64(height_data),
         "normals": _concat_lists_or_b64(normals),
-        "frictionData": _concat_lists_or_b64(friction_data) if has_friction else None,
-        "stiffnessData": _concat_lists_or_b64(stiffness_data)
-        if has_stiffness
-        else None,
+        "properties": merged_properties,
     }