// Command reference
simforge import
Generated from the CLI's own help (CLI 0.2.0-rc.9). Global flags and exit codes are on the reference index.
simforge import log
A recording (simforge.recording/v1 or log-scene/v1) as a scenario package: scenario, recording, trace, import report
simforge import log [OPTIONS] --map <DIR|NAME@VERSION> --out <DIR> <RECORDING>
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <recording> | required | The recording (JSON, optionally gzipped). With --cloud: The log: a recording (JSON, optionally gzipped) or a ROS 2 MCAP lidar log |
| --map DIR|NAME@VERSION | required | The installed map: a map directory, or name[@version] under the maps cache (semantic profile) |
| --out DIR | required | The package directory to write (created; must be empty if it exists) |
| --report REPORT.JSON | The register step's import report (simforge.import-report/v1 fields: methods, registration, laneMatch, droppedActors), merged into the package's | |
| --cache-root DIR | Map cache root to search for NAME@VERSION. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps | |
| --assets-root DIR | Actor-asset root whose closure restricts catalog binding to renderable models. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets | |
| --actor-closure SHA256 | The actor closure the package pins (default: this CLI's pinned public closure) | |
| --allow-no-colliders | Simulate without map colliders when the map publishes none (recorded; the default refuses) | |
| --feasibility-report FILE | Also write the opt-in ego feasibility report (simforge.ego-feasibility/v1) to this file: the logged ego track against its class's dynamic-v1 envelope. Never changes the trace or the workspace | |
| --tracked-replay FILE | Opt in to a tracked replay of the ego: instead of placing it on the log, drive its dynamic-v1 plant along the logged path (the engine's timed-path tracker) and write the tracking report (simforge.ego-tracking/v1) to this file. Changes the trace; other actors still replay exactly. Recorded in the package notes | |
| --name NAME | The scenario's name. Default: the file's name | |
| --max-cost CENTS | Explicit maximum cloud cost in cents | |
| --wait | one of true, false | Wait for the import to finish and print its scenario |
| --download | one of true, false | Download a finished import's scenario document, import report and Event Timeline into --out; implies --wait |
| --stage | one of true, false | Upload the log and price its import, starting nothing (the host prices an import from the uploaded log). --dry-run uploads nothing |
| --lidar-topic TOPIC | MCAP only: the lidar topic, when the log has several | |
| --gnss-topic TOPIC | MCAP only: the GNSS topic, when the log has several | |
| --ego-dims L,W,H | repeatable | MCAP only: the ego's box in metres, length,width,height (perceive's default otherwise) |
| --ego-rear-axle-to-centre METRES | MCAP only: how far the ego box's centre is ahead of base_link (the rear axle), metres |
simforge import openscenario
An OpenSCENARIO 1.x XML file as a scenario package; its map is found by the OpenDRIVE's sha256, and every element it cannot represent is refused by name
simforge import openscenario [OPTIONS] --out <DIR> <FILE.xosc>
Runs on: local runtime, or hosted with --cloud
| Argument / flag | Notes | What |
|---|---|---|
| <file.xosc> | required | The OpenSCENARIO 1.x XML file; its catalogs and OpenDRIVE are read beside it. With --cloud: The OpenSCENARIO 1.x file (its OpenDRIVE and catalogs are bundled from the paths it names), or a ready .zip bundle |
| --out DIR | required | The package directory to write (created; must be empty if it exists) |
| --map-version DIR|NAME@VERSION | The map version: a map directory, or name[@version] under the maps cache. It must hold the file's OpenDRIVE. Default: the installed map whose OpenDRIVE has the file's sha256 | |
| --ego ENTITY | The ego entity (default: one named ego or hero, else the first vehicle) | |
| --clip-seconds S | The clip, when the storyboard does not stop at a simulation time | |
| --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 whose closure restricts catalog binding to renderable models. Default: SIMFORGE_ACTOR_ASSETS_ROOT, then $XDG_DATA_HOME/simforge/actor-assets | |
| --actor-closure SHA256 | The actor closure the package pins (default: this CLI's pinned public closure) | |
| --allow-no-colliders | Simulate without map colliders when the map publishes none (recorded; the default refuses) | |
| --map NAME@VERSION|auto | default auto | The map: a map version id, a name, name@vN, or auto (the map whose OpenDRIVE the file names) |
| --name NAME | The scenario's name. Default: the file's name | |
| --xosc-path PATH | The .xosc inside a .zip bundle that holds several | |
| --max-cost CENTS | Explicit maximum cloud cost in cents | |
| --wait | one of true, false | Wait for the import to finish and print its scenario |
| --download | one of true, false | Download a finished import's scenario document, import report and Event Timeline into --out; implies --wait |
| --stage | one of true, false | Upload the bundle and price its import, starting nothing: the host resolves the map first, so this shows osc_map_unknown for free. --dry-run uploads nothing |