---
license: mit
tags:
  - image-rotation
  - orientation-estimation
  - angle-detection
  - circular-gaussian-distribution
  - mambaout
  - pytorch
datasets:
  - coco
metrics:
  - mae
pipeline_tag: image-classification
---

# Image Rotation Angle Estimation

**[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)**

Predicts the rotation angle of an image using the **Circular Gaussian Distribution (CGD)** method with a **MambaOut Base** backbone.

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.

## Available Checkpoints

| Checkpoint | Dataset | MAE | Median Error |
|---|---|---|---|
| `cgd_mambaout_base_coco2017.ckpt` | COCO 2017 | 2.84° | 0.55° |
| `cgd_mambaout_base_coco2014.ckpt` | COCO 2014 | 3.71° | 0.68° |

## Usage

Download the inference code from this Hub repo (`model_cgd.py`, `architectures.py`, `rotation_utils.py`), then:

```python
from model_cgd import CGDAngleEstimation
from PIL import Image

# Load model (defaults to COCO 2017 checkpoint)
model = CGDAngleEstimation.from_pretrained("maxwoe/image-rotation-angle-estimation")

# Or load a specific checkpoint
# model = CGDAngleEstimation.from_pretrained(
#     "maxwoe/image-rotation-angle-estimation",
#     model_name="cgd_mambaout_base_coco2014.ckpt",
# )

image = Image.open("your_image.jpg")
angle = model.predict_angle(image)
print(f"Predicted rotation: {angle:.1f}°")
```

`predict_angle` accepts a PIL Image, numpy array, or file path.

## Evaluation Results (COCO 2017, 5 seeds)

| Metric | Value |
|---|---|
| MAE | 2.84° |
| Median Error | 0.55° |
| RMSE | 8.45° |
| P90 Error | 3.54° |
| P95 Error | 12.00° |
| Accuracy at 2° | 90.2% |
| Accuracy at 5° | 97.5% |
| Accuracy at 10° | 98.1% |

## Model Details

- **Method:** Circular Gaussian Distribution (CGD), 360 bins, sigma = 6.0°
- **Backbone:** MambaOut Base (`mambaout_base.in1k`), pretrained on ImageNet-1K
- **Input size:** 224 x 224 pixels
- **Output:** Probability distribution over 360 angle bins, converted to angle via argmax
- **Loss:** KL Divergence with soft Gaussian labels
- **Optimizer:** AdamW with ReduceLROnPlateau scheduler

## License

MIT