Skip to content

Routes, Trajectories and Recorded-Scene Replay

RoutingAction sends a vehicle or a pedestrian through waypoints to a goal. Each waypoint may carry when: an arrival time or a departure condition. Who moves the entity is its mode:

mode Who drives Between waypoints Timing
RoutingMode.DRIVER (default) The entity's own driver: the TrafficManager or SUMO for a vehicle, the pedestrian route walker, Autoware for an Autoware ego Lanelet2 routes (walkable lanelets for a pedestrian) Met by speed commands to the driver (below); an Autoware ego takes the route only
RoutingMode.FOLLOW The action's own controller (OpenSCENARIO's trajectory following, FOLLOW) Straight legs Kept by the controller on the trajectory's clock
RoutingMode.POSITION Nobody: the entity is placed every tick (POSITION) Straight legs Exact (a kinematic replay)

It is what lets a recorded drive be written down as a scenario: a recording is transcribed into one trajectory per road user, and each one is replayed around the ego (follow or position), or handed to the road user's own driver to keep its timing (driver).

Breaking change (19.0.0): FollowTrajectoryAction is gone

FollowTrajectoryAction and the editor's Follow Trajectory card (follow_trajectory) were removed; RoutingAction and the Set Goal card (routing) do everything they did. In Python write RoutingAction(entity, trajectory=..., time_reference=..., mode=RoutingMode.FOLLOW) (or POSITION) for FollowTrajectoryAction(entity, trajectory, time_reference, TrajectoryFollowingMode.FOLLOW). In a document change type: follow_trajectory to type: routing and following_mode to mode (follow / position as before, or driver), and state time_domain (the card's default is now none). A document that still has a follow_trajectory card is refused with a message saying so; there is no automatic conversion.

Reading a dataset is left to tools outside the framework (see Replaying a recorded scene), so the framework carries no dataset format.

The action

A goal and Lanelet2 waypoints are what an ego is given (RoutingAction("ego", Lanelet2Pose(42, 10.0), waypoints=[Lanelet2Pose(17, 0.0)])); a trajectory writes the waypoints out, the last one the goal:

from autoware_carla_scenario import (
    Lanelet2Pose,
    MapPose,
    ReferenceContext,
    RoutingAction,
    RoutingMode,
    Trajectory,
    TrajectoryTimeCondition as At,
    TrajectoryTiming,
    TrajectoryVertex,
)

path = Trajectory(
    "npc1_path",
    [
        TrajectoryVertex(Lanelet2Pose(lanelet_id=120, s=0.0), At(0.0)),
        TrajectoryVertex(Lanelet2Pose(lanelet_id=120, s=30.0), At(4.0)),
        TrajectoryVertex(MapPose(x=81234.5, y=50123.0), At(7.0)),
    ],
)
self.register_pre_tick(
    RoutingAction(
        "npc1",
        trajectory=path,
        time_reference=TrajectoryTiming(ReferenceContext.RELATIVE),
        mode=RoutingMode.POSITION,
        label="npc1_follows_path",
    )
)

A trajectory has the same four parts as OpenSCENARIO's trajectory following:

OpenSCENARIO Here Notes
Trajectory (name, closed, shape) Trajectory(name, vertices, closed=False) Only the Polyline shape. A recording is a sequence of samples; a clothoid or NURBS fitted to one would add an approximation between the data and the vehicle.
Vertex (time, Position) TrajectoryVertex(position, advance=None) A vertex's time is its departure condition, advance=TrajectoryTimeCondition(time) (read back as vertex.time); any other condition can take its place -- see Waypoint conditions. Either every vertex has a time or none has, a vertex with another condition counting as having one.
TimeReference time_reference=None or TrajectoryTiming(domain, scale, offset) None is <None/>: the vertex times are ignored and the entity keeps the speed it had when the action started. With a timing, a vertex at time τ is reached at τ * scale + offset seconds after the scenario (ABSOLUTE) or the action (RELATIVE) started.
TrajectoryFollowingMode mode=RoutingMode.POSITION or FOLLOW (or DRIVER) See below.
initialDistanceOffset initial_distance_offset Start that many metres along. With a timing, the clock starts at the time the trajectory reaches that point, when the first vertex is due (τ * scale + offset for its time τ): the entity waits at the point until then -- out of the world with hidden_outside_trajectory -- and the rest of the trajectory is brought forward by the time the part skipped takes, in either domain, gated or not.

A vertex's position may be written in any frame the framework addresses:

  • Lanelet2Pose, OpenDrivePose and CarlaWorldPose -- as everywhere else;
  • MapPose(x, y, yaw=None, z=None) -- an absolute pose in Autoware's map frame (the Lanelet2 file's projected frame), which is the frame a recording states its poses in. A missing yaw is taken from the direction of the path; a missing z puts the entity on the road surface under it;
  • RelativeLanePose(ds=0.0, offset=0.0, d_lane=0, yaw=None, entity_ref=None) -- a pose relative to an entity, in lane coordinates (OpenSCENARIO's RelativeLanePosition); see below.

Positions are converted to CARLA world coordinates when the action first runs, through the loaded map. Vertices of different kinds may be mixed in one trajectory.

A vertex with no yaw of its own is a corner: the entity turns there from the direction of the segment arriving to that of the segment leaving, across a window around the vertex that reaches 1 m along each segment, or half of that segment if it is shorter, and the vertex itself faces half way round: half the turn before it, half after. Everywhere else along a segment it faces that segment's own direction -- the direction it is moving -- with a yaw rate of 0. So a sparse path (a few hand-written points) is driven along each straight leg and turns only at the corners, and a dense one (a recording) turns smoothly all the way along, at its own rate. Given yaws interpolate from one to the next across the segment between them; where one end of a segment gives a yaw and the other does not, the heading turns from the given one to the segment's direction (or back) up to the other end's corner window.

A segment that does not move -- the same point written twice in a row, as a recording resampled onto a faster tick writes every sample, or a closed trajectory that repeats its first vertex at the end -- is looked past: the corner is between the nearest segments that move before and after it, with the same window. Along the path (by distance) the pause takes no room: every copy of the point faces half way round, and the turn is half before the point and half after. On a timed trajectory the entity pauses there, and on the clock the turn is spread over the window's time and the pause's together, so a duplicated recording turns at its own rate rather than in bursts. A copy with a yaw of its own beside one without is not looked past: by distance the heading still jumps at the zero-length segment between them, as before.

A pause of half a second or longer is a stop, not part of a corner, and neither are the first and last vertices of an open trajectory, nor a point with a yaw of its own: they face along the path, a vertex at a stop keeping the heading it arrived with, and over the stop the entity turns on the spot to the heading it leaves with.

Every number of a MapPose, a RelativeLanePose or a route pose must be finite: nan and inf are refused when the pose is built, a yaw or z given as None excepted. Whatever the frame, a vertex that resolves to a non-finite position, heading or time is refused when the trajectory is resolved, rather than making the whole path nan.

Lane-relative vertices

A RelativeLanePose writes the shape of a manoeuvre -- pull out, overtake, cut in ahead of the ego -- once, to be played from wherever it begins:

from autoware_carla_scenario import EGO_ROLE_NAME, RelativeLanePose

overtake = Trajectory(
    "overtake",
    [
        TrajectoryVertex(RelativeLanePose(), At(0.0)),  # where npc1 is
        TrajectoryVertex(RelativeLanePose(ds=20.0, d_lane=1), At(2.0)),
        TrajectoryVertex(RelativeLanePose(ds=60.0, d_lane=1), At(5.0)),
        # 10 m ahead of the ego, in its lane: a cut-in.
        TrajectoryVertex(RelativeLanePose(ds=10.0, entity_ref=EGO_ROLE_NAME), At(7.0)),
    ],
)
self.register_pre_tick(
    RoutingAction(
        "npc1",
        trajectory=overtake,
        time_reference=TrajectoryTiming(),
        mode=RoutingMode.FOLLOW,
        label="npc1_overtakes",
    )
)
Field OpenSCENARIO Meaning
entity_ref entityRef role_name of the reference entity, a str or an EntityRole (stored as its string). None (default) is the entity the action moves.
ds ds Metres along the reference entity's lane, from where it is; negative goes back.
d_lane dLane Lanes across: +1 one lane to the left, -1 one to the right, 0 the reference's own lane.
offset offset Metres from the target lane's centreline, positive to the left -- the sign of Lanelet2Pose.t. The reference entity's own lateral position does not carry over.
yaw Orientation (relative) Radians from the target lane's direction, positive to the left (anticlockwise) -- the sense of Lanelet2Pose.heading. None faces along the path, as for MapPose.

A RelativeLanePose is also a place a condition can name: PlaceClearCondition(RelativeLanePose(ds=20.0, entity_ref=EGO_ROLE_NAME), 5.0, 2.0, label=...) holds while the spot 20 m ahead of the ego is clear (a 5 m by 2 m rectangle facing along the lane it is on, as a yaw of None there means), and EntityPositionDistanceCondition measures to such a spot. There it needs an entity_ref (no action moves an entity), and it follows that entity: it is placed afresh on every tick, and while the entity is not in the scene (not spawned yet, gone, or spawned hidden and parked under the map) the place is nowhere and the condition does not hold. A route pose without an anchor, counted from the ego, follows the ego the same way. A SpawnAction placed against an entity places it once, against where that entity stands when the action fires, facing along the lane it is placed on where it states no yaw. An entity another SpawnAction brought in, or a position-mode trajectory put, on that same frame (the same tick phase, as two spawn cards fired together) is not where the world shows it until the next tick, so it is read where it was last put. An entity that is not in the scene then (parked under the map included, and not brought in on that frame) leaves the place unresolved, said in a warning: the road user is brought in where it was declared, and a prop is not added.

How a vertex is placed, on the Lanelet2 map and its routing graph:

  1. The reference's lane. The lanelet the reference entity is on, and the exact distance along its centreline. Where lanelets overlap (a junction), meet (a seam) or are stacked (an overpass and the road beneath it), the entity's elevation picks the level -- the lanelets whose surface where it stands is within 1 m of the nearest one -- then, of those, the one whose direction is nearest the entity's heading wins, then the one nearest its elevation, then the lowest id. to_lanelet2 chooses by the same rule.
  2. ds along the lane. Past a lanelet's end the distance carries on into the lanelet that follows it in the routing graph; a negative ds past its start into the one before it. Where several follow (a fork) or precede (a merge), the one that turns least is taken, then the lowest id -- the "straight on" a route most often takes, and deterministic. A ds that runs off a lanelet nothing follows is an error naming that lanelet.
  3. d_lane across. At the point ds reached, one step per lane through the routing graph's left or right neighbour -- lane-changeable or not (a solid line still has a lane beyond it), but only lanes of the same direction of travel. The point keeps abreast: its distance along the neighbour is where the point projects onto it, so the outside of a bend is not shortchanged. A missing neighbour is an error naming the lanelet and the side. Lanelet2 only knows a neighbour that shares the lanelet's whole side, so where the two lanes are split into lanelets at different points (one 20 m lanelet beside two 10 m ones) there is no neighbour to step to, and the vertex raises the same error.
  4. offset and yaw are applied on that lanelet, which gives a Lanelet2Pose, converted to CARLA coordinates like any other.

When. A trajectory with relative vertices is placed when the action starts -- the first tick of a run, against where each reference entity is at that tick -- and is then fixed: the vertices do not move with the reference entity afterwards, so the rest of the action (timing, both modes, hiding) works on it exactly as on absolute vertices. A repeating action (once=False) places it again at the start of every run. A reference entity that is not in the world yet puts the start off until it is -- for as long as it takes: the action neither ends nor fails meanwhile, and warns once per run; a lane the map does not have raises a ValueError naming the trajectory and the vertex. These lane checks can only be made then: they depend on where the reference entity is.

Modes

  • DRIVER hands the route to the entity's own driver -- see Driver mode and timing.
  • POSITION places the entity on the trajectory every tick, with the velocity the trajectory implies (so speed conditions and the recorder see the recorded speed). It is a kinematic replay: it reproduces a recording exactly, whatever the vehicle could actually do.
  • FOLLOW drives the vehicle there with the pure-pursuit and speed controller of the external driver interface (TrajectoryFollower, on the vehicle's own powertrain model), by default with its time_indexed longitudinal controller, which keeps the vehicle where the trajectory's clock has it. The motion is the vehicle's own, so it can lag or cut a corner. A pedestrian is walked towards the path.

Driver mode and timing

In driver mode the route starts where the entity is -- the nearest point of its path within 6 m, a hidden one having been brought in by a SpawnAction -- and passes every waypoint after it, each placed on the lanelet under it (a walkable one for a pedestrian). A vehicle the traffic backend drives is handed it as a path (BackendDriven.route_to), a pedestrian walks it (PedestrianEntity.route_to), an Autoware ego is given it as a mission.

Timing. When waypoints carry times (with a time reference) or departure conditions, the action keeps running until the entity reaches the goal and, every tick, sets the driver's speed to meet them (TrafficManager set_desired_speed, SUMO setSpeed, the walker's step speed):

  • the next waypoint with a time: the distance left to it along the planned path over the time left, clamped to [0, limit] (the lane's speed limit, 2 m/s for a walker) and smoothed. A late entity goes at the limit to catch up. The driver still stops for lights and yields; the speed is a target;
  • the next waypoint with a departure condition: a rising route_progress condition (what a logical scenario times its road users by) is predicted -- its entity's progress rate says when it will hold -- and the entity is paced to arrive then. Any other condition, or a measured entity that is not moving forward, is approached at cruise speed (speed, else the limit) braking to stop 2 m short of the waypoint, where it holds until the condition does;
  • with nothing due ahead: speed if given, else the limit.

A hold can deadlock

An NPC holding before a waypoint until the ego has progressed, while it stands in the ego's way, waits for ever: the ego cannot pass it. Prediction slows the NPC down long before it would hold, so a route_progress condition on a moving ego seldom holds it; a condition that cannot be predicted does. Place waypoints that wait for the ego out of its path.

An Autoware ego takes no speed: it is given the route only, and the action warns once that its waypoints' times and conditions cannot be met.

Arrivals. In every mode, each waypoint with a time or a condition is logged when reached -- when it was due (its time; the moment its condition first held) against when the entity arrived -- as a waypoint_arrival record of the trajectory log, so a run can be scored on its timing.

Keeping to the recorded lanes. A vehicle's written-out waypoints are not routed one by one onto the nearest lane: the whole track between them is sampled every 2 m and matched to the lanes it runs along -- road lanelets within 4 m running within 60 degrees of its heading, joined on the routing graph by following on, a lane change or a short path, the closest sequence chosen (traffic.route_match) -- and the route goes through where it leaves each one. A track that cannot be matched falls back to its waypoints one by one, leaving out those no lane route reaches, with a warning. The TrafficManager is given the route with its own lane changes off (given back by end_route when a run that watches the route ends), and a route ending in a junction is carried on along the lane after it until it is clear of the junction, so it is never handed an empty path.

When it ends. A route given as a goal (and Lanelet2 waypoints) with nothing to time ends as soon as the vehicle has it (as an ego's initial goal always has), unless stop_at_goal asks for the vehicle to stop there: then it runs until the vehicle arrives, its last metres driven by the backend itself where it can (finish_at); a route written out as waypoints, timed or not, runs until the vehicle is within 1 m of its end along the planned path (a timed one then sets its driver's speed back to the cruise speed); a pedestrian's ends when it arrives.

Who drives in follow and position modes, and when it ends

For the length of the run the action is the entity's only driver. A vehicle is taken back from the traffic backend first (TrafficBackend.release); an ego driven by an external stack (Autoware, a driver policy) is refused, because two authorities on one vehicle is not a scenario anyone wrote.

The action stays runningState until the entity reaches the end of the trajectory: the last vertex's time with a timing, the end of the path without one (never, for a closed trajectory), within ARRIVAL_TOLERANCE_M (1 m) of it in FOLLOW mode. A timed path that ends at rest -- a brake check's, 2 s of braking that stops a few metres on -- lasts its time in FOLLOW mode too: a vehicle that reaches its end early stands there on the brake until the last vertex's time. Then a vehicle is braked to a stop and a walker stood still where the trajectory ended. Pass until= to end it on a condition of your own. One that ends the run before the entity reaches the end is OpenSCENARIO's stop transition, as an override is: a vehicle is braked where it is and handed back to its traffic backend (resume_traffic), a walker stood still; one that holds only after the end leaves the entity held there. stop_at_end=False (an extension) leaves a vehicle moving as it arrived instead -- in POSITION mode with the last segment's velocity -- for an action that hands it straight back to traffic, as the adversarial actions do (resume_traffic).

RoutingAction routes an entity that is in the scene; it does not bring one in or take it out (appear_on_start and hidden_outside_trajectory are gone from it as of 1.0). A road user that enters a recording late is spawned hidden and brought in by a SpawnAction (the spawn card): put on its place, physics on, facing its heading, moving at speed; its routing card is triggered on the spawn card completing and starts where it stands. Triggered by a RouteProgressCondition it enters when the ego has come as far as it had when the road user was first seen; a PlaceClearCondition on the same place in its trigger waits for the place to be clear, and shift_max lets it take the nearest clear place further on along its lane once the trigger gives up waiting. The run writes a spawn record to the trajectory log on the tick it is brought in (a prop the action adds has none). One that leaves early is removed by a DespawnAction.

Vertices may also be placed against a logical scenario's route (RouteLanePose, RouteOppositePose, RouteCrossingPose, RouteCrosswalkPose, RouteRoadsidePose; path_source: route in a document) -- see Logical Scenarios from Routes.

When a road user leaves: DespawnAction

A route's end is where the road user's recording ends, but its driver does not know that: a vehicle the TrafficManager drives carries on wherever its traffic takes it. DespawnAction(entity_name, condition) (card Despawn, despawn) takes a vehicle or a pedestrian -- never the ego -- out of the world when its condition holds: the traffic backend lets go of it (and stops protecting it), the collision log stops listening to it, its actor is destroyed and the entity is unregistered. An action still naming it afterwards logs that once and does nothing (a routing run on it ends); a condition reads it as absent. The run writes a despawn record to the trajectory log.

- id: npc1_leaves
  type: despawn
  actor: npc1
  trigger:
    type: action_state
    params: {action: npc1_drive, state: completeState}

A driver route written out as waypoints runs until the entity reaches its last one, timed or not, so its completion is the moment it arrives.

A road user the ego has left behind for good can leave too: one standing at least 30 m behind the ego along the road reads, in a trigger,

type: any
children:
- {type: action_state, params: {action: npc1_drive, state: completeState}}
- type: all
  children:
  - {type: action_state, params: {action: npc1_drive, state: runningState}}
  - {type: standstill, params: {entity: npc1, duration: 5.0}}
  - type: entity_distance
    params: {source: ego, target: npc1, measure: lane, signed: true,
             rule: less_than_or_equal, distance: -30.0}

signed (lane frame only) measures how far the target is ahead of the subject along the road, the way the subject faces, negative behind it (coordinate.lane_distance.lane_offset), so it reads the same whether the ego is moving or stopped.

A pedestrian routed in driver mode is walked by CARLA's own walker controller (controller.ai.walker) where the map has a pedestrian navigation mesh: it keeps to the pavements, crosses at crossings (waiting at the kerb, as CARLA's walkers do), and walks round what stands in its way. It is sent along its route a target every 10 m (reached 2 m short of it along the walk, or 2 m from it), its top speed the walk's pace; a walker held by its route's timing is kept on its controller at a top speed of 0 while it stands (taken off it, it would be put back on the navigation mesh's nearest point -- a jump -- when it walked on), and its target is sent again every 2 s (CARLA sends a walker standing 4 s somewhere random). Held at its last target -- within 2 m of it, as near as the controller takes it, or at the walkway point a target on the road was moved to -- the walk has arrived, though that is short of the 1 m a stepped walk arrives within, and the route finishes. A walker that a threat turns back after it steps off a kerb (the route's turn-back thresholds) is stepped back behind the kerb (or waits where it stands if its steps back get it no nearer for 1.5 s), waits there and steps off again, all off the controller, which would walk it straight back onto the road; 60 s after it first turned back it crosses and turns back no more. A walker taken off its controller (arrived, its walk stopped or overridden) has its physics and collisions, which the controller turned off, turned on again. Whether it may cross a road away from a crossing is its own: the RoutingAction's cross_factor (the card's Crosses away from crossings), the probability its route may use the road anywhere -- 1 for a recorded walk that crossed there, 0 keeps it to crossings, empty is CARLA's default (0). CARLA keeps one such factor for the world and reads it only as a walker's controller starts (Navigation::AddWalker), so it is set to the walker's own just then and put back straight after. A map without a navigation mesh is said once, and its walkers are stepped along their routes as before. The navigation mesh comes with the map's import (roadgen's <Name>Package.py builds it with CARLA's RecastBuilder). The controller is stopped and destroyed however the walk ends: on arrival, when another action overrides the route (a WalkStraightAction, or a second route, which starts a controller of its own with its own targets), when the route's until condition ends it first (the walker stands where it is), and at the end of the run (PedestrianEntity.stop_walk). A vehicle driven by the framework's own controller (follow mode, a final approach), which the TrafficManager does not drive, brakes for a walker in its way within its stopping distance (utils.clearance), but not for one on another level of road, such as a footbridge overhead. A walker that falls over all the same is taken out of the world once it has lain there 5 s (npc_collisions.FALLEN_DESPAWN_S, the monitor's despawn_fallen_after_s; never the ego), with a despawn record of reason fallen. That is any walker, an entity's or not: one no entity stands for (a SUMO pedestrian's mirror, whose person leaves SUMO with it, or a walker with no role_name, recorded under its blueprint id) is destroyed by its actor, its AI controller first.

A pedestrian's written-out waypoints a few metres apart (no more than 10 m from one to the next: a recorded walk) are walked as written, from where it starts; farther apart they are routed between on the walkable lanelets.

Waypoint conditions

Each vertex is departed on one condition, its advance: when it holds, the entity leaves the vertex for the next one. A vertex with none is passed through on arrival.

  • Time is one kind of condition. TrajectoryTimeCondition(time) departs the vertex when the trajectory's clock reaches time -- the scenario clock mapped through the action's TrajectoryTiming (domain, scale, offset) and its initial_distance_offset. That is what a vertex time has always meant, and vertex.time reads it back. Without a time reference times are ignored, as OpenSCENARIO's <None/> says, and such a vertex is passed through.
  • Any other condition -- one the framework has now, one it gains later, or your own: an elapsed time, the distance to another entity, a speed, a traffic signal, an ActionStateCondition on another action, and AndCondition / OrCondition / StickyCondition / PersistentCondition compositions of them. The action asks it only what every condition answers, check(world, elapsed), and as for a trigger anything but None counts as satisfied. elapsed is the scenario's elapsed time, so ElapsedTimeCondition(30.0, label=...) reads "not before the scenario is 30 s old". (A TrajectoryTimeCondition inside a composition has no trajectory clock to read and compares the scenario's elapsed time; the editor refuses it there.) A MetricCondition is the exception: it is judged once the run is over and reads nothing while the entity waits, so TrajectoryVertex refuses one with a ValueError, as an action's trigger and every composition do.

A vertex cannot carry two: a time and another condition are combined, if that is what is meant, by giving the vertex an AndCondition of an ElapsedTimeCondition and the other.

Between two vertices. After vertex i is departed at scenario time T:

  • if vertex i + 1 has a time whose scenario time is not before T, the entity arrives there exactly then, moving linearly in between. When i was departed on its own time this is exactly the timed interpolation a recording is replayed with (a zero-duration segment is a jump), so a trajectory of times alone moves as it always did;
  • otherwise -- no time on i + 1, or one already past because the entity waited -- it goes at the action's speed: speed= (m/s) when given, else the speed the entity had when the run started. At (near) zero that segment is never finished, and the action warns when the run starts.

So after a late departure, a next vertex whose time is at or just after the departure is reached at once -- a jump in POSITION; in FOLLOW the vehicle cannot keep up and drives as fast as its controller lets it. That is the rule "arrive at its time if that is not before the departure" doing what it says.

Waiting. In POSITION mode a condition is checked from the tick the entity reaches its vertex -- not before -- then on every tick while it waits there, standing still with zero velocity. Once it holds the vertex is departed for the rest of that run; it is not asked again. If it already holds on arrival the entity does not stop. A condition that never holds keeps the entity there until until= ends the run. On the last vertex of an open path a condition means "end the run when it holds" (a time: when the clock reaches it, as ever); arriving at a last vertex with none ends the run. On the first vertex it is the departure from the start (a time: wait at the start until then). Vertices before the point a run starts from (initial_distance_offset) are not checked. A repeating action (once=False) re-arms every condition at the start of each run, and a closed path -- which cannot carry times -- checks its conditions again on every lap, in POSITION and FOLLOW alike. Whatever state a condition object keeps is its own: a latched StickyCondition stays latched.

from autoware_carla_scenario import (
    EGO_ROLE_NAME,
    ComparisonRule,
    ElapsedTimeCondition,
    EntityDistanceCondition,
    MapPose,
    RoutingAction,
    RoutingMode,
    Trajectory,
    TrajectoryTimeCondition as At,
    TrajectoryTiming,
    TrajectoryVertex,
)

crossing = Trajectory(
    "walker_crossing",
    [
        TrajectoryVertex(MapPose(81200.0, 50100.0), At(0.0)),
        # At the kerb: wait until the ego is within 25 m, then step out.
        TrajectoryVertex(
            MapPose(81205.0, 50100.0),
            EntityDistanceCondition(
                "walker1", EGO_ROLE_NAME, 25.0, ComparisonRule.LESS_THAN,
                label="ego_close",
            ),
        ),
        # Across by 11 s -- or, if the ego came late, at 1.4 m/s.
        TrajectoryVertex(MapPose(81205.0, 50110.0), At(11.0)),
    ],
)
self.register_pre_tick(
    RoutingAction(
        "walker1",
        trajectory=crossing,
        time_reference=TrajectoryTiming(),
        mode=RoutingMode.FOLLOW,
        speed=1.4,
        label="cross",
    )
)

# A trajectory built elsewhere (a recording, a lanelet route): `gated` replaces
# what the vertices named depart on, a time included.
held = recorded.gated({12: ElapsedTimeCondition(20.0, label="not_before_20s")})

By mode.

  • DRIVER: see Driver mode and timing -- the entity is paced to arrive when the condition holds, or held 2 m short of the waypoint until it does.

  • POSITION places the entity where that timeline has it every tick; waiting, it stands on the vertex itself.

  • FOLLOW (vehicle): a vertex whose condition has not held yet is a stop line -- the controller's plan ends on it, slowed to come to rest there at 2 m/s². A car cannot stop within a tick, so here the condition is checked before arrival, from as far off as stopping there takes (braking distance, a second's travel and the arrival band); one that holds then is passed, letting the vehicle through at speed and costing the schedule nothing -- even if it would no longer hold by the time the vehicle gets there, and a PersistentCondition starts counting from that distance. The last vertex of an open path is the exception: it is checked only on arrival, since departing it ends the run. Otherwise it is looked at every tick; within ARRIVAL_TOLERANCE_M (1 m) along the path the vehicle has reached the vertex and waits on the brake. The plan after it is stamped from the timeline above.
  • FOLLOW (walker): looked at early in the same way, walked onto the vertex, slowing as it gets close; within 0.3 m it has reached it and stands.
  • On a closed path FOLLOW finds where the entity is by projecting it near where it was, and that search wraps from the end of the path to its start, so the entity is found on its next lap once it crosses the first vertex and the conditions are checked again on every lap, as in POSITION.

RoutingAction.held_vertex names the vertex (0-based) the entity waits at for a condition other than a time, or None.

Breaking change

TrajectoryVertex no longer takes time= (or a time as its second argument), and the editor's vertex rows no longer have a time column: write TrajectoryVertex(position, TrajectoryTimeCondition(time)), and in a document a trajectory_time waypoint condition on the vertex. The old forms raise an error that says so.

In the Scenario Editor

Set Goal (category Vehicle / Motion) is a card like any other, for the ego, a vehicle or a pedestrian. Driven by is its mode (Driver, Follow, Position). Its route comes from one of five sources:

  • Goal lanelet, via lanelets (the default) -- a goal lanelet and s along it, and the lanelets to pass on the way: what an ego is sent to. It takes no waypoint conditions and no time reference, and it is driven in Driver mode only, from where the entity stands (Start this far along 0): the goal is a destination for the entity's driver, not a way to follow, place it on, or start along. RoutingAction refuses a goal with mode=FOLLOW/POSITION or a positive initial_distance_offset too.
  • Vertices (map frame) -- written in the card, one vertex per line: x, y[, yaw] (metres, radians; 81234.5, 50123.0 leaves the yaw to the path). The line above the text says how many vertices and how long. Their times are waypoint conditions (below). This is what a recording transcribes to, so a replayed road user's card can be edited like any other.
  • Along lanelets -- the lanelets picked on the map, followed along their centrelines at a lateral offset and timed at a constant speed.
  • Along the scenario's route -- route vertices, see Logical Scenarios from Routes.
  • Relative to an entity's lane -- lane-relative vertices, one per line: ds[, offset][, d_lane][, yaw] (metres, metres, lanes, radians; only ds is required, d_lane is a whole number), measured from the entity chosen in Relative to -- or, left empty, from the card's own actor. The document stores them as rows [ds, offset, d_lane, yaw] and the reference as an entity id, which the compiler turns into that entity's role name. Deleting the reference entity clears the field, so the card is then measured from its own actor.

Waypoint conditions -- what each vertex departs on, its time included -- are under the card's fields in the inspector: + waypoint condition takes a vertex number -- counted from 1: the Nth vertex of the list (map-frame or relative), blank and comment lines not counted -- and a condition type, and adds an ordinary condition tree there, drawn and edited exactly as a trigger is (click it for its fields, add children to an All / Any). A vertex's time is the type Trajectory time (trajectory_time, one field: time on the trajectory's clock), read "depart vertex N at". A second condition added to the same vertex is combined with the first in an All (a Trajectory time cannot be combined: it is only ever a vertex's whole condition). The vertex number of each can be changed in place, and the bin removes it; a recording's long list of times folds away. The card on the canvas says how many it has, and Speed where no time paces sets the action's speed. In the document they are a list on the action, each a vertex and a condition node:

actions:
- id: a_walker
  type: routing
  actor: walker1
  params:
    path_source: vertices
    mode: follow
    vertices: [[81200.0, 50100.0, null], [81205.0, 50100.0, null],
               [81205.0, 50110.0, null]]
    time_domain: relative
    speed_ms: 1.4
  advance_conditions:
  - vertex: 1
    condition: {type: trajectory_time, params: {time: 0.0}}
  - vertex: 2          # the second vertex
    condition:
      type: entity_distance
      params: {source: walker1, target: ego, rule: less_than, distance: 25.0}
  - vertex: 3
    condition: {type: trajectory_time, params: {time: 11.0}}

The compiler builds each condition with the same builders as a trigger, and the validator checks them as it checks a trigger, plus where they sit and the timing rules: a vertex the card has, one condition per vertex, every vertex departing on something once any has a time, times that do not decrease, a time reference only with times, a Trajectory time only as a vertex's whole condition, no condition waiting for its own action to leave the running state (the action runs for as long as the entity waits), and only for vertices written in the card -- a lanelet path's vertices are generated every 2 m, nothing anyone could count, so it takes none (its speed times it). A condition that names an entity or action you delete goes with it, as a trigger does. The own-action rule is deliberately conservative: any reference to the card's own action but "is running" is refused, even under a Not where it could not deadlock. A row with a time cell, as documents had before, is refused with a message that gives the trajectory_time condition to write instead.

The other fields are the action's: the time reference (from the action start, from the scenario start, or none -- the default), its scale and offset, the mode, how far along to start, and whether the entity is out of the world outside the trajectory's time. The validator checks what the fields only mean together: a time reference needs vertex times (or a speed, for lanelets), and keeping the entity out of the world needs the Position mode and a time reference. For relative vertices it checks the numbers, the timing and that the reference entity exists; whether the lanes they name exist is only known when the action starts.

An entity's Spawn out of the world option (non-ego entities) spawns it under the map with its physics off, for a card that brings it in at its first vertex: a road user a recording picks up late, placed where it first appears, could otherwise collide at spawn with whatever stood there when the run began.

Replaying a recorded scene

A transcribed recording becomes an ordinary scenario document -- the one the editor edits and the declarative runtime runs -- with nothing beyond the parts above:

  • the ego spawns where the recording's ego started and is sent where it went;
  • every road user is an entity spawned on the lanelet it was first seen on, with one Set Goal card: map-frame vertices, each departed at its recorded time (a trajectory_time waypoint condition) on the scenario clock (time_domain: absolute, time_offset moving the recording's first frame to t = 0), in Position mode and hidden outside its trajectory;
  • a road user first seen after the start spawns out of the world (spawn.hidden) and appears at its first vertex.

Open it in the editor to add the conditions the test is about -- a road user can wait for the ego by replacing one of its vertex times with another waypoint condition.

Note

Transcribers written for the earlier format (a time column in the vertex rows) have to write trajectory_time waypoint conditions instead; a document with a time column is refused with a message saying so.

T4 scenes are transcribed this way by scenario-import-t4 of the separate scene_to_scenario_transpiler package, which depends on the framework, never the other way round.

Warning

Map-frame vertices are Autoware's map frame, so a document replaying a recording has to run on the map the scene was recorded on, loaded with the same projector.