Browse Source
docs: finalize scenario-centric architecture documentation
docs: finalize scenario-centric architecture documentation
- Updated context.md with new CLI, framework contracts, and Z-axis safety rules - Added .cursorrules to codify PowerShell and environment requirements - Added braking.md deep-dive post-mortem on spawning challenges - Formally marked scenario parameterization as a core feature1843_integration
3 changed files with 118 additions and 41 deletions
-
25.cursorrules
-
50intel/braking.md
-
84intel/context.md
@ -0,0 +1,25 @@ |
|||
# AI Rules for BATL_CARLA_SIM |
|||
|
|||
This document contains rules and instructions for AI agents working on this project. |
|||
|
|||
## Simulation Pipeline |
|||
- This project uses CARLA 0.9.16 and the Foxglove integration. |
|||
- Core logic is in `src/`. |
|||
- Scenarios are in `scenarios/`. |
|||
|
|||
## Environment Rules |
|||
- **Terminal**: Use **PowerShell** for all command executions. |
|||
- **Python**: Always use the `carla312` conda environment. |
|||
- **Activation**: `C:\ProgramData\miniconda3\Scripts\activate.bat carla312` |
|||
- **One-Click Runner**: Use `./run.bat` for most tasks as it handles activation and orchestration automatically. |
|||
|
|||
## Command Execution Rules |
|||
- **Direct Execution**: Background command capture works perfectly in PowerShell. You can run `python`, `git`, and `./run.bat` directly. |
|||
- **Wait Policy**: Use a moderate `WaitMsBeforeAsync` (e.g. `2000` to `5000`) for non-simulation commands to see immediate output. |
|||
- **Example**: `./run.bat --list-scenarios` |
|||
- **Example**: `python src/main.py --no-record --frames 10` |
|||
|
|||
## Project Architecture |
|||
- **Scenario-agnostic Core**: All scenario-specific logic must be exclusively in the `scenarios/` directory. |
|||
- **Global Config**: Use `config.py` only for global simulation settings (FPS, Sensors, Default Model/Weather). Do NOT add scenario parameters here. |
|||
- **Parameter Tuning**: Use the `--params "KEY=VAL"` CLI flag to tune scenarios from the command line. |
|||
@ -0,0 +1,50 @@ |
|||
# Braking Scenario: Hard Stop Evaluation (Deterministic) |
|||
|
|||
This document provides a technical guide to the **Lead Vehicle Hard Braking** scenario, including its architectural design, common CARLA-specific pitfalls, and the robust fixes implemented to ensure 100% repeatability. |
|||
|
|||
--- |
|||
|
|||
## 🏗️ 1. Scenario Architecture |
|||
|
|||
The Braking scenario consists of two main actors on a multi-lane road (default: **Town10HD_Opt**): |
|||
1. **Ego Vehicle**: The vehicle under test, tracking a set of target coordinates or following a lead vehicle. |
|||
2. **Lead Vehicle**: An NPC spawn 25m ahead on the same lane. |
|||
|
|||
**Success Metric**: The Ego ADNC stack must detect the lead vehicle's emergency deceleration and brake safely without collision. |
|||
|
|||
--- |
|||
|
|||
## 🏎️ 2. Critical Spawning Fixes (Lessons Learned) |
|||
|
|||
During implementation, we identified several subtle CARLA behaviors that led to `RuntimeError: Spot occupied` failures. These are now documented for all future scenario developers. |
|||
|
|||
### 🛑 Issue A: Stale Physics (Synchronous Mode Delay) |
|||
- **Problem**: When spawning a new actor in **Synchronous Mode**, its location (`get_location()`) often defaults to stale values (like `0,0,0`) until the world's physics engine has processed at least one frame. |
|||
- **Impact**: Calculating NPC spawn points based on the Ego's position immediately after spawning resulted in NPCs appearing at the map origin instead of ahead of the Ego. |
|||
- **Fix**: Added an explicit **`world.tick()`** call in the core orchestrator immediately after the Ego is spawned and before the scenario's `setup()` method is called. This "settles" the Ego and guarantees accurate coordinate data. |
|||
|
|||
### 🛑 Issue B: Ground-Mesh Clipping & Bounding Box Overlap |
|||
- **Problem**: CARLA waypoints sit exactly on the road surface (`Z = 0.0`). Spawning a vehicle's center-point at this height causes its collision box (chassis and tires) to overlap with the road mesh. |
|||
- **Impact**: CARLA identifies this overlap as an "obstacle" and fails the spawn with a "Spot occupied" error. |
|||
- **Fix**: Implemented a mandatory **0.5m Z-offset (lift)** for all NPC spawn transforms. NPCs are spawned slightly in the air and "dropped" onto the road, which is the industry-standard way to ensure collision-free actor placement in CARLA. |
|||
|
|||
### 🛑 Issue C: Deterministic "Spawn-and-Move" Pattern |
|||
- **Problem**: Directly spawning an actor at an absolute intersection coordinate (`P2` from our showcase) is fragile and frequently fails due to microscopic geometry conflicts in Town10. |
|||
- **Fix**: Developed a two-stage **Spawn-and-Move** pattern: |
|||
1. Spawn the Ego at a "safe" map spawn index (provided by `map.get_spawn_points()`). |
|||
2. Immediately translate it to the target scenario coordinates using **`set_transform()`**. |
|||
- **Result**: `set_transform` is significantly more lenient than `try_spawn_actor`, ensuring we never fail to reach our starting intersection. |
|||
|
|||
--- |
|||
|
|||
## 🧪 3. Parametric Tuning via CLI |
|||
|
|||
The orchestrator now supports dynamic parameter injection for the braking scenario: |
|||
```powershell |
|||
./run.bat braking --params "BRAKE_FRAME=120,LEAD_DISTANCE_M=30" |
|||
``` |
|||
- **BRAKE_FRAME**: The exact simulation frame where the lead vehicle disengages autopilot and applies a `brake=1.0` override. |
|||
- **LEAD_DISTANCE_M**: The initial separation between Ego and Lead vehicle. |
|||
|
|||
--- |
|||
*Created: March 2026 | Intel Repository — ADAS Development* |
|||
Write
Preview
Loading…
Cancel
Save
Reference in new issue