Trajectory Log¶
Every run writes {stem}.trajectory.jsonl next to its _result.json: the
vehicles, pedestrians and traffic lights of the world, once per world.tick(),
and what the run made of them -- the map it ran on, the ego's plan, its
conditions tick by tick and its verdict -- one JSON object per line.
TrajectoryRecorder (autoware_carla_scenario/trajectory_recorder.py) writes
it, and the carla-hub run report replays it. The file holds everything needed
to show the run again without CARLA, the ego's plan and the path it drove
included: the autoware_carla_scenario_rerun package (the rerun extra;
rerun.enabled=true runs it on each log as its run ends) makes a Rerun
recording of it, which is how a run is seen (Seeing a run).
scenario-t4scene writes it as a T4Scene, the scene exchange format of
tier4/e2e-devkit (T4 Scene), and scenario-wosac as a rollout
of the Waymo Open Sim Agents Challenge (WOSAC Rollouts).
Its format is published as a JSON Schema of one line, the contract for readers
in any language: schemas/trajectory.schema.json in the package and in the
wheel (JSON Schema 2020-12, tuples as prefixItems). From Python, find it with
importlib.resources.files("autoware_carla_scenario") / "schemas" /
"trajectory.schema.json", which needs no CARLA client. Code that already
imports the recorder can use trajectory_recorder.SCHEMA_PATH.
trajectory_recorder.schema.json, next to the recorder, is the same schema in
draft-07 (trajectory_recorder.DRAFT7_SCHEMA_PATH), for the generators that
cannot read 2020-12 tuples.
Versions¶
The format has a version, schema_version in the world line: 2. Version
2 added the records map, warmup, actor_gone, markers, condition,
action and result, and schema_version itself; a file of version 1 has no
schema_version and none of those records, and still follows the schema.
The records marked (2) in the table below that are not in that list
(rear_axle, turn_indicators, plan, adversity, waypoint_arrival, collision, walker_fallen, metric,
spawn, despawn, run) came later within version 2: a reader of version 2 that does not
know one skips it. So did the tick's optional angular_velocity field and
the collision's optional start_frame field: a file written before one has
none.
Every change keeps the records there are: a new version adds records (and
optional fields), so a reader that skips the types and ignores the fields
it does not know reads any later file.
Records¶
Each line is one record, told apart by type; the table below lists every
type the schema has. A file starts with one world line and one map line,
then one traffic_light line per light, one run line and one warmup line. After that come the ticks: each tick line is preceded by an
actor line for every vehicle or walker appearing in it for the first time
(an ego's followed by a rear_axle line) and
an actor_gone line for every one that has gone since the last, and followed
by a turn_indicators line when a vehicle's turn indicators changed on it, a markers line when the ego's plan changed on it (and a plan line after
it, the plan timed), then an action line for each action that moved on (each
followed by the adversity, waypoint_arrival, spawn and despawn lines its
tick brought), the collision, walker_fallen and fallen walkers' despawn
lines, and last a condition line for each condition that changed. A run judged on a MetricCondition then has, after its last tick, a metric line for each frame its metrics were computed for, in frame order, and then, for each metric condition in turn, its condition lines, whether its metric was NG, from its first frame again: after the ticks, frame goes back each time a new block starts, so a reader wanting one timeline sorts these lines by frame (Metrics). The collision lines ending the contacts still going when the run ended (at its last tick's frame) come after all of these. A run that reached a verdict ends with result: its final one, the one _result.json holds, after the MetricConditions are judged. A run that raises before that -- in its tick loop, or after it (a CommonRoad worker that died while the metrics were computed, a Ctrl-C) -- writes no _result.json and ends without a result line (#2067).
{"type":"world","schema_version":2,"map":"Carla/Maps/Town10HD_Opt","episode":7}
{"type":"map","name":"Town10HD_Opt","source":"git+https://huggingface.co/datasets/AutowareFoundation/carla-ue5-maps@c834d5c#autoware_maps/Town10HD_Opt","lanelet2":{"path":"/.../lanelet2_map.osm","sha256":"5d88...","bytes":1234567},"opendrive":{"path":"/.../Town10HD_Opt.xodr","sha256":"9a1f...","bytes":2345678},"projector_info":{"projector_type":"MGRS","vertical_datum":"WGS84","mgrs_grid":"54SUE"},"projector_type":null,"mgrs_offset":[81655.0,50137.5],"z_offset":0.0}
{"type":"traffic_light","id":9,"opendrive_id":"42","location":[10.0,20.0,0.0],"boxes":[[10.0,20.0,5.0,0.2,0.3,0.6,180.0]],"stops":[[5.0,18.0,0.0,-90.0]]}
{"type":"run","seed":0,"scenario_hash":"3f1c...e9"}
{"type":"warmup","ticks":66,"start_frame":34,"end_frame":100}
{"type":"actor","id":1,"type_id":"vehicle.lincoln.mkz","role":"ego","extent":[2.45,1.07,0.77],"center":[0.0,0.0,0.7]}
{"type":"rear_axle","id":1,"offset":-1.4}
{"type":"tick","frame":100,"t":0.0,"actors":[[1,0.0,1.0,0.0,0.0,0.0,90.0,0.0,0.0,0.0]],"control":{"1":[0.5,0.0,0.0,1]},"lights":{"9":"Red"}}
{"type":"markers","frame":100,"t":0.0,"actor":1,"polylines":[{"points":[[0.0,1.0,0.3],[5.0,1.0,0.3]],"color":[0,255,0],"thickness":0.1,"point_size":0.1}]}
{"type":"plan","frame":100,"t":0.0,"actor":1,"step":1,"planned_at_us":3050000,"policy":"resworld","inference_seconds":0.031,"turn_indicator":1,"debug_scalars":{},"points":[[0.1,0.0,1.0,0.0,90.0],[0.2,5.0,1.0,0.0,90.0]]}
{"type":"action","frame":101,"t":0.05,"phase":"post_tick","index":0,"label":"cut_in","action_type":"LaneChangeAction","state":"startTransition"}
{"type":"condition","frame":101,"t":0.05,"role":"pass","index":0,"label":"arrived","satisfied":false}
{"type":"actor_gone","id":3,"frame":180,"t":4.0}
{"type":"result","passed":true,"message":"Ego reached the goal","elapsed_seconds":12.3,"conditions":[{"label":"pass[0](arrived)","role":"pass","condition_type":"EntityPositionDistanceCondition","satisfied":true,"message":"..."}]}
| Record | Written | Fields |
|---|---|---|
world |
once, first | schema_version (the format's version, 2; absent in version 1), map (CARLA map name), episode (world.id) |
traffic_light |
once per light, when recording starts | id, opendrive_id, location [x,y,z], boxes [[x,y,z,ex,ey,ez,yaw]] (one per light head), stops [[x,y,z,yaw]] (stop-line waypoints) |
actor |
before the first tick a vehicle/walker appears in | id, type_id (blueprint), role (role_name), extent (bounding box half size), center (box centre offset from the actor origin, actor frame) |
tick |
after each world.tick() |
frame (CARLA frame), t (scenario seconds), actors [[id,x,y,z,roll,pitch,yaw,vx,vy,vz]], control {id: [throttle,steer,brake,gear]} (egos only), angular_velocity {id: [wx,wy,wz]} (egos only, deg/s in CARLA's world axes; (2), absent before it was recorded), lights {id: state} (changes only) |
map (2) |
once, after world |
name (short map name), source (map.directory, else carla-pack:OWNER/REPO/PACK@VERSION for a map read from a content pack (map.pack, named with the version it resolved to), else map.source, else null: the one the map was read from, in the order the run resolves them, a directory before a pack before a source), lanelet2 / opendrive ({path, sha256, bytes} of the file read, or null), projector_info (map_projector_info.yaml as read, or null), projector_type (the config's override, or null), mgrs_offset [ox,oy] and z_offset (the loaded Lanelet2 map's, or null) |
run (2) |
once, after the traffic lights | seed (the run's seed, BaseScenario.random_seed), scenario_hash (the SHA-256 of the concrete scenario the run's config describes, its seed aside: autoware_carla_scenario.scenario_hash, which WOSAC Rollouts tells a scenario's rollouts by; null for a scenario not built by the scenario command) |
warmup (2) |
once, before the first tick | ticks (frames of the CARLA recording before the scenario clock started: the warm-up), start_frame (the frame the recorder started at, null without a recording), end_frame (the frame of the first tick, t = 0) |
rear_axle (2) |
right after an ego's actor line |
id, offset (where its rear axle -- Autoware's base_link, the driver policy's rig origin -- is from the actor origin along its x axis, metres, negative behind: where the ego put its base_link for the run -- a driver policy's entity's rig origin (driver.rear_axle_offset_m), a ROS 2 ego's odometry (rear_axle_offset_m), an Autoware ego's base_link (AutowareBridgeConfig.base_link_offset_m) -- else, beside a T4 dataset, its driver.rear_axle_offset_m, else from its wheels, else half its box's half-length behind (-0.5 * extent.x, a quarter of its length); the T4 dataset's rule, t4.ego_rear_axle()) |
actor_gone (2) |
before the first tick a vehicle/walker is missing from | id, and the frame and t of that tick |
turn_indicators (2) |
after a tick on which a recorded vehicle's turn indicators changed (every vehicle's on the first tick it is in) | frame, t, states {id: state}, each off, left, right or hazard (only the vehicles whose indicators changed; the blinker bits of their CARLA light state, both being hazard); a vehicle's hold until the next line that names it |
markers (2) |
after a tick on which the ego's debug markers changed | frame, t, actor (the ego, or null), polylines [{points [[x,y,z]], color [r,g,b], thickness, point_size}]; they hold until the next markers line, and none ([]) clears them |
plan (2) |
right after the markers line of a driver's plan (a driver policy's, CarlaDriverEntity, or an Autoware ego's trajectory command, Ros2EgoEntity; ego_plan.PlanMarkers), once per plan, even an empty one |
frame, t, actor (the ego, or null), step (the plan's number in the driver's session, from 1), planned_at_us (when it was made, on the driver's clock -- a policy's microseconds since its session began, an Autoware command's stamp -- not t), policy, inference_seconds (0 when not said, null for NaN or infinity), turn_indicator (0 no command, 1 off, 2 left, 3 right), debug_scalars {name: value} (null for NaN or infinity), points [[dt,x,y,z,yaw]] (the rig's planned poses, dt seconds after the plan was made; world frame, not lifted as the markers are; a pose that is not finite left out) |
condition (2) |
when a condition is first checked, and when it changes | frame, t, role (pass/fail), index (in its list), label, satisfied |
action (2) |
on the first tick of the loop, and when the action's state changes | frame, t, phase (pre_tick/post_tick), index (in its list), label, action_type (its class), state (standbyState, startTransition, runningState, endTransition, completeState: OpenSCENARIO's, ActionState) |
adversity (2) |
on the tick NADE samples an adversity (AdversarialTrafficAction) |
frame, t, label (the action's), agent, kind (AdversityKind), location (AdversityLocation), probability (p, cut for an unavoidable one), is_probability (q), weight (the run's, once sampled), avoidable, victims, response (avoid, accept or empty) |
waypoint_arrival (2) |
when a routed entity has reached a waypoint with a time or a departure condition (RoutingAction, any mode), and its target is known |
frame, t, label (the action's), entity, vertex (0-based), kind (time, or condition: the target is when it first held), mode (driver, follow, position), target_t, actual_t, error_s (actual_t - target_t) |
collision (2) |
when a vehicle other than the ego begins a contact with a vehicle or a walker, and when it ends (no event from the pair for a second, or the run ended with it still going) (npc_collisions) |
frame, t (one tick's: at the start, the tick that took the contact up; at the end, the tick that saw it end), actors [role, role] (type ids where an actor has no role), ids [id, id], impulse (N*s; at the end, the strongest), ego (one side is the ego), phase (start/end), duration (s, at the end; null at the start), start_frame (optional: the frame of the contact's first event, as the sensor heard it) |
walker_fallen (2) |
once per walker seen fallen over (tipped beyond 50 deg, or dropped more than a quarter of its height, and at least 0.2 m, below the lowest it stood over its last four looks -- a quarter second apart, so about the last second -- while barely moving sideways) | frame, t, id, role, drop (m, below that lowest), tilt (deg) |
spawn (2) |
on the tick a SpawnAction brought an entity into the scene (one spawned hidden, as a rule; not for a prop) |
frame, t, label (the action's), entity (role), id (its actor's, or null) |
despawn (2) |
on the tick a DespawnAction removed an entity, or the run a walker that lay fallen 5 s |
frame, t, label (the action's), entity (role; a fallen walker with none, its blueprint id), id (its actor's, or null), reason (action/fallen) |
metric (2) |
after the last tick, a run judged on a MetricCondition, for each frame its metrics were computed for (every tick; CriMe's and CommonRoad-Reach's every 0.1 s) |
frame, t, values {key: value} (the metrics computed for that tick: a number in the metric's unit, a boolean for a yes/no metric, or a string for one that names its state; null where one read nothing or no finite number) |
result (2) |
last, when the run reached a verdict | passed, message, elapsed_seconds, conditions [{label, role, condition_type, satisfied, message}] (_result.json's, without the details) |
Fixed-length arrays are tuples: the schema gives each position its meaning, and generated types keep them as tuples where the target language has them.
Frames, units and time¶
- Positions and rotations are in CARLA's left-handed world frame (x east,
y south, z up; see Coordinate frames). Positions are in metres, angles in degrees, and velocities
are world-frame m/s (an angular velocity, world-frame deg/s, a pseudovector:
into a right-handed frame its
xandzflip, not itsy). Every float is rounded to 3 decimals, but for the values of ametricrecord and theprobability,is_probabilityandweightof anadversityrecord, written as they were computed (an importance-sampling weight, or the probability of a rare adversity, is far smaller than a thousandth); theirtis rounded as every other. - A walker's velocity is measured from where it stood the tick before: one walking on CARLA's walker controller reports 0. Every other actor's is the one CARLA reports.
tis simulated time since the scenario clock started, the time pass/fail conditions see. It is not wall time. Warm-up ticks are not recorded: thewarmupline says how many there were, so a frame of the CARLA recording, which starts with them, isframe - warmup.start_frame.- Ticks are 20 Hz (
FIXED_DELTA_SECONDS). - A
planline has two clocks:t, the tick it is written on, andplanned_at_us, the driver's own (a policy's from its session's start, an Autoware ego's command stamps), which its points'dtcount from. A plan is written on the tick it is made on, except one made before the first recorded tick (while the run waits for the ego to be ready), written on that tick: compare plans byplanned_at_us, not byt.
To move a pose into the Lanelet2 / Autoware map frame from Python, build a
CarlaWorldPose and call coordinate.transform.to_map_frame (see
Coordinate transforms).
In other languages, apply the same conversion with the map's MGRS offset
(ox, oy) and elevation offset z_offset (MapManager.mgrs_offset and
MapManager.z_offset):
x_map = x + ox
y_map = -y + oy
z_map = z + z_offset
yaw_map = -radians(yaw) (pitch negated likewise; roll unchanged)
vy_map = -vy
A file of version 2 carries these offsets in its map line (mgrs_offset,
z_offset), with the Lanelet2 and OpenDRIVE files the run read and their
SHA-256, so a reader can load the very map the run was on.
What a reader has to handle¶
- Light states are deltas.
lightsholds only the lights that changed since the last written tick (all of them in the first tick), and is absent when none changed. Carry each light's state forward. Aturn_indicatorsline is a delta the same way, per vehicle. - Ticks can be missing. A tick without any vehicle or walker is not
written, so
frameandtcan skip. - Entities brought in late are marked. An entity spawned hidden is in
actorsfrom the start, parked out of sight under the map; aspawnline says when aSpawnActionput it on its place, as adespawnline says when one was taken out. - Actors that go are marked. A vehicle or walker that is destroyed or
despawned stops appearing in
actors, and from version 2 anactor_goneline says so before the first tick it is missing from. - Markers, conditions and actions are deltas too. A
markersline holds until the next one, and aplanline until the nextplanline (markers that carry no plan clear the drawing, not the plan); aconditionline until the next of the sameroleandindex; anactionline until the next of the samephaseandindex(startTransitionandendTransitionhold for one tick; an action with nountilthat does not reissue its command goes fromstartTransitionstraight tocompleteState, orstandbyStatewhen it repeats, with norunningStateorendTransitionline; a repeating one whose trigger still holds fires again on that same tick and staysstartTransition, so no newactionline is written until it stops firing. An action stopped by one built withoverrides=Truegoes straight tocompleteState, repeating or not, with noendTransitionline). The run stops checking conditions at the first that decides it, so the last tick may have no line for the ones after it. - Episode ids are 64-bit.
episodeis a random uint64, so it is often past 2^53: read it as an unsigned 64-bit integer (it only tells episodes apart). - Map keys are strings.
controlandlightsare keyed by actor id as a decimal string ("1"), a JSON object key. - Integers are plain JSON numbers. Nothing is quoted: unlike the
protobuf JSON mapping, which writes 64-bit integers as strings, the file and
its schema keep them numbers. The schema caps
frame(uint64 in LibCarla) at 2^53 - 1 and actor ids (uint32) at 2^32 - 1;episode, a random uint64, is capped at 2^64 - 1 (see above). Any reader, including JavaScript's double-onlyJSON.parse, holds them exactly; a value past the cap fails validation rather than silently losing precision. - The last line can be cut off. Each line is written whole, but a run
killed mid-write (SIGKILL, an out-of-memory kill, a job's time limit, a
full disk) loses at most the tick being written: the last line of the file
that holds anything may be part of a record, with no trailing newline.
Leave that one line out and keep every record before it. A line that is
not JSON with any line after it is a corrupt file, not a killed run.
scenario-t4scene(and the T4Scene written as each run ends) warns about a cut-off last line and converts the rest, and refuses a line that is not JSON anywhere else, or a record it cannot use anywhere, naming the file and line; the results UI's metrics skip any line they cannot read. The Rerun converter (rerun.enabled,python -m autoware_carla_scenario.rerun) refuses a cut-off last line: that log's conversion fails. - Only egos have controls.
controlcarries actors whoseroleisegoorhero(any case).steeris normalised to [-1, 1]; it is not a wheel angle.
Reading it from another language¶
Generate types from the schema with the generator for your language:
| Language | Generator | Notes |
|---|---|---|
| TypeScript | json-schema-to-typescript | A discriminated union on type, with tuple types |
| Python | datamodel-code-generator | Pydantic models; tuples become length-checked lists |
| Rust | typify | Reads 2020-12; an enum on type (the schema's discriminator), tuples as tuples |
| C++, Go, Rust, C#, ... | quicktype | Reads the draft-07 copy; merges the records into one type with optional fields; tuples become arrays |
npx json-schema-to-typescript -i schemas/trajectory.schema.json -o trajectory.d.ts
uvx --from datamodel-code-generator datamodel-codegen \
--input schemas/trajectory.schema.json --input-file-type jsonschema \
--output-model-type pydantic_v2.BaseModel --output trajectory_log.py
Any JSON Schema 2020-12 validator checks a file line by line, for example
jsonschema in Python:
import json
import jsonschema
from importlib.resources import files
schema = files("autoware_carla_scenario") / "schemas" / "trajectory.schema.json"
validator = jsonschema.Draft202012Validator(json.loads(schema.read_text()))
with open("CutInScenario.trajectory.jsonl") as f:
for line in f:
validator.validate(json.loads(line))
The top level is a oneOf of the records, each fixing type with a const,
and names the field in an OpenAPI-style discriminator (propertyName: type,
with the mapping from each type to its record), which validators ignore and
generators that know it use for a tagged union. x-schema-version is the
format version the schema describes. The draft-07 copy says the same with
definitions and items arrays.
Changing the format¶
A change to a record in trajectory_recorder.py needs the same change in
schemas/trajectory.schema.json, and the draft-07 copy written again from it:
The recorder's tests check every line they record against both schemas, which
forbid fields they do not list (additionalProperties: false), and that the
copy is the one the script writes, so they fail until both have the change. A
change that a reader of the last version could not skip over is a new
schema_version (SCHEMA_VERSION, and x-schema-version in the schema).