transfer
Move a scenario or recording onto another map: recorded tracks warped through lane frames, behaviour re-bound by the matcher; simulated and gated, with a transfer report. Locally it needs the map’s odr derivative, whichsimforge maps pull does not install yet: run it with —cloud
simforge transfer [OPTIONS] --map <DIR|NAME@VERSION> --out <DIR> <SOURCE>
| Argument / flag | Notes | What |
|---|---|---|
<source> | required | The source: a recording (simforge.recording/v1 or log-scene/v1, optionally gzipped), a v2 scenario, or a package directory holding one |
--map DIR|NAME@VERSION | required | The target map: a map directory, or name[@version] under the maps cache (semantic profile) |
--source-map DIR|NAME@VERSION|FILE.xodr | The source’s map (default: the map the source names): a map directory, name[@version], or a bare OpenDRIVE file for a recording | |
--recording FILE | repeatable | A recording the scenario’s replay routes pin (repeatable) |
--from-root | Transfer from the source’s root: follow its recording’s derivedFrom (a transfer’s warped recording, a scenario’s rollout of the one recording it replays) through the --recording files to the recording it started from, and transfer that onto the map. The source’s own scenario content (its edits) is not carried; the report records the chain in source.root | |
--sites SITES | one of network, corridor, same; default network | Where recorded motion looks for sites |
--profile PROFILE | one of pure, generalized, key-only; default pure | Which recorded actors transfer |
--crossing CROSSING | one of any, faithful; default any | How a crosswalk crossing must land |
--max-try N | Sites tried (transferred, gated and simulated) before giving up [default: 6 per —max-sites] | |
--max-sites N | default 1 | Distinct accepted sites to transfer onto (recorded motion), ranked; more than one writes each to site-<rank>/ under —out |
--site-cell-m M | With —max-sites: one site per cell of this size (metres) and heading quadrant [default: 200]. Smaller admits near-copies of the same drive | |
--min-path-separation-m M | With —max-sites: no two placements whose egos’ target paths come within this distance (metres) [default: 10] | |
--out DIR | required | The output directory (created; must be empty if it exists) |
--cache-root DIR | Map cache root to search for NAME@VERSION. Default: SIMFORGE_MAPS_CACHE_ROOT, then $XDG_DATA_HOME/simforge/maps | |
--allow-no-colliders | Simulate without map colliders when the map publishes none (recorded; the default refuses) | |
--budget-s SECONDS | default 32400 | Last-resort wall-clock limit, seconds: a transfer still running then fails whole (transfer_budget_exceeded, nothing written). Set far above any healthy transfer (about 10x the slowest seen); what a transfer tries is bounded by —max-try and the import’s rounds, never by time, so its result does not depend on the machine |
--mode MODE | one of motion, semantic; default motion | How the scenario moves to the target map |
--experimental | Allow an experimental —mode | |
--target-control CLASS,...|as-source | default as-source | Semantic mode: the target approach classes accepted, comma separated (two_way_stop_minor, two_way_stop_major, all_way_stop, signal, yield_minor, yield_major, stop_line_only, uncontrolled, mixed), or as-source. A class other than the source’s is recorded as a requested substitution |
--t-junction | Semantic mode: also fit a four-arm source onto a T-junction whose stem is the ego’s approach; the roles on the source’s opposite arm are left out (recorded), and each such placement is tagged t_junction | |
--policy FILE | A transfer policy JSON file to transfer with, instead of a registered version | |
--policy-version VERSION | A registered transfer policy version (sdk/contracts/transfer-policies.json, e.g. transfer-v2). Default: the registry’s active version | |
--revision REVISION_ID | The immutable revision of a hosted scenario SOURCE | |
--name NAME | The new scenario’s name. Default: <source title> · <target map> | |
--max-cost CENTS | Explicit maximum cloud cost in cents | |
--wait | one of true, false | Wait for the transfer to finish |
--download | one of true, false | Download a finished transfer’s new scenario, report and receipt into —out; implies —wait |
--stage | one of true, false | Save a SOURCE file to the workspace as an immutable revision (free) and price the transfer on it; starts nothing. —dry-run saves nothing |