Simulator/intel/scenarios/showcase.md

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 scripts/data_to_mcap.py automatically.

Run Command:

python src/main.py --scenario showcase --frames 250 --weather ClearNoon

---

Created: March 2026 | Intel Repository — ADAS Development