DOCSEARCHbyAlgolia
Submit Docs

ScenarioRunner Documentation

repository·master·Indexed 20 days ago

https://github.com/carla-simulator/scenario_runner

A Python-based execution engine for defining and running complex traffic scenarios within the CARLA simulator, supporting OpenSCENARIO standards. It includes tools for OSC2 scenario configuration, AST generation using Antlr4, and a framework for implementing and evaluating AutonomousAgents via the AutonomousAgent base class.

Tokens
15K
Snippets
35
Records
58
Agent score
71%

What's inside ScenarioRunner

  1. Overview of the Metrics Module

    master

    The Metrics module allows users to calculate and monitor parameters from a completed CARLA simulation without re-running the scenario. It relies on the CARLA recorder to store simulation information.

    Users follow a three-step workflow:

    1. Record a scenario: Generate .log and .json files using scenario_runner.py.
    2. Define metrics: Create custom metric classes by inheriting from BasicMetric.
    3. Run the metrics manager: Execute metrics_manager.py to process the recorded data and visualize results.

    The module structure is as follows:

    • metrics_manager.py: The main entry point.
    • srunner/metrics/data/: Stores scenario information.
    • srunner/metrics/examples/: Contains example metrics and the BasicMetric base class.
    • srunner/metrics/tools/: Contains metrics_parser.py (converts recording strings to dictionaries) and metrics_log.py (provides query functions).

  2. Overview of ScenarioRunner for CARLA

    master

    ScenarioRunner is a module designed for defining and executing traffic scenarios within the CARLA simulator. It supports two primary methods for scenario definition:

    1. Python Interface: Define scenarios directly using Python scripts.
    2. OpenSCENARIO Standard: Use the industry-standard OpenSCENARIO format.

    It is commonly used to prepare Autonomous Driving (AD) agents for evaluation by generating complex traffic scenarios and routes. Results can be used for validation in the CARLA Leaderboard.

  3. Supported Scenarios in ScenarioRunner

    master

    ScenarioRunner provides a collection of pre-defined driving scenarios used to test ego vehicle behavior in CARLA. These scenarios range from simple following behaviors to complex intersection negotiations and emergency maneuvers.

    Following Scenarios

    • FollowLeadingVehicle: The ego vehicle follows a leading car in Town01. The leading car slows down and stops; the ego vehicle must react to avoid collision. Ends on timeout or when the ego vehicle stops near the leader.
    • FollowLeadingVehicleWithObstacle: Similar to FollowLeadingVehicle, but a hidden obstacle is placed in front of the leading vehicle.
    • OtherLeadingVehicle: The ego vehicle follows a leading car. When the leader decelerates, the ego vehicle must change lanes to avoid collision. Ends on timeout or after driving a certain distance.

    Intersection and Turning Scenarios

    • VehicleTurningRight: Ego vehicle turns right at an intersection; a cyclist suddenly enters the path, requiring the ego vehicle to stop and then continue once the path is clear.
    • VehicleTurningLeft: Similar to VehicleTurningRight, but the ego vehicle performs a left turn.
    • OppositeVehicleRunningRedLight: Tests handling of an illegal maneuver where an opposing vehicle runs a red light at an intersection. The ego vehicle must stop despite having a green light.
    • NoSignalJunctionCrossing: Tests negotiation at an unsignalized junction where the ego vehicle and another vehicle cross paths.
    • SignalizedJunctionRightTurn: Tests a right turn at a signalized urban intersection where the hero vehicle turns into the same direction as a vehicle initially crossing from a lateral direction.
    • SignalizedJunctionLeftTurn: Tests a left turn at a signalized urban intersection where the hero vehicle cuts across the path of an oncoming vehicle.

    Obstacle and Crossing Scenarios

    • StationaryObjectCrossing: A stationary cyclist blocks the road, requiring the ego vehicle to stop.
    • DynamicObjectCrossing: A dynamic cyclist suddenly drives into the ego vehicle's path, requiring a stop and subsequent resumption of driving.

    Emergency and Maneuver Scenarios

    • ControlLoss: Tests if a vehicle can regain control and correct its course after losing control due to road conditions.
    • ManeuverOppositeDirection: Tests passing a vehicle in a rural area where the ego vehicle encroaches into the lane of a vehicle traveling in the opposite direction.

  4. Traverse the AST using Listeners or Visitors

    master

    Antlr4 provides two mechanisms to access the syntax parse tree:

    1. Listeners: The ExampleListener class automatically triggers callback methods during tree traversal. For every sub-node, Antlr generates an enterxxx() method (called when entering a node) and an exitxxx() method (called after all child nodes have been traversed). To use a listener, inherit from the generated listener class and override the required methods.

    2. Visitors: Unlike listeners, visitors must explicitly call a visit method to access sub-nodes; otherwise, the subtree will not be visited. To generate visitor classes, add the -visitor flag to the Antlr4 command:

    antlr4 -Dlanguage=Python3 -visitor Example.g4

  5. Implement evaluation criteria using StopTriggers

    master

    Since the OpenSCENARIO 1.0 standard does not explicitly define test/evaluation criteria, you can implement pass/fail results in CARLA by re-using StopTrigger conditions. This is achieved via ParameterConditions by providing specific criteria names.

    Supported criteria names for evaluation include:

    • criteria_RunningStopTest
    • criteria_RunningRedLightTest
    • criteria_WrongLaneTest
    • criteria_OnSideWalkTest
    • criteria_KeepLaneTest
    • criteria_CollisionTest
    • criteria_DrivenDistanceTest

  6. Understand the global_plan route structure

    master

    The self.global_plan variable contains the entire route the agent is expected to travel. It is represented as a list of tuples. Each tuple contains:

    1. A dictionary representing the waypoint (containing 'lat', 'lon', and 'z').
    2. A RoadOption indicating the recommended action (e.g., LANEFOLLOW, or specific intersection instructions like turning left/right).

    Example structure:

    [({'z': 0.0, 'lat': 48.998, 'lon': 8.002}, <RoadOption.LANEFOLLOW: 4>), ...]

  7. Understand the symbol_manager module

    master

    The symbol_manager module manages symbol definitions and tracks their usage to ensure symbols are defined before use and remain within their valid scope.

    • Symbol Class: The Symbol class is the base class for all symbols, containing basic information like name and category. Specific symbol types extend this class.
    • Scope Management: Scopes are created as a tree structure by traversing the syntax parsing tree. This structure implements the inheritance and extension features required by OpenScenario 2.0.

  8. Access scenario data via MetricsLog

    master
    When defining a custom metric in ScenarioRunner, all recorded scenario information is accessed through the MetricsLog class. This object is passed as the log argument to the _create_metric() function. The MetricsLog class (located at srunner/metrics/tools/metrics_log.py) provides a suite of query methods to retrieve actor data, simulation timing, physics, and environmental states (like traffic lights) for specific frames or across entire recording intervals.

  9. OSC2 Syntax: Composition and Modifiers

    master

    OpenScenario 2.0 (OSC2) allows you to define complex behaviors using composition operators and movement modifiers.

    Composition Operators

    • serial: Executes scenarios sequentially.
    • parallel: Executes scenarios simultaneously.
    • one_of: At least one of a set of scenarios must hold.

    Supported Movement Modifiers in CARLA

    • speed(value): Set target speed (e.g., speed(30kph)).
    • position(value, [params]): Set position (e.g., position(10m, behind: npc, at: start)).
    • lane(index, [params]): Set lane (e.g., lane(1, at: start)).
    • acceleration(value): Set vehicle acceleration (e.g., acceleration(15kphps)).
    • keep_lane(): Maintain the current lane.
    • change_speed(value): Change the current speed.
    • change_lane(params): Change to a different lane (e.g., change_lane(lane_changes:[1..2], side: left)).

    Example Scenario Structure

    import basic.osc

scenario top:
    path: Path
    path.set_map("Town04")
    path.path_min_driving_lanes(2)

    ego_vehicle: Model3
    npc: Rubicon

    event start
    event end

    do parallel(duration: 18s):
        npc.drive(path) with:
            speed(30kph)
            lane(2, at: start)

        serial:
            get_ahead: parallel(duration: 3s):
                ego_vehicle.drive(path) with:
                    speed(30kph)
                    lane(same_as: npc, at: start)
                    position([10m..20m], behind: npc, at: start)

  10. Understand the ast_manager module

    master

    The ast_manager module is responsible for creating Abstract Syntax Trees (ASTs).

    • Node Definition: The Node class is the base class for all AST nodes. It defines the source code position, the node's scope, and its child nodes. All specific AST nodes inherit from Node.
    • AST Construction: ASTs are built by traversing the syntax parse tree generated by Antlr4. A listener is used to traverse the tree; during the callback functions, AST nodes are created and added to the abstract syntax tree.

  11. Quickstart: Run an OpenScenario 2.0 scenario

    master

    Follow these steps to execute a scenario using OpenScenario 2.0 syntax:

    1. Launch CARLA: Run the CARLA simulator executable.

      cd /path/to/CARLA
./CarlaUE4.sh

    2. Start Manual Control: In a new terminal, run the Scenario Runner's manual_control.py script to control the ego vehicle.

      python manual_control.py -a --rolename=ego_vehicle

      Note: Ensure you are running the version in the Scenario Runner repository, not the one in CARLA's PythonAPI/examples.

    3. Run the Scenario: Execute scenario_runner.py using the --openscenario2 flag.

      python scenario_runner.py --sync --openscenario2 srunner/examples/overtake_concrete.osc --reloadWorld

    Pro-tip: You can launch both manual control and the scenario runner in a single command using gnome-terminal:

    gnome-terminal -- bash -c "python manual_control.py -a --rolename=ego_vehicle"; python scenario_runner.py --sync --openscenario2 srunner/examples/overtake_concrete.osc --reloadWorld
    python scenario_runner.py --sync --openscenario2 srunner/examples/overtake_concrete.osc --reloadWorld