VEHICLE LAB / DOCUMENTATION

Connect simulation evidence

Vehicle Lab displays evidence from external engines. It does not replace a physics engine or claim that a visually plausible animation is a solved mechanical system.

Engine-neutral replay

tools/replay.py exports version 1 rigid-body replays. You supply sampled positions and quaternions from your own run. The contract uses metres, seconds and quaternion order x, y, z, w. Every frame contains every named body, with strictly increasing time. Non-finite values and non-normalized quaternions are rejected.

from pathlib import Path
from replay import write_replay

write_replay(
    Path("my-run.json"),
    engine="My engine and exact version",
    scope="Describe the model, assumptions and test boundary.",
    bodies=[{"id": "part", "shape": "box",
             "dimensions": [0.2, 0.1, 0.05]}],
    frames=sampled_frames,
)

Add tools/ to your Python import path or put the exporter beside the adapter. Each sampled frame has t, a poses map of body IDs to seven numbers, and optional numeric metrics. This API accepts data; it does not create a simulation or invent sampled frames.

Attach a replay to your project

python3 tools/project.py add-replay   projects/my-rover/project.json my-run.json   --id terrain-run --status failed
python3 tools/project.py validate projects/my-rover/project.json

A new stage appears in your project's studio. The player applies saved poses without interpolation and displays up to three recorded metrics. Supported shapes are boxes and cylinders; deformable meshes, arbitrary terrain/contact replay and live solver control are outside the generic adapter in v0.1.

Test the adapter without an engine

python3 tools/project.py add-replay   projects/my-rover/project.json examples/pendulum-replay.json   --id adapter-check --status unverified

The included pendulum file is prescribed analytical motion for interface testing. It is explicitly not a dynamics solution, a Chrono result or a physical experiment.

Using Project Chrono

Run and verify the mechanical model in your chosen Chrono environment, then export its body states into the replay contract. Keep exact engine version, model revision, timestep, assumptions, convergence work and run failures in your evidence record. See Chrono documentation and its Python overview for engine installation and simulation APIs. This release does not bundle or install Chrono.

Recorded motion and framing

Playback starts at the first recorded timestamp and preserves the original time labels. The viewer fits every body across the complete saved motion, including bounds that contain rotations. It keeps a translating body in view when the viewport changes shape. Positions and quaternions remain in the original metre coordinate system; framing changes only the camera and display ground.

Recorded time

Recordings may begin at a nonzero time. Playback elapsed time starts at zero; duration is the final timestamp minus the first. Telemetry preserves the original recorded timestamps. The browser validates every pose, quaternion, frame order and body identity before creating the replay.

The vehicle replay

The worked example preserves a historical CQ-PH1.1 obstacle run: 18 dynamic bodies, 26 constraints and a 0.5 ms integration timestep. The rear axle did not clear the obstacle. Its simplified contact geometry is separate from the detailed Ridge CAD. Old per-check PASS values predate corrected producer gates and are not current vehicle acceptance. The full original sampled poses, issues and missing-model list are retained in the public replay data.