# 🦊 Fox CARLA ADAS Simulation Project

A modular, scenario-driven simulation framework built on **CARLA 0.9.16** for demonstrating structured ADAS driving scenarios with multi-modal sensor data and physics-based radar synthesis.

---

## 🚀 1. Prerequisites

Before setting up the project, ensure you have the following installed:

*   **Operating System**: Windows 10/11 (Required for CARLA 0.9.16 and Shenron synthesis).
*   **CARLA Simulator**: Version **0.9.16** (Must be installed and reachable).
*   **Miniconda/Anaconda**: For environment management.
*   **NVIDIA GPU**: Required for high-fidelity radar synthesis and CARLA rendering.

---

## 🛠️ 2. Environment Setup

### 1. Clone the Repository
Clone this repository into your CARLA PythonAPI folder:
```powershell
cd C:\Path\To\CARLA_0.9.16\PythonAPI
git clone <repository_url> Fox
cd Fox
```

### 2. Create Conda Environment
We use Python **3.12** for compatibility with modern libraries and CARLA 0.9.16.

**Option A: Using environment.yml (Recommended)**
```powershell
conda env create -f environment.yml
conda activate carla312
```

**Option B: Manual Setup**
```powershell
conda create -n carla312 python=3.12 -y
conda activate carla312
pip install -r requirements.txt
```

### 3. Install CARLA Python API
Regardless of the option above, you must install the CARLA 0.9.16 wheel:
```powershell
pip install ..\carla\dist\carla-0.9.16-cp312-cp312-win_amd64.whl
```

---

## 🖥️ 3. Usage & Execution

### 🖱️ One-Click Dashboard (GUI)
The easiest way to run the orchestrator is via the Flask dashboard:
1.  Launch **CARLA** (e.g., `CarlaUE4.exe`).
2.  Double-click `dashboard.bat` in the project root.
3.  Navigate to `http://127.0.0.1:5000` to manage scenarios and view telemetry.

### ⌨️ Command Line Interface (CLI)
You can run scenarios directly via the `run.bat` wrapper:

*   **List Scenarios**: `.\run.bat --list-scenarios`
*   **Run Scenario**: `.\run.bat braking --frames 300`
*   **With Parameters**: `.\run.bat cutin --params "TARGET_SPEED=40,CUTIN_DIST=15"`
*   **Skip Processing**: `.\run.bat showcase --skip-shenron --skip-mcap`

---

## 🏗️ 4. Project Architecture

*   **`src/`**: Core logic including `PipelineManager`, `SensorManager`, and `Recorder`.
*   **`scenarios/`**: Modular scenario implementations (e.g., `braking.py`, `cutin.py`).
*   **`scripts/`**: Data conversion tools (MCAP) and the **Shenron** radar synthesis engine (orchestrated by `ShenronOrchestrator`).
*   **`dashboard/`**: Flask-based web interface for the orchestrator.
*   **`intel/`**: Deep-dive documentation, project history (CHRONICLES.md), and versioned changelogs.

---

## 🛰️ 5. The Data Pipeline

The simulation follows a structured multi-stage pipeline:
1.  **Simulation Stage**: Captures RGB, LiDAR, and raw Radar data from CARLA.
2.  **Shenron Stage**: Synthesizes high-fidelity physics-based radar heatmaps.
3.  **MCAP Stage**: Converts all data into a single `.mcap` file for **Foxglove** visualization.
4.  **Video Stage**: Generates `.mp4` previews of the session.

---

## 📂 6. Replication Checklist for New PC

If you are moving this project to another machine:
1.  [ ] Install **CARLA 0.9.16**.
2.  [ ] Verify **CUDA** drivers are up to date for Shenron synthesis.
3.  [ ] Create `carla312` environment and install `requirements.txt`.
4.  [ ] Ensure `run.bat` and `dashboard.bat` point to the correct `activate.bat` path (default: `C:\ProgramData\miniconda3\Scripts\activate.bat`).
5.  [ ] Run `cmd /c "run.bat showcase --frames 50"` to verify the full pipeline end-to-end.

---

## 🛠️ 7. Troubleshooting & Tips

*   **GPU Idle Mode**: If the simulator feels "frozen," check if **Idle Mode** is enabled in the Dashboard. This throttles CARLA to ~0 FPS to save GPU for Shenron processing.
*   **Stop Flag**: If the simulation won't start, check for a `tmp/stop.flag` file and delete it.
*   **Environment Activation**: If `run.bat` fails to find `conda`, edit the script to point to your `activate.bat` location (usually in `C:\miniconda3\Scripts` or `C:\Users\<User>\miniconda3\Scripts`).
*   **Coordinate Systems**: Remember that CARLA uses a left-handed coordinate system (LHS), while Foxglove/ROS2 use right-handed (RHS). The MCAP converter handles this conversion automatically.

---

*Generated by Antigravity AI | Version 1.1 "Ares"*