Publish model card, configuration, inference code and checkpoints
Browse files- .gitattributes +1 -0
- README.md +155 -80
- cgd_convnextv2_base_coco2017.ckpt +3 -0
- config.json +8 -3
- example.jpg +3 -0
- model_cgd.py +4 -2
.gitattributes
CHANGED
|
@@ -33,3 +33,4 @@ saved_model/**/* filter=lfs diff=lfs merge=lfs -text
|
|
| 33 |
*.zip filter=lfs diff=lfs merge=lfs -text
|
| 34 |
*.zst filter=lfs diff=lfs merge=lfs -text
|
| 35 |
*tfevents* filter=lfs diff=lfs merge=lfs -text
|
|
|
|
|
|
| 33 |
*.zip filter=lfs diff=lfs merge=lfs -text
|
| 34 |
*.zst filter=lfs diff=lfs merge=lfs -text
|
| 35 |
*tfevents* filter=lfs diff=lfs merge=lfs -text
|
| 36 |
+
example.jpg filter=lfs diff=lfs merge=lfs -text
|
README.md
CHANGED
|
@@ -1,80 +1,155 @@
|
|
| 1 |
-
---
|
| 2 |
-
license: mit
|
| 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 |
-
model
|
| 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 |
-
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
---
|
| 2 |
+
license: mit
|
| 3 |
+
base_model: timm/convnextv2_base.fcmae_ft_in22k_in1k
|
| 4 |
+
tags:
|
| 5 |
+
- image-rotation
|
| 6 |
+
- rotation-estimation
|
| 7 |
+
- orientation-estimation
|
| 8 |
+
- angle-detection
|
| 9 |
+
- circular-gaussian-distribution
|
| 10 |
+
- convnextv2
|
| 11 |
+
- pytorch
|
| 12 |
+
datasets:
|
| 13 |
+
- coco
|
| 14 |
+
metrics:
|
| 15 |
+
- mae
|
| 16 |
+
pipeline_tag: image-classification
|
| 17 |
+
model-index:
|
| 18 |
+
- name: cgd_convnextv2_base_coco2017
|
| 19 |
+
results:
|
| 20 |
+
- task:
|
| 21 |
+
type: image-classification
|
| 22 |
+
name: Image rotation angle estimation
|
| 23 |
+
dataset:
|
| 24 |
+
type: coco
|
| 25 |
+
name: COCO test photos (1,030 images), rotated and saved as JPEG
|
| 26 |
+
metrics:
|
| 27 |
+
- type: mae
|
| 28 |
+
value: 3.77
|
| 29 |
+
name: Mean absolute error (degrees)
|
| 30 |
+
---
|
| 31 |
+
|
| 32 |
+
# Image Rotation Angle Estimation
|
| 33 |
+
|
| 34 |
+
**[Try the interactive demo](https://huggingface.co/spaces/maxwoe/image-rotation-angle-estimation)** | **[GitHub](https://github.com/maxwoe/image-rotation-angle-estimation)** | **[Paper](https://arxiv.org/abs/2603.25351)**
|
| 35 |
+
|
| 36 |
+
Estimates by how many degrees a photo is rotated away from upright, anywhere in the full 360° range, so that it can be turned back.
|
| 37 |
+
On COCO test photos the mean absolute error is 3.77° and 97% of the predictions are within 10°.
|
| 38 |
+
|
| 39 |
+

|
| 40 |
+
|
| 41 |
+
The model is a **ConvNeXt V2 Base** backbone with a **Circular Gaussian Distribution (CGD)** head.
|
| 42 |
+
It outputs a probability distribution over 360 one-degree bins and returns the most probable angle, so there is no discontinuity at 0°/360°.
|
| 43 |
+
|
| 44 |
+
## Usage
|
| 45 |
+
|
| 46 |
+
```bash
|
| 47 |
+
pip install torch torchvision pytorch-lightning timm huggingface_hub pillow numpy loguru
|
| 48 |
+
```
|
| 49 |
+
|
| 50 |
+
```python
|
| 51 |
+
import sys
|
| 52 |
+
from huggingface_hub import snapshot_download
|
| 53 |
+
from PIL import Image
|
| 54 |
+
|
| 55 |
+
# The inference code is part of this repository
|
| 56 |
+
sys.path.insert(0, snapshot_download("maxwoe/image-rotation-angle-estimation", allow_patterns=["*.py"]))
|
| 57 |
+
from model_cgd import CGDAngleEstimation
|
| 58 |
+
|
| 59 |
+
model = CGDAngleEstimation.from_pretrained("maxwoe/image-rotation-angle-estimation")
|
| 60 |
+
|
| 61 |
+
image = Image.open("your_image.jpg")
|
| 62 |
+
angle = model.predict_angle(image) # degrees in [0, 360), counter-clockwise
|
| 63 |
+
print(f"Predicted rotation: {angle:.1f}°")
|
| 64 |
+
|
| 65 |
+
upright = image.rotate(-angle, expand=True) # turn the image back
|
| 66 |
+
```
|
| 67 |
+
|
| 68 |
+
- `predict_angle` accepts a PIL Image, a numpy array or a file path.
|
| 69 |
+
- The angle is measured counter-clockwise: 90° means the image was turned a quarter turn to the left, and rotating it by `-angle` restores it.
|
| 70 |
+
- Inference takes about 0.3 seconds per image on a CPU; call `model.to("cuda")` to use a GPU.
|
| 71 |
+
|
| 72 |
+
## Evaluation
|
| 73 |
+
|
| 74 |
+
1,030 COCO test photos, each rotated by a random angle and cropped to the largest rectangle that contains no border; means over five sets of random angles.
|
| 75 |
+
In the first column the rotated image is saved once as JPEG (quality 90) before the model sees it, which is how rotated photos exist in practice.
|
| 76 |
+
In the second column it is passed to the model without ever being saved.
|
| 77 |
+
|
| 78 |
+
| Metric | Saved as JPEG after rotation | Never saved after rotation |
|
| 79 |
+
|---|---|---|
|
| 80 |
+
| Mean absolute error | 3.77° | 4.45° |
|
| 81 |
+
| Median error | 1.12° | 1.33° |
|
| 82 |
+
| Within 2° | 71.4% | 64.5% |
|
| 83 |
+
| Within 5° | 93.7% | 89.7% |
|
| 84 |
+
| Within 10° | 97.4% | 95.8% |
|
| 85 |
+
| 90th percentile error | 5.45° | 6.74° |
|
| 86 |
+
| 95th percentile error | 14.62° | 17.10° |
|
| 87 |
+
| RMSE | 9.76° | 11.19° |
|
| 88 |
+
|
| 89 |
+
The error is nearly the same across JPEG quality settings (3.87° at quality 95, 3.75° at quality 75).
|
| 90 |
+
The checkpoint is one of three training runs of this configuration, which reach 3.70°, 3.77° and 3.81° (mean 3.76°).
|
| 91 |
+
The strongest earlier model, OAD-360, reaches 6.09° on the same images.
|
| 92 |
+
|
| 93 |
+
## Limitations
|
| 94 |
+
|
| 95 |
+
- **Photos only.** The model was trained and tested on everyday photos (COCO). Documents, scans, screenshots, drawings, aerial and medical images were not evaluated.
|
| 96 |
+
- **Ambiguous images.** Close-ups, textures and symmetric scenes have no clear "up". More than half of the large errors are confusions by 90° or 180° on such images.
|
| 97 |
+
- **Central square.** The image is resized so that its shorter side is 224 pixels and the central 224 x 224 square is used. In a very elongated image the model does not see the ends.
|
| 98 |
+
- **Images never saved after rotation.** Rotations that are applied in memory or kept in a lossless format are slightly outside the training distribution, which is why the error is a little higher in the second column above.
|
| 99 |
+
- **No confidence value.** `predict_angle` returns an angle only, and the probabilities of the model were not evaluated as a measure of confidence.
|
| 100 |
+
|
| 101 |
+
## Checks for Processing Traces
|
| 102 |
+
|
| 103 |
+
A model for this task can score well without looking at the image content: when a decoded JPEG photo is rotated, the 8x8 block grid of the JPEG codec turns with it and reveals the angle.
|
| 104 |
+
This model was trained under the trace-free protocol of the paper, in which every training image is saved as JPEG after rotation, and it was then tested for reliance on such traces:
|
| 105 |
+
|
| 106 |
+
- **Content-free probe.** Noise images without any orientation, with and without a JPEG grid, are rotated and shown to the model, which should then be at chance. It meets both criteria of the probe in six of seven conditions. In the seventh, 14.0% of its predictions land within 5° of the grid angle (chance: 11.1%); the upper confidence bound of this excess is 5.1 points, against a limit of 5 points fixed in advance, so it misses that criterion by 0.1 point.
|
| 107 |
+
- **Cue conflict.** When a grid is stamped at an angle that contradicts the content, the model follows the content; the grid attracts at most 6% of the predictions.
|
| 108 |
+
- **Test photos.** A rotated source grid changes the share of predictions within 2° by -0.4 points, and the interpolation pattern of the rotation by 1.5 points; both are inside the limit of 5 points.
|
| 109 |
+
|
| 110 |
+
The scripts for these checks are in the GitHub repository.
|
| 111 |
+
|
| 112 |
+
## Checkpoints
|
| 113 |
+
|
| 114 |
+
| Checkpoint | Training data | Error, saved as JPEG after rotation | Error, never saved after rotation |
|
| 115 |
+
|---|---|---|---|
|
| 116 |
+
| `cgd_convnextv2_base_coco2017.ckpt` (default) | COCO 2017 | 3.77° | 4.45° |
|
| 117 |
+
| `cgd_mambaout_base_coco2017.ckpt` (legacy) | COCO 2017 | 24.45° | 2.84° |
|
| 118 |
+
| `cgd_mambaout_base_coco2014.ckpt` (legacy) | COCO 2014 | 21.05° | 3.71° |
|
| 119 |
+
|
| 120 |
+
**Do not use the legacy checkpoints for real photos.**
|
| 121 |
+
They were trained on images that were rotated but never saved again, and they learned to read the rotated JPEG grid described above.
|
| 122 |
+
That makes them very precise on images that were never saved after rotation and unreliable on everything else.
|
| 123 |
+
They remain available so that earlier results stay reproducible, and can be loaded with `from_pretrained(..., model_name="cgd_mambaout_base_coco2017.ckpt")`.
|
| 124 |
+
|
| 125 |
+
## Model Details
|
| 126 |
+
|
| 127 |
+
- **Method:** Circular Gaussian Distribution (CGD), 360 bins, sigma = 6.0°, KL divergence against soft Gaussian labels, angle decoded by argmax
|
| 128 |
+
- **Backbone:** ConvNeXt V2 Base (`convnextv2_base.fcmae_ft_in22k_in1k`), pretrained on ImageNet, fine-tuned end to end
|
| 129 |
+
- **Size:** 88 million parameters, 352 MB (weights only)
|
| 130 |
+
- **Input:** 224 x 224 pixels, ImageNet normalization
|
| 131 |
+
- **Training data:** COCO 2017 train split without the test images (117,372 images), 10% held out for validation
|
| 132 |
+
- **Training images:** rotated by a random angle in [0°, 360°), cropped to the largest rectangle without border, saved as JPEG at a random quality between 40 and 90; the interpolation method of the rotation is drawn at random
|
| 133 |
+
- **Optimizer:** AdamW, learning rate reduced on plateau, early stopping
|
| 134 |
+
|
| 135 |
+
## Paper and Citation
|
| 136 |
+
|
| 137 |
+
The method comparison behind this model is described in [Image Rotation Angle Estimation: Comparing Circular-Aware Methods](https://arxiv.org/abs/2603.25351).
|
| 138 |
+
The current arXiv version predates the trace-free protocol: its COCO results (for example 2.84°) are those of the legacy checkpoints.
|
| 139 |
+
An updated version is in preparation.
|
| 140 |
+
|
| 141 |
+
```bibtex
|
| 142 |
+
@misc{woehrer2026irae,
|
| 143 |
+
title={Image Rotation Angle Estimation: Comparing Circular-Aware Methods},
|
| 144 |
+
author={Woehrer, Maximilian},
|
| 145 |
+
year={2026},
|
| 146 |
+
eprint={2603.25351},
|
| 147 |
+
archivePrefix={arXiv},
|
| 148 |
+
primaryClass={cs.CV},
|
| 149 |
+
url={https://arxiv.org/abs/2603.25351}
|
| 150 |
+
}
|
| 151 |
+
```
|
| 152 |
+
|
| 153 |
+
## License
|
| 154 |
+
|
| 155 |
+
MIT
|
cgd_convnextv2_base_coco2017.ckpt
ADDED
|
@@ -0,0 +1,3 @@
|
|
|
|
|
|
|
|
|
|
|
|
|
| 1 |
+
version https://git-lfs.github.com/spec/v1
|
| 2 |
+
oid sha256:6b79eaff257f94b5bca1fc4e2bb3c25f757d45e20c84be24ac319760e610a8f0
|
| 3 |
+
size 352404164
|
config.json
CHANGED
|
@@ -1,15 +1,20 @@
|
|
| 1 |
{
|
| 2 |
"models": {
|
| 3 |
-
"CGD +
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
| 4 |
"filename": "cgd_mambaout_base_coco2017.ckpt",
|
| 5 |
"architecture": "mambaout_base.in1k",
|
| 6 |
"input_size": 224
|
| 7 |
},
|
| 8 |
-
"CGD + MambaOut Base (COCO 2014
|
| 9 |
"filename": "cgd_mambaout_base_coco2014.ckpt",
|
| 10 |
"architecture": "mambaout_base.in1k",
|
| 11 |
"input_size": 224
|
| 12 |
}
|
| 13 |
},
|
| 14 |
-
"default_model": "CGD +
|
| 15 |
}
|
|
|
|
| 1 |
{
|
| 2 |
"models": {
|
| 3 |
+
"CGD + ConvNeXt V2 Base (COCO 2017, trace-free protocol)": {
|
| 4 |
+
"filename": "cgd_convnextv2_base_coco2017.ckpt",
|
| 5 |
+
"architecture": "convnextv2_base.fcmae_ft_in22k_in1k",
|
| 6 |
+
"input_size": 224
|
| 7 |
+
},
|
| 8 |
+
"Legacy: CGD + MambaOut Base (COCO 2017, conventional protocol)": {
|
| 9 |
"filename": "cgd_mambaout_base_coco2017.ckpt",
|
| 10 |
"architecture": "mambaout_base.in1k",
|
| 11 |
"input_size": 224
|
| 12 |
},
|
| 13 |
+
"Legacy: CGD + MambaOut Base (COCO 2014, conventional protocol)": {
|
| 14 |
"filename": "cgd_mambaout_base_coco2014.ckpt",
|
| 15 |
"architecture": "mambaout_base.in1k",
|
| 16 |
"input_size": 224
|
| 17 |
}
|
| 18 |
},
|
| 19 |
+
"default_model": "CGD + ConvNeXt V2 Base (COCO 2017, trace-free protocol)"
|
| 20 |
}
|
example.jpg
ADDED
|
Git LFS Details
|
model_cgd.py
CHANGED
|
@@ -126,7 +126,9 @@ class CGDAngleEstimation(pl.LightningModule):
|
|
| 126 |
self.inference_method = inference_method
|
| 127 |
self.loss_type = loss_type
|
| 128 |
|
| 129 |
-
|
|
|
|
|
|
|
| 130 |
self.cgd = CircularGaussianDistribution(num_bins=num_bins, sigma=sigma)
|
| 131 |
|
| 132 |
@classmethod
|
|
@@ -216,7 +218,7 @@ class CGDAngleEstimation(pl.LightningModule):
|
|
| 216 |
transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])
|
| 217 |
])
|
| 218 |
|
| 219 |
-
image_tensor = transform(image).unsqueeze(0)
|
| 220 |
|
| 221 |
with torch.no_grad():
|
| 222 |
pred_distributions = self(image_tensor)
|
|
|
|
| 126 |
self.inference_method = inference_method
|
| 127 |
self.loss_type = loss_type
|
| 128 |
|
| 129 |
+
# inference only: every weight comes from the checkpoint, so the ImageNet weights
|
| 130 |
+
# of the backbone are not downloaded
|
| 131 |
+
self.model = timm.create_model(model_name, pretrained=False, num_classes=num_bins)
|
| 132 |
self.cgd = CircularGaussianDistribution(num_bins=num_bins, sigma=sigma)
|
| 133 |
|
| 134 |
@classmethod
|
|
|
|
| 218 |
transforms.Normalize(mean=[0.485, 0.456, 0.406], std=[0.229, 0.224, 0.225])
|
| 219 |
])
|
| 220 |
|
| 221 |
+
image_tensor = transform(image).unsqueeze(0).to(self.device)
|
| 222 |
|
| 223 |
with torch.no_grad():
|
| 224 |
pred_distributions = self(image_tensor)
|