Documentation

Installation Guide

OccluSense AI - Advanced Occlusion-Aware Object Detection System for Autonomous Vehicles Using YOLOv8 and Custom NMS Algorithms

Step-by-step Setup Verified Instructions Chat Support
Back to Project
Complete Guide

Installation and Setup Guide

Follow these comprehensive step-by-step instructions to set up and run the OccluSense AI project on your local machine.

Prerequisites

  • Python 3.9 or higher - Download from python.org
  • pip - Python package manager (comes with Python)
  • Git - Version control system (optional, for cloning)
  • Webcam - Optional, required only for real-time detection feature
  • Minimum 4GB RAM - Recommended 8GB for smooth performance
  • 500MB Free Disk Space - For dependencies and model weights

Step 1: Extract Project Files

Extract the downloaded project ZIP file to your desired location. Navigate to the extracted folder:

cd "Occlusion aware Object Detection for SelfDriving Cars"

Note: If you cloned from Git, use: git clone [repository-url]

Step 2: Create Virtual Environment

Creating a virtual environment isolates project dependencies from your system Python installation:

python -m venv venv

Why Virtual Environment? It prevents dependency conflicts and keeps your system Python clean.

Step 3: Activate Virtual Environment

Activate the virtual environment based on your operating system:

For Windows:

venv\Scripts\activate

For Linux/Mac:

source venv/bin/activate

Success Indicator: You should see (venv) prefix in your command prompt.

Step 4: Install Dependencies

Install all required Python packages using the requirements file:

pip install -r requirements.txt

This will install the following major packages:

  • Django 5.0+ - Web framework
  • PyTorch 2.0+ - Deep learning framework
  • Ultralytics - YOLOv8 implementation
  • OpenCV - Computer vision library
  • NumPy - Numerical computing
  • Pandas - Data manipulation
  • Pillow - Image processing

Installation Time: This may take 5-10 minutes depending on your internet speed.

Step 5: Download YOLOv8 Model Weights

The YOLOv8 pre-trained model weights will be automatically downloaded on first run. However, you can manually download them:

python -c "from ultralytics import YOLO; model = YOLO('yolov8n.pt')"

Available model sizes:

  • yolov8n.pt - Nano (6.3MB) - Fastest, recommended for CPU
  • yolov8s.pt - Small (21.5MB) - Balanced performance
  • yolov8m.pt - Medium (49.7MB) - Better accuracy
  • yolov8l.pt - Large (83.7MB) - High accuracy
  • yolov8x.pt - Extra Large (131.7MB) - Best accuracy, requires GPU

Default Model: The project uses yolov8n.pt for optimal speed-accuracy balance.

Step 6: Apply Database Migrations

Set up the SQLite database schema by running migrations:

python manage.py makemigrations detection
python manage.py migrate

This creates the following database tables:

  • UploadedMedia - Stores uploaded images and videos
  • DetectionSession - Tracks detection sessions
  • DetectionResult - Stores individual object detections
  • PerformanceMetric - Logs performance statistics

Step 7: Create Superuser Account (Optional)

Create an admin account to access the Django admin panel:

python manage.py createsuperuser

You will be prompted to enter:

  • Username
  • Email address
  • Password (entered twice for confirmation)

Admin Panel URL: Access at http://127.0.0.1:8000/admin/

Step 8: Create Media Directories

Ensure media directories exist for file uploads and results:

mkdir -p media/uploads media/results

For Windows:

mkdir media\uploads media\results

Step 9: Run Development Server

Start the Django development server:

python manage.py runserver

You should see output similar to:

Starting development server at http://127.0.0.1:8000/
Quit the server with CTRL-BREAK.

Custom Port: To run on a different port, use python manage.py runserver 8080

Step 10: Access the Application

Open your web browser and navigate to:

Configuration Settings

You can customize detection parameters in occlusion_detection/settings.py:

DETECTION_CONFIG = {
    'MODEL_PATH': 'yolov8n.pt',              # YOLOv8 model variant
    'DEFAULT_CONFIDENCE_THRESHOLD': 0.25,     # Minimum confidence score
    'DEFAULT_IOU_THRESHOLD': 0.45,            # IoU threshold for NMS
    'DEFAULT_NMS_METHOD': 'standard',         # NMS method (standard/soft/diou)
    'SOFT_NMS_SIGMA': 0.5,                    # Sigma for Soft-NMS
    'TARGET_CLASSES': [0, 1, 2, 3, 5, 7, 9],  # COCO class IDs to detect
}

Target Classes (COCO Dataset)

Class ID Class Name Description
0 person Pedestrians, cyclists
1 bicycle Bicycles on road
2 car Cars and sedans
3 motorcycle Motorcycles and scooters
5 bus Buses
7 truck Trucks and lorries
9 traffic light Traffic signals

Webcam Setup (Optional)

For real-time webcam detection feature:

Windows:

  1. Ensure webcam drivers are installed
  2. Grant camera permissions in Windows Settings > Privacy > Camera
  3. Allow browser to access camera when prompted

Linux:

# Check if webcam is detected
ls /dev/video*

# Install v4l-utils if needed
sudo apt-get install v4l-utils

# Test webcam
v4l2-ctl --list-devices

Mac:

  1. Grant camera permissions in System Preferences > Security & Privacy > Camera
  2. Allow Terminal/iTerm to access camera
  3. Allow browser to access camera when prompted

Using the REST API

The application provides RESTful API endpoints for programmatic access:

1. Upload Image for Detection

curl -X POST -F "file=@image.jpg" \
     -F "nms_method=soft" \
     -F "confidence_threshold=0.25" \
     -F "iou_threshold=0.45" \
     http://127.0.0.1:8000/api/detect/

2. Get Detection Results

curl http://127.0.0.1:8000/api/results/1/

3. Compare NMS Methods

curl -X POST -F "file=@image.jpg" \
     http://127.0.0.1:8000/api/compare-nms/

4. Get Performance Metrics

curl http://127.0.0.1:8000/api/metrics/

Production Deployment (Optional)

For deploying to production environment:

1. Update Settings

# In settings.py
DEBUG = False
ALLOWED_HOSTS = ['yourdomain.com', 'www.yourdomain.com']

# Use PostgreSQL instead of SQLite
DATABASES = {
    'default': {
        'ENGINE': 'django.db.backends.postgresql',
        'NAME': 'occlusense_db',
        'USER': 'your_db_user',
        'PASSWORD': 'your_db_password',
        'HOST': 'localhost',
        'PORT': '5432',
    }
}

2. Collect Static Files

python manage.py collectstatic

3. Install Production Server

pip install gunicorn

# Run with Gunicorn
gunicorn occlusion_detection.wsgi:application --bind 0.0.0.0:8000

4. Setup Nginx (Reverse Proxy)

# Install Nginx
sudo apt-get install nginx

# Configure Nginx
sudo nano /etc/nginx/sites-available/occlusense

# Add configuration
server {
    listen 80;
    server_name yourdomain.com;

    location / {
        proxy_pass http://127.0.0.1:8000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }

    location /static/ {
        alias /path/to/static/;
    }

    location /media/ {
        alias /path/to/media/;
    }
}

Troubleshooting Common Issues

Issue 1: Module Not Found Error

Error: ModuleNotFoundError: No module named 'django'

Solution: Ensure virtual environment is activated and dependencies are installed:

# Activate venv first
source venv/bin/activate  # Linux/Mac
venv\Scripts\activate     # Windows

# Then install
pip install -r requirements.txt

Issue 2: Port Already in Use

Error: Error: That port is already in use.

Solution: Use a different port or kill the process:

# Use different port
python manage.py runserver 8080

# Or kill existing process (Linux/Mac)
lsof -ti:8000 | xargs kill -9

# Windows
netstat -ano | findstr :8000
taskkill /PID [process_id] /F

Issue 3: CUDA Out of Memory (GPU)

Error: RuntimeError: CUDA out of memory

Solution: Switch to CPU or use smaller model:

# In settings.py, set:
DETECTION_CONFIG = {
    'MODEL_PATH': 'yolov8n.pt',  # Use nano model
    'DEVICE': 'cpu',              # Force CPU usage
}

Issue 4: Webcam Not Detected

Solution:

  • Check camera permissions in browser settings
  • Ensure camera drivers are installed
  • Verify camera works in other applications
  • Use HTTPS (some browsers require secure connection for camera access)

Issue 5: Model Download Fails

Error: Unable to download model weights

Solution: Manually download and place in project root:

# Download from:
# https://github.com/ultralytics/assets/releases/download/v0.0.0/yolov8n.pt

# Place in project root directory
mv ~/Downloads/yolov8n.pt /path/to/project/

Issue 6: Permission Denied on Media Folder

Error: PermissionError: [Errno 13] Permission denied: 'media/uploads'

Solution: Set proper permissions:

# Linux/Mac
chmod -R 755 media/

# Windows - Run as Administrator
icacls media /grant Everyone:F /T

Testing the Installation

Verify everything is working correctly:

1. Basic Functionality Test

  1. Navigate to http://127.0.0.1:8000/upload/
  2. Upload a test image (car or street scene)
  3. Select NMS method (try "Standard" first)
  4. Set confidence threshold to 0.25
  5. Click "Detect Objects"
  6. Verify detection results are displayed

2. NMS Comparison Test

  1. Navigate to http://127.0.0.1:8000/compare/
  2. Upload a crowded street scene
  3. Wait for processing
  4. Compare results from all three NMS methods

3. API Test

# Test API endpoint
curl -X POST -F "file=@test_image.jpg" \
     -F "nms_method=standard" \
     http://127.0.0.1:8000/api/detect/

# Should return JSON with detection results

4. Webcam Test

  1. Navigate to http://127.0.0.1:8000/webcam/
  2. Grant camera permissions when prompted
  3. Click "Start Detection"
  4. Verify real-time detection is working
  5. Check FPS counter is updating

Performance Optimization Tips

  • Use GPU if available: Set DEVICE='cuda' in settings for 5-10x faster processing
  • Adjust confidence threshold: Higher values (0.4-0.5) reduce false positives and improve speed
  • Use smaller model for CPU: yolov8n.pt is optimized for CPU inference
  • Resize large images: Process at 640x640 resolution for optimal speed-accuracy
  • Batch processing: Process multiple images together for better throughput
  • Cache model: Model loads once and stays in memory during server runtime

Next Steps

  1. Explore the analytics dashboard for performance insights
  2. Try different NMS methods and compare results
  3. Test with your own images and videos
  4. Customize detection parameters for your use case
  5. Integrate the API with other applications
  6. Extend the project with custom features
  7. Deploy to production for real-world use

Getting Help

If you encounter any issues during installation or usage:

Need Help?

Our team is here to assist you with installation and setup.

Chat with Us
WhatsAppTelegramSignal
Chat with us