diff --git a/README.md b/README.md new file mode 100644 index 0000000..8eb25fe --- /dev/null +++ b/README.md @@ -0,0 +1,110 @@ +# 🦊 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 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. +* **`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\\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"* diff --git a/environment.yml b/environment.yml new file mode 100644 index 0000000..3cebb2b --- /dev/null +++ b/environment.yml @@ -0,0 +1,39 @@ +name: carla312 +channels: + - pytorch + - nvidia + - conda-forge + - defaults +dependencies: + - python=3.12 + - pip + - pip: + - numpy==2.4.3 + - opencv-python==4.13.0.92 + - scipy==1.17.1 + - pandas==3.0.2 + - pillow==12.1.1 + - tqdm==4.67.3 + - pygame==2.6.1 + - matplotlib==3.10.8 + - plotly==6.6.0 + - open3d==0.19.0 + - pyntcloud==0.3.1 + - Flask==3.1.3 + - Werkzeug==3.1.7 + - itsdangerous==2.2.0 + - Jinja2==3.1.6 + - click==8.3.1 + - blinker==1.9.0 + - torch==2.5.1 + - torchvision==0.20.1 + - torchaudio==2.5.1 + - PyYAML==6.0.3 + - mcap==1.3.1 + - mcap-ros2-support==0.5.7 + - lz4==4.4.5 + - zstandard==0.25.0 + - psutil==7.2.2 + - nvidia-ml-py==13.595.45 + - requests==2.33.1 + - certifi==2026.2.25 diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..853acf8 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,40 @@ +# Core Simulation & Data Processing +numpy==2.4.3 +opencv-python==4.13.0.92 +scipy==1.17.1 +pandas==3.0.2 +pillow==12.1.1 +tqdm==4.67.3 +pygame==2.6.1 + +# Visualization & Heatmaps +matplotlib==3.10.8 +plotly==6.6.0 +open3d==0.19.0 +pyntcloud==0.3.1 + +# Dashboards & GUI +Flask==3.1.3 +Werkzeug==3.1.7 +itsdangerous==2.2.0 +Jinja2==3.1.6 +click==8.3.1 +blinker==1.9.0 + +# Radar Synthesis (Shenron) +torch==2.5.1 +torchvision==0.20.1 +torchaudio==2.5.1 +PyYAML==6.0.3 + +# Foxglove & MCAP Serialization +mcap==1.3.1 +mcap-ros2-support==0.5.7 +lz4==4.4.5 +zstandard==0.25.0 + +# System Utilities +psutil==7.2.2 +nvidia-ml-py==13.595.45 +requests==2.33.1 +certifi==2026.2.25 diff --git a/scratch/full_requirements.txt b/scratch/full_requirements.txt new file mode 100644 index 0000000..c7db5ac --- /dev/null +++ b/scratch/full_requirements.txt @@ -0,0 +1,87 @@ +asttokens==3.0.1 +attrs==26.1.0 +blinker==1.9.0 +carla @ file:///D:/CARLA/CARLA_0.9.16/PythonAPI/carla/dist/carla-0.9.16-cp312-cp312-win_amd64.whl#sha256=b4700a1cfff8a9bda1018a233b25045ce6e00a7b180b8bd0edea6366c3f7c9eb +certifi==2026.2.25 +charset-normalizer==3.4.6 +click==8.3.1 +colorama==0.4.6 +comm==0.2.3 +ConfigArgParse==1.7.5 +contourpy==1.3.3 +cycler==0.12.1 +dash==4.1.0 +decorator==5.2.1 +executing==2.2.1 +fastjsonschema==2.21.2 +filelock==3.25.2 +Flask==3.1.3 +fonttools==4.62.1 +fsspec==2026.3.0 +idna==3.11 +importlib_metadata==9.0.0 +ipython==9.12.0 +ipython_pygments_lexers==1.1.1 +ipywidgets==8.1.8 +itsdangerous==2.2.0 +jedi==0.19.2 +Jinja2==3.1.6 +jsonschema==4.26.0 +jsonschema-specifications==2025.9.1 +jupyter_core==5.9.1 +jupyterlab_widgets==3.0.16 +kiwisolver==1.5.0 +lz4==4.4.5 +MarkupSafe==3.0.3 +mat4py==0.6.0 +matplotlib==3.10.8 +matplotlib-inline==0.2.1 +mcap==1.3.1 +mcap-ros2-support==0.5.7 +mpmath==1.3.0 +narwhals==2.18.1 +nbformat==5.10.4 +nest-asyncio==1.6.0 +networkx==3.6.1 +numpy==2.4.3 +nvidia-ml-py==13.595.45 +open3d==0.19.0 +opencv-python==4.13.0.92 +packaging @ file:///C:/miniconda3/conda-bld/packaging_1761049137378/work +pandas==3.0.2 +parso==0.8.6 +pillow==12.1.1 +platformdirs==4.9.4 +plotly==6.6.0 +prompt_toolkit==3.0.52 +psutil==7.2.2 +pure_eval==0.2.3 +pygame==2.6.1 +Pygments==2.20.0 +pyntcloud==0.3.1 +pyparsing==3.3.2 +python-dateutil==2.9.0.post0 +PyYAML==6.0.3 +referencing==0.37.0 +requests==2.33.1 +retrying==1.4.2 +rpds-py==0.30.0 +scipy==1.17.1 +setuptools==80.10.2 +six==1.17.0 +stack-data==0.6.3 +sympy==1.13.1 +torch==2.5.1+cu121 +torchaudio==2.5.1+cu121 +torchvision==0.20.1+cu121 +tqdm==4.67.3 +traitlets==5.14.3 +typing_extensions==4.15.0 +tzdata==2025.3 +urllib3==2.6.3 +wcwidth==0.6.0 +Werkzeug==3.1.7 +wheel==0.46.3 +widgetsnbextension==4.0.15 +zipp==3.23.0 +zstandard==0.25.0