// Command reference
simforge render
Generated from the CLI's own help (CLI 0.2.0-rc.9). Global flags and exit codes are on the reference index.
simforge render
Render the same scenario file locally or with --cloud
simforge render [OPTIONS] <TARGET> [EXTRA]...
| Argument / flag | Notes | What |
|---|---|---|
| <target> | required | Scenario JSON file or materialized workspace; identical input for local and cloud |
| <extra> | repeatable | Runtime-specific options; forwarded without shell interpolation |
| --out OUT | Output folder; local requires it, cloud waits and downloads when it is given | |
| --mode MODE | one of 2d, schematic, 3d; default 2d | 2d (top-down map video on the CPU), schematic (the flat OpenDRIVE view, GPU) or 3d (photoreal camera sensors, GPU) |
| --rig RIG | Sensor rig JSON (simforge rig init). Default: the basic-dash-camera rig on the ego | |
| --preset PRESET | one of training, showcase, schematic | Render preset |
| --camera-detector FILE | Local native render only: authored instantaneous HDR detector response JSON | |
| --camera-temporal FILE | Local native render only: bounded exact-time HDR exposure request JSON | |
| --camera-delivery FILE | Local bounded offline measurement delivery or controlled delivery-only resume | |
| --fps FPS | Frame rate every camera records (2d: the video's), over the render preset's own rate; 3d takes 5 to 60 | |
| --wait | Wait for a submitted cloud job to finish | |
| --download | Download a succeeded cloud job into --out; implies --wait | |
| --max-cost CENTS | Explicit maximum cloud cost in cents; required for billable cloud jobs | |
| --revision REVISION | Immutable revision for an existing hosted scenario target | |
| --stage | With --cloud: save a scenario file to the workspace as an immutable revision (free) and price the run on it; starts nothing. --dry-run saves nothing | |
| --replay-of RUN_ID | Cloud 3d render: the drive a succeeded closed_loop run scored (its episode timeline), rendered on the target's revision that run drove | |
| --ego-dynamics MODEL | Ego dynamics model for this run: dynamic-v1 (the engine's own model, today's behaviour), kinematic-bicycle (Helios episodes only) or full-car-v1 (reserved, refused until admitted). Outranks the scenario's physics.egoDynamics. Omitted: the run-mode default, which the result records | |
| --ego-vehicle ACTOR=CATALOG_ID | repeatable | The vehicle for an ego actor, ACTOR=CATALOG_ID, repeatable. A vehicle pack needs pack profiles, which are not enabled yet: refused ego_vehicle_unsupported, never run on the class profile |
| --camera CAMERA | one of follow-ego, overview; default follow-ego | 2d engine: the camera |
| --north-up | 2d engine, follow-ego: keep north up (looking ahead of the ego) instead of turning the view with it | |
| --debug-signals | 2d engine: also draw signal heads the timeline has no phases for (hollow grey rings) | |
| --no-hud | 2d engine: no HUD (header, legend, clock, speed); the map fills the whole frame | |
| --actor-labels LABELS.JSON | 2d engine: tags to draw next to actors, a JSON object {actorId: text} (e.g. a labelling page's candidate numbers). An id that is not an actor of the timeline fails the render | |
| --legibility LEGIBILITY | one of standard, high; default standard | 2d engine: icon legibility; high is for labelling clips (larger props, light people, faint untagged parked vehicles, no edge chevrons or collision marks, non-overlapping tag badges) |
| --px-per-m PX | 2d engine: a fixed map scale in pixels per metre. Default: 14 to 9 by the ego's speed (follow-ego); the scenario actors fitted, 5 to 12 (overview) | |
| --size WxH | default 1280x720 | 2d engine: the frame size |
| --ego ACTOR_ID | 2d engine: the ego actor. Default: the workspace's metric subject | |
| --timeline TIMELINE.JSON | Render a timeline instead of simulating the workspace, on the same map | |
| --clip START:END | 2d engine: the clip, START:END seconds of the timeline. Default: the whole timeline | |
| --buildings | 2d engine: draw building footprints when the map has them | |
| --title TEXT | 2d engine: the header's title. Default: the map's name (its id in words) and the scenario's title from the package (else the workspace directory); render.json keeps the ids | |
| --lidar-model LIDAR_MODEL | one of legacy, physical; default legacy | Native LiDAR model. legacy is the byte-identical default |
| --lidar-profile NAME|FILE | Physical profile name (built-in) or a JSON profile file | |
| --lidar-seed LIDAR_SEED | default 0 | Physical-model deterministic noise seed |
| --lidar-motion-compensated | Express physical returns in the sensor pose at sweep start | |
| --visual-dynamics | Derive each logged four-wheeler's body pitch and roll from its recorded track (log replays only; any other input is refused ego_visual_dynamics_input_invalid). The timeline key changes; without the flag the timeline is unchanged | |
| --vd-rate-hz HZ | With --visual-dynamics: the rate the log's poses were recorded at, Hz. Default: 50. A rate the poses contradict (a resampled lower-rate log declared higher) is refused, and so is a pose-only log below 10 Hz | |
| --passes PASSES | one of rgb, hdr, id, depth, semantic; default rgb; repeatable | Camera passes, comma-separated. The shared render output contract defaults to RGB only |
| --camera-capture-stage CAMERA_CAPTURE_STAGE | one of scene-pre-postprocess/v1 | Capture renderer-relative HDR before postprocess, with capture-owned provenance |
| --set KEY=VALUE | repeatable | Render-config overrides on the preset (key=value, e.g. aa.mode=fxaa); repeatable |
| --textures TEXTURES | one of uastc-full, bc7-512 | The staged texture tier (photoreal presets). Default: uastc-full |
| --video VIDEO | one of auto, required, off; default auto | Encode videos with ffmpeg |
| --simulate-only | Simulate only (native): the same timeline, scene state, rig schedule and job as a render, each tick applied and observed in a device-free world (observed-frames.jsonl, the parity gate, results.json), with no frame drawn, no video and no GPU | |
| --first-frame | Render the first frame only (native): tick 0 of the same job, every camera as its RGB PNG (no video). Every camera must capture tick 0 | |
| --attitude ATTITUDE | one of on, off; default on | Native: on (default) lowers each four-wheeler's body pitch and roll and the road attitude into the frames (cameras and sensors on a body mount tilt with it); off lowers yaw-only rotations, the rigid twin of the same render. Recorded as lowering.attitude |
| --vram-budget BYTES | A texture budget in bytes; without it the device capacity is unmeasured and admission is skipped (reported) | |
| --allow-software-adapter | Render on a software (CPU) Vulkan adapter such as lavapipe, explicitly. Slow; pixels differ from a GPU's | |
| --progress | Write render.progress events to stderr (the step, and frames done of the total while drawing) | |
| --map-dir DIR | Use this native map directory (.corpus/<map>) instead of the installed map found by content | |
| --cache-root DIR | Map cache root to search. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps | |
| --assets-root DIR | Actor-asset root. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets | |
| --actor-closure SHA256 | The actor closure to bind, instead of the workspace's catalog.actorClosureDigest | |
| --actor-layer SHA256 | The workspace's private model layer (an actor closure in the same store) for workspace.* models, instead of the workspace's simforge.actorLayer extension | |
| --allow-map-drift | Render on the installed map release even where its members differ from the workspace's map closure (recorded in the result; the default refuses) |