HBB2OBB: Horizontal to Oriented Bounding Box Conversion and Evaluation Tool

HBB2OBB converts horizontal (axis-aligned) bounding boxes (HBBs) into oriented (rotated) bounding boxes (OBBs) by using existing HBB annotations as prompts for segmentation models from the SAM (Segment Anything Model) family. It targets object detection tasks where objects appear at arbitrary orientations, such as aerial imagery, satellite data, and traffic monitoring, producing oriented boxes that tightly encapsulate non-upright objects without any re-annotation. Beyond conversion, it provides horizontal box detection, evaluation, hyperparameter optimization, an interactive annotation viewer, and annotation format-conversion tools, exposed through both a command-line interface and a Python API.

Why HBB2OBB

• 🎯 Accurate OBBs from HBBs: prompts SAM-family segmentation models with existing horizontal boxes to fit tight oriented boxes around non-upright objects, with no re-annotation required.
• 🚗 No HBBs? Detect them: the hbb2obb-detect command runs an Ultralytics detector over the images and writes the horizontal boxes the conversion consumes, confidence column included.
• 🧩 Model ensemble: combines masks from multiple SAM variants through majority voting for more robust, accurate results.
• 🛡️ Spatially constrained and safe: region-specific masking and contour refinement keep segmentation inside the object, and a fallback retains the original HBB when no valid mask is found.
• 🔎 Confidence-scored output: every OBB receives a heuristic quality score in [0, 1] that flags silent fallbacks and low-confidence conversions, so you know which boxes to trust; the scores go in the label files or in a side-car directory that keeps them strictly standard, and the detector's own confidence can be carried through instead of, or on top of, that score.
• 📐 Flexible scaling: positive or negative scale factors, optionally different for the short and long sides, recover cropped object parts or tighten overly conservative annotations.
• 📊 Evaluate and optimize: built-in IoU evaluation against ground truth plus the hbb2obb-optimize command, a hyperparameter search over SAM inference resolution, scale factors, and morphological opening kernel, driven by a configuration file so that a whole benchmark of model ensembles is a single reproducible command.
• 🔄 Six annotation formats: read and write YOLO, DOTA, Pascal VOC, COCO, and LabelMe, for horizontal and oriented boxes alike, with a check that proves every format encodes the same boxes.
• 🔍 Interactive viewer: the hbb2obb-view command pans and zooms over the annotations, in any format, coloring boxes by confidence and overlaying predictions against ground truth.

Features

• HBB to OBB conversion of YOLO-format annotations using SAM-based segmentation.
• HBB detection: produce the horizontal boxes in the first place with any Ultralytics detector, local, from the Ultralytics catalogue, or from Hugging Face.
• Multiple model support: SAM, SAM2, SAM2.1, SAM3, Mobile SAM, and FastSAM families.
• Model ensemble via majority voting for enhanced accuracy.
• Confidence scoring: a per-OBB quality score flags silent fallbacks and low-confidence conversions for triage, optionally combined with the detector confidence from the input, written either as an extra column or to a side-car directory beside standard label files.
• Polygon output: optionally save the segmentation contour behind each OBB, row-aligned with the OBB file, as a tighter object outline for downstream masking.
• Evaluation tools to assess OBB accuracy against ground truth using IoU metrics.
• Hyperparameter optimization over SAM inference resolutions, HBB scale factors, and morphological opening kernels, one sweep at a time or a whole benchmark from a configuration file, with an aggregate summary and resumable long runs.
• Provenance records: write the reproducing command, the library versions, and the SHA-256 of every checkpoint that ran beside the annotations, so that a released set can be regenerated rather than trusted.
• Visualization tools for HBBs, segmentation masks, derived contours, and resulting OBBs.
• Interactive viewer: pan and zoom over annotated frames, toggle each layer, and compare two annotation sets against each other.
• Format conversion utilities between YOLO, DOTA, Pascal VOC, COCO, and LabelMe annotations, in either direction, for both box kinds.

Planned Enhancements

• Improved morphological operations for better mask refinement.
• Support for additional segmentation models beyond the SAM and FastSAM families.

Related Projects

• Geo-trax 🛰️: georeferenced vehicle trajectory extraction pipeline for high-altitude drone imagery. Its vehicle detector supplies the HBB inputs for vehicle use cases (car, bus, truck, and motorcycle), and hbb2obb-detect --model geotrax runs that detector directly.
• Stabilo 🌀: Python library for video and trajectory stabilization using robust homography transformations, supporting various feature detectors, RANSAC algorithms, and user-defined masks.
• Stabilo-Optimize 🎯: benchmarking and hyperparameter optimization framework for Stabilo, evaluating stabilization performance through ground-truth-free assessment using random perturbations.

Citation

If you use HBB2OBB in your research or software, please cite the archived release:

@software{fonod2026hbb2obb,
  author  = {Fonod, Robert},
  title   = {HBB2OBB: Horizontal to Oriented Bounding Box Conversion and Evaluation Tool},
  year    = {2026},
  license = {MIT},
  doi     = {10.5281/zenodo.15151143},
  url     = {https://github.com/rfonod/hbb2obb}
}

Contributions

Community contributions are welcome: open a GitHub Issue or submit a pull request.

License

This project is distributed under the MIT License. See the LICENSE file for more details.