EcoSort - AI Recycling Classifier

Quick Start

Prerequisites

•Node.js v18 or higher
•Python 3.9 or higher
•pnpm/npm (package manager)
•Git for cloning the repository

Backend Setup

1. Navigate to backend directory

cd eco-backend

2. Create virtual environment

python -m venv .venv
source .venv/bin/activate  # Linux/Mac
.venv\Scripts\activate   # Windows

3. Install dependencies

pip install -r requirements.txt

4. Run migrations

python manage.py migrate

5. Start server

python manage.py runserver

✅ Backend runs at http://127.0.0.1:8000

Frontend Setup

1. Install dependencies

pnpm install

2. Create environment file

echo "NEXT_PUBLIC_BACKEND_URL=http://127.0.0.1:8000" > .env.local

3. Start development server

pnpm dev

✅ Frontend runs at http://localhost:3000

4. Open in browser

http://localhost:3000

System Overview

EcoSort is an AI-powered waste classification system that automatically identifies and categorizes recyclable materials using computer vision.

🎯 Real-time Classification

Instantly categorizes waste using YOLOv11n model

📸 Multiple Input Methods

Supports drag-drop, file upload, and camera capture

📊 Performance Metrics

Detailed statistics and model performance analytics

12 Waste Categories:

📄Paper

📦Cardboard

🥤Plastic

🌿Vegetation

🍂Biological

🔩Metal

👕Clothes

🍾Glass

🗑️Trash

👟Shoes

🔋Battery

Architecture

Technology Stack

Frontend

• Next.js 16 (App Router)
• React 19
• TypeScript
• Tailwind CSS v4
• shadcn/ui components

Backend

• Django 4.2
• Django REST Framework
• Python 3.x
• Ultralytics YOLO
• Gunicorn (production)

Data Flow:

User Upload → Frontend (Next.js) → API Proxy → Django Backend
                                            ↓
                                     YOLO Model (YOLOv11n)
                                            ↓
                                     Classification Result
                                            ↓
                             Conveyor Animation + Bin Sorting
                                            ↓
                                    Statistics Update

API Reference

POST/api/classify/

Classifies an uploaded image using the YOLO model

Request:

Content-Type: multipart/form-data

image: <file>           # Required: Image file
model: "yolov11n-12class"  # Optional: Model key

Success Response (200):

{
  "message": "Image classified successfully",
  "predictions": [
    {
      "class_id": 2,
      "class_name": "plastic",
      "confidence": 0.8742
    },
    {
      "class_id": 0,
      "class_name": "paper",
      "confidence": 0.0523
    }
  ],
  "count": 2,
  "model": "yolov11n-12class"
}

Example cURL:

curl -X POST http://127.0.0.1:8000/api/classify/ \
  -F "image=@test_image.jpg"

GET/api/models/

Returns list of available models and the default model

Success Response (200):

{
  "models": [
    {
      "key": "yolov11n-12class",
      "name": "YOLOv11n (12 Classes)",
      "classes": 12
    }
  ],
  "default": "yolov11n-12class"
}

Example cURL:

curl http://127.0.0.1:8000/api/models/

Key Components

Frontend Components

recycling-plant.tsx
Main orchestrator managing state and workflow
image-uploader.tsx
Handles image upload and camera capture
conveyor-belt.tsx
Animated conveyor belt with scanning beam
recycling-bins.tsx
3D-style bins with animations
trash-item.tsx
Individual items on conveyor

Backend Components

views.py
API endpoints (classify, models)
yolo_model.py
YOLO model wrapper with singleton pattern
serializers.py
Request/response validation
settings.py
Django configuration and model paths

Testing

1. Verify Backend

# Check if backend is running
curl http://127.0.0.1:8000/api/models/

# Test classification
curl -X POST http://127.0.0.1:8000/api/classify/ \
  -F "image=@path/to/test_image.jpg"

2. Test Frontend

• Navigate to http://localhost:3000
• Upload a test image (drag-drop or click to browse)
• Watch the conveyor animation
• Verify item is sorted into correct bin
• Check stats counter increments

3. Common Issues

CORS Error

Add frontend URL to CORS_ALLOWED_ORIGINS in Django settings

Model Not Found

Ensure yoloMODEL_old_cls_12.pt exists in eco-backend directory

Backend Connection Failed

Check NEXT_PUBLIC_BACKEND_URL in .env.local

Deployment

Backend (Render)

Build Command:

cd eco-backend && pip install -r requirements.txt && python manage.py collectstatic --noinput

Start Command:

cd eco-backend && gunicorn config.wsgi:application --bind 0.0.0.0:$PORT

Environment Variables:

• PYTHON_VERSION=3.11
• SECRET_KEY=your-secret-key
• DEBUG=False
• ALLOWED_HOSTS=.onrender.com

Frontend (Vercel)

Framework:

Next.js (auto-detected)

Build Command:

next build

Environment Variables:

NEXT_PUBLIC_BACKEND_URL=https://your-backend.onrender.com

✅ Custom domain: ecopro.hamzaihsan.me

Dataset & Model Information

Training Dataset

The model was trained on a comprehensive dataset of waste images collected and manually labeled.

~20K

Total Images

Dataset Distribution:

👕 Clothes5,325 (26.7%)

🍾 Glass2,431 (12.2%)

👟 Shoes1,977 (9.9%)

🥤 Plastic1,786 (9.0%)

🔩 Metal1,559 (7.8%)

📄 Paper1,550 (7.8%)

🍂 Biological1,396 (7.0%)

📦 Cardboard1,352 (6.8%)

🔋 Battery945 (4.7%)

🗑️ Trash697 (3.5%)

🗑️ Miscellaneous495 (2.5%)

🌿 Vegetation436 (2.2%)

Note: The dataset shows some class imbalance. Data augmentation techniques were used during training to mitigate this.

Training Notebook

Yolo medium 3 classes/TestingF.ipynb

Jupyter notebook containing model training, evaluation, and metrics generation. Includes confusion matrix generation and performance visualization.

YOLOv11n-12class Model

Specifications

• Model: YOLOv11n (nano variant)
• Task: Image Classification
• Parameters: ~2.6M
• Input: 224x224 RGB images
• Output: Top-5 predictions
• Inference: ~50-200ms (CPU)

Performance

• Classes: 12 waste categories
• Framework: Ultralytics YOLO
• File: yoloMODEL_old_cls_12.pt
• Size: ~5.5MB

View detailed metrics →

Usage Example:

from ultralytics import YOLO

model = YOLO('yoloMODEL_old_cls_12.pt')
results = model('test_image.jpg')

for result in results:
    probs = result.probs
    top5_idx = probs.top5
    top5_conf = probs.top5conf
    
    for idx, conf in zip(top5_idx, top5_conf):
        print(f"{result.names[idx]}: {conf:.2%}")

Additional Resources

Ultralytics YOLO

Official documentation for YOLO models

Next.js Documentation

Learn about Next.js features and API

Django Documentation

Getting started with Django framework

shadcn/ui

Beautiful UI components used in this project

For complete technical documentation, see FULL_DOCUMENTATION.md

EcoSort v1.0.0 • Built with ❤️ using Next.js and Django