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 your 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, or traffic monitoring, producing OBBs that tightly encapsulate non-upright objects. Beyond conversion, it ships evaluation, hyperparameter optimization, and annotation format-conversion tools, with both a command-line interface and a Python API.

Why HBB2OBB

• 🎯 Accurate OBBs from HBBs: prompts SAM-family segmentation models with your existing horizontal boxes to fit tight oriented boxes around non-upright objects, with no re-annotation required.
• 🧩 Model ensemble: combines masks from multiple SAM variants through majority voting for more robust, accurate results (see Usage).
• 🛡️ Spatially constrained & safe: region-specific masking and contour refinement keep segmentation inside the object, and a fallback keeps the original HBB when no valid mask is found.
• 🔎 Confidence-scored output: every OBB gets a quality score in [0, 1] that flags silent fallbacks and low-confidence conversions, so you know which boxes to trust (see Confidence scores).
• 📐 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 & optimize: built-in IoU evaluation against ground truth plus a hyperparameter optimizer over SAM inference resolution × scale factors.
• 🔄 Format conversions: utilities to move between YOLO TXT and COCO / Pascal VOC / LabelMe JSON annotations.
• ⚙️ CLI + Python API: hbb2obb and hbb2obb-eval commands plus an importable API, with transparent visualizations of every step.

Install

Create and activate a Python virtual environment (Python 3.9–3.13), then install from PyPI:

python3.11 -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate
pip install hbb2obb

Also works with uv (uv pip install hbb2obb) and conda.

[!NOTE] SAM model weights are downloaded automatically by Ultralytics on first use into a models/ directory relative to your current working directory: run commands from a consistent location so weights are reused. The one exception is SAM 3, which must be downloaded manually (see below).

conda create -n hbb2obb python=3.11 -y
conda activate hbb2obb

uv venv --python 3.11
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

git clone https://github.com/rfonod/hbb2obb.git
cd hbb2obb && pip install -e '.[dev]'

Quick Start

A small sample dataset ships in data/. From the repository root:

# Convert the sample HBBs to OBBs (default single model) and save visualizations
hbb2obb data/images --save_img

# Higher accuracy with a model ensemble
hbb2obb data/images --sam_models sam_b sam_l sam2_b sam2.1_b

# Evaluate the converted OBBs against ground truth
hbb2obb-eval data/labels_obb_gt data/labels_obb -mp data/classes.yaml

Converted OBB annotations are written to data/labels_obb/. Run hbb2obb --help or hbb2obb-eval --help for all options.

Usage

Converting HBB to OBB

# Default single model (sam_b), HBBs read from <img_source>/../labels_hbb
hbb2obb /path/to/images --hbb_dir /path/to/hbb/annotations

# Model ensemble (majority voting across models)
hbb2obb /path/to/images --sam_models sam_b sam_l sam2_b sam2.1_b

# Scale HBBs: expand to recover cropped parts, or shrink conservative boxes
hbb2obb /path/to/images --scale_factors 0.1      # expand uniformly
hbb2obb /path/to/images --scale_factors -0.02    # shrink uniformly
hbb2obb /path/to/images --scale_factors 0.1 0.05 # short side / long side

# Save visualization images of the conversion
hbb2obb /path/to/images --save_img

Evaluating OBB Predictions

hbb2obb-eval /path/to/ground_truth /path/to/predictions

from pathlib import Path
from hbb2obb.converter import hbb2obb, save_obb_annotations

img_path = Path("/path/to/images/img1.jpg")

# Single SAM model
obb_annotations = hbb2obb(
    img_path=img_path,
    hbb_dir="/path/to/hbb/annotations",
    sam_models="sam_b",
    imgsz=1280,
    scale_factors=0.05,
    opening_kernel_percentage=0.15,
    save_img=True,
    viz_dir="/path/to/save/visualizations",
)

# Model ensemble with per-side scale factors
obb_annotations = hbb2obb(
    img_path=img_path,
    hbb_dir="/path/to/hbb/annotations",
    sam_models=["sam_b", "sam_l", "sam2_b", "sam2.1_b"],
    scale_factors=[0.1, 0.05],  # short side / long side
)

# Writes <obb_dir>/img1.txt, deriving the filename from img_path
save_obb_annotations(obb_annotations, "/path/to/save/obb/annotations", img_path)

# Also return per-OBB confidence scores, and write them as a 10th column
obb_annotations, confidences = hbb2obb(img_path=img_path, sam_models="sam_b", return_confidence=True)
save_obb_annotations(obb_annotations, "/path/to/save/obb/annotations", img_path, confidences=confidences)

from pathlib import Path
from hbb2obb.evaluator import evaluate_obb, print_results

results = evaluate_obb(
    gt_dir=Path("/path/to/ground_truth_annotations"),
    pred_dir=Path("/path/to/predictions"),
    iou_threshold=0.1,
    class_agnostic=True,      # optional: match regardless of class label
    exclude_edge_cases=True,  # optional: drop boxes at the image edge
    img_width=3840,
    img_height=2160,
)

print_results(results, "/path/to/label_map.yaml")

# 1. Convert HBB and OBB ground-truth JSON to YOLO TXT
python scripts/json2yolo.py project/json_hbb -td project/labels_hbb
python scripts/json2yolo.py project/json_obb_gt -td project/labels_obb_gt

# 2. Optimize hyperparameters to find the best settings
python scripts/optimize_hbb2obb.py project/images project/labels_obb_gt -sm sam_b sam_l sam2_b -n multi_sam

# 3. Inspect the best parameters, then convert with them
cat project/benchmark_results/multi_sam/summary.txt
hbb2obb project/images --hbb_dir project/labels_hbb --obb_dir project/labels_obb \
  --sam_models sam_b sam_l --imgsz 1280 --scale_factors 0.05 \
  --opening_kernel_percentage 0.15 --save_img --viz_dir project/visualizations

# 4. Evaluate against ground truth
hbb2obb-eval project/labels_obb_gt project/labels_obb -mp project/label_map.yaml

# 5. Convert OBBs back to JSON for review in LabelMe
python scripts/yolo2json.py project/labels_obb project/label_map.yaml -jd project/json_obb
labelme project/images --output project/json_obb --nodata

Utility Scripts

Format Conversion

# LabelMe JSON -> YOLO TXT (HBB and OBB); -mp label map optional
python scripts/json2yolo.py /path/to/json_dir -mp /path/to/label_map.yaml

# Official COCO instance JSON -> YOLO TXT (HBB only)
python scripts/json2yolo.py /path/to/instances.json --input_format coco -td /path/to/labels_yolo

# Pascal VOC XML -> YOLO TXT (HBB)
python scripts/voc2yolo.py /path/to/voc_xml_dir -td /path/to/labels_yolo

# YOLO TXT -> LabelMe-compatible JSON (HBB and OBB); label map required
python scripts/yolo2json.py /path/to/yolo /path/to/label_map.yaml

json2yolo.py defaults to LabelMe input (each JSON has imageHeight, imageWidth, shapes); use --input_format coco for official COCO instance files (images, annotations, categories, HBB only).

Hyperparameter Optimization

# Search inference resolutions x scale factors for one or more SAM models
python scripts/optimize_hbb2obb.py /path/to/images /path/to/ground_truth -sm sam_b sam_l sam2_b sam2.1_b -n multi_sam

# Visualize the results
python scripts/plot_optimization_results.py /path/to/optimization_results

Data Format

HBB annotations (input): YOLO TXT, one file per image; coordinates relative (0–1) or absolute px:

class_id x_center y_center width height

You bring your own HBB annotations. If you don't have any and your objects are vehicles (car, bus, truck, motorcycle), you can generate them from drone imagery with Geo-trax and feed its detections straight into HBB2OBB.

OBB annotations (output): YOLO TXT, one file per image; four corners in absolute px:

class_id x1 y1 x2 y2 x3 y3 x4 y4

With --save_confidence, a 10th column holds the per-OBB confidence score:

class_id x1 y1 x2 y2 x3 y3 x4 y4 confidence

hbb2obb-eval ignores the trailing confidence column, so evaluation works on either variant.

Label map (optional): YAML mapping class IDs to names:

0: Car
1: Bus
2: Truck

How It Works

HBB2OBB fits each OBB by prompting SAM with your HBBs, refining the resulting mask, and wrapping it in a minimum-area rotated box.

Confidence Scores

Each OBB carries a heuristic quality score in [0, 1] that helps triage a converted dataset: high scores are trustworthy SAM fits, low scores warrant a look, and 0.0 marks a fallback where the original HBB was kept. It is a heuristic, not a calibrated probability. The detail crop below shows the score that --show_confidence prints next to each converted box.

The score is the product of two factors:

• Rectangularity: the fitted contour area divided by the area of its minimum-area rotated rectangle, i.e. how tightly the OBB wraps the segmented shape (1.0 for a perfectly rectangular object).
• Ensemble consensus: the fraction of the per-model mask union that survived the majority vote, i.e. how strongly the SAM models agree. This is 1.0 for a single model and equals the mask IoU for two models.

Enable it with --save_confidence (writes a 10th column to each output file). In the visualization, OBBs are always tinted on a green→red gradient by score, and --show_confidence prints the numeric value next to each box. When using the Python API, pass return_confidence=True to hbb2obb() to get the scores back alongside the OBBs.

Best Practices

• For optimal results, combine multiple SAM models, e.g. --sam_models sam_b sam_l sam2_b sam2.1_b sam3.
• Experiment with scale factors and inference resolutions based on your dataset.
• Run the hyperparameter optimizer to find the best settings for your data.
• Use class-agnostic evaluation when comparing against manually annotated ground truth with different class labels.
• Visualize the conversion to understand how the model interprets your HBBs.

Limitations

• Results depend on the quality of the input HBBs and the SAM models used; poor annotations or weak segmentation lead to inaccurate OBBs.
• Highly occluded or complex objects, where the HBB gives insufficient context, may not convert well.

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}
}

Each GitHub release is automatically archived to Zenodo via the Zenodo–GitHub integration; see CITATION.cff for the latest version and DOI.

Contributing

Contributions are welcome! If you encounter issues or have suggestions, please open a GitHub Issue or submit a pull request.

License

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