Text2Traffic3D

Text2Traffic3D is a minimal Python engineering skeleton for generating traffic scenarios from natural-language prompts and exporting runnable scenario artifacts for CARLA-oriented workflows.

This milestone implements a no-CARLA end-to-end loop: prompt parsing, logical scenario construction, validation, deterministic concretization, and CARLA script export.

Scope

OpenDRIVE is treated as the static map layer: road networks, lanes, markings, and traffic signals. OpenSCENARIO and CARLA scripts are treated as the scenario execution layer: actors, maneuvers, storyboards, and runtime behavior.

Implemented in this MVP:

• Standard src/ Python package layout.
• Pydantic schemas for ODD, functional, logical, and concrete scenarios.
• Rule-based parsing for left-turn pedestrian, cut-in, lead-vehicle braking, and right-turn cyclist prompts.
• Logical scenario builder with parameter ranges, routes, constraints, and risk metrics.
• Validation for actors, lanes, routes, speeds, timing, TTC, and initial collision risk.
• Deterministic seeded concretization from logical to concrete scenarios.
• JSON, OpenSCENARIO, and CARLA Python script exporters.
• CLI commands: parse, validate, concretize, export-carla.
• Smoke tests for imports, schemas, CLI, validation, concretization, and export.

Stage 3A (branch stage3a-carla-minimal-loop) adds:

• Real CARLA runtime client: connect, load_map, set_weather, spawn_ego, spawn_actor, attach_rgb_sensor, tick_loop, record_states, destroy_all.
• run-carla CLI command to execute a concrete_scenario.json for 10–20 seconds.
• Mocked unit tests so CI stays CARLA-free.

Not implemented yet:

• Full traffic-controller / route-following behavior beyond basic autopilot and walker AI.
• Neural LLM scenario generation.
• Full OpenDRIVE parsing.
• Full OpenSCENARIO 1.x semantics.

Install

pip install -e .

For development:

pip install -e ".[dev]"
pytest

CLI

text2traffic3d --help
text2traffic3d parse examples/prompts/left_turn_pedestrian.txt --output scenario_dsl.json --logical-output logical_scenario.json
text2traffic3d concretize logical_scenario.json --output concrete_scenario.json --seed 7
text2traffic3d validate concrete_scenario.json
text2traffic3d export-carla logical_scenario.json --output run_carla_scenario.py --seed 7

Stage 3A CARLA execution (requires a running CARLA simulator and its Python API on PYTHONPATH):

text2traffic3d run-carla concrete_scenario.json --record-output recorded_states.json --duration 15

Output Files

• Functional scenario JSON: high-level actors, scene, maneuvers, and ODD.
• Logical scenario JSON: parameter ranges and constraints.
• Concrete scenario JSON: sampled actor poses, speeds, and timing.
• CARLA script: self-contained Stage-2 scenario execution scaffold for later CARLA API integration.
• OpenSCENARIO XML: minimal XML scaffold for scenario execution-layer integration.