README.md

---
license: mit
language:
- en
library_name: pytorch
pipeline_tag: image-classification
tags:
- image-classification
- pytorch
- resnet
- transfer-learning
- medical-imaging
- dentistry
- oral-health
- computer-vision
datasets:
- nsr51324/Oral_Diseases
metrics:
- accuracy
- f1
- precision
- recall
model-index:
- name: Oral_Diseases_Image_Classification
  results:
  - task:
      type: image-classification
      name: Image Classification
    dataset:
      type: nsr51324/Oral_Diseases
      name: Oral Diseases
    metrics:
    - type: accuracy
      value: 0.9477
      name: Test Accuracy
    - type: f1
      value: 0.9411
      name: Test F1 (macro)
---

<div align="center">

# 🦷 Oral Diseases Image Classification

**ResNet50 fine-tuned to classify 6 intraoral conditions from a single photo — benchmarked against 3 other architectures, evaluated on a held-out test set.**

[![Dataset](https://img.shields.io/badge/🤗%20Dataset-Oral__Diseases-blue)](https://huggingface.co/datasets/nsr51324/Oral_Diseases)
[![License](https://img.shields.io/badge/License-MIT-green)](#license)

### 🏆 94.77% Accuracy · 0.9411 F1-Score (macro)

</div>

---

## Model Description

This repository hosts the winning checkpoint from a 4-way benchmark of image classifiers trained to recognize intraoral conditions:

**Calculus · Caries · Gingivitis · Ulcers · Tooth Discoloration · Hypodontia**

Four architectures were trained under identical conditions (same data split, same augmentation, same evaluation protocol) and compared on a test set none of them saw during training:

| Rank | Model | Params (trainable) | Test Accuracy | Test F1 (macro) |
|:---:|---|---:|:---:|:---:|
| 🥇 | **ResNet50** *(this checkpoint)* | 23,520,326 | **94.77%** | **0.9411** |
| 🥈 | DenseNet121 | 6,960,006 | 94.51% | 0.9351 |
| 🥉 | EfficientNet-B0 | 4,015,234 | 94.17% | 0.9335 |
| 4 | ScratchCNN (no pretraining) | 11,179,590 | 83.45% | 0.8236 |

ResNet50 (ImageNet-pretrained, fine-tuned in two stages — freeze then unfreeze) came out on top and is the model served by `Gradio.py` and packaged as `checkpoints/best_model.pth`.

## Intended Use & Limitations

This model is a **research and educational tool** for preliminary visual screening. It is **not a certified diagnostic device** and must not be used to replace examination by a licensed dentist or physician. Performance depends on image quality and lighting similar to the training data, and may not generalize to conditions or populations outside the training distribution.

## Files in this Repository

| Path | Description |
|---|---|
| `checkpoints/best_model.pth` | Final ResNet50 checkpoint — a dict with `state_dict`, `model_name`, `class_names`, and `test_f1`. |
| `checkpoints/` | Also contains the individually saved weights for the other 3 models trained in the same run. |
| `notebooks/` | The full training notebook — data prep, transforms, model definitions, training loop, evaluation. |
| `outputs/` | `models_comparison.csv`, per-model loss/accuracy curves, and confusion matrices. |
| `Gradio.py` | Standalone web demo — upload an image, get the predicted class, confidence, and full probability breakdown. |

## How to Use

### Load directly with `huggingface_hub`

```python
from huggingface_hub import hf_hub_download
import torch

weights_path = hf_hub_download(
    repo_id="nsr51324/Oral_Diseases_Image_Classification",
    filename="checkpoints/best_model.pth"
)

checkpoint = torch.load(weights_path, map_location="cpu")
class_names = checkpoint["class_names"]
```

### Rebuild the model and run inference

```python
import torch.nn as nn
from torchvision.models import resnet50
from torchvision import transforms
from PIL import Image

model = resnet50(weights=None)
model.fc = nn.Sequential(
    nn.Dropout(0.3),
    nn.Linear(model.fc.in_features, len(class_names))
)
model.load_state_dict(checkpoint["state_dict"])
model.eval()

transform = transforms.Compose([
    transforms.Resize((224, 224)),
    transforms.ToTensor(),
    transforms.Normalize([0.485, 0.456, 0.406], [0.229, 0.224, 0.225]),
])

image = Image.open("sample.jpg").convert("RGB")
tensor = transform(image).unsqueeze(0)

with torch.no_grad():
    probs = torch.softmax(model(tensor), dim=1)[0]

pred = class_names[probs.argmax().item()]
print(f"{pred}: {probs.max().item()*100:.2f}%")
```

### Run the interactive demo

```bash
pip install torch torchvision gradio pillow huggingface_hub
python Gradio.py
```

Point `MODEL_PATH` at the top of `Gradio.py` to your local copy of `checkpoints/best_model.pth`.

## Training Data

Trained on **[nsr51324/Oral_Diseases](https://huggingface.co/datasets/nsr51324/Oral_Diseases)**, sourced from the [Oral Diseases dataset on Kaggle](https://www.kaggle.com/datasets/salmansajid05/oral-diseases) (salmansajid05), split 80/10/10 (train/val/test) with stratification to preserve class balance across all three sets.

## Training Procedure

- **Image size:** 224×224 · **Batch size:** 32 · **Epochs:** up to 30 (early stopping)
- **Two-stage fine-tuning:** backbone frozen for 5 epochs (head-only training, `lr=1e-3`), then fully unfrozen for fine-tuning at `lr=1e-5`
- **Regularization:** dropout (0.4), weight decay (1e-4), label smoothing (0.1), early stopping on validation loss
- **Augmentation** (train split only): random resized crop, horizontal flip, rotation, color jitter, random erasing

## Evaluation

Full classification report, confusion matrix, and training curves for all 4 models are in `outputs/`. Summary metrics are in `outputs/models_comparison.csv`.

## Disclaimer

This model is provided for research and educational purposes only. It is not intended for clinical decision-making. Always consult a qualified healthcare professional for medical diagnosis.

## License

MIT. The underlying dataset has its own terms — see the [dataset card](https://huggingface.co/datasets/nsr51324/Oral_Diseases) before commercial use.

## Author

**Nasr Mohamed** — AI Engineer
[🤗 huggingface.co/nsr51324](https://huggingface.co/nsr51324)