simview 3.2__py3-none-any.whl

simview/model.py

@@ -0,0 +1,690 @@
+import base64
+import logging
+from dataclasses import dataclass, field
+from enum import StrEnum
+from typing import Any
+
+import numpy as np
+import torch
+from einops import rearrange
+
+logger = logging.getLogger("simview.model")
+
+BLOB_PREFIX = "__b64__"
+
+
+def _encode_blob(array) -> str:
+    """Encode a numpy array as a little-endian float32 base64 blob string.
+
+    The `__b64__` prefix marks the value so the server (and merge) can round-trip
+    it as an opaque binary blob instead of verbose JSON.
+    """
+    return BLOB_PREFIX + base64.b64encode(array.astype("<f4").tobytes()).decode("utf-8")
+
+
+def _decode_blob(value):
+    """Decode a `__b64__`-prefixed base64 blob string back into a flat list of
+    little-endian float32 values. Values that aren't blob strings (already plain
+    JSON lists, or None) pass through unchanged, so callers can use this
+    unconditionally on fields that may or may not be binary-encoded."""
+    if not (isinstance(value, str) and value.startswith(BLOB_PREFIX)):
+        return value
+    raw = base64.b64decode(value[len(BLOB_PREFIX) :])
+    return np.frombuffer(raw, dtype="<f4").tolist()
+
+
+class BodyShapeType(StrEnum):
+    POINTCLOUD = "pointcloud"
+    MESH = "mesh"
+    BOX = "box"
+    SPHERE = "sphere"
+    CYLINDER = "cylinder"
+
+
+class OptionalBodyStateAttribute(StrEnum):
+    CONTACTS = "contacts"
+    VELOCITY = "velocity"
+    ANGULAR_VELOCITY = "angularVelocity"
+    FORCE = "force"
+    TORQUE = "torque"
+
+
+@dataclass
+class SimViewTerrain:
+    extent_x: float
+    extent_y: float
+    shape_x: int
+    shape_y: int
+    min_x: float
+    min_y: float
+    max_x: float
+    max_y: float
+    min_z: float
+    max_z: float
+    # These are plain nested lists when constructed directly, but `create()` (and
+    # deserialization from JSON) may instead store an opaque `__b64__`-prefixed
+    # base64 blob string for compactness; `to_json`/`from_dict` pass them through
+    # as-is either way.
+    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
+
+    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,
+                "sizeY": self.extent_y,
+                "resolutionX": self.shape_x,
+                "resolutionY": self.shape_y,
+            },
+            "bounds": bounds,
+            "heightData": self.height_data,
+            "normals": self.normals,
+            "isSingleton": self.is_singleton,
+            "frictionData": self.friction_data,
+            "stiffnessData": self.stiffness_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.
+        """
+        try:
+            dimensions = d["dimensions"]
+            bounds = d["bounds"]
+            height_data = d["heightData"]
+            normals = d["normals"]
+            is_singleton = d["isSingleton"]
+        except KeyError as e:
+            raise ValueError(f"Terrain dict is missing required key: {e}") from e
+
+        return cls(
+            extent_x=dimensions["sizeX"],
+            extent_y=dimensions["sizeY"],
+            shape_x=dimensions["resolutionX"],
+            shape_y=dimensions["resolutionY"],
+            min_x=bounds["minX"],
+            min_y=bounds["minY"],
+            max_x=bounds["maxX"],
+            max_y=bounds["maxY"],
+            min_z=bounds["minZ"],
+            max_z=bounds["maxZ"],
+            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"),
+        )
+
+    @staticmethod
+    def create(
+        heightmap: torch.Tensor,  # ! remember the x,y indexing is assumed to follow torch's "xy" convention, so increasing column index is increasing x coordinate
+        normals: torch.Tensor,
+        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,
+    ) -> "SimViewTerrain":
+        if heightmap.ndim != 3:
+            raise ValueError(
+                f"Heightmap must include a batch dimension (ndim=3); got ndim={heightmap.ndim}."
+            )
+        if normals.ndim != 4:
+            raise ValueError(
+                f"Normals must include a batch dimension (ndim=4); got ndim={normals.ndim}."
+            )
+        if normals.shape[1] != 3:
+            raise ValueError(
+                f"Normals must have 3 channels (shape[1] == 3); got shape={tuple(normals.shape)}."
+            )
+        B, Dy, Dx = heightmap.shape
+        min_x, max_x = x_lim
+        min_y, max_y = y_lim
+        min_z = heightmap.min().item()
+        max_z = heightmap.max().item()
+        extent_x = max_x - min_x
+        extent_y = max_y - min_y
+        height_data_list = _encode_blob(
+            rearrange(heightmap, "b d1 d2 -> b (d1 d2)").cpu().numpy()
+        )
+        normals_list = _encode_blob(
+            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:
+                raise ValueError(
+                    f"Friction map must include a batch dimension (ndim=3); got ndim={friction_map.ndim}."
+                )
+            friction_data_list = _encode_blob(
+                rearrange(friction_map, "b d1 d2 -> b (d1 d2)").cpu().numpy()
+            )
+            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:
+                raise ValueError(
+                    f"Stiffness map must include a batch dimension (ndim=3); got ndim={stiffness_map.ndim}."
+                )
+            stiffness_data_list = _encode_blob(
+                rearrange(stiffness_map, "b d1 d2 -> b (d1 d2)").cpu().numpy()
+            )
+            min_stiffness = stiffness_map.min().item()
+            max_stiffness = stiffness_map.max().item()
+
+        return SimViewTerrain(
+            extent_x=extent_x,
+            extent_y=extent_y,
+            shape_x=Dx,
+            shape_y=Dy,
+            min_x=min_x,
+            min_y=min_y,
+            max_x=max_x,
+            max_y=max_y,
+            min_z=min_z,
+            max_z=max_z,
+            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,
+        )
+
+
+@dataclass
+class SimViewBody:
+    name: str
+    shape: dict
+    available_attributes: list[OptionalBodyStateAttribute] | None = None
+    # `parent`/`local_transform` express this body's pose relative to another
+    # body instead of world space. `local_transform` (a constant [x,y,z,w,qx,qy,qz]
+    # offset) marks a *rigid* attachment (e.g. a wheel bolted to a chassis): this
+    # body never appears in any state's `bodies[]`, and its world pose is derived
+    # every frame from the parent's current pose plus this fixed offset. An
+    # *articulated* attachment (e.g. an arm joint) instead sets only `parent` and
+    # keeps supplying a per-frame `bodyTransform` in states as usual -- it's just
+    # interpreted as local to the parent's current-frame pose rather than world.
+    parent: str | None = None
+    local_transform: list[float] | None = None
+
+    def __post_init__(self):
+        if self.local_transform is not None:
+            if self.parent is None:
+                raise ValueError(
+                    f"Body '{self.name}' has local_transform but no parent; "
+                    "local_transform only makes sense relative to a parent body."
+                )
+            if len(self.local_transform) != 7:
+                raise ValueError(
+                    f"Body '{self.name}' local_transform must have 7 elements "
+                    f"([x, y, z, w, qx, qy, qz]); got {len(self.local_transform)}."
+                )
+
+    def set_available_attributes(
+        self, available_attributes: list[str | OptionalBodyStateAttribute]
+    ) -> None:
+        if self.available_attributes is not None:
+            raise ValueError("Available attributes already set")
+        self.available_attributes = [
+            v
+            if isinstance(v, OptionalBodyStateAttribute)
+            else OptionalBodyStateAttribute(v)
+            for v in available_attributes
+        ]
+
+    @staticmethod
+    def _create_shape_dict(body_type: BodyShapeType, **kwargs) -> dict:
+        """Helper to create the shape dictionary, converting tensors."""
+        shape_dict: dict[str, Any] = {"type": body_type.value}
+        for key, value in kwargs.items():
+            if isinstance(value, torch.Tensor):
+                if value.numel() > 1:
+                    shape_dict[key] = _encode_blob(value.cpu().numpy())
+                else:
+                    shape_dict[key] = value.item()
+            else:
+                shape_dict[key] = value
+        return shape_dict
+
+    @staticmethod
+    def create(
+        name: str,
+        body_type: BodyShapeType,
+        available_attributes: list[OptionalBodyStateAttribute | str] | None = None,
+        parent: str | None = None,
+        local_transform: Any | None = None,
+        **kwargs,
+    ) -> "SimViewBody":
+        shape_dict = SimViewBody._create_shape_dict(body_type, **kwargs)
+        if local_transform is not None and hasattr(local_transform, "tolist"):
+            local_transform = local_transform.tolist()
+        body = SimViewBody(
+            name=name,
+            shape=shape_dict,
+            parent=parent,
+            local_transform=list(local_transform)
+            if local_transform is not None
+            else None,
+        )
+        if available_attributes is not None:
+            body.set_available_attributes(available_attributes)
+        return body
+
+    @staticmethod
+    def create_box(
+        name: str, hx: float, hy: float, hz: float, **kwargs
+    ) -> "SimViewBody":
+        return SimViewBody.create(
+            name, BodyShapeType.BOX, hx=hx, hy=hy, hz=hz, **kwargs
+        )
+
+    @staticmethod
+    def create_sphere(name: str, radius: float, **kwargs) -> "SimViewBody":
+        return SimViewBody.create(name, BodyShapeType.SPHERE, radius=radius, **kwargs)
+
+    @staticmethod
+    def create_cylinder(
+        name: str, radius: float, height: float, **kwargs
+    ) -> "SimViewBody":
+        return SimViewBody.create(
+            name, BodyShapeType.CYLINDER, radius=radius, height=height, **kwargs
+        )
+
+    @staticmethod
+    def create_pointcloud(name: str, points: torch.Tensor, **kwargs) -> "SimViewBody":
+        return SimViewBody.create(
+            name, BodyShapeType.POINTCLOUD, points=points, **kwargs
+        )
+
+    @staticmethod
+    def create_mesh(
+        name: str, vertices: torch.Tensor, faces: torch.Tensor, **kwargs
+    ) -> "SimViewBody":
+        return SimViewBody.create(
+            name, BodyShapeType.MESH, vertices=vertices, faces=faces, **kwargs
+        )
+
+    def to_json(self) -> dict:
+        r = {"name": self.name, "shape": self.shape}
+        if self.available_attributes is not None:
+            r["availableAttributes"] = [v.value for v in self.available_attributes]
+        if self.parent is not None:
+            r["parent"] = self.parent
+        if self.local_transform is not None:
+            r["localTransform"] = self.local_transform
+        return r
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "SimViewBody":
+        """Reconstruct a SimViewBody from the dict produced by `to_json`."""
+        try:
+            name = d["name"]
+            shape = d["shape"]
+        except KeyError as e:
+            raise ValueError(f"Body dict is missing required key: {e}") from e
+        available_attributes = d.get("availableAttributes")
+        return cls(
+            name=name,
+            shape=shape,
+            available_attributes=[
+                OptionalBodyStateAttribute(v) for v in available_attributes
+            ]
+            if available_attributes is not None
+            else None,
+            parent=d.get("parent"),
+            local_transform=d.get("localTransform"),
+        )
+
+
+@dataclass
+class SimViewStaticObject:
+    name: str
+    is_singleton: bool
+    shape: dict | None = None  # Used if is_singleton is True
+    shapes: list[dict] | None = None  # Used if is_singleton is False
+
+    def __post_init__(self):
+        if self.is_singleton and self.shape is None:
+            raise ValueError("Singleton static object requires 'shape'.")
+        if not self.is_singleton and self.shapes is None:
+            raise ValueError("Batched static object requires 'shapes'.")
+        if self.is_singleton and self.shapes is not None:
+            raise ValueError("Singleton static object cannot have 'shapes'.")
+        if not self.is_singleton and self.shape is not None:
+            raise ValueError("Batched static object cannot have 'shape'.")
+        # Basic validation for batched shapes length could be added if batch_size is known here
+
+    @staticmethod
+    def create_singleton(
+        name: str, shape_type: BodyShapeType, **kwargs
+    ) -> "SimViewStaticObject":
+        shape_dict = SimViewBody._create_shape_dict(
+            shape_type, **kwargs
+        )  # Reuse helper
+        return SimViewStaticObject(name=name, is_singleton=True, shape=shape_dict)
+
+    @staticmethod
+    def create_batched(
+        name: str, shape_type: BodyShapeType, shapes_kwargs: list[dict[str, Any]]
+    ) -> "SimViewStaticObject":
+        """
+        Creates a batched static object where all instances share the same shape type.
+
+        Args:
+            name: The name of the static object group.
+            shape_type: The BodyShapeType common to all instances in the batch.
+            shapes_kwargs: A list of dictionaries, where each dictionary contains the
+                           keyword arguments for creating the shape of one instance
+                           in the batch (e.g., [{'hx': 0.1, 'hy': 0.1, 'hz': 0.1}, {'hx': 0.2, ...}]).
+                           The length of this list must match the batch size.
+        """
+        shapes_list = []
+        if not shapes_kwargs:
+            raise ValueError("Batched shapes kwargs list cannot be empty.")
+        # The check for list length matching batch_size happens in SimViewModel.add_static_object
+        for kwargs in shapes_kwargs:
+            # Ensure 'type' isn't passed within kwargs, as it's defined by shape_type
+            if "type" in kwargs:
+                raise ValueError(
+                    "Do not include 'type' in shapes_kwargs; use the shape_type argument."
+                )
+            shapes_list.append(
+                SimViewBody._create_shape_dict(shape_type, **kwargs)
+            )  # Reuse helper
+        return SimViewStaticObject(name=name, is_singleton=False, shapes=shapes_list)
+
+    def to_json(self) -> dict:
+        r = {"name": self.name, "isSingleton": self.is_singleton}
+        if self.is_singleton:
+            r["shape"] = self.shape
+        else:
+            r["shapes"] = self.shapes
+        return r
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "SimViewStaticObject":
+        """Reconstruct a SimViewStaticObject from the dict produced by `to_json`."""
+        try:
+            name = d["name"]
+            is_singleton = d["isSingleton"]
+        except KeyError as e:
+            raise ValueError(f"Static object dict is missing required key: {e}") from e
+        return cls(
+            name=name,
+            is_singleton=is_singleton,
+            shape=d.get("shape"),
+            shapes=d.get("shapes"),
+        )
+
+
+def _validate_parent_ref(name: str, parent: str | None, known_bodies: dict) -> None:
+    """Raise ValueError if `parent` is self-referential or isn't already in
+    `known_bodies`. Requiring the parent to already be known (rather than doing
+    a full topological sort) structurally prevents cycles as each body is
+    added/parsed: a cycle would require some body to reference a not-yet-known
+    name, which this catches immediately."""
+    if parent is None:
+        return
+    if parent == name:
+        raise ValueError(f"Body '{name}' cannot be its own parent.")
+    if parent not in known_bodies:
+        raise ValueError(
+            f"Body '{name}' references unknown parent '{parent}'; the parent "
+            "must already be defined in the model (added/listed before its children)."
+        )
+
+
+@dataclass
+class SimViewModel:
+    batch_size: int
+    scalar_names: list[str]
+    dt: float
+    collapse: bool
+    terrain: SimViewTerrain | None = None
+    bodies: dict[str, SimViewBody] = field(default_factory=dict)
+    static_objects: dict[str, SimViewStaticObject] = field(default_factory=dict)
+    batch_names: list[str] | None = None
+
+    def __post_init__(self):
+        if self.batch_names is not None and len(self.batch_names) != self.batch_size:
+            raise ValueError(
+                f"batch_names length ({len(self.batch_names)}) must match batch size ({self.batch_size})"
+            )
+
+    def add_terrain(self, terrain: SimViewTerrain) -> None:
+        if self.terrain is not None:
+            raise ValueError("Terrain already exists")
+        self.terrain = terrain
+
+    def add_body(self, body: SimViewBody) -> None:
+        if body.name in self.bodies:
+            raise ValueError(f"Dynamic body {body.name} already exists")
+        _validate_parent_ref(body.name, body.parent, self.bodies)
+        self.bodies[body.name] = body
+
+    def add_static_object(self, static_object: SimViewStaticObject) -> None:
+        if static_object.name in self.static_objects:
+            raise ValueError(f"Static object {static_object.name} already exists")
+        if not static_object.is_singleton:
+            # SimViewStaticObject.__post_init__ guarantees `shapes` is set
+            # (not None) whenever `is_singleton` is False.
+            assert static_object.shapes is not None
+            if len(static_object.shapes) != self.batch_size:
+                raise ValueError(
+                    f"Batched static object '{static_object.name}' shapes count "
+                    f"({len(static_object.shapes)}) must match batch size "
+                    f"({self.batch_size})."
+                )
+        self.static_objects[static_object.name] = static_object
+
+    def create_terrain(
+        self,
+        heightmap: torch.Tensor,
+        normals: torch.Tensor,
+        x_lim: tuple[float, float],
+        y_lim: tuple[float, float],
+        friction_map: torch.Tensor | None = None,
+        stiffness_map: torch.Tensor | None = None,
+    ) -> None:
+        if heightmap.ndim == 2:
+            heightmap = heightmap.unsqueeze(0)  # add batch dim
+        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)
+
+        # 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
+        # code silently mishandled the mixed case (e.g. shared height + per-batch
+        # normals), producing an inconsistent isSingleton flag.
+        provided = {
+            "heightmap": heightmap,
+            "normals": normals,
+            "friction_map": friction_map,
+            "stiffness_map": stiffness_map,
+        }
+        for name, tensor in provided.items():
+            if tensor is not None and tensor.shape[0] not in (1, self.batch_size):
+                raise ValueError(
+                    f"Terrain '{name}' batch dim ({tensor.shape[0]}) must be 1 "
+                    f"(shared) or {self.batch_size} (per-batch)."
+                )
+
+        # Singleton only when every provided field is shared and there is more than
+        # one batch to share it across.
+        is_singleton = self.batch_size > 1 and all(
+            tensor.shape[0] == 1 for tensor in provided.values() if tensor is not None
+        )
+
+        # The viewer always splits terrain data into batch_size chunks, so broadcast
+        # any shared field up to the full batch size before encoding.
+        if self.batch_size > 1:
+            if heightmap.shape[0] == 1:
+                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)
+
+        self.terrain = SimViewTerrain.create(
+            heightmap=heightmap,
+            normals=normals,
+            x_lim=x_lim,
+            y_lim=y_lim,
+            is_singleton=is_singleton,
+            friction_map=friction_map,
+            stiffness_map=stiffness_map,
+        )
+
+    def create_body(
+        self,
+        body_name: str,
+        shape_type: BodyShapeType,
+        available_attributes: list[OptionalBodyStateAttribute | str] | None = None,
+        parent: str | None = None,
+        local_transform: Any | None = None,
+        **kwargs,
+    ) -> None:
+        if body_name in self.bodies:
+            raise ValueError(f"Dynamic body {body_name} already exists")
+        body = SimViewBody.create(
+            body_name,
+            shape_type,
+            available_attributes=available_attributes,
+            parent=parent,
+            local_transform=local_transform,
+            **kwargs,
+        )
+        self.add_body(body)
+
+    def create_static_object_singleton(
+        self, name: str, shape_type: BodyShapeType, **kwargs
+    ) -> None:
+        static_obj = SimViewStaticObject.create_singleton(name, shape_type, **kwargs)
+        self.add_static_object(static_obj)
+
+    def create_static_object_batched(
+        self, name: str, shape_type: BodyShapeType, shapes_kwargs: list[dict[str, Any]]
+    ) -> None:
+        """Helper method to create and add a batched static object."""
+        if len(shapes_kwargs) != self.batch_size:
+            raise ValueError(
+                f"Length of shapes_kwargs ({len(shapes_kwargs)}) must match batch size ({self.batch_size}) for '{name}'."
+            )
+        static_obj = SimViewStaticObject.create_batched(name, shape_type, shapes_kwargs)
+        self.add_static_object(
+            static_obj
+        )  # add_static_object already performs the length check
+
+    def to_json(self) -> dict:
+        if not self.bodies:
+            logger.warning("No dynamic bodies defined in the model.")
+        if self.terrain is None:
+            raise ValueError("No terrain defined")
+        r = {
+            "simBatches": self.batch_size,
+            "scalarNames": self.scalar_names,
+            "dt": self.dt,
+            "collapse": self.collapse,
+            "terrain": self.terrain.to_json(),
+            "bodies": [b.to_json() for b in self.bodies.values()],
+            "staticObjects": [s.to_json() for s in self.static_objects.values()],
+        }
+        if self.batch_names is not None:
+            r["batchNames"] = self.batch_names
+        return r
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "SimViewModel":
+        """Reconstruct a SimViewModel from the dict produced by `to_json`.
+
+        Centralizes parsing of the wire format: terrain, bodies and static
+        objects are all rebuilt via their own `from_dict`, keyed by name so
+        `add_body`/`add_static_object`'s uniqueness checks stay meaningful.
+        """
+        try:
+            batch_size = d["simBatches"]
+            scalar_names = d["scalarNames"]
+            dt = d["dt"]
+            collapse = d["collapse"]
+            terrain_dict = d["terrain"]
+            body_dicts = d["bodies"]
+            static_object_dicts = d["staticObjects"]
+        except KeyError as e:
+            raise ValueError(f"Model dict is missing required key: {e}") from e
+
+        bodies = {}
+        for body_dict in body_dicts:
+            body = SimViewBody.from_dict(body_dict)
+            if body.name in bodies:
+                raise ValueError(f"Model dict has duplicate body name '{body.name}'")
+            _validate_parent_ref(body.name, body.parent, bodies)
+            bodies[body.name] = body
+
+        static_objects = {}
+        for static_object_dict in static_object_dicts:
+            static_object = SimViewStaticObject.from_dict(static_object_dict)
+            static_objects[static_object.name] = static_object
+
+        return cls(
+            batch_size=batch_size,
+            scalar_names=scalar_names,
+            dt=dt,
+            collapse=collapse,
+            terrain=SimViewTerrain.from_dict(terrain_dict),
+            bodies=bodies,
+            static_objects=static_objects,
+            batch_names=d.get("batchNames"),
+        )
+
+    @property
+    def is_complete(self) -> bool:
+        return self.terrain is not None