# CARLA Custom Scenario Design: Deterministic Showcase Suite (Intel)

This document serves as a "Deep Dive" into the design decisions, technical implementation, and lessons learned during the development of the **Deterministic Showcase Suite**. Use this as a reference for creating future high-impact ADAS demo scenarios.

---

## 🏗️ 1. Architecture: Manual vs. Traffic Manager

**Standard Approach**: Using `ego_vehicle.set_autopilot(True)` and relying on Traffic Manager (TM).
- **Pros**: Easy to set up, handles traffic rules automatically.
- **Cons**: Unpredictable. Random lane changes, braking for minor obstacles, and "softening" of turns makes for poor demo repeatability.

**Deterministic Approach (Showcase)**: Manual coordinate-based control.
- **Core Strategy**: Define precise spawn points (X, Y, Z) and use a custom steering-to-target loop.
- **Why**: Ensures that the "Left-Turn Across Path" (LTAP) maneuver happens at the *exact same frame* every time, regardless of noise or simulation variance.

---

## 🏎️ 2. The "Secret Sauce": Physics Velocity Injection

One of the biggest challenges in CARLA is consistent timing. Rolling friction, gear shifts, and engine torque curves cause variability in speed.

**The Fix**: Direct `set_target_velocity` override.
- **Implementation**: Instead of applying `throttle=1.0` and hoping for the best, we calculate the forward vector and force the velocity to exactly **9.72 m/s** (35 km/h).
- **Result**: The NPC reaches the intersection at the *exact same frame* every run, allowing us to tune the EGO's arrival time down to the millisecond.

---

## 🗺️ 3. Multi-Stage Waypoint Guidance

**The Issue**: Standard "Steer toward target" logic often leads to curb-clipping or unrealistic, jagged turns at intersections. CARLA's pathfinding is optimized for driving, not cinematic maneuvers.

**The Solution**: Intermediate `MID` points.
- **Strategy**: Instead of pointing the NPC directly at the final target, we created a `P1_MID` waypoint.
- **Outcome**: This forces the vehicle to stay in its lane longer and take a wider, "swept" turn, which looks significantly more professional and avoids clipping the junction geometry.

---

## 📡 4. Radar Calibration & Serialization

**The Caveat**: CARLA's Radar sensor exports data in **Spherical Coordinates** (Depth, Azimuth, Altitude, Velocity). Most visualization tools (like Foxglove PointClouds) expect **Cartesian (XYZ)**.

**The Math**:
- `x = depth * cos(alt) * cos(az)`
- `y = depth * cos(alt) * sin(az)`
- `z = depth * sin(alt)`
- **Note**: The `velocity` field must be included separately and requires a 16-byte point stride (XYZ + V) in the MCAP schema.

---

## ⚡ 5. Performance & Caveats

### Asynchronous I/O
- Always use `ThreadPoolExecutor` for image saving. Saving 720p PNGs synchronously will drop your simulation from 30 FPS to ~5 FPS, ruining the physics time-step.

### The "Progress Bar Clash"
- When using `tqdm`, standard `print()` statements will "staircase" the bar and ruin the UI.
- **Fix**: Refactor scenarios to accept a `pbar` object and use `pbar.write(msg)` instead of `print(msg)`.

### CARLA API Gotchas
- **Weather API**: The parameter for sun height is `sun_altitude_angle`, NOT `pitch`. Using the wrong name (or passing an `int` when a `float` is expected) will trigger a `Boost.Python` type error.
- **Sensor Sync**: Always fetch sensor data *after* `world.tick()` to ensure the frames match the metadata.

---

## 🚀 6. The Automation Pipeline

We turned a 2-step manual process into a single-step autonomous pipeline:
1. `main.py` runs the simulation.
2. `recorder.py` captures frames (Async) + generates `.mp4` previews.
3. `main.py` cleanup callback triggers `data_to_mcap.py` automatically.

**Run Command**:
```powershell
python src/main.py --scenario showcase --frames 250 --weather ClearNoon
```

---
*Created: March 2026 | Intel Repository — ADAS Development*