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.

📖 Documentation: rfonod.github.io/hbb2obb, with a quick start on the bundled sample data, a guide per command, pages on how the conversion works, the confidence score, the metrics and provenance, and a CLI and API reference generated from the code.

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, a mask split by an occluder is fitted back together, and a fallback retains the original HBB when no valid mask is found, counted and reported rather than left to be discovered afterwards.
• 🔎 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: evaluation against ground truth on IoU, orientation error, and the share of boxes above a high IoU bar, 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.
• 🔬 Where the score comes from: the hbb2obb-analyze command breaks one evaluation down by the ground truth's orientation, size, frame edge, difficulty and class, and scores the conversion against emitting the horizontal prompt unchanged.
• 🔄 Five 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. Where a set ships the same boxes several ways, it names the format on screen and switches between them on a keypress.

Features

• HBB to OBB conversion of YOLO-format annotations using SAM-based segmentation, written in absolute pixels or, with --normalize, relative to [0, 1], the convention Ultralytics reads.
• HBB detection: produce the horizontal boxes in the first place with any Ultralytics detector, a local file, a link, the Ultralytics catalogue, or Hugging Face, passing any other predictor argument straight through.
• 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 on mean and median IoU, the orientation error of every matched pair, and the share of matched boxes above IoU 0.5, 0.75, 0.85 and 0.9, reported overall and per class. Mean IoU saturates on well-fitted boxes; the other two do not, and separate configurations that it cannot.
• Accuracy breakdown: cut one evaluation by ground-truth orientation, size, frame edge, difficult flag and class, beside an identity baseline and the converted-to-reference side ratios, written as a report, a YAML and a figure.
• 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. Figures can be redrawn against any recorded metric without re-running the search, and the benchmark is also written as a LaTeX table and a print-ready PDF figure for a manuscript.
• Provenance records: write the reproducing command, the library versions, the SHA-256 of every checkpoint that ran and how many boxes fell back to their horizontal prompt, beside the annotations, so that a released set can be regenerated rather than trusted. Detections also record the licence and references the Hugging Face Hub declares for their weights, so the credit travels with the labels.
• Visualization tools for HBBs, segmentation masks, derived contours, and resulting OBBs.
• Interactive viewer: pan and zoom over annotated frames, toggle each layer, switch between the formats a set ships, 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. A COCO file derived from another can keep the image and annotation identifiers of its source, so the two still join.

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.