OrientedDet

OrientedDet is a lightweight, modern PyTorch library for rotated object detection in aerial and satellite imagery. 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 minimal API.

Features

• Geometry: Rotated bounding boxes (rbox: cx, cy, w, h, angle), quadrilateral boxes (qbox), polygon ↔ rbox ↔ hbox conversions, angle normalization (le90, 0–180°), flip/rotate/scale transforms, visualization helpers
• IoU & NMS: Rotated IoU and oriented NMS (CPU with optional GPU kernels when available); AABB pre-filtering; obb_to_xyxy / HBB conversion
• Datasets: DOTA polygon loader (pattern, split file, or separate folders), image tiling, label filtering, ignore masks, oriented mAP evaluation
• Models: Oriented R-CNN (Xie et al., ICCV 2021; horizontal RPN + MidpointOffset → oriented RoIAlign + oriented ROI head), Rotated Faster R-CNN (Ren et al., NeurIPS 2015 two-stage baseline with horizontal RPN + horizontal RoIAlign + rotated ROI head; MMRotate reference), Rotated RetinaNet (Lin et al., ICCV 2017; oriented anchors, sigmoid focal loss); ResNet + FPN backbones; selective loading of external checkpoints where configs wire checkpoint.load_from_checkpoint
• Training: JSON configs + odet train, mixed precision (AMP), gradient accumulation, checkpointing, best-metric tracking, TensorBoard, optional curriculum learning and profiling

Installation

• Python >= 3.9. Use uv to install Python versions and manage the virtual environment.
• From the repo root (Linux with CUDA 12.1):

# Make sure you're in the project directory
cd ~/oriented-det

# Install uv if needed: https://docs.astral.sh/uv/getting-started/installation/
# Create a venv with Python 3.12 (uv downloads the interpreter if missing)
uv venv --python 3.12
source .venv/bin/activate

# Install PyTorch with CUDA 12.1 from PyTorch's index (2.3.0 or a higher version is fine)
uv pip install "torch>=2.3.0" "torchvision>=0.18.0" --index-url https://download.pytorch.org/whl/cu121

# Install dependencies and the project in editable mode
uv pip install -r requirements.txt
uv pip install -e .

• To auto-activate .venv when entering this repo, install the direnv shell hook and run direnv allow from the repo root. The local .envrc is intentionally gitignored so each developer can opt in on their machine.
• From PyPI: pip install oriented-det
• For development and tests: uv pip install -e ".[dev]"
• For the Gradio prediction viewer: uv pip install -e ".[viewer]" or pip install "oriented-det[viewer]"
• For macOS Apple Silicon or CPU-only, see Installation.
• Verify: pytest tests/test_geometry.py tests/test_iou.py tests/test_nms.py

Quick start

After installation:

# Train on DOTA tiles (edit dataset paths in the config first)
odet train --config configs/oriented_rcnn/dota_le90_1x.json

# Or use the Makefile wrapper (same default config)
make train

Default starter recipe: configs/oriented_rcnn/dota_le90_1x.json (see configs/oriented_rcnn/README.md). Use configs/oriented_rcnn/dota_le90_3x.json when you want the longer Oriented R-CNN schedule.

Programmatic APIs and a longer walkthrough: Getting Started. Config fields: Configuration.

Paths in documentation and configs

Examples throughout this repo use placeholder paths such as /path/to/data and /path/to/oriented-det. You can point commands and JSON configs at your real locations (e.g. dataset.data_root in a training config), or keep those placeholders and map them with symbolic links:

# Create the parent directory (may need sudo for paths under /path/to)
sudo mkdir -p /path/to

# Point the placeholder at your DOTA dataset
ln -s /home/username/dota /path/to/data

# Point the placeholder at your clone of this repo
ln -s /home/username/oriented-det /path/to/oriented-det

After that, copy-pasted commands and unmodified configs that reference /path/to/data or /path/to/oriented-det resolve to your machine. Use relative symlink targets when you want the link to stay valid if the parent directory moves.

Repository layout

| What | Where | You use it for | |------|--------|----------------| | Library | oriented_det/ | Geometry, models, datasets, training engine, ops — import in Python or extend in your own code | | CLI | odet (oriented_det/cli/) | Train, tile data, run val inference, metrics, demos — primary interface after uv pip install -e . | | CLI implementations | tools/ | Python modules that implement odet subcommands (train, preds, tiling, …). Not a separate “old” API; contributors and debugging may call python -m tools.train directly | | Configs | configs/ | Experiment JSON (_base_ inheritance, schema in configs/config.schema.json) | | Runs | runs/<model_type>/<timestamp>/ | Checkpoints, config.json snapshot, train.log (created at train time; not shipped in the repo) | | Docs | docs/ | MkDocs user guide and API reference | | Export | export/ | Optional ONNX / TensorFlow export pipeline | | Examples | demo/, pretrained/ | Demo images; registered checkpoints (large .pth files are usually gitignored) |

odet vs tools/: Installing the package registers the odet command. It loads modules under tools/ (for example tools.train, tools.save_predictions). Shared inference and collate code lives in oriented_det/runtime/. You do not need two workflows — use odet (or make, which calls odet).

Publishing a clean tree: Ship the library, configs, docs, and tests. Omit local experiment output (runs/), datasets, and machine-specific paths in configs/Makefile.

Documentation

Full documentation is in the docs/ folder and can be built and served with MkDocs:

• Build/serve: make docs or make docs-serve (see docs/README.md); or uv pip install -e ".[docs]" then mkdocs serve.
• Guides: Getting Started, User Guide, API Reference, Examples.

Documentation by folder

| Folder | README | Description | |--------|--------|-------------| | export/ | export/README.md | Phase 1: PyTorch → ONNX → Keras detect bundle; cd export && make export-tf | | demo/ | demo/README.md | Demo images; odet image-demo or make demo with the latest runs/ checkpoint | | pretrained/ | pretrained/README.md | Registered checkpoints for fine-tunes; large .pth files are usually gitignored | | oriented_det/cli/ | oriented_det/cli/README.md | odet entry point and subcommand list | | tools/ | tools/README.md | CLI script implementations (invoked by odet; see Repository layout) | | configs/ | configs/README.md | DOTA configs and pretrain model zoo (_base_ inheritance) | | deploy/example/ | deploy/example/README.md | Minimal DOTA deploy smoke image | | docs/ | docs/README.md | MkDocs source; full user guide and API reference |

Training and evaluation

Install once: uv pip install -e .. Then:

| Task | Command | |------|---------| | Train | odet train --config configs/oriented_rcnn/dota_le90_1x.json or make train | | Multi-GPU | make train-multi-gpu (torchrun + cuDNN on LD_LIBRARY_PATH) | | Tile DOTA | odet tile-dota /path/to/dota/train | | Val predictions | odet preds --experiment-dir runs/oriented_rcnn/<timestamp> or make preds | | Offline mAP | make eval-val or make preds then make metrics |

DOTA configs: per-model dota_le90_1x.json / dota_le90_3x.json under configs/. Run odet --help for all subcommands. Makefile shortcuts and script-level options: tools/README.md. Config reference: docs/user-guide/configuration.md, configs/config.schema.json, configs/README.md.

Pretrained weights and evaluation

• Place exported best checkpoints under pretrained/ or use Hub slugs (odet pretrained download oriented_rcnn_dota_le90_3x or oriented_rcnn_dota_le90_1x). See pretrained/README.md and configs/README.md.
• Tiled validation: after training, run make preds then make metrics. Published mAP reports: docs/eval-reports/ (git). Raw detections for the viewer: gitignored predictions/.

Important notes

• Angles: Radians; use a single convention (e.g. le90 for DOTA). Helper: normalize_le90 from oriented_det.geometry. For angle-delta normalization in custom code, see oriented_det.models.oriented_rpn.normalize_angle_delta.
• NMS: torchvision.ops.nms_rotated does not exist; the project uses a Python-based oriented NMS with AABB pre-filtering. GPU kernels are us