♻️ Smart Garbage Classification System

Recognizing trash is only the first step — knowing how to dispose of it properly is what matters.

An intelligent image-based garbage classifier that goes beyond simple labeling. It identifies your waste and tells you exactly which bin to use in 38 major Chinese cities, based on local municipal regulations.

🚀 Live Demo

✨ Highlights

Feature	Why It Matters
🏙️ City-Specific Disposal Guide	After classification, the system maps the result to your city's local waste-sorting rules (e.g., "In Shanghai, this goes in the Residual Waste bin"). Supports 38 Chinese cities.
🎯 Top-3 Candidates with Confidence	Instead of a single guess, the model returns the top 3 probable categories with softmax confidence scores, so you know when to double-check.
📈 Iterative Model Refinement	Accuracy improved from 90.84% → 92.37% (V1 → V2) not by random tuning, but by systematic error-sample analysis and targeted data augmentation (+583 images).
📦 Batch Processing & CSV Export	Upload multiple images at once and get a summary report (filename, predicted class, confidence) downloadable as CSV — useful for community managers or property maintenance.
🛡️ Production-Grade Robustness	Strict input validation chain, lazy model loading, automatic CPU/GPU fallback, and graceful degradation when the model is not yet deployed.

---

🚀 Quick Start

Prerequisites

• Python 3.9+
• (Optional) CUDA-capable GPU for faster inference

1. Clone & Setup

git clone <repo-url>
cd Garbage-Classification-System

# Backend
python3 -m venv .venv
source .venv/bin/activate  # Windows: .venv\Scripts\activate
pip install -r src/requirements.txt

# Frontend (no build step needed)
# Simply serve the frontend/ directory

2. Download Model & Data

Note: Due to file size limits, model weights (*.pt) and the full image dataset are not included in this repository.

• Model weights: Please contact the team or check the release notes for the model.pt and class_names.json.
• Dataset sources: The training data is derived from publicly available datasets:
  • TACO Trash Dataset
  • Garbage Classification v2
  • TrashNet

Place the downloaded model files into model/current/.

3. Run

# Terminal 1: Backend API
uvicorn src.backend.server:app --host 0.0.0.0 --port 8000 --reload

# Terminal 2: Frontend
python3 -m http.server 3000 --directory frontend

Open http://localhost:3000 to use the app. The backend API runs at http://localhost:8000.

---

📊 Model Performance

Metric	V1	V2 (Current)
Architecture	ConvNeXt-Tiny	ConvNeXt-Tiny
Input Size	384×384	384×384
Test Accuracy	90.84%	92.37%
Macro F1	0.9176	0.9299
Weighted F1	0.9085	0.9235
ROC-AUC (macro)	0.9834	0.9897
Loss Function	CrossEntropy	Focal Loss
Data Augmentation	—	+583 images (targeted)

The improvement from V1 to V2 was driven by error-sample analysis: we inspected the misclassified images, identified under-represented categories and edge cases, and supplemented the training set accordingly. See analysis/error_sample_analysis/ for full reports.

---

🏗️ System Overview

┌─────────────┐     HTTP/JSON      ┌─────────────────┐     File I/O      ┌─────────────┐
│  Frontend   │ ◄────────────────► │  FastAPI Backend│ ◄──────────────►│  Model (V2) │
│ (Pure HTML/ │                    │  - /health      │                 │ ConvNeXt-Tiny│
│  CSS/JS)    │                    │  - /meta        │                 │  Lazy Load  │
│             │                    │  - /predict     │                 └─────────────┘
│  ├ Drag &   │                    │    (Top-3 +     │
│  │  Drop    │                    │     confidence) │
│  ├ City     │                    └─────────────────┘
│  │  Selector│
│  └ Batch    │
│     Upload  │
└─────────────┘

Key Engineering Details:

• Lazy Model Initialization: The model is only loaded into memory upon the first prediction request, saving GPU VRAM during idle periods.
• Multi-Format Checkpoint Support: Automatically handles raw model objects, nested state_dict, and DataParallel trained weights.
• Strict Input Validation Chain: File existence → extension → MIME type → size limit (10MB) → image decoding → validity check → preprocessing → inference.
• Graceful Degradation: If the model file is missing, the backend still serves /health and /meta, and only returns "model not ready" on /predict.
• CORS Enabled: Seamless local development between frontend dev server and backend API.

---

📁 Project Structure

Garbage-Classification-System/
├── frontend/                  # Single-page web app (HTML/CSS/JS)
├── src/                       # FastAPI backend service
│   └── backend/
│       └── server.py          # API routes & inference engine
├── model/
│   ├── current/               # Model weights for backend (gitignored)
│   ├── v1/                    # V1 training logs & evaluation charts
│   └── v2/                    # V2 training logs & evaluation charts
├── analysis/                  # Error-sample analysis & metric comparison
│   └── error_sample_analysis/
│       ├── model_error_and_metrics_analysis.ipynb
│       └── v1_v2_comparison_analysis.ipynb
├── data/                      # Dataset (gitignored)
└── _docs/                     # Presentation slides & documentation

---

👥 Team & Credits

This is a course project built by a team of 5 students from Peking University.

Member	Role	Key Contribution
Jiayuan Li	Data	Dataset collection, cleaning, and standardization
Junle Huang	Model	ConvNeXt-Tiny training, Focal Loss implementation, V2 optimization
Xiangyuan Chen	Analysis	Error-sample analysis, metric evaluation, V1/V2 comparison reports
Yueci Li	Frontend	UI/UX design, drag-and-drop upload, city selector, batch report interface
Cheng Zhang	Backend & Integration	FastAPI service, model serving, input validation, frontend-backend integration

---

📝 License

This project is for academic and educational purposes. Model weights and datasets are subject to their respective original licenses.

---

🤝 Acknowledgements

• Base datasets: TACO, Garbage Classification v2, TrashNet
• Model architecture: ConvNeXt (Meta AI)