File size: 4,638 Bytes
5e2f346 7f802a1 5e2f346 fc212d6 d0000f0 9687be0 925f626 7f802a1 5e2f346 a73d4d4 5e2f346 a73d4d4 5e2f346 97987d0 5e2f346 80e4e04 5e2f346 80e4e04 5e2f346 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 | ---
license: apache-2.0
tags:
- image-classification
- rotation-prediction
- resnet
- pytorch
- vision
datasets:
- ILSVRC/imagenet-1k
pipeline_tag: image-classification
library_name: transformers
---
# 🔄 GyroScope — Image Rotation Prediction
**GyroScope** is a ResNet-18 trained **from scratch** to detect whether an image is rotated by **0°, 90°, 180°, or 270°** — and correct it automatically.
> Is that photo upside down? Let GyroScope figure it out.
---
## 🎯 Task
Given any image, GyroScope classifies its orientation into one of **4 classes**:
| Label | Meaning | Correction |
|-------|---------|------------|
| 0 | 0° — upright ✅ | None |
| 1 | 90° CCW | Rotate 270° CCW |
| 2 | 180° — upside down | Rotate 180° |
| 3 | 270° CCW (= 90° CW) | Rotate 90° CCW |
**Correction formula:** `correction = (360 − detected_angle) % 360`
---
## 📊 Benchmarks
Trained on **50,000 images** from [ImageNet-1k](https://huggingface.co/datasets/ILSVRC/imagenet-1k) × 4 rotations = **200k training samples**.
Validated on **5,000 images** × 4 rotations = **20k validation samples**.
| Metric | Value |
|--------|-------|
| **Overall Val Accuracy** | **79.81%%** |
| Per-class: 0° (upright) | 79.8% |
| Per-class: 90° CCW | 80.1% |
| Per-class: 180° | 79.4% |
| Per-class: 270° CCW | 79.8% |
| Training Epochs | 12 |
| Training Time | ~4h (Kaggle T4 GPU) |
### Training Curve
| Epoch | Train Acc | Val Acc |
|-------|----------|---------|
| 1 | 41.4% | 43.2% |
| 2 | 52.0% | 46.9% |
| 3 | 59.4% | 62.8% |
| 4 | 64.1% | 66.0% |
| 5 | 67.8% | 69.48% |
| 6 | 70.6% | 72.22% |
| 7 | 73.3% | 74.25% |
| 8 | 75.6% | 76.49% |
| 9 | 77.5% | 77.47% |
| 10 | 79.1% | 79.47% |
| 11 | 80.3% | 79.78% |
| 12 | 80.9% | 79.81% |
---
## 🏗️ Architecture
| Detail | Value |
|--------|-------|
| Base | ResNet-18 (from scratch, **no pretrained weights**) |
| Parameters | 11.2M |
| Input | 224 × 224 RGB |
| Output | 4 classes (0°, 90°, 180°, 270°) |
| Framework | 🤗 Hugging Face Transformers (`ResNetForImageClassification`) |
### Training Details
- **Optimizer:** AdamW (lr=1e-3, weight_decay=0.05)
- **Scheduler:** Cosine annealing with 1-epoch linear warmup
- **Loss:** CrossEntropy with label smoothing (0.1)
- **Augmentations:** RandomCrop, ColorJitter, RandomGrayscale, RandomErasing
- **⚠️ No flips** — horizontal/vertical flips would corrupt rotation labels
- **Mixed precision:** FP16 via `torch.cuda.amp`
---
## 🚀 Quick Start
### Installation
```bash
pip install transformers torch torchvision pillow requests
```
### Inference — Single Image from URL
```bash
python3 use_with_UI.py
```
--> Download `use_with_UI.py` first 😄
## 💡 Example
Input (rotated 180°):
GyroScope Output:
**📐 Recognized: 90° | Correction: 270°**
**📊 Probs: {'0°': '0.0257', '90°': '0.8706', '180°': '0.0735', '270°': '0.0300'}**
<br>
Corrected:
*Original Image Source: [Link to Pexels](https://www.pexels.com/de-de/foto/ruhiger-schlaf-einer-getigerten-hauskatze-auf-einem-sofa-32441547/)*
## ⚠️ Limitations
- Rotationally symmetric images (balls, textures, patterns) are inherently ambiguous — no model can reliably classify these.
- Trained on natural images (ImageNet). Performance may degrade on:
- Documents / text-heavy images
- Medical imaging
- Satellite / aerial imagery
- Abstract art
Only handles 90° increments — arbitrary angles (e.g. 45° or 135°) are **not supported**!
Trained from scratch on 50k images — a pretrained backbone would likely yield higher accuracy (Finetuning).
## 📝 Use Cases
- 📸 Photo management — auto-correct phone/camera orientation
- 🗂️ Data preprocessing — fix rotated images in scraped datasets
- 🤖 ML pipelines — orientation normalization before feeding to downstream models
- 🖼️ Digital archives — batch-correct scanned/uploaded images
> Yesterday, I was sorting photos and like every photo was rotated wrong! This inspired me to make this tool 😂
## 💻 Training code
The full training code can be found in `train.py`. Have fun 😊
## 📜 License
Apache 2.0
## 🙏 Acknowledgments
- Dataset: ILSVRC/ImageNet-1k
- Architecture: Microsoft ResNet via 🤗 Transformers
- Trained on Kaggle (Tesla T4 GPU)
---
> GyroScope — because every image deserves to stand upright. |