Skip to content

OrientedDet

OrientedDet (oriented-det) is an open-source PyTorch framework for oriented and rotated object detection in aerial and satellite images.
It focuses on clean geometry, reliable operators, simple datasets, and practical baseline models — without the complexity of large detection frameworks.

OrientedDet is designed for researchers, practitioners, and geospatial developers who need accurate rotation-aware detectors with a clean and minimal API.

For a quick overview and installation on GitHub, see the repository README. Short overview: oriented detection in aerial and satellite images. Write-ups with code, metrics, and inference knobs: DeepLearning.Earth. For consulting, training workshops, or custom development, see DL4EO.

🚀 Features

🔸 Core Geometry

  • Rotated bounding boxes (rbox: cx, cy, w, h, angle)
  • Quadrilateral boxes (qbox) and conversions
  • Polygon ↔ rbox ↔ hbox conversion utilities
  • Angle normalization (le90, 0–180°, etc.) - Fixed: Corrected le90 normalization to properly handle width/height swaps and angle normalization
  • Flip, rotate, and scale transformations
  • Visualization helpers for debugging

🔸 Fast Rotated IoU + Rotated NMS

  • Python-based NMS using polygon intersection (CPU)
  • Note: torchvision.ops.nms_rotated does not exist in current torchvision versions
  • Optimized with AABB pre-filtering (~2.6x faster than naive implementation)
  • Clean wrappers with fully validated interfaces
  • Future: GPU-accelerated kernels via custom CUDA implementation

🔸 Remote-Sensing Datasets

  • DOTA polygon loader → rbox/qbox conversion
  • HRSC2016, FAIR1M, SSDD, and HRSID native loaders (SSDD / HRSID finetune DOTA 1× Hub locally; no SAR zoo)
  • Three loading modes: Pattern matching, split file, separate folders
  • Image tiling / patch generation with configurable overlap
  • Label filtering, edge handling, ignore masks
  • Oriented mAP evaluation compatible with DOTA protocol

🔸 Baseline Models

  • Oriented R-CNN — horizontal RPN + MidpointOffset (6-param) proposals + oriented RoIAlign (Xie et al., ICCV 2021)
  • Rotated Faster R-CNN — horizontal RPN + horizontal RoIAlign + rotated ROI head (MMRotate DOTA baseline)
  • Rotated RetinaNet (1-stage baseline) — oriented anchors and focal loss head
  • Rotated FCOS (anchor-free 1-stage) — distance-angle coder, centerness, L1 / KFIoU / decoded rIoU
  • Rotated RTMDet (speed tier) — CSPNeXt + PAFPN, SepBN head, dynamic soft-label assigner, decoded rIoU
  • True oriented detection: Predicts rotation angles, not just axis-aligned boxes
  • Standard backbones (ResNet + FPN, CSPNeXt + PAFPN)
  • OrientedDet pretrained weights via Hugging Face Hub (odet pretrained download)

🔸 Simple Training Pipeline

A clean, readable PyTorch training loop with efficient features: - Mixed precision training (AMP) - Gradient accumulation - Checkpointing with best model tracking - Metric tracking and TensorBoard logging - Performance profiling support - Robust error handling

Quick Start

Hands-on installation and a minimal walkthrough are in Getting Started. For JSON-driven training and every config option, see Configuration and Training.

Installation

From PyPI:

pip install oriented-det

For development (clone + uv):

git clone https://github.com/DL4EO/oriented-det
cd oriented-det
uv venv --python 3.12 && source .venv/bin/activate
uv pip install -r requirements.txt
uv pip install -e ".[dev]"

See Installation for CUDA, macOS, and CPU setups.

Documentation Structure

Roadmap

v0.4.1 is shipped (citation and discoverability). v0.4.0 shipped Rotated RTMDet (Hub rotated_rtmdet_dota_le90_3x, 77.60% official Task 1). Next: native YOLO-OBB (v0.4.2; already in the tree, COCO pretrain and DOTA training next), Swin-FPN backbones (v0.5+). Details: Roadmap.

Important Notes

True Oriented Detection

✅ OrientedRCNN, RotatedFasterRCNN, RotatedRetinaNet, RotatedFCOS, and RotatedRTMDet perform true oriented object detection: - Predict oriented bounding boxes with 5 parameters (cx, cy, w, h, angle) - Preserve angle information throughout training and inference - Use oriented IoU for matching and oriented NMS for post-processing - Output RBoxes include predicted angles (not angle=0)

Angle Normalization

  • Default: Full circle representation (-Ï€, Ï€]
  • For DOTA compatibility: Use normalize_le90() for [-Ï€/2, Ï€/2) convention
  • Fixed: Corrected le90 normalization to properly handle width/height swaps

NMS Performance

  • Note: torchvision.ops.nms_rotated does not exist in current torchvision versions
  • Uses optimized Python implementation with AABB pre-filtering (~2.6x faster)
  • Future: GPU-accelerated kernels planned

Memory Optimization

  • OrientedRCNN uses memory-efficient ROI align (chunked processing)
  • Recommended: roi_chunk_size=16-32 for typical GPU memory (8-24GB)
  • Enable roi_use_checkpoint=True for additional memory savings (~2x less memory)

License

Apache-2.0 — Copyright © Jeff Faudi and DL4EO. See LICENSE for details.

The framework license does not grant rights to the DOTA or HRSC datasets. See Apache 2.0 vs DOTA / HRSC dataset terms. For consulting, training workshops, or custom development, see DL4EO.