maxwoe commited on
Commit
e5bed11
·
verified ·
1 Parent(s): cd023dd

Publish model card, configuration, inference code and checkpoints

Browse files
Files changed (6) hide show
  1. .gitattributes +1 -0
  2. README.md +155 -80
  3. cgd_convnextv2_base_coco2017.ckpt +3 -0
  4. config.json +8 -3
  5. example.jpg +3 -0
  6. 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
- tags:
4
- - image-rotation
5
- - orientation-estimation
6
- - angle-detection
7
- - circular-gaussian-distribution
8
- - mambaout
9
- - pytorch
10
- datasets:
11
- - coco
12
- metrics:
13
- - mae
14
- pipeline_tag: image-classification
15
- ---
16
-
17
- # Image Rotation Angle Estimation
18
-
19
- **[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)**
20
-
21
- Predicts the rotation angle of an image using the **Circular Gaussian Distribution (CGD)** method with a **MambaOut Base** backbone.
22
-
23
- The model outputs a probability distribution over 360 angle bins (1 degree resolution) and extracts the predicted angle via argmax. It handles the full 360 degree range with no boundary discontinuities.
24
-
25
- ## Available Checkpoints
26
-
27
- | Checkpoint | Dataset | MAE | Median Error |
28
- |---|---|---|---|
29
- | `cgd_mambaout_base_coco2017.ckpt` | COCO 2017 | 2.84° | 0.55° |
30
- | `cgd_mambaout_base_coco2014.ckpt` | COCO 2014 | 3.71° | 0.68° |
31
-
32
- ## Usage
33
-
34
- Download the inference code from this Hub repo (`model_cgd.py`, `architectures.py`, `rotation_utils.py`), then:
35
-
36
- ```python
37
- from model_cgd import CGDAngleEstimation
38
- from PIL import Image
39
-
40
- # Load model (defaults to COCO 2017 checkpoint)
41
- model = CGDAngleEstimation.from_pretrained("maxwoe/image-rotation-angle-estimation")
42
-
43
- # Or load a specific checkpoint
44
- # model = CGDAngleEstimation.from_pretrained(
45
- # "maxwoe/image-rotation-angle-estimation",
46
- # model_name="cgd_mambaout_base_coco2014.ckpt",
47
- # )
48
-
49
- image = Image.open("your_image.jpg")
50
- angle = model.predict_angle(image)
51
- print(f"Predicted rotation: {angle:.1f}°")
52
- ```
53
-
54
- `predict_angle` accepts a PIL Image, numpy array, or file path.
55
-
56
- ## Evaluation Results (COCO 2017, 5 seeds)
57
-
58
- | Metric | Value |
59
- |---|---|
60
- | MAE | 2.84° |
61
- | Median Error | 0.55° |
62
- | RMSE | 8.45° |
63
- | P90 Error | 3.54° |
64
- | P95 Error | 12.00° |
65
- | Accuracy at 2° | 90.2% |
66
- | Accuracy at 5° | 97.5% |
67
- | Accuracy at 10° | 98.1% |
68
-
69
- ## Model Details
70
-
71
- - **Method:** Circular Gaussian Distribution (CGD), 360 bins, sigma = 6.0°
72
- - **Backbone:** MambaOut Base (`mambaout_base.in1k`), pretrained on ImageNet-1K
73
- - **Input size:** 224 x 224 pixels
74
- - **Output:** Probability distribution over 360 angle bins, converted to angle via argmax
75
- - **Loss:** KL Divergence with soft Gaussian labels
76
- - **Optimizer:** AdamW with ReduceLROnPlateau scheduler
77
-
78
- ## License
79
-
80
- MIT
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
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
+ ![Five rotated photos and the same photos turned back by the predicted angle](example.jpg)
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 + MambaOut Base (COCO 2017) \u2014 2.84\u00b0 MAE": {
 
 
 
 
 
4
  "filename": "cgd_mambaout_base_coco2017.ckpt",
5
  "architecture": "mambaout_base.in1k",
6
  "input_size": 224
7
  },
8
- "CGD + MambaOut Base (COCO 2014) \u2014 3.71\u00b0 MAE": {
9
  "filename": "cgd_mambaout_base_coco2014.ckpt",
10
  "architecture": "mambaout_base.in1k",
11
  "input_size": 224
12
  }
13
  },
14
- "default_model": "CGD + MambaOut Base (COCO 2017) \u2014 2.84\u00b0 MAE"
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

  • SHA256: ecaa1729bed29a39b693af7c0305dbbf46a7e11237642bd28ed76b8755eb1ad6
  • Pointer size: 131 Bytes
  • Size of remote file: 582 kB
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
- self.model = timm.create_model(model_name, pretrained=True, num_classes=num_bins)
 
 
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)