Skip to content

Model (Bodies, Shapes, Terrain)

simview.model defines the static, once-per-scene part of the JSON format: SimViewModel, the bodies/shapes that make it up, static (non-moving) objects, and the terrain heightfield.

simview.model

SimViewBody dataclass 

SimViewBody(
    name: str,
    shape: dict,
    available_attributes: list[OptionalBodyStateAttribute]
    | None = None,
    parent: str | None = None,
    local_transform: list[float] | None = None,
)

create_pointcloud staticmethod 

create_pointcloud(
    name: str,
    points: Tensor,
    color: Tensor | None = None,
    embedding: 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.

from_dict classmethod 

from_dict(d: dict) -> SimViewBody

Reconstruct a SimViewBody from the dict produced by to_json.

SimViewModel dataclass 

SimViewModel(
    batch_size: int,
    scalar_names: list[str],
    dt: float,
    collapse: bool,
    terrain: SimViewTerrain | None = None,
    bodies: dict[str, SimViewBody] = dict(),
    static_objects: dict[str, SimViewStaticObject] = dict(),
    batch_names: list[str] | None = None,
    metadata: dict[str, Any] | None = None,
)

create_static_object_batched 

create_static_object_batched(
    name: str,
    shape_type: BodyShapeType,
    shapes_kwargs: list[dict[str, Any]],
) -> None

Helper method to create and add a batched static object.

create_terrain 

create_terrain(
    heightmap: Tensor,
    normals: Tensor | None = None,
    x_lim: tuple[float, float] | None = None,
    y_lim: tuple[float, float] | None = None,
    grid_res: float | None = None,
    properties: dict[str, Tensor] | None = None,
    embedding_map: Tensor | None = None,
) -> None

Adds terrain to the internal simulation model.

Parameters:

Name Type Description Default
heightmap Tensor

2D or 3D tensor of terrain heights.

 required
normals Tensor | None

3D or 4D tensor of terrain normals. If None, normals are automatically computed from the heightmap gradients.

 None
x_lim tuple[float, float] | None

(min, max) coordinates for the X axis.

 None
y_lim tuple[float, float] | None

(min, max) coordinates for the Y axis.

 None
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.

 None
properties dict[str, 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.

 None
embedding_map 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.

 None

from_dict classmethod 

from_dict(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.

SimViewStaticObject dataclass 

SimViewStaticObject(
    name: str,
    is_singleton: bool,
    shape: dict | None = None,
    shapes: list[dict] | None = None,
)

create_batched staticmethod 

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.

Parameters:

Name Type Description Default
name str

The name of the static object group.

 required
shape_type BodyShapeType

The BodyShapeType common to all instances in the batch.

 required
shapes_kwargs list[dict[str, Any]]

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.

 required

from_dict classmethod 

from_dict(d: dict) -> SimViewStaticObject

Reconstruct a SimViewStaticObject from the dict produced by to_json.

SimViewTerrain dataclass 

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,
    height_data: list[list[float]] | str,
    normals: list[list[list[float]]] | str,
    is_singleton: bool,
    properties: dict[str, TerrainProperty] = dict(),
    embedding_data: list[list[float]] | str | None = None,
)

from_dict classmethod 

from_dict(d: dict) -> SimViewTerrain

Reconstruct a SimViewTerrain from the dict produced by to_json.

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.

TerrainProperty dataclass 

TerrainProperty(
    data: list[list[float]] | str,
    min: float | None = None,
    max: float | None = None,
)

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.