Create readme.md

readme.md

@@ -0,0 +1,80 @@
+# Sport Classification Comparison
+
+This app compares 3 image classification approaches on sports images:
+
+- Fine-tuned transfer learning model (`sports-vit-transfer-improved`)
+- Zero-shot CLIP (`openai/clip-vit-large-patch14`)
+- OpenAI vision model (LLM image classification)
+
+## Dataset Used For Training
+
+- Custom dataset loaded with Hugging Face `imagefolder`
+- Local dataset structure: `data/sports/train` and `data/sports/test`
+- Classes: `football`, `tennis`, `golf`, `baseball`, `basketball`
+- Number of classes: `5`
+- Train split used for learning, test split used as validation during training
+
+## Preprocessing Steps
+
+- Convert images to RGB
+- Resize/crop to the backbone input size
+- Normalize with the backbone mean/std values
+- Training augmentation:
+  - RandomResizedCrop
+  - RandomHorizontalFlip
+  - RandomRotation
+  - ColorJitter
+- Backbone frozen for the final improved model to stabilize training on the small dataset
+
+## Trained Model
+
+- Hugging Face model link: [https://huggingface.co/ochsncon/sport-vit-transfer](https://huggingface.co/ochsncon/sport-vit-transfer)
+- Local training output folder: `sports-vit-transfer-improved`
+- Base model: `microsoft/resnet-18`
+
+## Training Performance
+
+The table below shows the improved training run on the sports dataset.
+
+| Training Loss | Epoch | Step | Validation Loss | Accuracy |
+|---:|---:|---:|---:|---:|
+| 1.7275 | 1.82 | 20 | 1.6322 | 0.1905 |
+| 1.4909 | 5.45 | 60 | 1.2697 | 0.5952 |
+| 1.3534 | 10.91 | 120 | 0.9794 | 0.7619 |
+| 1.2263 | 14.55 | 160 | 0.9674 | 0.8810 |
+| 1.2805 | 20.00 | 220 | 0.9006 | 0.9048 |
+
+Final validation accuracy: `0.9048`
+
+## Example Image Results
+
+The table below reports the true class and Top-3 predictions for the custom model and CLIP.
+
+| Image | True Class | Custom Model Top-3 (score) | CLIP Top-3 (score) | OpenAI LLM (label, confidence) |
+|---|---|---|---|---|
+| `example_images/baseball.jpg` | baseball | `baseball` (0.787038)<br>`football` (0.083003)<br>`tennis` (0.063252) | `baseball` (0.982466)<br>`cricket` (0.007831)<br>`athletics` (0.007332) | `baseball` (1.0) |
+| `example_images/basketball.jpg` | basketball | `basketball` (0.651632)<br>`football` (0.190022)<br>`baseball` (0.078006) | `basketball` (0.985004)<br>`handball` (0.008034)<br>`athletics` (0.006052) | `basketball` (1.0) |
+| `example_images/football.jpg` | football | `football` (0.586812)<br>`baseball` (0.252700)<br>`basketball` (0.099161) | `football` (0.935547)<br>`handball` (0.049766)<br>`athletics` (0.007480) | `football` (1.0) |
+| `example_images/golf.jpg` | golf | `golf` (0.569676)<br>`baseball` (0.206489)<br>`tennis` (0.099076) | `golf` (0.996420)<br>`badminton` (0.001648)<br>`cricket` (0.000783) | `golf` (1.0) |
+| `example_images/tennis.jpg` | tennis | `tennis` (0.363185)<br>`football` (0.318908)<br>`basketball` (0.141583) | `tennis` (0.983747)<br>`badminton` (0.008469)<br>`table tennis` (0.005272) | `tennis` (1.0) |
+
+Note: These values are taken from the current Space output and can be extended with additional test runs if desired.
+
+## Links to Model and App
+
+Fill in these fields after upload:
+
+- Hugging Face Model: `https://huggingface.co/ochsncon/sport-vit-transfer`
+- Hugging Face Space: `https://huggingface.co/spaces/ochsncon/sport-classification`
+
+## Comparison Results
+
+The results below summarize the three-model comparison used in the app.
+
+| Image | True Label | Custom Model (Top-1, Score) | CLIP (Top-1, Score) | OpenAI (Label, Confidence) |
+|---|---|---|---|---|
+| `example_images/baseball.jpg` | baseball | baseball (0.7870) | baseball (0.9825) | baseball (0.99) |
+| `example_images/basketball.jpg` | basketball | basketball (0.6516) | basketball (0.9850) | basketball (1.0) |
+| `example_images/football.jpg` | football | football (0.5868) | football (0.9355) | football (1.0) |
+| `example_images/golf.jpg` | golf | golf (0.5697) | golf (0.9964) | golf (0.95) |
+| `example_images/tennis.jpg` | tennis | tennis (0.3632) | tennis (0.9837) | tennis (0.98) |