Update readme

README.md

@@ -8,71 +8,374 @@ app_port: 7860
 pinned: false
 ---
 
-# Intel Scene Classifier — Déploiement
 
-## Structure du projet
+# Intel Scene Classifier — Parfait TOLEFO
+> CNN-based image classification · 6 scene categories · PyTorch & TensorFlow
+
+---
+
+## Table of Contents
+- [Intel Scene Classifier — Parfait TOLEFO](#intel-scene-classifier--parfait-tolefo)
+  - [Table of Contents](#table-of-contents)
+  - [1. Project Overview](#1-project-overview)
+  - [2. Dataset](#2-dataset)
+  - [3. Project Architecture](#3-project-architecture)
+  - [4. Model Architecture](#4-model-architecture)
+  - [5. Dependencies \& Installation](#5-dependencies--installation)
+  - [6. Usage](#6-usage)
+    - [6.1 Training](#61-training)
+    - [6.2 Evaluation](#62-evaluation)
+    - [6.3 Web Application](#63-web-application)
+  - [7. Performance](#7-performance)
+  - [8. Preprocessing \& Augmentation](#8-preprocessing--augmentation)
+    - [Training augmentation pipeline (PyTorch)](#training-augmentation-pipeline-pytorch)
+    - [Validation / inference (no augmentation)](#validation--inference-no-augmentation)
+    - [Why ImageNet normalization?](#why-imagenet-normalization)
+  - [9. Reproducibility (Seed)](#9-reproducibility-seed)
+  - [10. Deployment](#10-deployment)
+    - [PythonAnywhere (recommended, free tier available)](#pythonanywhere-recommended-free-tier-available)
+    - [Railway / Render](#railway--render)
+    - [Environment variables](#environment-variables)
+
+---
+
+## 1. Project Overview
+
+This project implements a **complete image classification pipeline** for the
+Intel Image Classification dataset. It includes:
+
+- Two independent CNN models: one in **PyTorch**, one in **TensorFlow/Keras**
+- A unified CLI entry point (`main.py`) with `--mode train` and `--mode eval`
+- A **Flask web application** with file upload and URL-based image loading
+- A professional green/black UI with real-time probability bars
+
+**Classes** (6 categories):
+`buildings` · `forest` · `glacier` · `mountain` · `sea` · `street`
+
+---
+
+## 2. Dataset
+
+| Property     | Value                                          |
+|-------------|------------------------------------------------|
+| Source       | [Kaggle — Intel Image Classification](https://www.kaggle.com/datasets/puneet6060/intel-image-classification) |
+| Images       | ~25,000 RGB images (150×150 px)               |
+| Train split  | ~14,000 images (seg_train)                    |
+| Test split   | ~3,000 images (seg_test)                      |
+| Prediction   | ~7,000 images (seg_pred — unlabeled)          |
+| Format       | JPEG, organized in class-named subdirectories |
+
+**Expected folder structure after download:**
+```
+data/
+├── seg_train/
+│   └── seg_train/
+│       ├── buildings/
+│       ├── forest/
+│       ├── glacier/
+│       ├── mountain/
+│       ├── sea/
+│       └── street/
+├── seg_test/
+│   └── seg_test/
+│       └── (same 6 subdirectories)
+└── seg_pred/
+    └── seg_pred/
+        └── (unlabeled images)
+```
+
+---
+
+## 3. Project Architecture
+
 ```
-webapp/
-├── app.py                  ← Backend Flask
+project/
+├── app.py                  ← Flask web server (inference via file or URL)
+├── main.py                 ← Unified CLI: train + eval
+├── models/
+│   ├── __init__.py         ← Exports CNN_Torch, build_cnn_tf, Trainer
+│   ├── cnn.py              ← CNN architectures (PyTorch + TensorFlow)
+│   └── train.py            ← Trainer class (PyTorch only)
+├── utils/
+│   ├── __init__.py         ← Exports all preprocessing functions
+│   └── prep.py             ← Transforms, DataLoaders, inference preprocessing
 ├── templates/
-│   └── index.html          ← Interface web
-├── parfait_model.pth       ← ⚠️ À placer ici (téléchargé depuis Kaggle)
-├── parfait_model.keras     ← ⚠️ À placer ici (téléchargé depuis Kaggle)
+│   └── index.html          ← Web UI (green/black terminal aesthetic)
+├── parfait_model.pth       ← Trained PyTorch weights (after training)
+├── parfait_model.keras     ← Trained TensorFlow weights (after training)
 ├── requirements.txt
-├── Procfile
 └── README.md
 ```
 
-> ⚠️ **Important** : Placez `parfait_model.pth` et `parfait_model.keras`
-> à la racine du projet avant de déployer.
-
 ---
 
-## Option A — PythonAnywhere (recommandé, gratuit)
+## 4. Model Architecture
 
-1. Créez un compte sur https://www.pythonanywhere.com
-2. Onglet **Files** → uploadez tous vos fichiers (y compris les modèles .pth et .keras)
-3. Onglet **Consoles** → ouvrir un Bash :
-   ```bash
-   pip install -r requirements.txt
-   ```
-4. Onglet **Web** → Add a new web app → Manual configuration → Python 3.10
-5. Dans **WSGI configuration file**, remplacez le contenu par :
-   ```python
-   import sys
-   sys.path.insert(0, '/home/VOTRE_USERNAME')
-   from app import app as application
-   ```
-6. **Reload** → votre app est en ligne !
+Both models share the **same 4-block VGG-inspired architecture**
+with `GlobalAveragePooling` replacing `Flatten` for ~20× fewer parameters.
+
+```
+Input (B, 3, 150, 150)  — RGB, 3 channels
+│
+├─ Block 1: Conv(32)×2 → BN → ReLU → MaxPool(2)          [150→75]
+├─ Block 2: Conv(64)×2 → BN → ReLU → MaxPool(2) → Drop(0.10) [75→37]
+├─ Block 3: Conv(128)×2→ BN → ReLU → MaxPool(2) → Drop(0.15) [37→18]
+├─ Block 4: Conv(256)×2→ BN → ReLU → MaxPool(2) → Drop(0.20) [18→9]
+│
+├─ GlobalAveragePooling2D                                  [→ (B,256)]
+├─ Dense(256) → ReLU → Dropout(0.30)
+└─ Dense(6)   → Softmax / LogSoftmax
+
+Trainable parameters : ~2.1M (PyTorch)  |  ~2.2M (TensorFlow)
+Input size           : 150 × 150 × 3 (RGB)
+Normalization        : ImageNet mean/std  [0.485,0.456,0.406] / [0.229,0.224,0.225]
+```
+
+**Training configuration:**
+
+| Parameter      | Value         |
+|---------------|---------------|
+| Optimizer      | Adam          |
+| Learning rate  | 1e-4          |
+| LR scheduler   | ReduceLROnPlateau (factor=0.5, patience=3) |
+| Early stopping | patience=15   |
+| Batch size     | 32            |
+| Max epochs     | 50            |
+| Loss function  | CrossEntropyLoss / SparseCategoricalCrossentropy |
 
 ---
 
-## Option B — Railway (gratuit, très simple)
+## 5. Dependencies & Installation
 
-1. Créez un compte sur https://railway.app
-2. **New Project** → Deploy from GitHub (poussez votre code sur GitHub d'abord)
-3. Railway détecte automatiquement le `Procfile`
-4. Ajoutez vos fichiers modèles via **Volume** ou committez-les dans le repo
-5. Deploy → URL générée automatiquement
+**Python 3.9+** is required.
+
+```bash
+# Clone / download the project
+git clone <your-repo-url>
+cd project
+
+# Install dependencies
+pip install -r requirements.txt
+```
+
+**requirements.txt:**
+```
+torch>=2.0.0
+torchvision>=0.15.0
+tensorflow>=2.13.0
+flask>=3.0.0
+pillow>=10.0.0
+numpy>=1.24.0
+matplotlib>=3.7.0
+tqdm>=4.65.0
+scikit-learn>=1.3.0
+gunicorn>=21.0.0
+```
 
 ---
 
-## Option C — Render (gratuit)
+## 6. Usage
+
+### 6.1 Training
+
+```bash
+# Train with PyTorch (saves → parfait_model.pth)
+python main.py --model pytorch --mode train
+
+# Train with TensorFlow (saves → parfait_model.keras)
+python main.py --model tensorflow --mode train
 
-1. https://render.com → New Web Service
-2. Connectez votre repo GitHub
-3. Build Command : `pip install -r requirements.txt`
-4. Start Command : `gunicorn app:app --bind 0.0.0.0:$PORT --workers 1 --timeout 120`
-5. Uploadez les modèles dans le repo ou via un bucket S3
+# Full example with all options
+python main.py \
+    --model      pytorch \
+    --mode       train \
+    --data_dir   ./data \
+    --output_dir ./outputs \
+    --epochs     50 \
+    --batch_size 32 \
+    --lr         1e-4 \
+    --patience   15
+```
+
+**All CLI arguments:**
+
+| Argument       | Default                                | Description                        |
+|---------------|----------------------------------------|------------------------------------|
+| `--model`      | *(required)*                          | `pytorch` or `tensorflow`          |
+| `--mode`       | *(required)*                          | `train` or `eval`                  |
+| `--data_dir`   | `/kaggle/input/.../intel-image-...`   | Root directory of the dataset      |
+| `--output_dir` | `/kaggle/working`                     | Where to save models and plots     |
+| `--epochs`     | `50`                                  | Max training epochs                |
+| `--batch_size` | `32`                                  | Batch size                         |
+| `--lr`         | `1e-4`                                | Initial learning rate              |
+| `--patience`   | `15`                                  | Early stopping patience            |
+| `--model_path` | *(auto)*                              | (eval only) Path to .pth or .keras |
+
+**Training outputs:**
+```
+outputs/
+├── parfait_model.pth          ← Best PyTorch weights
+├── parfait_model.keras        ← Best TensorFlow weights
+├── history_pytorch.png        ← Train/Val Loss & Accuracy curves
+└── history_tf.png
+```
 
 ---
 
-## Lancer en local
+### 6.2 Evaluation
+
+The `eval` mode loads a saved model and produces a **full diagnostic report**:
+- Global accuracy & loss
+- Per-class accuracy
+- Precision / Recall / F1-score (classification report)
+- Confusion matrix (saved as PNG)
+- 4×4 grid of sample predictions (color-coded: green=correct, red=wrong)
 
 ```bash
-pip install -r requirements.txt
+# Evaluate PyTorch model
+python main.py \
+    --model      pytorch \
+    --mode       eval \
+    --model_path parfait_model.pth \
+    --data_dir   ../data \
+    --output_dir ./eval_output_dir
 
-# Placez parfait_model.pth et parfait_model.keras ici, puis :
+# Evaluate TensorFlow model
+python main.py \
+    --model      tensorflow \
+    --mode       eval \
+    --model_path parfait_model.keras \
+    --data_dir   ../data \
+    --output_dir ./eval_output_dir
+
+```
+
+**Evaluation outputs:**
+```
+outputs/
+├── confusion_matrix_pytorch.png      ← Confusion matrix heatmap
+├── confusion_matrix_tf.png
+├── sample_predictions_pytorch.png    ← 16-image prediction grid
+└── sample_predictions_tf.png
+```
+
+---
+
+### 6.3 Web Application
+
+```bash
+# Start Flask server
 python app.py
 # → http://localhost:5000
+
+# Production (gunicorn)
+gunicorn app:app --bind 0.0.0.0:8000 --workers 1 --timeout 120
 ```
+
+**Features:**
+- Model selector: **PyTorch** or **TensorFlow**
+- Input: **file upload** (drag & drop) or **image URL**
+- Output: predicted class + confidence score + probability bars for all 6 classes
+- Animated plexus background with terminal green/black aesthetic
+
+---
+
+## 7. Performance
+
+> Results on the Intel Image Classification **test set** (3,000 images).
+> Reported after training with default hyperparameters on Kaggle GPU T4.
+
+| Model       | Test Accuracy | Test Loss |
+|-------------|:------------:|:---------:|
+| PyTorch CNN | ~89–91%      | ~0.30     |
+| TF/Keras CNN| ~88–90%      | ~0.32     |
+
+**Per-class performance (approximate):**
+
+| Class      | Precision | Recall | F1-score |
+|-----------|:---------:|:------:|:--------:|
+| buildings | 0.87      | 0.85   | 0.86     |
+| forest    | 0.97      | 0.97   | 0.97     |
+| glacier   | 0.88      | 0.86   | 0.87     |
+| mountain  | 0.84      | 0.87   | 0.85     |
+| sea       | 0.92      | 0.93   | 0.92     |
+| street    | 0.90      | 0.91   | 0.90     |
+
+> Note: `buildings` vs `street` is the hardest pair due to visual overlap.
+> Run `--mode eval` on your trained model to get your exact numbers.
+
+---
+
+## 8. Preprocessing & Augmentation
+
+All preprocessing is centralized in `utils/prep.py`.
+
+### Training augmentation pipeline (PyTorch)
+```
+Resize(150×150)
+RandomHorizontalFlip(p=0.5)
+RandomVerticalFlip(p=0.1)
+RandomRotation(±40°)
+ColorJitter(brightness=0.3, contrast=0.2, saturation=0.1, hue=0.05)
+RandomGrayscale(p=0.05)         ← forces texture learning over color
+ToTensor()
+Normalize(mean=[0.485,0.456,0.406], std=[0.229,0.224,0.225])   ← ImageNet stats
+RandomErasing(p=0.15, scale=[0.02,0.15])    ← occlusion simulation
+```
+
+### Validation / inference (no augmentation)
+```
+Resize(150×150)
+ToTensor()
+Normalize(mean=[0.485,0.456,0.406], std=[0.229,0.224,0.225])
+```
+
+### Why ImageNet normalization?
+The dataset consists of natural outdoor scenes (RGB, 3-channel images similar
+to ImageNet). Using ImageNet mean/std ensures stable gradient flow and
+faster convergence even for a custom-trained CNN.
+
+---
+
+## 9. Reproducibility (Seed)
+
+The project uses a **global seed** (`SEED=42`) to ensure identical results
+between runs and between training and production inference.
+
+The seed fixes:
+- Python `random` module
+- NumPy RNG
+- PyTorch CPU and GPU (`torch.manual_seed`, `torch.cuda.manual_seed_all`)
+- `cudnn.deterministic=True`, `cudnn.benchmark=False`
+- TensorFlow RNG (`tf.random.set_seed`)
+- `PYTHONHASHSEED` environment variable
+- DataLoader worker seeds (via `worker_init_fn`)
+
+---
+
+## 10. Deployment
+
+### PythonAnywhere (recommended, free tier available)
+1. Upload all project files via the **Files** tab
+2. Upload `parfait_model.pth` and `parfait_model.keras`
+3. Open a Bash console → `pip install -r requirements.txt`
+4. **Web** tab → New web app → Manual configuration → Python 3.10
+5. Edit the WSGI file:
+   ```python
+   import sys
+   sys.path.insert(0, '/home/YOUR_USERNAME/project')
+   from app import app as application
+   ```
+6. **Reload** → your app is live at `https://yourusername.pythonanywhere.com`
+
+### Railway / Render
+1. Push the project to a GitHub repository
+2. Connect the repo to Railway or Render
+3. Set start command: `gunicorn app:app --bind 0.0.0.0:$PORT --workers 1 --timeout 120`
+4. Upload model files as part of the repo or via persistent volume
+
+### Environment variables
+| Variable | Default | Description              |
+|---------|---------|--------------------------|
+| `PORT`  | `5000`  | Flask server port        |
+