Skip to content

State & Trajectories

simview.state defines the per-frame dynamic data in the JSON format: SimViewBodyState for one frame at a time, and BodyTrajectory for authoring a whole (T, B, ...) trajectory in a single call.

simview.state

BodyTrajectory dataclass 

BodyTrajectory(
    name: str | list[str],
    positions: ArrayLike,
    orientations: ArrayLike,
    velocity: ArrayLike | None = None,
    angular_velocity: ArrayLike | None = None,
    force: ArrayLike | None = None,
    torque: ArrayLike | None = None,
    contacts: list | None = None,
)

A whole-timeline pose (and optional vectors) for one body.

Shapes are (T, B, k) — T timesteps, B batches — or (T, k) when the scene has a single batch. Orientations are [w, x, y, z] (scalar-first), matching the rest of SimView. Pass a list of these to :meth:SimulationScene.add_trajectory to append an entire time-series in one call instead of building a SimViewBodyState per frame.

name may be a list of body names instead of a single string, to cover several bodies that move rigidly together (e.g. links welded to the same parent). All named bodies must already exist in the model, and the transform/vectors here are applied identically to each of them, avoiding the need to duplicate the same data per body.

If the named body has a parent set in the model (see SimulationScene.create_body), positions/orientations here are interpreted as local to that parent's current-frame pose instead of world space. A body with a constant local_transform on the model instead must never appear in a BodyTrajectory at all.

SimViewBodyState 

SimViewBodyState(
    body_name: str | list[str],
    position: ArrayLike,
    orientation: ArrayLike,
    optional_attributes: dict | None = None,
    binary: bool = True,
)

body_name may be a list of body names sharing this exact transform (and any optional attributes), for bodies that move rigidly together — see :class:BodyTrajectory for the same idea applied to whole trajectories.

If the named body has a parent set in the model, position/ orientation here are interpreted as local to that parent's current-frame pose instead of world space (see SimulationScene.create_body).

With binary=True (the default, matching SimulationScene.add_trajectory), bodyTransform and any provided vector attributes (velocity/angularVelocity/force/torque) are packed as float32 __b64__ blobs, shrinking the output file; the viewer and :func:merge_simulation_files decode these transparently. Set binary=False to emit plain JSON lists.