irn-engine 0.1.0__tar.gz

irn_engine-0.1.0/PKG-INFO

@@ -0,0 +1,375 @@
+Metadata-Version: 2.4
+Name: irn-engine
+Version: 0.1.0
+Summary: Automated Road Network Modeling Engine for Lane-Free Indian Traffic Simulations
+Author-email: Yash Pouranik <yash@example.com>, Yashika Goswami <yashika@example.com>, Vipul Yadav <vipul@example.com>, Vivek Tekwani <vivek@example.com>
+License: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pandas>=2.0
+Requires-Dist: pyarrow>=14.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: shapely>=2.0
+Requires-Dist: pyproj>=3.5
+Requires-Dist: typer>=0.9.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: geo
+Requires-Dist: geopandas>=0.14; extra == "geo"
+Requires-Dist: osmnx>=2.0; extra == "geo"
+Provides-Extra: cv
+Requires-Dist: opencv-python-headless>=4.8; extra == "cv"
+Requires-Dist: ultralytics>=8.0; extra == "cv"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: lxml>=4.9; extra == "dev"
+
+# IRN Engine (`irn`)
+### Automated Road Network Modeling Engine for Lane-Free Indian Traffic Simulations
+
+[![Python Version](https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13-blue.svg)](https://www.python.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Traffic Convention](https://img.shields.io/badge/Traffic-Left--Hand%20(LHT)-green.svg)]()
+[![Standards](https://img.shields.io/badge/Standards-OpenDRIVE%20%7C%20SUMO%20Sublane-orange.svg)]()
+[![Institution](https://img.shields.io/badge/Institution-SVIIT%20Indore-red.svg)]()
+
+> **B.Tech CSE Major Project (2026–27)**  
+> **Department of Computer Science & Engineering**  
+> **Shri Vaishnav Institute of Information Technology (SVIIT), SVVV, Indore**
+
+---
+
+## 1. Overview & Problem Statement
+
+Standard microscopic traffic simulators (Eclipse SUMO, CARLA) and autonomous driving models inherently assume **lane-disciplined, homogeneous traffic** operating on uniformly marked roads.
+
+Indian urban traffic fundamentally breaks these assumptions:
+- **Heterogeneous Traffic Mix:** Roads are shared by two-wheelers, auto-rickshaws, cars, commercial buses, trucks, cycle rickshaws, pedestrians, and stray animals.
+- **Lane-Free Lateral Dynamics:** Vehicles navigate opportunistically without following painted lane boundaries, packing tightly into lateral gaps.
+- **Unmapped Physical Anomalies:** Potholes, unstandardized speed breakers, barricades, and parked vehicle obstructions actively constrain vehicle trajectories and speed profiles.
+
+**IRN Engine** is a high-performance Python data pipeline that bridges this gap. It ingests static road networks from **OpenStreetMap (OSM)**, fuses localized obstacle detections from the **IIIT-Hyderabad Indian Driving Dataset (IDD Multimodal)** using rigorous mathematical geospatial fusion, and compiles simulation-ready networks for **Eclipse SUMO (Sublane Model)** and **ASAM OpenDRIVE (`.xodr`)**.
+
+---
+
+## 2. Pipeline Architecture
+
+The engine is structured around four decoupled modules communicating strictly via validated **Data Contracts**:
+
+```mermaid
+flowchart TD
+    OSM[OpenStreetMap Overpass API] -->|BBox / Place Query| M1[M1: Map Fetcher\nOSMnx + UTM Projection]
+    M1 -->|Contract D1| D1[(D1: edges.gpkg\nnodes.gpkg\nosm_snapshot.json)]
+
+    IDD[IDD Video Frames & GPS] -->|Calibrated Rig| M2[M2: CV Layer\nYOLOv8 + ByteTrack]
+    M2 -->|Contract D2| D2[(D2: detections.parquet)]
+
+    D1 --> M3[M3: Geospatial Data Fusion\nRay Cast + HMM Viterbi + Mahalanobis]
+    D2 --> M3
+    GPS[Vehicle GPS CSV] --> M3
+    RIG[configs/rig.yaml] --> M3
+
+    M3 -->|Contract D3| D3[(D3: anomalies.db SQLite)]
+    M3 -->|Contract D4| D4[(D4: enriched_edges.parquet\nanomalies.parquet)]
+
+    D4 --> M4[M4: Simulation Compiler\nPlain-XML + netconvert + OpenDRIVE]
+    M4 --> OUT[Simulation Scenario Bundle\n- network.net.xml LHT\n- network.xodr 1.6.1\n- vtypes.add.xml Sublane\n- anomalies.add.xml\n- scenario.sumocfg\n- preview.geojson]
+```
+
+### Module Breakdown & Team Ownership
+
+| Module | Lead | Responsibilities & Scope | Tech Stack |
+| :--- | :--- | :--- | :--- |
+| **M1: Map Fetcher** | **Yashika Goswami** | OSM acquisition via BBox/place query, rate-limit backoff, attribute normalization (lanes, speed, width), UTM projection, zero-length pruning, Contract D1 export. | `osmnx >= 2.0`, `geopandas`, `shapely`, `pyproj` |
+| **M2: CV Layer** | **Vipul Yadav** | IDD Multimodal dataset ingestion, YOLOv8 inference for Indian road obstacles/agents, ByteTrack tracking, bottom-center ground contact projection, Contract D2 Parquet export. | `ultralytics`, `pyarrow`, `pydantic`, `opencv-python` |
+| **M3: Geospatial Fusion** | **Yash Pouranik** *(Core)* | Ground-plane ray intersection ($z = -h$), temporal GPS sync, cKDTree candidate filtering, HMM Viterbi map matching, relative linear referencing $(s, t)$, 2-level Mahalanobis de-duplication. | `numpy`, `scipy`, `shapely 2.0`, `pyproj`, `sqlite3` |
+| **M4: Simulation Compiler** | **Vivek Tekwani** | SUMO Plain-XML generation (`.nod.xml`, `.edg.xml`), `netconvert` compilation with `--lefthand=true`, Indian vehicle types with arbitrary lateral alignment, ASAM OpenDRIVE 1.6.1 `.xodr` generation. | `lxml`, `sumo-tools`, Eclipse SUMO `>= 1.18` |
+
+---
+
+## 3. Data Contracts
+
+All modules communicate strictly through validated, versioned disk artifacts:
+
+| Contract | Path | Format | Description |
+| :--- | :--- | :--- | :--- |
+| **D1: Road Graph** | `data/d1_graph/` | GeoPackage (`.gpkg`) + JSON | Cleaned drivable road network (`edges.gpkg`, `nodes.gpkg`, `osm_snapshot.json`) with WGS84 coordinates and local UTM projections. |
+| **D2: CV Detections** | `data/d2_detections/` | Apache Parquet (`.parquet`) | Structured obstacle detections (`sequence_id`, `frame_idx`, `frame_ts`, `class_name`, `conf`, `u`, `v`, `track_id`). |
+| **D3: Anomaly Ledger** | `data/d3_store/` | SQLite (`anomalies.db`) | Append-only observation log and canonical anomaly lifecycle tracker (`CANDIDATE` $\to$ `CONFIRMED` $\to$ `RESOLVED`). |
+| **D4: Enriched Graph** | `data/d4_enriched/` | Apache Parquet | `enriched_edges.parquet` and `anomalies.parquet` with linear referencing offsets $(s, t)$ and lateral positioning. |
+| **Output Scenario** | `output_scenario/` | XML + XODR + GeoJSON | SUMO `.net.xml`, `.xodr`, `.sumocfg`, vehicle profiles (`vtypes.add.xml`), obstacle zones (`anomalies.add.xml`), and `preview.geojson`. |
+
+---
+
+## 4. Getting Started & Setup Guide
+
+### 4.1 Prerequisites
+
+- **Python:** 3.10, 3.11, 3.12, or 3.13
+- **Operating System:** Windows 10/11, Ubuntu 20.04+, or macOS
+- **Optional Tools:**
+  - [Eclipse SUMO](https://eclipse.dev/sumo/) ($\ge 1.18$) for running microscopic simulations and SUMO-GUI.
+  - [QGIS](https://qgis.org/) for visualizing generated GeoPackages and GeoJSON layers.
+
+---
+
+### 4.2 Clone & Environment Setup
+
+#### Option A: Windows (PowerShell)
+```powershell
+# 1. Clone repository
+git clone https://github.com/yash-pouranik/irn-engine.git
+cd irn-engine
+
+# 2. Create virtual environment
+python -m venv .venv
+
+# 3. Activate virtual environment
+.venv\Scripts\Activate.ps1
+
+# 4. Upgrade pip & build tools
+python -m pip install --upgrade pip setuptools wheel
+```
+
+> **Note (PowerShell Execution Policy):** If script activation fails with an execution policy error, run:
+> ```powershell
+> Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
+> ```
+
+#### Option B: Linux / macOS (Bash / Zsh)
+```bash
+# 1. Clone repository
+git clone https://github.com/yash-pouranik/irn-engine.git
+cd irn-engine
+
+# 2. Create virtual environment
+python3 -m venv .venv
+
+# 3. Activate virtual environment
+source .venv/bin/activate
+
+# 4. Upgrade pip & build tools
+pip install --upgrade pip setuptools wheel
+```
+
+---
+
+### 4.3 Install Dependencies
+
+Install the core pipeline in editable mode:
+
+```bash
+# Install core pipeline
+pip install -e .
+
+# Install optional geospatial, CV, and development tools
+pip install -e ".[geo,cv,dev]"
+```
+
+Verify your installation:
+```bash
+irn info
+# Or run as a module:
+python -m irn.cli info
+```
+
+Expected output:
+```text
+=================================================================
+IRN: Road Network Modeling Engine (SVIIT Indore Major Project)
+=================================================================
+OSMnx Version:    2.1.1
+Shapely Version:  2.2.0
+PyArrow Version:  25.0.1
+Traffic Rule:     Strict Left-Hand Traffic (LHT)
+Coordinate Grid:  WGS84 Storage (EPSG:4326) / Local Projected UTM
+=================================================================
+```
+
+---
+
+## 5. Usage & CLI Workflow
+
+The pipeline is controlled via the `irn` command-line interface.
+
+### 5.1 Generate Synthetic Ground Truth World
+To verify mathematical formulas without downloading external maps or videos, generate the synthetic test world:
+```bash
+irn synth --out data/synthetic --length 150.0
+```
+This generates:
+- `data/synthetic/d1_graph/edges.gpkg` (Synthetic dual-carriageway road)
+- `data/synthetic/d1_graph/nodes.gpkg`
+- `data/synthetic/d2_data/detections.parquet` (Planted potholes & speed breakers)
+- `data/synthetic/d2_data/gps_trajectory.csv` (Simulated vehicle trajectory)
+
+---
+
+### 5.2 Fetch Road Graph from OpenStreetMap (Module 1)
+
+#### Option 1: Live Download via Bounding Box
+Fetches drivable network, projects to the optimal local UTM zone, parses Indian road attributes, and exports Contract D1:
+```bash
+# Example: IIIT-Hyderabad / Gachibowli Corridor (west, south, east, north)
+irn fetch --bbox "78.3400,17.4350,78.3650,17.4550" --out data/d1_graph
+```
+
+#### Option 2: Live Download via Place Name
+```bash
+irn fetch --place "Gachibowli, Hyderabad, India" --out data/d1_graph
+```
+
+#### Option 3: Offline Mode (No Internet Required)
+Generates a calibrated geometric grid for testing without calling the Overpass API:
+```bash
+irn fetch --offline --out data/d1_graph
+```
+
+---
+
+### 5.3 Generate / Ingest Obstacle Detections (Module 2)
+Generate schema-validated detections in Apache Parquet format:
+```bash
+irn detect --seq seq_demo_01 --frames 120 --out data/d2_detections/detections.parquet
+```
+
+---
+
+### 5.4 Execute Geospatial Data Fusion (Module 3)
+Execute 3D ground-plane ray projection, GPS alignment, HMM Viterbi map matching, relative linear referencing $(s, t)$, and Mahalanobis de-duplication:
+```bash
+irn fuse --graph data/synthetic/d1_graph/edges.gpkg --detections data/synthetic/d2_data/detections.parquet --gps data/synthetic/d2_data/gps.csv
+```
+
+---
+
+### 5.5 Compile Simulation Scenario (Module 4)
+Compile enriched road network into Eclipse SUMO (Sublane model) and ASAM OpenDRIVE 1.6.1:
+```bash
+irn compile --enriched data/d4_enriched/enriched_edges.parquet --anomalies data/d4_enriched/anomalies.parquet --nodes data/synthetic/d1_graph/nodes.gpkg --out output_scenario
+```
+
+---
+
+### 5.6 CLI Command Reference
+
+| Command | Arguments / Flags | Description |
+| :--- | :--- | :--- |
+| `irn info` | None | Displays engine versions, active CRS projection, and convention flags. |
+| `irn fetch` | `--bbox <W,S,E,N>`<br>`--place <STR>`<br>`--out <DIR>`<br>`--timeout <SEC>`<br>`--offline` | Ingests drivable OSM network, cleans attributes, normalizes lanes/widths, and saves D1 GeoPackage. |
+| `irn detect` | `--seq <NAME>`<br>`--frames <INT>`<br>`--out <FILE>` | Runs detection pipeline / mock generator and writes Contract D2 Parquet. |
+| `irn synth` | `--out <DIR>`<br>`--length <METERS>` | Builds a mathematically controlled ground-truth corridor for unit/regression testing. |
+| `irn fuse` | `--graph <PATH>`<br>`--detections <PATH>`<br>`--gps <PATH>`<br>`--rig <PATH>` | Executes M3 Ray casting, HMM map matching, and multi-pass anomaly clustering. |
+| `irn compile` | `--enriched <PATH>`<br>`--anomalies <PATH>`<br>`--nodes <PATH>`<br>`--out <DIR>` | Compiles Plain-XML $\to$ SUMO `.net.xml` and ASAM OpenDRIVE `.xodr` scenario. |
+
+---
+
+## 6. Configuration Management
+
+Zero magic numbers are permitted in the codebase. All operational parameters are maintained in `configs/`:
+
+### `configs/run_config.yaml`
+- **Traffic Conventions:** Left-Hand Traffic (`LHT`).
+- **M1 Fetcher:** Target Bounding Box, Overpass timeout, user-agent.
+- **M2 CV:** Confidence thresholds ($0.25$ candidate extraction), class taxonomy.
+- **M3 Fusion:** GPS max temporal delta ($dt \le 0.2\,\text{s}$), HMM search radius ($35\,\text{m}$), HMM bearing angle gate ($100^\circ$), Mahalanobis Chi-square gate ($\chi^2 = 9.21, p=0.01$).
+- **M4 Compiler:** `lanefree_mode: "collapse"`, sublane lateral resolution ($0.6\,\text{m}$), step length ($0.1\,\text{s}$).
+
+### `configs/rig.yaml`
+- **Camera Intrinsics:** $f_x, f_y, c_x, c_y$ calibrated for IDD front-facing camera.
+- **Extrinsics & Mounting:** Camera height $h = 1.5\,\text{m}$, downward pitch $\theta = -2.5^\circ$, roll/yaw offsets.
+- **Processing Gates:** Ground range gate $[4.0\,\text{m}, 30.0\,\text{m}]$, ray projection covariance gates.
+
+---
+
+## 7. Running Tests
+
+Run the complete test suite with `pytest`:
+
+```bash
+# Run all tests
+pytest
+
+# Run tests with verbose output
+pytest -v
+
+# Run tests with execution timing
+pytest -v --durations=5
+```
+
+### What is Tested:
+1. **Rule G-1 (Coordinate Round-Trip Precision):** Asserts sub-millimeter conversion accuracy between WGS84 (`EPSG:4326`) and local UTM projections (Zone 43N/44N).
+2. **M1 Attribute Cleaner:** Asserts parsing of non-standard OSM tags (`lanes`, `maxspeed`, `width`) and zero-length edge pruning.
+3. **M2 Schema & Ground Contact:** Asserts bottom-center $(u, v)$ calculation and Parquet round-trip serialization.
+4. **Synthetic World Fixture:** Validates deterministic graph generation and planted anomaly recovery.
+
+---
+
+## 8. Repository Structure
+
+```text
+irn-engine/
+├── configs/                       # Configuration parameters (zero magic numbers)
+│   ├── rig.yaml                   # Camera intrinsics, mounting height, pitch, range gates
+│   └── run_config.yaml            # Pipeline run config, thresholds, and SUMO sublane parameters
+├── data/                          # Runtime data artifacts (git-ignored except sample fixtures)
+│   ├── d1_graph/                  # Contract D1: edges.gpkg, nodes.gpkg, osm_snapshot.json
+│   ├── d2_detections/             # Contract D2: detections.parquet
+│   └── synthetic/                 # Synthetic ground truth fixtures
+├── irn/                           # Core Engine Python Package
+│   ├── cli.py                     # Typer CLI application entry point
+│   ├── common/                    # Shared coordinate transformations, I/O, logging
+│   │   ├── crs.py                 # Vectorized WGS84 <-> UTM projections
+│   │   ├── io.py                  # Atomic file writing & SHA-256 hashing
+│   │   └── logger.py              # Structured logging with reason codes
+│   ├── m1_fetcher/                # Module 1: OpenStreetMap Ingestion (Yashika)
+│   │   ├── cleaner.py             # Tag normalization & graph topology cleaning
+│   │   └── osm_fetcher.py         # OSMnx network download with backoff & caching
+│   ├── m2_cv_interface/           # Module 2: Computer Vision Interface (Vipul)
+│   │   ├── detector.py            # YOLOv8 inference & mock generator
+│   │   ├── idd_adapter.py         # IDD Multimodal dataset loader
+│   │   └── schema.py              # Pydantic schema & PyArrow Parquet writer
+│   ├── m3_fusion/                 # Module 3: Geospatial Data Fusion (Yash)
+│   └── m4_compiler/               # Module 4: Simulation Compiler (Vivek)
+├── tests/                         # Automated Test Suite (QA Agent)
+│   ├── fixtures/
+│   │   └── synthetic_world.py     # Ground-truth mathematical test corridor
+│   └── test_m1_m2_core.py         # Core CRS, cleaner, schema, and synthetic tests
+├── AGENTS.md                      # Multi-Agent Operational Framework & Guardrails
+├── PLAN.md                        # Master Phased Engineering Plan
+├── pyproject.toml                 # Package configuration & dependencies
+└── README.md                      # Project documentation & setup instructions
+```
+
+---
+
+## 9. Engineering Constraints & Rules
+
+1. **Rule G-1 (Coordinate Systems):** Stored geometries are always WGS84 (`EPSG:4326`). All distance, ray-casting, and metric computations use the local UTM projection calculated from the area centroid.
+2. **Rule G-2 (Traffic Convention):** Strict Left-Hand Traffic (LHT). OpenDRIVE roads declare `rule="LHT"` and SUMO `netconvert` runs with `--lefthand=true`.
+3. **Rule G-3 (Vectorization):** Hot paths use `numpy`, `scipy`, `shapely 2.0`, and `pyarrow`. No Python `for` loops over large detection batches.
+4. **Rule G-4 (File Decoupling):** Modules do not call each other's internal functions across module boundaries. Communication occurs strictly via Data Contracts (D1, D2, D3, D4).
+5. **Rule G-6 (SUMO Construction):** SUMO internal edges are never written by hand. Plain-XML files (`.nod.xml`, `.edg.xml`, `.con.xml`) are compiled via `netconvert`.
+
+---
+
+## 10. Contributors & Major Project Team
+
+**Department of Computer Science & Engineering**  
+**Shri Vaishnav Institute of Information Technology (SVIIT), Indore**  
+*B.Tech CSE Major Project (2026–27)*
+
+- **Yash Pouranik** — *Team Lead & Algorithmic Owner (Module 3: Geospatial Fusion)*
+- **Yashika Goswami** — *Geospatial Data Engineer (Module 1: Map Fetcher)*
+- **Vipul Yadav** — *Computer Vision Engineer (Module 2: CV Layer)*
+- **Vivek Tekwani** — *Simulation & Standards Engineer (Module 4: Simulation Compiler)*
+
+---
+
+## 11. License & Acknowledgements
+
+- **License:** MIT License. See [LICENSE](LICENSE) for details.
+- **Data Attribution:**
+  - Road network geometries © [OpenStreetMap contributors](https://www.openstreetmap.org/copyright) (ODbL).
+  - Indian Driving Dataset courtesy of [IIIT-Hyderabad CVIT / IDD Multimodal](https://idd.insaan.iiit.ac.in/).