simview 3.6__tar.gz → 4.0.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: simview
-Version: 3.6
+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.6 → 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.6 → simview-4.0.0}/pyproject.toml

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

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

@@ -374,11 +374,12 @@ def build_parser() -> argparse.ArgumentParser:
     )
     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(

{simview-3.6 → 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()
+        },
     }
 
 
@@ -466,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.6 → 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,
     }
 
 

{simview-3.6 → simview-4.0.0}/simview/model.py

@@ -49,6 +49,27 @@ class OptionalBodyStateAttribute(StrEnum):
     TORQUE = "torque"
 
 
+@dataclass
+class TerrainProperty:
+    """One arbitrary named per-cell scalar field over the terrain grid (e.g.
+    friction, stiffness, or any other user-defined property), stored the same
+    way as `SimViewTerrain.height_data` -- a plain nested list, or an opaque
+    `__b64__`-prefixed blob string for compactness."""
+
+    data: list[list[float]] | str
+    # Value range used by the viewer to normalize the color map (analogous to
+    # min_z/max_z for height). None when not computed.
+    min: float | None = None
+    max: float | None = None
+
+    def to_json(self):
+        return {"data": self.data, "min": self.min, "max": self.max}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "TerrainProperty":
+        return cls(data=d["data"], min=d.get("min"), max=d.get("max"))
+
+
 @dataclass
 class SimViewTerrain:
     extent_x: float
@@ -68,33 +89,22 @@ class SimViewTerrain:
     height_data: list[list[float]] | str
     normals: list[list[list[float]]] | str
     is_singleton: bool
-    friction_data: list[list[float]] | str | None = None
-    stiffness_data: list[list[float]] | str | None = None
-    # Value ranges used by the viewer to normalize the color map (analogous to
-    # min_z/max_z for height). None when the corresponding data is absent.
-    min_friction: float | None = None
-    max_friction: float | None = None
-    min_stiffness: float | None = None
-    max_stiffness: float | None = None
+    # Arbitrary named per-cell scalar fields (e.g. "friction", "stiffness", or
+    # any other user-defined property), keyed by name -- see `TerrainProperty`.
+    # Adding a new property never requires touching this class or the viewer:
+    # supply it by name in `create()`'s `properties` dict and it becomes
+    # selectable as a terrain color mode automatically.
+    properties: dict[str, TerrainProperty] = field(default_factory=dict)
+    # Per-cell K-wide feature vector (e.g. a reduced-dim PCA projection of a
+    # learned backbone's features), stored the same way as `normals` (width
+    # inferred client-side from flat length, not shipped explicitly). Used by
+    # the viewer's "features" color mode: cosine similarity to a clicked cell,
+    # computed entirely in-browser -- not a named scalar property, so it has
+    # no min/max bounds (similarity is always [-1, 1]) and isn't part of
+    # `properties`.
+    embedding_data: list[list[float]] | str | None = None
 
     def to_json(self):
-        # min/max friction/stiffness are independent Optional fields (not tied to
-        # friction_data/stiffness_data by the type system, only by convention in
-        # create()/from_dict), so the dict's values are genuinely `float | None`.
-        bounds: dict[str, float | None] = {
-            "minX": self.min_x,
-            "minY": self.min_y,
-            "maxX": self.max_x,
-            "maxY": self.max_y,
-            "minZ": self.min_z,
-            "maxZ": self.max_z,
-        }
-        if self.friction_data is not None:
-            bounds["minFriction"] = self.min_friction
-            bounds["maxFriction"] = self.max_friction
-        if self.stiffness_data is not None:
-            bounds["minStiffness"] = self.min_stiffness
-            bounds["maxStiffness"] = self.max_stiffness
         return {
             "dimensions": {
                 "sizeX": self.extent_x,
@@ -102,22 +112,31 @@ class SimViewTerrain:
                 "resolutionX": self.shape_x,
                 "resolutionY": self.shape_y,
             },
-            "bounds": bounds,
+            "bounds": {
+                "minX": self.min_x,
+                "minY": self.min_y,
+                "maxX": self.max_x,
+                "maxY": self.max_y,
+                "minZ": self.min_z,
+                "maxZ": self.max_z,
+            },
             "heightData": self.height_data,
             "normals": self.normals,
             "isSingleton": self.is_singleton,
-            "frictionData": self.friction_data,
-            "stiffnessData": self.stiffness_data,
+            "properties": {
+                name: prop.to_json() for name, prop in self.properties.items()
+            },
+            "embeddingData": self.embedding_data,
         }
 
     @classmethod
     def from_dict(cls, d: dict) -> "SimViewTerrain":
         """Reconstruct a SimViewTerrain from the dict produced by `to_json`.
 
-        `heightData`/`normals`/`frictionData`/`stiffnessData` are kept in
-        whatever form they were serialized in (plain nested lists or a
-        `__b64__` blob string) -- decode with `simview.model._decode_blob` if
-        you need the flat float values back out.
+        `heightData`/`normals`/each property's `data` are kept in whatever
+        form they were serialized in (plain nested lists or a `__b64__` blob
+        string) -- decode with `simview.model._decode_blob` if you need the
+        flat float values back out.
         """
         try:
             dimensions = d["dimensions"]
@@ -128,6 +147,11 @@ class SimViewTerrain:
         except KeyError as e:
             raise ValueError(f"Terrain dict is missing required key: {e}") from e
 
+        properties = {
+            name: TerrainProperty.from_dict(p)
+            for name, p in (d.get("properties") or {}).items()
+        }
+
         return cls(
             extent_x=dimensions["sizeX"],
             extent_y=dimensions["sizeY"],
@@ -142,12 +166,8 @@ class SimViewTerrain:
             height_data=height_data,
             normals=normals,
             is_singleton=is_singleton,
-            friction_data=d.get("frictionData"),
-            stiffness_data=d.get("stiffnessData"),
-            min_friction=bounds.get("minFriction"),
-            max_friction=bounds.get("maxFriction"),
-            min_stiffness=bounds.get("minStiffness"),
-            max_stiffness=bounds.get("maxStiffness"),
+            properties=properties,
+            embedding_data=d.get("embeddingData"),
         )
 
     @staticmethod
@@ -157,8 +177,8 @@ class SimViewTerrain:
         x_lim: tuple[float, float],
         y_lim: tuple[float, float],
         is_singleton: bool,
-        friction_map: torch.Tensor | None = None,
-        stiffness_map: torch.Tensor | None = None,
+        properties: dict[str, torch.Tensor] | None = None,
+        embedding_map: torch.Tensor | None = None,
     ) -> "SimViewTerrain":
         if heightmap.ndim != 3:
             raise ValueError(
@@ -186,31 +206,30 @@ class SimViewTerrain:
             rearrange(normals, "b c d1 d2 -> b (d1 d2) c").cpu().numpy()
         )
 
-        friction_data_list = None
-        min_friction = max_friction = None
-        if friction_map is not None:
-            if friction_map.ndim != 3:
+        properties_out: dict[str, TerrainProperty] = {}
+        for name, prop_map in (properties or {}).items():
+            if prop_map.ndim != 3:
                 raise ValueError(
-                    f"Friction map must include a batch dimension (ndim=3); got ndim={friction_map.ndim}."
+                    f"Property '{name}' map must include a batch dimension "
+                    f"(ndim=3); got ndim={prop_map.ndim}."
                 )
-            friction_data_list = _encode_blob(
-                rearrange(friction_map, "b d1 d2 -> b (d1 d2)").cpu().numpy()
+            properties_out[name] = TerrainProperty(
+                data=_encode_blob(
+                    rearrange(prop_map, "b d1 d2 -> b (d1 d2)").cpu().numpy()
+                ),
+                min=prop_map.min().item(),
+                max=prop_map.max().item(),
             )
-            min_friction = friction_map.min().item()
-            max_friction = friction_map.max().item()
 
-        stiffness_data_list = None
-        min_stiffness = max_stiffness = None
-        if stiffness_map is not None:
-            if stiffness_map.ndim != 3:
+        embedding_data_list = None
+        if embedding_map is not None:
+            if embedding_map.ndim != 4:
                 raise ValueError(
-                    f"Stiffness map must include a batch dimension (ndim=3); got ndim={stiffness_map.ndim}."
+                    f"Embedding map must include a batch dimension (ndim=4); got ndim={embedding_map.ndim}."
                 )
-            stiffness_data_list = _encode_blob(
-                rearrange(stiffness_map, "b d1 d2 -> b (d1 d2)").cpu().numpy()
+            embedding_data_list = _encode_blob(
+                rearrange(embedding_map, "b k d1 d2 -> b (d1 d2) k").cpu().numpy()
             )
-            min_stiffness = stiffness_map.min().item()
-            max_stiffness = stiffness_map.max().item()
 
         return SimViewTerrain(
             extent_x=extent_x,
@@ -226,12 +245,8 @@ class SimViewTerrain:
             height_data=height_data_list,
             normals=normals_list,
             is_singleton=is_singleton,
-            friction_data=friction_data_list,
-            stiffness_data=stiffness_data_list,
-            min_friction=min_friction,
-            max_friction=max_friction,
-            min_stiffness=min_stiffness,
-            max_stiffness=max_stiffness,
+            properties=properties_out,
+            embedding_data=embedding_data_list,
         )
 
 
@@ -335,7 +350,37 @@ class SimViewBody:
         )
 
     @staticmethod
-    def create_pointcloud(name: str, points: torch.Tensor, **kwargs) -> "SimViewBody":
+    def create_pointcloud(
+        name: str,
+        points: torch.Tensor,
+        color: torch.Tensor | None = None,
+        embedding: torch.Tensor | None = None,
+        **kwargs,
+    ) -> "SimViewBody":
+        """`color` (N, 3) in [0, 1] is an optional static per-point RGB color,
+        used by the viewer for vertex-colored rendering. `embedding` (N, K) is
+        an optional per-point K-wide feature vector (e.g. a reduced-dim PCA
+        projection of a learned backbone's features) enabling the viewer's
+        click-to-similarity color mode: cosine similarity to a clicked point,
+        computed entirely in-browser from this data. Both round-trip through
+        the existing generic `__b64__` blob mechanism -- no new wire format."""
+        if points.ndim != 2 or points.shape[1] != 3:
+            raise ValueError(
+                f"points must have shape (N, 3); got {tuple(points.shape)}."
+            )
+        N = points.shape[0]
+        if color is not None:
+            if tuple(color.shape) != (N, 3):
+                raise ValueError(
+                    f"color must have shape ({N}, 3) matching points; got {tuple(color.shape)}."
+                )
+            kwargs["color"] = color
+        if embedding is not None:
+            if embedding.ndim != 2 or embedding.shape[0] != N:
+                raise ValueError(
+                    f"embedding must have shape ({N}, K) matching points; got {tuple(embedding.shape)}."
+                )
+            kwargs["embedding"] = embedding
         return SimViewBody.create(
             name, BodyShapeType.POINTCLOUD, points=points, **kwargs
         )
@@ -532,8 +577,8 @@ class SimViewModel:
         x_lim: tuple[float, float] | None = None,
         y_lim: tuple[float, float] | None = None,
         grid_res: float | None = None,
-        friction_map: torch.Tensor | None = None,
-        stiffness_map: torch.Tensor | None = None,
+        properties: dict[str, torch.Tensor] | None = None,
+        embedding_map: torch.Tensor | None = None,
     ) -> None:
         """Adds terrain to the internal simulation model.
 
@@ -545,8 +590,14 @@ class SimViewModel:
             y_lim (tuple[float, float] | None): (min, max) coordinates for the Y axis.
             grid_res (float | None): Grid resolution. If x_lim and y_lim are omitted,
                 they will be automatically inferred assuming the grid is centered at 0.
-            friction_map (torch.Tensor | None): Optional friction coefficient map.
-            stiffness_map (torch.Tensor | None): Optional stiffness coefficient map.
+            properties (dict[str, torch.Tensor] | None): Optional arbitrary named
+                per-cell scalar maps (2D or 3D, like `heightmap`), e.g.
+                `{"friction": friction_map, "stiffness": stiffness_map}`. Each becomes
+                selectable as a terrain color mode in the viewer automatically, with no
+                further code changes needed.
+            embedding_map (torch.Tensor | None): Optional per-cell K-wide feature map
+                (3D channels-first `(K, Dy, Dx)` or 4D `(B, K, Dy, Dx)`, like `normals`)
+                enabling the viewer's click-to-similarity "features" color mode.
         """
         if heightmap.ndim == 2:
             heightmap = heightmap.unsqueeze(0)  # add batch dim
@@ -574,10 +625,12 @@ class SimViewModel:
 
         if normals.ndim == 3:  # channels first
             normals = normals.unsqueeze(0)  # add batch dim
-        if friction_map is not None and friction_map.ndim == 2:
-            friction_map = friction_map.unsqueeze(0)
-        if stiffness_map is not None and stiffness_map.ndim == 2:
-            stiffness_map = stiffness_map.unsqueeze(0)
+        properties = {
+            name: (prop.unsqueeze(0) if prop.ndim == 2 else prop)
+            for name, prop in (properties or {}).items()
+        }
+        if embedding_map is not None and embedding_map.ndim == 3:  # channels first
+            embedding_map = embedding_map.unsqueeze(0)
 
         # Each field's batch dim must be either 1 (shared across all batches) or
         # exactly batch_size (per-batch). Anything else is a mistake, and the old
@@ -586,8 +639,8 @@ class SimViewModel:
         provided = {
             "heightmap": heightmap,
             "normals": normals,
-            "friction_map": friction_map,
-            "stiffness_map": stiffness_map,
+            "embedding_map": embedding_map,
+            **properties,
         }
         for name, tensor in provided.items():
             if tensor is not None and tensor.shape[0] not in (1, self.batch_size):
@@ -609,10 +662,14 @@ class SimViewModel:
                 heightmap = heightmap.repeat(self.batch_size, 1, 1)
             if normals.shape[0] == 1:
                 normals = normals.repeat(self.batch_size, 1, 1, 1)
-            if friction_map is not None and friction_map.shape[0] == 1:
-                friction_map = friction_map.repeat(self.batch_size, 1, 1)
-            if stiffness_map is not None and stiffness_map.shape[0] == 1:
-                stiffness_map = stiffness_map.repeat(self.batch_size, 1, 1)
+            properties = {
+                name: (
+                    prop.repeat(self.batch_size, 1, 1) if prop.shape[0] == 1 else prop
+                )
+                for name, prop in properties.items()
+            }
+            if embedding_map is not None and embedding_map.shape[0] == 1:
+                embedding_map = embedding_map.repeat(self.batch_size, 1, 1, 1)
 
         self.terrain = SimViewTerrain.create(
             heightmap=heightmap,
@@ -620,8 +677,8 @@ class SimViewModel:
             x_lim=x_lim,
             y_lim=y_lim,
             is_singleton=is_singleton,
-            friction_map=friction_map,
-            stiffness_map=stiffness_map,
+            properties=properties,
+            embedding_map=embedding_map,
         )
 
     def create_body(