README.md

---
title: Intel Image Classifier
emoji: 🧠
colorFrom: blue
colorTo: green
sdk: docker
pinned: false
---

# Intel Image Classifier

Full-stack application for classifying natural scene images using two CNN models (PyTorch & TensorFlow).

> **For deployment instructions and detailed setup, see [DEPLOYMENT.md](DEPLOYMENT.md)**

---

## What's New (Consolidated Version)

✅ **Unified Docker Deployment** - Single container for Hugging Face Spaces  
✅ **Production-Ready** - Gunicorn + WhiteNoise for static files  
✅ **AutoStart Scripts** - Automatic migrations and superuser setup  
✅ **Health Check Endpoint** - `/health/` for monitoring  
✅ **Optimized Build** - Multi-stage Docker with Node.js + Python  

---

## Quick Start

### 🐳 Docker (Recommended)

```bash
# Build the unified container
docker build -t intel-classifier .

# Run on port 7860 (Hugging Face compatible)
docker run -p 7860:7860 intel-classifier
```

Visit: `http://localhost:7860`

### 🚀 Hugging Face Spaces

1. Fork this repository to your Hugging Face account
2. Add your trained models to `backend/api/models/`
3. Push to your HF Space
4. Watch it deploy automatically!

```bash
git push hf main
```

---

## Project Structure

```
intel-classifier/
├── backend/                      # Django REST API
│   ├── api/notifications/        # Classification app
│   │   └── models/
│   │       ├── pytorch_model.pth
│   │       └── model_best.keras
│   ├── requirements.txt
│   └── api/entrypoint.sh
│
├── frontend/                     # React + Material-UI
│   ├── src/
│   └── package.json
│
├── ml/                           # Training code (optional)
│   ├── models/
│   ├── utils/
│   └── requirements.txt
│
├── Dockerfile                    # Unified deployment
├── docker-compose.yml            # Local development
└── DEPLOYMENT.md                 # Full deployment guide
```

---

## API Usage

### Classification Endpoint

**POST** `/api/classify/`

```bash
curl -X POST \
  -F "image=@photo.jpg" \
  -F "model=pytorch" \
  http://localhost:7860/api/classify/
```

**Response:**
```json
{
  "class": "mountain",
  "confidence": 0.95,
  "model_used": "pytorch",
  "probabilities": {
    "buildings": 0.02,
    "forest": 0.01,
    "glacier": 0.01,
    "mountain": 0.95,
    "sea": 0.01,
    "street": 0.00
  }
}
```

### Documentation

- 📚 Swagger: `http://localhost:7860/swagger/`
- 📖 ReDoc: `http://localhost:7860/redoc/`
- 🔐 Admin: `http://localhost:7860/admin/` (user: admin, pass: admin)
- ✅ Health: `http://localhost:7860/health/`

---

## Supported Classes

| English  | French     | Wolof          | Example              |
|----------|------------|----------------|----------------------|
| buildings| Bâtiments  | Kër yi         | Houses, offices      |
| forest   | Forêt      | Géej bu wees   | Trees, vegetation    |
| glacier  | Glacier    | Dëkk bu sedd   | Ice, snow            |
| mountain | Montagne   | Tund bi        | Hills, peaks         |
| sea      | Mer        | Géej bi        | Ocean, water         |
| street   | Rue        | Yoon bi        | Roads, urban areas   |

---

## Local Development

### Setup Backend

```bash
cd backend/api
python -m venv venv
source venv/bin/activate
pip install -r ../requirements.txt

# Run migrations
python manage.py migrate

# Start server
python manage.py runserver 8000
```

### Setup Frontend

```bash
cd frontend
npm install
npm start
```

Access at:
- Frontend: `http://localhost:3000`
- Backend: `http://localhost:8000`

---

## Adding Your Models

1. Train your models using scripts in `/ml/`
2. Place trained models in `backend/api/models/`:
   ```
   backend/api/models/
   ├── pytorch_model.pth
   └── model_best.keras
   ```
3. Deploy or restart the application

---

## Deployment Checklist

- [ ] Clone repository
- [ ] Add trained models
- [ ] Test locally with Docker
- [ ] Push to Hugging Face Spaces
- [ ] Test on live URL
- [ ] Update README with your username

---

## Technologies

### Backend
- Django REST Framework
- PyTorch
- TensorFlow
- Gunicorn

### Frontend
- React 19
- Material-UI (MUI)
- Redux Toolkit
- Axios

### DevOps
- Docker & Docker Compose
- Hugging Face Spaces
- WhiteNoise (static files)

---

## Configuration

Create `backend/.env` for custom settings:

```env
DEBUG=False
DJANGO_SECRET_KEY=your-secret-here
ALLOWED_HOSTS=localhost,.hf.space
```

For full configuration details, see [DEPLOYMENT.md](DEPLOYMENT.md)

---

## Troubleshooting

### Models not loading?
Ensure files exist in `backend/api/models/`:
- `pytorch_model.pth` (PyTorch)
- `model_best.keras` (TensorFlow)

### Port conflicts?
Change port in Docker command:
```bash
docker run -p 8080:7860 intel-classifier
# Access at localhost:8080
```

### CORS errors?
Check that frontend and backend share same origin. HF Spaces handles this automatically.

For more issues, see [DEPLOYMENT.md#troubleshooting](DEPLOYMENT.md#troubleshooting)

---

## Resources

- 📚 [Intel Image Classification Dataset](https://www.kaggle.com/datasets/puneet6060/intel-image-classification)
- 🤖 [PyTorch Documentation](https://pytorch.org/)
- 🎓 [TensorFlow Documentation](https://tensorflow.org/)
- 🤗 [Hugging Face Spaces Guide](https://huggingface.co/docs/hub/spaces)
- 🚀 [Django Deployment Guide](https://docs.djangoproject.com/en/5.0/howto/deployment/)

---

## License

MIT License - See LICENSE file

## Support

- 🐛 [Issues](https://github.com/danielle2035/Intel_classification/issues)
- 💬 [Discussions](https://huggingface.co/spaces/danielle2035/Intel_classification/discussions)
- 📧 Email: contact@example.com

---

## Citation

```bibtex
@misc{intel_classifier,
  title={Intel Image Classifier},
  author={Your Name},
  year={2024},
  publisher={Hugging Face Spaces},
  url={https://huggingface.co/spaces/YOUR_USERNAME/Intel_classification}
}
```

---

**Made with ❤️ for the Hugging Face Community**

---

### 2. Backend (Django)

```bash
# Aller dans le dossier backend
cd backend

# Créer un environnement virtuel
python -m venv venv

# Activer l'environnement virtuel
# Windows :
venv\Scripts\activate
# Mac/Linux :
source venv/bin/activate

# Installer les dépendances
pip install -r requirements.txt

# Aller dans le dossier Django
cd api

# Appliquer les migrations
python manage.py migrate

# Lancer le serveur
python manage.py runserver
```

Le backend sera disponible sur : **http://127.0.0.1:8000**

API Swagger disponible sur : **http://127.0.0.1:8000/swagger/**

---

### 3. Frontend (React)

Ouvre un **nouveau terminal** :

```bash
# Aller dans le dossier frontend
cd frontend

# Installer les dépendances
npm install

# Lancer l'application  
npm start
```

Le frontend sera disponible sur : **http://localhost:3000**

---

## Installation et lancement (avec Docker)

```bash
# À la racine du projet
docker-compose up --build
```

- Frontend : http://localhost:3000
- Backend  : http://localhost:8000
- Swagger  : http://localhost:8000/swagger/

---

## Entraînement des modèles

### Sur Kaggle (recommandé)

1. Upload `ml/train_kaggle.py` dans un notebook Kaggle
2. Active le GPU (Settings → Accelerator → GPU T4)
3. Ajoute le dataset `puneet6060/intel-image-classification`
4. Exécute le notebook
5. Télécharge `danielle_model.pth` et `danielle_model.keras`
6. Place-les dans `backend/api/models/`

### En local

```bash
cd ml

# Installer les dépendances ML
pip install torch torchvision tensorflow numpy matplotlib seaborn scikit-learn tqdm pillow

# Entraîner le modèle PyTorch
python -m models.train --model pytorch --epochs 25 --data data

# Entraîner le modèle TensorFlow
python -m models.train --model tensorflow --epochs 25 --data data
```

Structure du dataset attendue :
```
ml/data/
├── seg_train/
│   └── seg_train/
│       ├── buildings/
│       ├── forest/
│       ├── glacier/
│       ├── mountain/
│       ├── sea/
│       └── street/
└── seg_test/
    └── seg_test/
        ├── buildings/
        ├── forest/
        ...
```

---

## API — Endpoint de classification

### `POST /api/classify/`

**Paramètres (form-data) :**

| Paramètre  | Type   | Requis | Description                        |
|------------|--------|--------|------------------------------------|
| image      | file   | Non*   | Fichier image (jpg, png...)        |
| image_url  | string | Non*   | URL d'une image en ligne           |
| model      | string | Non    | `pytorch` (défaut) ou `tensorflow` |

*Au moins `image` ou `image_url` est requis.

**Réponse (200 OK) :**

```json
{
  "predicted_class": "forest",
  "confidence": 0.97,
  "model_used": "pytorch",
  "all_probabilities": [
    { "class": "forest",    "probability": 0.97 },
    { "class": "mountain",  "probability": 0.01 },
    { "class": "glacier",   "probability": 0.01 },
    { "class": "sea",       "probability": 0.01 },
    { "class": "buildings", "probability": 0.00 },
    { "class": "street",    "probability": 0.00 }
  ]
}
```

---

## Fonctionnalités de l'interface

- Upload d'image depuis le disque
- Chargement d'image depuis une URL
- Sélection du modèle (PyTorch CNN / TensorFlow CNN)
- Affichage du résultat avec barre de confiance
- Affichage de toutes les probabilités par classe
- Interface multilingue : **Anglais / Français / Wolof**
- Design responsive avec Material UI

---

## Technologies utilisées

| Couche     | Technologies                                    |
|------------|-------------------------------------------------|
| Frontend   | React 19, Material UI 6, Axios                  |
| Backend    | Django 5, Django REST Framework, drf-yasg       |
| ML         | PyTorch 2.2, TensorFlow 2.16, torchvision, timm |
| Données    | Intel Image Classification (Kaggle)             |
| DevOps     | Docker, Docker Compose                          |

---

## Problèmes fréquents

**Erreur CORS au démarrage du frontend**
→ Vérifie que le backend tourne sur `http://127.0.0.1:8000`

**`Model file not found`**
→ Vérifie que `danielle_model.pth` et/ou `danielle_model.keras` sont bien dans `backend/api/models/`

**`ModuleNotFoundError: No module named 'notifications'`**
→ Lance `manage.py` depuis le dossier `backend/api/` et non depuis `backend/`

**TensorFlow lent au premier chargement**
→ Normal, le modèle est chargé en mémoire à la première requête (lazy loading)

---

## Auteurs

Projet universitaire — Classification d'images Intel — 2026
>>>>>>> b102039 (Initial commit - Intel Image Classifier)