Skip to content
BranchesTags

Repository files navigation

🛡️ SAFAR — Safety Assisting Forward-looking AI Reflex

SAFAR is a high-performance, physics-grounded Advanced Driver Assistance System (ADAS) and autonomous safety copilot engineered for realistic multi-simulator environments (Webots R2025a, Unreal Engine 5 Chaos Physics, and CARLA).

SAFAR combines deep-learning computer vision (YOLO11), machine-learning road surface classification, real-time kinematic physics, and an ultra-fast C++ reasoning core to prevent collisions, protect vehicle chassis integrity against severe road craters, and safeguard passenger comfort.

🌟 Core Operating Philosophy

  1. Passive Driver Principle (Human-Authoritative Control):
    • During ordinary driving, the human driver retains 100% authoritative control over throttle, steering, and braking.
    • SAFAR silently monitors the driving corridor, tracking obstacles, road anomalies, and kinematic stopping envelopes.
    • SAFAR intervenes only when a physical, multi-frame confirmed safety hazard leaves insufficient stopping margin.
  2. Decoupled Perception and Physical Reasoning:
    • Machine Learning answers strictly: "What object or road anomaly is this, and with what confidence?"
    • Kinematic and Spatial Geometry answer: "Does it intersect our tire tracks or chassis, and can we stop before impact?"
    • Vehicle actuation is never surrendered directly to raw ML probabilities.
  3. Failure-Safe Guarantee:
    • $\text{NO_DATA} \ne \text{DANGER}$.
    • $\text{LOW_CONFIDENCE} (< 70%) \ne \text{EMERGENCY_BRAKE}$.
    • Sensor dropouts, camera occlusion, or network lag default safely to PASSIVE MONITORING ($Brake = 0.0$), eliminating false phantom braking.

🔄 End-to-End System Architecture

                  WINDSHIELD CAMERA / STEREO RIG / SENSORS
                                     │
                                     ▼
        ┌────────────────────────────────────────────────────────┐
        │                 1. PERCEPTION PIPELINE                 │
        │  • Ultralytics YOLO11 Neural Network (Road Obstacles)  │
        │  • Pothole Surface ML Classifier (Gradient Boosting)   │
        │  • Virtual Stereo Depth & Disparity Estimation         │
        └────────────────────────────┬───────────────────────────┘
                                     │ Detections (Class, Confidence, Bounding Boxes)
                                     ▼
        ┌────────────────────────────────────────────────────────┐
        │            2. TRACKING & KINEMATIC PROJECTION          │
        │  • Pinhole Monocular Distance: Z = (fx * W) / w_px     │
        │  • Ego Corridor & Wheel-Track Geometry (|X| <= 1.65m)  │
        │  • Multi-Object Relative Velocity & Time-To-Collision  │
        └────────────────────────────┬───────────────────────────┘
                                     │ Spatial Intersections & Closing Dynamics
                                     ▼
        ┌────────────────────────────────────────────────────────┐
        │         3. PHYSICS & STOPPING ENVELOPE ENGINE          │
        │  • Dynamic Stopping Distance: d_stop = v*t + v²/(2μg)  │
        │  • SQLite Empirical Road Friction Conditioning (μ=0.82)│
        │  • Required Deceleration Calculation: a_req            │
        │  • Continuous Causal Risk Scoring: S_risk ∈ [0.0, 1.0] │
        └────────────────────────────┬───────────────────────────┘
                                     │ Threat Severity: SAFE | LOW | MED | HIGH | CRITICAL
                                     ▼
        ┌────────────────────────────────────────────────────────┐
        │          4. STATE MACHINE & SAFETY ARBITRATION         │
        │  • C++ Core & Python Decision Engines                  │
        │  • Anti-Jitter Temporal Filter (>= 2 frames)           │
        │  • Dual-Threshold Hysteresis (0.65 Activate / 0.40 Off)│
        │  • Automatic Transmission Reverse Gear Lockout         │
        └────────────────────────────┬───────────────────────────┘
                                     │ Actuation Command (PASSIVE vs GRADUATED INTERVENTION)
                                     ▼
                      CLOSED-LOOP VEHICLE ACTUATION
      ┌──────────────────────────────┬──────────────────────────────┐
      │  Webots BMW X5 Highway ADAS  │  Unreal Engine 5 Chaos Sim   │
      │  (Throttle, Brake, Reverse)  │  (Chaos Vehicle Movement)    │
      └──────────────────────────────┴──────────────────────────────┘

🎮 Current Simulation Capabilities

1. Webots R2025a Closed-Loop ADAS Highway Track (webots_sim/)

  • 1,000-Meter Highway Environment: 14.0-meter wide roadway featuring dual 3.5m lanes ($X = \pm 2.0\text{m}$) and 5.0m runoff shoulders bounded by W-beam barriers and ground safety collision planes.
  • 10 Multi-Class Procedural Potholes: Distributed along the 1km track:
    • Class 0 (Drivable Surface): Roughness depth $&lt; 1.2\text{cm}$ $\to$ Passive cruising ($80\text{ km/h}$).
    • Class 1 (Small Pothole): Depth $\sim 3.2\text{cm}$ $\to$ Advisory warning, gentle throttle ease ($40\text{ km/h}$).
    • Class 2 (Medium Pothole): Depth $\sim 4.6\text{cm}$ $\to$ Smooth progressive service brake ($55%$ to $22\text{ km/h}$).
    • Class 3 (Severe Crater): Depth $&gt; 7.5\text{cm}$ $\to$ Full AEB emergency stop ($100%$ lockup + hazard flashers), halting safely 4m before the rim.
  • 3D Concentric Crater Meshes: Rendered with outer distressed asphalt fracture rings ($1.15\times$ radius) and recessed inner dark cavity meshes.
  • Suspension Strike Feedback: Vehicle translation impulses simulate real chassis shock if the driver crosses severe craters at high speeds without braking.
  • Anti-Wedging & Agile Steering:
    • Removed vertical tripping curbs to eliminate tire wedging.
    • Microsecond timestamp opposite-key override logic allows instant snapping between [A] (left) and [D] (right) with zero deadband.
    • Progressive 4.2 rad/s slew rate with speed-sensitive steering lock ($0.42\text{ rad} \approx 24^\circ$ at low speeds, tapering to $0.22\text{ rad} \approx 12.6^\circ$ at highway speeds).
  • Lateral Bypass Resumption: When stopped before a crater, the driver steers into the clear lane and taps forward ([W]). Once the vehicle exits the pothole corridor laterally, SAFAR instantly drops the AEB lock and restores cruising power.
  • Highway Obstacle Vehicle: A 3D lead vehicle positioned at $Y = 95\text{m}$ ($X = 2.0\text{m}$) enables live demonstration of visual detection and collision avoidance alongside surface potholes.

2. Live Asynchronous YOLO11 Windshield Perception

  • Attached Front Windshield Camera: 640x480 resolution @ 30 FPS, pitched downward by $8.6^\circ$ ($0.15\text{ rad}$) for optimal road and vehicle visibility ($5\text{m} - 50\text{m}$).
  • Threaded Non-Blocking Queue: Isolates YOLO inference latency (~90ms on CPU) inside AsyncYOLOPerceptionThread, guaranteeing the vehicle control loop runs at a flawless 100 Hz.
  • Pinhole Monocular Distance Estimation: Calculates real metric distance ($Z$) and lateral offset ($X$) from bounding box width using optical focal length $f_x = 706.7\text{px}$.
  • Live OpenCV HUD Perception Stream:
    • Displays real-time color-coded bounding boxes around detected vehicles, pedestrians, trucks, and cyclists.
    • Highlights in RED if an obstacle intersects the vehicle's driving corridor ($|X| \le 1.65\text{m}$).
    • Projects upcoming road potholes onto the camera image plane with depth labels and distance tags.
    • Telemetry header displays live perception FPS, vehicle speed, steering angle, and active ADAS status.
  • Obstacle Collision Prevention: Automatically initiates service braking or emergency stops if a detected lead vehicle or pedestrian enters the stopping distance envelope.

3. Universal 100% Offline Asset Portability

  • Offline Asset Bundle (webots_sim/assets_cache.zip): Packages all 205 Webots PROTOs, 3D meshes, textures, and skybox HDRs (23.4 MB).
  • Automated Asset Pre-Cacher (setup_simulation_assets.py): Automatically detects the local OS Webots cache directory (Windows, Linux, macOS) and unzips all assets on first run. Webots never attempts external GitHub streaming, eliminating the "cannot load asset" error.
  • Universal Launchers:
    • launch_webots_safar.bat: Portable Windows launcher with dynamic Webots path auto-detection.
    • launch_sim.py: Cross-platform Python launcher for Windows, macOS, and Linux.

4. Unreal Engine 5 Chaos Simulation (ue_sim/)

  • Chaos Wheeled Movement Integration: Closed-loop testing on TrafficGame in an urban city environment with Chaos physics.
  • Reverse Gear Protection: Speed-gated service braking ($Speed &gt; 0.5\text{ m/s}$) and stationary handbrake hold ($Speed \le 0.5\text{ m/s}$) to prevent Chaos automatic transmission from slipping into reverse gear during forward braking.
  • Ambient Traffic Isolation: Filters out ambient AI traffic and ego-vehicle reflections, restricting SAFAR interventions exclusively to the player-controlled pawn.

⚙️ Core Technical Pipelines

1. Machine Learning Pipeline (core_safar_logic/pothole_system/)

  • Stratified Benchmark Comparison: Evaluated multiple architectures on pothole_dataset.csv:
    • Decision Trees: 97.0% Accuracy
    • Random Forest: 98.4% Accuracy
    • Extra Trees: 98.8% Accuracy
    • Gradient Boosting (Production): 99.0% Test Accuracy, 99.4% ± 0.8% 5-Fold Stratified CV, 100% Precision & 100% Recall on Severe Craters.
  • Calibrated Confidence Gating: Rejects uncertain detections ($P &lt; 0.70$) or corrupted physical inputs (NaN, negative dimensions) to eliminate phantom braking.
  • Model Serialization: Exported production pipeline via joblib into pothole_model.joblib.

2. High-Performance C++ Reasoning Core (core_safar_logic/c_core/)

  • Microsecond Execution Engine: Multi-threaded C++ safety core implementing:
    • Multi-Object Tracking: Relative velocity estimation and dead reckoning.
    • Trajectory & TTC Engine: Pinhole geometry, forward projection, and kinematic time-to-collision.
    • Threat Assessment: Dynamic stopping envelopes and multi-candidate risk prioritization.
    • Decision State Machine: Temporal confirmation and anti-jitter hold timers.
    • Watchdog Supervisor: 250ms background thread monitoring thread health and fail-safe fallback.
  • IPC Network Bridges:
    • TCP Perception Receiver on Port 9002.
    • UDP Vehicle Actuation Bridge on Port 9003 / 8888.

3. Kinematic Physics & Friction Engine

  • Dynamic Stopping Distance ($d_{\text{stop}}$): $$d_{\text{stop}} = \underbrace{v \cdot t_{\text{react}}}{\text{Reaction Distance}} + \underbrace{\frac{v^2}{2\mu g}}{\text{Braking Distance}} + \underbrace{d_{\text{buffer}}}{\text{Safety Margin}}$$ *(Parameters: $t{\text{react}} = 0.45\text{s}$, nominal $a = 6.0\text{ m/s}^2$, $d_{\text{buffer}} = 4.0\text{m}$)*.
  • SQLite Empirical Braking Database: Queries real stopping test records based on surface type (dry, wet, snow, gravel) and vehicle mass (2100 kg), estimating road friction $\mu = 0.82$.
  • Required Deceleration ($a_{\text{req}}$): $$a_{\text{req}} = \frac{v^2}{2(d_{\text{fwd}} - v \cdot t_{\text{react}} - d_{\text{buffer}})}$$ If $a_{\text{req}} &gt; 7.5\text{ m/s}^2$, nominal braking is insufficient and maximum emergency deceleration is engaged.
  • Wheel-Track Spatial Geometry:
    • Left Wheel Track: $[-0.925\text{m}, -0.675\text{m}]$ (Centered at $-0.80\text{m}$) $\to$ Risk Multiplier: $1.00$.
    • Right Wheel Track: $[+0.675\text{m}, +0.925\text{m}]$ (Centered at $+0.80\text{m}$) $\to$ Risk Multiplier: $1.00$.
    • Undercarriage: Passes between wheels; harmless if depth $&lt; 12\text{cm}$, critical if depth $&gt; 14\text{cm}$.

📁 Repository Structure

SAFAR/
├── core_safar_logic/
│   ├── c_core/                     # High-performance C++ real-time reasoning core
│   │   ├── src/                    # C++ modules (Tracking, Threat, Decision, Bridge)
│   │   ├── include/                # Header definitions
│   │   └── CMakeLists.txt          # CMake build configuration
│   ├── pothole_system/             # Python Pothole Safety Subsystem
│   │   ├── classifier.py           # ML inference with calibrated confidence
│   │   ├── physics.py              # Dynamic stopping distance & TTC kinematics
│   │   ├── path.py                 # Wheel-track and corridor spatial geometry
│   │   ├── risk.py                 # Continuous causal risk engine [0.0, 1.0]
│   │   ├── decision.py             # State machine with temporal stabilization
│   │   ├── speed_manager.py        # Graduated speed policies and arbitration
│   │   ├── model.py                # Model training & benchmarking suite
│   │   └── pothole_model.joblib    # Serialized Gradient Boosting model
│   └── python_perception/          # Computer Vision & Sensor Processing
│       ├── yolo_detector.py        # Ultralytics YOLO11 backend wrapper
│       ├── yolo_adapter.py         # Standardized perception adapter
│       ├── yolo11n.pt              # YOLO11 neural network weights (5.4 MB)
│       └── stereo_depth.py         # Virtual stereo depth & disparity maps
├── webots_sim/                     # Webots R2025a High-Fidelity Simulation
│   ├── worlds/
│   │   ├── safar_pothole_track.wbt # 14m highway world with 10 potholes + obstacle car
│   │   └── .safar_pothole_track.wbproj
│   ├── controllers/
│   │   └── safar_vehicle_controller/
│   │       ├── safar_vehicle_controller.py  # 100Hz debounced vehicle ADAS controller
│   │       └── yolo_vision_bridge.py        # Multi-threaded async YOLO vision bridge
│   ├── hazards.json                # Procedural hazard manifest (10 road anomalies)
│   └── assets_cache.zip            # 205-asset offline Webots cache bundle (23.4 MB)
├── ue_sim/                         # Unreal Engine 5 Chaos Vehicle Simulation
├── safar_test/                     # Verification test harnesses & benchmarks
│   ├── pothole_harness/            # Friction estimation, SQLite DB, and YOLO tests
│   └── unit_tests/                 # Deterministic scenario tests
├── Devlogs/                        # Project development logs (Day 1 - Day 6)
├── setup_simulation_assets.py      # Automated offline asset extractor & validator
├── launch_webots_safar.bat         # Portable Windows simulation launcher
├── launch_sim.py                   # Universal cross-platform simulation launcher
├── generate_random_track.py        # Procedural 1000m track generator
├── requirements.txt                # Python dependencies
└── README.md                       # Master Documentation

🚀 Quickstart & How to Run

1. Clone & Install Dependencies

git clone https://github.com/SenorDan031/SAFAR.git
cd SAFAR

# Install required Python packages
pip install -r requirements.txt

2. Pre-Cache Simulation Assets (Offline Setup)

Extracts all 205 Webots PROTOs and textures into your local cache so Webots never needs internet:

python setup_simulation_assets.py

3. Launch the Simulation

  • Windows (Direct Batch Launcher): 
    launch_webots_safar.bat
  • Any OS (Windows / macOS / Linux): 
    python launch_sim.py

Driving Controls:

  • [W] / [UP ARROW]: Drive Forward / Accelerate
  • [S] / [DOWN ARROW]: Firm Service Brake (shifts into Reverse when stopped)
  • [A] / [LEFT ARROW]: Steer Left (immediate opposite-key override)
  • [D] / [RIGHT ARROW]: Steer Right (immediate opposite-key override)
  • [C]: Instant Center Steering Wheel
  • [SPACEBAR]: Emergency Handbrake Lockup
  • [R]: Instant Vehicle Reset to Start Line

4. Interactive Standalone CLI Pothole Analysis

Evaluate any vehicle speed and pothole geometry directly from the command line:

# Syntax: python -m safar.pothole.main <speed_mps> <distance_m> <width_m> <length_m> <depth_m> [lateral_m]
python -m safar.pothole.main 20.0 35.0 0.70 1.40 0.06 0.0

5. Run Deterministic Pothole Benchmark Suite (12 Scenarios)

python -m safar.pothole.test_scenarios

🔮 Future Roadmap & Integrations

  ┌────────────────────────┐      ┌────────────────────────┐      ┌────────────────────────┐
  │        PHASE 1         │      │        PHASE 2         │      │        PHASE 3         │
  │ Real-Time Vision & CV  │ ──►  │ Active Evasive Steering│ ──►  │ Indian Road Conditions │
  │ YOLO11 + Windshield HUD│      │ Collision-Free Swerve  │      │ Cattle, Auto-Rickshaws │
  │  (✅ Implemented)      │      │ Adjacent Lane Analysis │      │ Unmarked Speed Breakers│
  └────────────────────────┘      └────────────────────────┘      └────────────────────────┘
                                                                               │
                                                                               ▼
  ┌────────────────────────┐      ┌────────────────────────┐      ┌────────────────────────┐
  │        PHASE 6         │      │        PHASE 5         │      │        PHASE 4         │
  │ Physical Testbed       │ ◄──  │ Automotive Embedded    │ ◄──  │ Multi-Sensor Fusion    │
  │ Drive-by-Wire Car Test │      │ Jetson Orin + CAN Bus  │      │ Camera + LiDAR + Radar │
  │ Closed-Loop Track Test │      │ ROS 2 Humble + AUTOSAR │      │ Extended Kalman Filter │
  └────────────────────────┘      └────────────────────────┘      └────────────────────────┘

🔹 Phase 2: Active Evasive Steering Assistance (AES)

  • When $d_{\text{stop}} &gt; d_{\text{forward}}$ and braking alone cannot prevent impact, calculate collision-free adjacent lane escape trajectories.
  • Execute smooth, torque-limited steering intervention if adjacent lanes are verified clear of obstacles.

🔹 Phase 3: Indian Road & Complex Traffic Specializations

  • Specialized detection models trained on unstructured traffic: auto-rickshaws, lane-splitting two-wheelers, stray cattle, unmarked speed humps, and unpaved road shoulders.

🔹 Phase 4: Multi-Sensor Extended Kalman Filter Fusion

  • Fuse front cameras with solid-state LiDAR point clouds and millimeter-wave (mmWave) radar vectors for all-weather robustness across dense fog, heavy rain, dust, and glare.

🔹 Phase 5: Automotive Embedded Deployment (ECU & CAN Bus)

  • Compile the C++ core (core_safar_logic/c_core) with TensorRT model acceleration onto automotive hardware (NVIDIA Jetson AGX Orin and NXP S32G Automotive Processors).
  • Integrate standard automotive communications: CAN Bus (J1939 / CAN-FD), AUTOSAR Adaptive Platform, and ROS 2 Humble.

🔹 Phase 6: Physical Vehicle Testbed

  • Deploy the SAFAR safety stack onto a physical drive-by-wire electric vehicle for proving-ground track testing.

👥 Team Members

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

About

Making roads smarter with AI-powered assisted driving, SAFAR. SAFAR detects hazards, understands road conditions, and guides drivers through safer, faster routes.

Resources

Readme
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages