rightwayup

Python package and CLI for RightWayUp, a neural network model by ORTUS AI that estimates how far an image is rotated from upright, over the full 360° at 1° resolution, and abstains when an image has no clear "up".

pip install rightwayup
rightwayup predict frame.jpg                          # angle, confidence, abstain flag
rightwayup fix photo.jpg --snap 90 --out upright/     # writes the upright image; leaves it alone if it abstains
rightwayup predict frames/*.jpg --tier nano --batch --batch-size 64 --json

from rightwayup import Orienter

o = Orienter(tier="max")          # weights download from Hugging Face on first use
r = o.predict("frame.jpg")        # r.angle_cw, r.confidence, r.abstain, r.routed
upright = o.correct("photo.jpg", snap=90)
results = Orienter(tier="fast", batch=True).predict_batch(["a.jpg", "b.jpg"], batch_size=64)

angle_cw is the clockwise rotation of the image content; turning the image counter-clockwise by angle_cw makes it upright (r.correction_ccw). abstain is true when the image has no reliable "up" (the angle is still reported); correct() then returns the image unchanged unless force=True.

Tiers

¹ Intel Core i7-1260P, ONNX Runtime INT8, 4 threads, batch 1. Cascade shares are those of the calibration data; on photos and thermal images Balanced and Pro route more (10–33% / 30–80% on the sealed test sets). Accuracy tables, GPU and Apple timings: model card.

Options

predict_batch(images, batch_size=16) accepts file paths, PIL images or NumPy arrays. rightwayup fix also takes --min-angle (treat smaller corrections as upright, default 1.0°) and --force; it exits with status 2 if it left any image unchanged because the model abstained.

Abstain and route thresholds were fixed on calibration data only, separately for each file format (FP32, FP16, INT8, and the batch-capable files); the package applies the thresholds of the format it loads.

Files and formats

The weights repository ortusai/rightwayup holds, for every model, ONNX FP32 / FP16 / INT8 files (pico-s70-*, nano-s112-*, fast-s224-*, max-l280-*), batch-capable ONNX files for Pico, Nano and Fast (*-batch-*), a full-token Pico build for ONNX Runtime Web (pico-s70-web-*), and Core ML packages for Apple silicon (coreml/*-b1.mlpackage, *-b16.mlpackage). The package uses the ONNX files; tiers.json in the weights repository documents the preprocessing and every threshold for use without Python.

Known limitations

• Thermal images: accuracy on unseen thermal cameras varies widely and confidence is not reliable there; use max and do not rely on the abstain flag alone.
• Clean photos with small tiers: nano and fast are less accurate than Woehrer 2026 on clean everyday photos; use pro or max for photo apps.
• Pico is weak on strongly rolled CCTV (41.1% on one held-out camera rolled about 36°).
• Rotation corners: images turned by software get flat-colour corners; black, white and grey corners are handled by every tier, but a sky-blue fill can flip nano by 180°.
• No "up": straight-down aerial images and featureless close-ups have no defined "up"; use the abstain flag.
• Max is not the fast tier: per image it is slower than Woehrer 2026 on CPUs and most GPUs.

No telemetry: the only network calls go to Hugging Face to fetch the weight files (and check cached copies). Pass model_dir= or set HF_HUB_OFFLINE=1 to run fully offline.

• Write-up and video: https://cheqit.ortusai.io/resources/rightwayup/
• Code, results, technical report and data provenance: https://github.com/ortusaitech/rightwayup
• Weights (all six tiers): https://huggingface.co/ortusai/rightwayup

Apache-2.0. Built by ORTUS AI, the team behind CHEQIT camera-health monitoring.