Skip to content
BranchesTags

Repository files navigation

🚖 Intelligent CARLA Taxi Dispatch System

An advanced autonomous taxi dispatch and ETA prediction system built on CARLA simulator, featuring intelligent route planning, real-time fleet management, and machine learning-based ETA prediction.

🎯 Key Features

  • Intelligent Route Planning: Multi-route generation with diversity-based selection using advanced algorithms
  • ETA Prediction: Ensemble ML model (XGBoost + Random Forest) for accurate travel time estimation
  • Fleet Management: Real-time taxi tracking and optimal assignment with distance analysis
  • Concurrent Operations: Multi-threaded system supporting simultaneous taxi operations
  • Traffic Simulation: Realistic traffic conditions with moving vehicles and dynamic weather conditions
  • Comprehensive Logging: Detailed ride analytics and prediction accuracy tracking with JSON serialization
  • Training Data Generation: Automated collection of route features and actual drive times
  • Dispatcher: Assignment logic and coordination with auto-assignment every 2 seconds
  • Graph Construction: Road network graph construction with lane change support and edge removal strategies

📋 System Requirements

CARLA Simulator

  • Version: CARLA 0.9.11
  • Platform: Windows

Python Environment

  • Python: 3.7
  • Architecture: 64-bit

Required Python Packages

Core Dependencies

pip install carla==0.9.11
pip install networkx>=2.6
pip install numpy>=1.21.0
pip install scikit-learn>=1.0.0
pip install pandas>=1.3.0
pip install xgboost>=1.5.0
pip install joblib>=1.1.0

Built-in Python Modules (No Installation Required)

  • json - JSON data handling
  • time - Time operations and measurements
  • os - Operating system interface
  • datetime - Date and time handling
  • sys - System-specific parameters
  • math - Mathematical functions
  • typing - Type hints
  • uuid - UUID generation
  • queue - Thread-safe queues
  • enum - Enumeration support
  • random - Random number generation
  • threading - Multi-threading support
  • glob - File pattern matching
  • warnings - Warning control

Hardware Requirements

Please see CARLA documentation for hardware requirements.

🚀 Installation & Setup

1. CARLA Setup

  1. Download CARLA 0.9.11 from CARLA Releases
  2. Follow steps in CARLA Documentation to install CARLA python API

2. Python Environment

# Create virtual environment (recommended)
python -m venv carla_taxi_env

# Activate environment
carla_taxi_env\Scripts\activate     # Windows
# or
source carla_taxi_env/bin/activate  # Linux/Mac

# Install all dependencies
pip install networkx numpy scikit-learn pandas xgboost joblib

3. Project Setup

  1. Extract/clone the project files
  2. Update CARLA path in all Python files that contain: 
    sys.path.append(r"C:\Users\eliav\Desktop\Uni\Workshop\CARLA_0.9.11\WindowsNoEditor\PythonAPI\carla")
    Replace with your path: 
    sys.path.append(r"C:\YOUR_PATH\CARLA_0.9.11\WindowsNoEditor\PythonAPI\carla")
  3. Ensure CARLA server is running before starting the system
  4. Navigate to the project directory in terminal/command prompt
  5. Make sure virtual environment is activated/all dependencies are installed and accessible by running: 
    pip list

🏗️ Project Architecture

Core Components

main.py - Main System Controller

  • TaxiService: Main orchestrator class with concurrent menu and operation management
  • Concurrent Operations: Multi-threaded menu and taxi management with real-time command processing
  • Auto-Assignment: Intelligent ride-to-taxi matching every 2 seconds with enhanced selection analysis
  • Logger Integration: Performance tracking and analytics with JSON serialization fixes
  • Route Optimization: Eliminates triple route generation through pre-calculation and reuse

config.py - World Configuration

  • WorldConfig: CARLA world setup and management with traffic spawning
  • Weather Control: Dynamic weather conditions (7 different weather types)
  • Traffic Spawning: Realistic traffic vehicle generation with autopilot and movement verification
  • Vehicle Management: Automatic cleanup of stationary vehicles and traffic optimization
  • Moving Vehicle Check: Monitors and removes non-moving traffic vehicles after spawn

Taxi System Management (taxi_system/)

  • fleet_manager.py: Enhanced taxi fleet tracking with detailed selection analysis showing all taxi distances
  • ride_manager.py: Ride request processing with diverse route planning and feature extraction
  • dispatcher.py: Assignment logic with auto-assignment, quiet operation, and efficiency metrics

Route Planning & Analysis

  • graph_builder.py: Road network graph construction with lane change support and edge metadata
  • route_gen.py: Advanced diverse route generation with multiple strategies:
    • Edge Removal Strategy: Systematic removal of route segments to force alternatives
    • Random Pattern Generation: Multiple seed-based random edge removal
    • Waypoint Strategy: Intermediate waypoint routing for maximum diversity
    • Diversity Filtering: 20% minimum difference requirement between routes
  • feature_extractor.py: Comprehensive route feature extraction (25+ features) with environmental integration

Driving Agent

  • driving_agent.py: Advanced autonomous driving agent with enhanced patches:
    • Waypoint Buffer Optimization: Reduced buffer size for responsive updates
    • Traffic Light Compliance: Proper red light waiting with reset counters
    • Stuck Vehicle Recovery: Gentle unstuck mechanisms with waypoint advancement
    • Distance Adjustment: Conservative waypoint distance for roundabout handling

AI & Prediction

  • model/predictETA.py: Ensemble ML model combining XGBoost and Random Forest
  • model/train_model.py: Model training pipeline with feature selection
  • model/enhanced_eta_model.pkl: Pre-trained ensemble model

Logging & Analytics

  • logger.py: Ride performance tracking with JSON serialization fixes for numpy types

Training Data Collection

  • generate_training_data.py: Automated training data generation with route variety and weather conditions

Machine Learning Model Details

Model Architecture

  • Ensemble Approach: XGBoost + Random Forest combination
  • Feature Engineering: 25+ comprehensive route characteristics
  • Training Pipeline: Automated data collection and model updating

Model Performance

  • MAE (Mean Absolute Error):
    • Training MAE: ~7.2 seconds
    • Testing MAE: ~18-25 seconds
  • Model Validation: Cross-validation with diverse route conditions
  • Feature Importance: Traffic controls, distance, and weather impact as top predictors

Training Data

  • Route Variety: Short, medium, long, and cross-city routes
  • Weather Conditions: All 7 weather types for environmental robustness
  • Real Driving Times: Actual measured performance from CARLA simulation

System Flow

1. World Setup → 2. Graph Building → 3. Fleet Spawning → 4. Traffic Validation
                           ↓
5. Ride Requests → 6. Route Planning (Diverse) → 7. Assignment Analysis
                           ↓
8. Concurrent Driving → 9. Performance Logging → 10. ML Analytics

🎮 Usage Instructions

Starting the System

Step 1: Start CARLA Server

cd C:\CARLA_0.9.11\WindowsNoEditor
CarlaUE4.exe

Wait for CARLA to fully load (you'll see the CARLA window with the city)

Step 2: Run Taxi System

cd /path/to/your/project
python main.py

System Initialization Process

The system will automatically:

  1. Connect to CARLA (port 2000)
  2. Set weather conditions (default: clear_day)
  3. Clean existing vehicles from previous sessions
  4. Spawn traffic vehicles (10 vehicles with autopilot)
  5. Validate moving traffic (removes stationary vehicles)
  6. Build road network graph (~30 seconds, shows progress)
  7. Initialize managers (Fleet, Ride, Dispatcher)
  8. Spawn taxi fleet (2 taxis at different spawn points)
  9. Position overview camera (aerial view)
  10. Enable auto-assignment system

Expected Output:

🚖🚖 INTELLIGENT TAXI DISPATCH SYSTEM
=== SETTING UP WORLD ===
✅ Spawned 10 traffic vehicles
=== BUILDING ROAD NETWORK GRAPH ===
Graph built: XXXX nodes, XXXX edges
=== SPAWNING TAXI FLEET ===
✅ Spawned taxi_000 at spawn X
✅ Spawned taxi_001 at spawn Y
✅ System initialized successfully!

Menu Options

  • Option 1: Create custom ride request

    • Enter passenger name
    • Specify pickup spawn point (0 to max)
    • Specify dropoff spawn point (0 to max)
    • System shows available spawn point examples

  • Option 2: Create random ride request

    • Randomizes passenger name
    • Randomizes pickup/dropoff spawn points
    • Ensures different pickup/dropoff locations
    • Shows generated route details

  • Option 3: Show quick system status

    • Available/busy taxis count
    • Pending rides
    • Active assignments

  • Option 4: Show detailed system status

    • Fleet positions and states
    • Ride processing status
    • Assignment summaries

  • Option 5: View session statistics and prediction accuracy

    • Prediction accuracy distribution
    • Average prediction errors
    • Completed vs failed rides

  • Option 6: Exit system

    • Shows final session statistics
    • Clean shutdown with resource cleanup

Example Workflow

  1. Start CARLA and wait for city to load
  2. Run python main.py and wait for initialization (30-60 seconds)
  3. System ready when you see the menu
  4. Create rides with Option 1 or 2
  5. Watch autonomous operation:
    • Taxi selection analysis shows distances to all available taxis
    • Route visualization appears in CARLA (blue=pickup, red/green=passenger)
    • Real-time driving with traffic rule compliance
    • Progress updates every 30 seconds
  6. Monitor performance with Options 3-5
  7. System handles multiple concurrent rides automatically
  8. Exit cleanly with Option 6

Taxi Selection Process

When a ride is created, you'll see:

🎯 TAXI SELECTION ANALYSIS
📍 Pickup location: (X, Y)
🚖 Available taxis: 2
📊 Distance analysis:
  🏆 SELECTED taxi_000: 45.2m (at 140, 430)
     taxi_001: 78.9m (at 200, 500)
✅ Assignment decision: taxi_000 selected (closest at 45.2m)
💡 Efficiency: 33.7m closer than next best option

Route Visualization

  • Blue lines: Taxi driving to pickup location
  • Red/Green lines: Passenger route (alternates by taxi)
  • Text markers: START and END points for each route

🔧 Configuration Options

Weather Conditions

Available in config.py - setup_weather():

  • clear_day - Sunny conditions (default)
  • overcast - Cloudy sky with reduced lighting
  • rain - Rainy weather (impacts driving performance and visibility)
  • night - Night time (significantly reduced visibility)
  • rainy_night - Combined rain and night conditions (challenging)
  • foggy - Foggy conditions (significantly reduced visibility)
  • snowy - Snow conditions (most challenging driving)

Traffic Settings

  • Vehicle Count: Adjust num_vehicles in spawn_traffic_vehicles() (default: 10)
    • Range: 1-50 vehicles (higher numbers may impact performance)
  • Vehicle Type: All traffic uses same vehicle type (Tesla Model 3) for consistency
  • Traffic Behavior: Autopilot with realistic following distances (2.5m)
  • Traffic Manager: Configured for hybrid physics and asynchronous mode
  • Movement Validation: Automatic removal of stationary vehicles after 3-second test

System Parameters

Fleet Configuration

  • Fleet Size: Modify num_taxis in fleet spawning (default: 2)
    • Location: main.py, line ~95
  • Taxi Spacing: Spawn points separated by 8 positions for optimal distribution
  • Taxi Model: Toyota Prius for all taxis

Route Planning Configuration

  • Route Diversity Threshold: 20% minimum difference between alternatives
    • Location: route_gen.py, plan_diverse_routes() function
  • Maximum Routes: Up to 3 alternative routes per journey
    • Location: Multiple files, search for max_routes=3
  • Graph Resolution: 2.0 meter waypoint spacing
    • Location: main.py, build_graph(self.world, resolution=2.0)
    • Range: 1.0-5.0 meters (lower = more precise, higher = faster processing)

ETA Prediction Configuration

  • Model Type: Ensemble XGBoost + Random Forest
  • Feature Count: 25+ route characteristics
  • Prediction Update: Real-time during route planning
  • Accuracy Tracking: 4-tier classification system (EXCELLENT/GOOD/FAIR/POOR)

Auto-Assignment Configuration

  • Assignment Frequency: Every 2 seconds
    • Location: main.py, operation_manager() method
    • Configurable range: 1-10 seconds
  • Distance-Based Selection: Closest available taxi with full analysis
  • Quiet Operation: Status messages every 10 seconds when no taxis available

Driving Agent Configuration

  • Behavior Type: Normal driving with traffic rule compliance
    • Options: 'normal', 'aggressive', 'cautious'
    • Location: driving_agent.py, setup_agent() method
  • Traffic Light Handling: Proper red light waiting with timeout management
  • Waypoint Buffer Size: Optimized size (2-3) for responsive updates
  • Minimum Distance: Conservative 3.5m for intersection handling
  • Stuck Recovery: Gentle reverse maneuvers after 80 seconds of no movement
  • Progress Updates: Every 30 seconds (reduced from 10 seconds for cleaner output)

Configurable Performance Parameters

  • Max Driving Steps: 6500 steps per route (≈5-6 minutes maximum drive time)
  • Stuck Detection Interval: Every 20 seconds (400 steps * 0.05s)
  • Route Timeout: Automatic failure after max_steps reached
  • Distance Tolerance: 8.0m proximity to destination for success
  • Final Distance Tolerance: 15.0m for realistic success criteria

📊 Training Data Generation

Generating Training Data

python generate_training_data.py

This module generates training data for the ML model by automatically driving routes and collecting performance metrics.

🚨 Troubleshooting

Common Issues

"Failed to connect to CARLA"

  • Solution: Ensure CARLA server is running and fully loaded before starting system
  • Check: CARLA path is correctly set in Python files
  • Verify: Port 2000 is not blocked by firewall
  • Wait: Allow CARLA to completely initialize (30-60 seconds)

"No available taxis" messages

  • Solution: All taxis are busy - system will auto-assign when available
  • Normal: Message appears every 10 seconds when no taxis free (not spam)
  • Check: Number of concurrent rides vs available taxis (default: 2 taxis)

Route generation fails

  • Solution: Try different spawn points - some may not be connected in graph
  • Check: Spawn point indices are valid (0 to max_spawn_points)
  • Graph Issue: Ensure graph building completed successfully (~30 seconds)
  • Retry: Some spawn points may have temporary connection issues

Poor ETA predictions

  • Solution: Generate more training data with generate_training_data.py
  • Improve: Run training with different weather conditions for robustness
  • Model: Check if ensemble model file enhanced_eta_model.pkl exists
  • Retrain: Use train_model.py with more diverse training data

JSON Serialization Errors

  • Solution: Updated logger automatically handles numpy types
  • Fixed: Float32/int32 conversion issues resolved in logger.py
  • Check: All logged data is now properly serializable to JSON

Traffic vehicles not moving

  • Solution: System automatically detects and removes stationary vehicles
  • Check: Traffic manager configuration in config.py
  • Restart: CARLA server if traffic consistently fails to move

Threading and Concurrency Issues

Multi-Threading Challenges

The system uses complex multi-threading which can occasionally cause issues:

  • Race Conditions: Multiple threads accessing CARLA world simultaneously

    • Symptoms: Occasional crashes or vehicle spawning failures
    • Solution: System includes thread synchronization and retry mechanisms
    • Mitigation: Restart the system if persistent issues occur

  • Resource Contention: Multiple taxis trying to access the same CARLA resources

    • Symptoms: Slow performance or temporary freezes
    • Solution: System implements resource queuing and timeout handling
    • Recommendation: Limit to 2-3 concurrent taxis for optimal performance

  • Memory Leaks: Long-running sessions may accumulate memory usage

    • Symptoms: Gradually increasing RAM usage over time
    • Solution: Restart CARLA server every 30-60 minutes for extended sessions
    • Prevention: System includes automatic cleanup routines

Driving Agent Stop Sign Issues (CARLA BehaviorAgent Limitation)

Known Issue: Vehicles may occasionally get stuck at stop signs due to CARLA's BehaviorAgent implementation.

  • Root Cause: This is a limitation in CARLA's built-in BehaviorAgent, not our system
  • Symptoms: Taxi stops at stop sign and remains stationary for extended periods
  • Expected Behavior: Vehicle should wait 2-3 seconds then proceed
  • Actual Behavior: May wait 10-50 seconds before automatically resuming
  • System Response:
    • Stuck detection activates after 80 seconds of no movement
    • Gentle recovery mechanisms attempt to unstuck the vehicle
    • System differentiates between legitimate waiting and actual stuck situations
  • Recommendation:
    • Allow vehicles time to self-recover (10-50 seconds is normal)
    • System will eventually detect and resolve stuck situations
    • This behavior is realistic as it represents cautious driving
  • Workaround: If persistent, restart the ride request or system

Performance Tips

  • Reduce traffic vehicles if experiencing lag (modify num_vehicles)
  • Lower CARLA graphics settings for better performance
  • Close other applications while running CARLA
  • Use SSD storage for better CARLA loading times
  • Monitor RAM usage - system spawns traffic automatically

Memory Issues

  • Restart CARLA periodically for long sessions
  • Monitor RAM usage - CARLA can be memory-intensive
  • Reduce concurrent taxis if system struggles
  • Traffic cleanup: System automatically manages traffic vehicles

🎯 Key System Features

Advanced Route Planning

  • Diverse Route Generation: Multiple strategies for route variety
    • Edge removal with systematic patterns
    • Random seed-based alternative generation
    • Waypoint-based routing for maximum diversity
  • Graph-Based Navigation: Efficient pathfinding on road networks with lane change support
  • Lane Change Support: Realistic multi-lane driving capabilities with automatic lane change edge detection
  • Route Optimization: Eliminates redundant calculations through pre-computation

Intelligent Fleet Management

  • Enhanced Taxi Selection: Complete distance analysis for all available taxis
  • Real-Time State Tracking: Comprehensive taxi status monitoring with callbacks
  • Concurrent Operations: Multiple taxis operating simultaneously with thread safety
  • Efficiency Metrics: Distance advantages and detailed assignment explanations

ETA Prediction System

  • Ensemble ML Model: XGBoost + Random Forest combination
  • Feature-Rich Analysis: 25+ route characteristics including:
    • Traffic control density and infrastructure
    • Weather impact scores and visibility
    • Route complexity indices and directness
    • Vehicle density analysis and congestion
    • Road type classification and characteristics
  • Real-Time Validation: Live prediction accuracy tracking
  • Performance Analytics: MAE tracking and accuracy categorization

Performance Analytics

  • Prediction Accuracy: Detailed error analysis with ratings (EXCELLENT/GOOD/FAIR/POOR)
  • Session Statistics: Comprehensive performance tracking across rides
  • Real-Time Monitoring: Live system status and metrics
  • JSON Logging: Complete ride data with proper numpy type serialization

Traffic Simulation

  • Realistic Traffic: Moving vehicles with autopilot behavior and validation
  • Dynamic Weather: 7 different weather conditions affecting driving performance
  • Traffic Management: Automatic cleanup of stationary vehicles
  • Consistent Behavior: All traffic uses same vehicle type for consistency

Driving Agent Enhancements

  • Traffic Rule Compliance: Proper traffic light handling and red light waiting
  • Waypoint Optimization: Reduced buffer size for responsive navigation
  • Stuck Recovery: Gentle unstuck mechanisms without aggressive maneuvers
  • Roundabout Handling: Conservative distance settings for complex intersections

📁 File Structure

carla_taxi_project/
├── main.py                 # Main system entry point
├── config.py              # World configuration and setup
├── graph_builder.py       # Road network graph construction
├── route_gen.py           # Diverse route generation algorithms
├── feature_extractor.py   # Route feature extraction (25+ features)
├── driving_agent.py       # Autonomous driving agent with patches
├── logger.py               # Performance logging and JSON serialization
├── generate_training_data.py  # Training data collection
├── taxi_system/
│   ├── fleet_manager.py   # Enhanced taxi fleet management
│   ├── ride_manager.py    # Ride request handling with route diversity
│   └── dispatcher.py      # Assignment coordination with analysis
├── model/
│   ├── predictETA.py      # Ensemble ETA prediction model
│   ├── train_model.py     # Model training pipeline
│   ├── enhanced_eta_model.pkl  # Pre-trained ensemble model
│   └── route_features/    # Generated training data (auto-created)
└── README.md             # This file

🤖 Machine Learning Model Details

Model Architecture

  • Ensemble Method: XGBoost + Random Forest combination
  • Primary Model: XGBoost for main predictions
  • Secondary Model: Random Forest for validation and ensemble voting
  • Feature Selection: Automated feature importance ranking

Model Performance Metrics

  • Training MAE: 7.2 seconds average error
  • Testing MAE: 18-25 seconds average error
  • Validation Strategy: 10-fold cross-validation with temporal splits
  • Accuracy Categories:
    • EXCELLENT: ≤15% error
    • GOOD: 15-25% error
    • FAIR: 25-40% error
    • POOR: >40% error

Feature Engineering (25+ Features)

Distance & Route Characteristics

  • total_distance, route_directness, avg_segment_distance

Traffic Infrastructure

  • traffic_lights, stop_signs, traffic_control_density

Route Complexity

  • junctions, total_turns, lane_changes, route_complexity_index

Environmental Factors

  • weather_impact_score, visibility_score, hour_of_day, is_rush_hour

Traffic Conditions

  • avg_nearby_vehicles, vehicle_density_per_km, congestion_score

Road Types & Characteristics

  • highway_ratio, urban_ratio, avg_lane_width, elevation_changes

Model Training Pipeline

  1. Data Collection: Automated via generate_training_data.py
  2. Feature Extraction: 25+ characteristics per route
  3. Data Preprocessing: Handling missing values and outliers
  4. Model Training: Ensemble approach with hyperparameter tuning
  5. Validation: Performance testing with real driving scenarios
  6. Model Persistence: Saved as enhanced_eta_model.pkl

📈 Model Training Workflow

  1. Generate Training Data: Run generate_training_data.py with various conditions
  2. Collect Diverse Routes: Short, medium, long, and cross-city routes with different weather
  3. Feature Extraction: 25+ comprehensive route characteristics per route
  4. Weather Variation: Train under all 7 weather conditions for robustness
  5. Model Training: Ensemble XGBoost + Random Forest with train_model.py
  6. Performance Validation: Test accuracy with real driving scenarios
  7. Accuracy Analysis: Detailed prediction error analysis and improvement
  8. Model Persistence: Save trained model as enhanced_eta_model.pkl

🔍 Technical Improvements

Recent Enhancements

  • Route Optimization: Eliminated triple route generation through pre-calculation
  • Logger Fixes: Resolved JSON serialization problems with numpy types
  • Random Rides: Improved randomization with time-based seeding for variety
  • Quiet Operation: Reduced console spam with smart messaging intervals
  • Enhanced Analysis: Detailed taxi selection explanations with all distances
  • Performance Tracking: Complete ride timing analysis with pickup/passenger phases

Machine Learning Integration

  • Feature Engineering: Comprehensive route characteristic extraction
  • Ensemble Modeling: XGBoost + Random Forest for robust predictions
  • Model Pipeline: Automated training data collection and model updating
  • Prediction Validation: Real-time accuracy tracking and categorization
  • Data Quality: Proper handling of all data types for ML training

Concurrent System Design

  • Thread Safety: Proper synchronization for multi-taxi operations
  • Resource Management: Efficient CARLA resource handling and cleanup
  • State Management: Robust taxi state tracking with callback notifications
  • Error Handling: Graceful failure recovery and system continuation

🤝 Contributing

When modifying the system:

  • Test thoroughly with various spawn points and weather conditions
  • Maintain compatibility with existing components and thread safety
  • Document changes in code comments and update README
  • Verify ETA accuracy after model modifications
  • Check JSON serialization for any new logged data types
  • Test concurrent operations to ensure thread safety and resource management

📞 Support

For issues related to:

  • CARLA Setup: Check CARLA Documentation
  • Python Dependencies: Verify package versions and compatibility
  • System Performance: Review hardware requirements and optimization tips
  • XGBoost Issues: Ensure proper installation and model file availability
  • Threading Problems: Check for race conditions in concurrent operations
  • Model Training: Verify training data quality and feature extraction

Built with: CARLA Simulator, Python, NetworkX, XGBoost, Random Forest, Scikit-learn Tested on: CARLA 0.9.11, Python 3.7, Windows 10 Project Type: Autonomous Vehicle Simulation, Machine Learning, Multi-Agent Systems ML Model: Ensemble XGBoost + Random Forest with 25+ engineered features Performance: MAE 15-25 seconds, 4-tier accuracy classification system

About

No description, website, or topics provided.

Resources

Readme
Activity

Stars

0 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

Packages

Contributors

Languages