• HBB to OBB conversion: converts YOLO-format horizontal bounding boxes to oriented bounding boxes.
• HBB detection: produce the horizontal boxes in the first place with any Ultralytics detector, local, from the Ultralytics catalogue, or from Hugging Face (details).
• Segmentation-based: uses state-of-the-art SAM models for accurate object boundary detection.
• Multiple model support: SAM, SAM2, SAM2.1, SAM3, Mobile SAM, and FastSAM families (details).
• Model ensemble: combine multiple models via majority voting for enhanced accuracy.
• Confidence scoring: a per-OBB quality score flags fallbacks and low-confidence conversions for triage, optionally combined with the detector confidence from the input (details).
• Polygon output: optionally save the segmentation contour behind each OBB, row-aligned with the OBB file, as a tighter object outline for downstream masking (details).
• Evaluation tools: assess OBB accuracy against ground truth using IoU metrics.
• Hyperparameter optimization: search SAM inference resolutions, HBB scale factors and opening kernels for the best settings on your data, one sweep at a time or a whole benchmark from a config file.
• Provenance records: --save_provenance writes the command, the versions, a digest of the source that ran and the SHA-256 of every checkpoint, so a released annotation set can be regenerated rather than trusted.
• Visualization tools: render HBBs, segmentation masks, derived contours, and resulting OBBs.
• Interactive viewer: pan and zoom over annotated frames, toggle each layer, and compare two annotation sets side by side.
• Format conversion utilities: convert between YOLO, DOTA, Pascal VOC, COCO and LabelMe annotations, in either direction, for both box kinds.

• Improved morphological operations: more advanced operations for better mask refinement.
• Support for other segmentation models: extend compatibility beyond the SAM/FastSAM families.

HBB2OBB integrates with and complements several specialized tools:

• Geo-trax 🚀: georeferenced vehicle trajectory extraction pipeline for high-altitude drone imagery, built on YOLO detection and multi-object tracking. Its vehicle detector supplies the HBB inputs for vehicle use cases (car, bus, truck, motorcycle), and hbb2obb-detect runs it by default (details).

• Stabilo ⚖️: Python library for video and trajectory stabilization using robust homography transformations. Supports various feature detectors, RANSAC algorithms, and user-defined masks.

• Stabilo-Optimize 🎯: benchmarking and hyperparameter optimization framework for Stabilo. Evaluates stabilization performance through ground truth-free assessment using random perturbations.

Miniconda:

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

uv (fastest; then uv pip install 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]'

The -e flag makes your local changes take effect without reinstalling; the [dev] extra adds pytest and ruff. For a plain install, use pip install . instead.

Unlike other SAM models, SAM 3 weights (sam3.pt) are not auto-downloaded by Ultralytics. To use SAM 3:

1. Request access on the SAM 3 model page on Hugging Face.
2. Once approved, download sam3.pt.
3. Place sam3.pt in the models/ directory (relative to where you run the conversion).

See the Ultralytics SAM 3 documentation for more.

Run hbb2obb --help / hbb2obb-eval --help for the full list. Key conversion arguments:

• --hbb_dir / -hd: directory of HBB annotations in YOLO TXT format (default: <img_source>/../labels_hbb).
• --obb_dir / -od: directory to save OBB annotations (default: <img_source>/../labels_obb).
• --sam_models / -sm: SAM model(s) to use (e.g. sam_b, sam_l, sam2_b, sam2.1_b, sam3, mobile_sam, FastSAM-s).
• --imgsz: SAM inference resolution (default: 1280).
• --scale_factors / -sf: factor(s) to scale HBBs (single value, or two values for short/long sides).
• --opening_kernel_percentage / -okp: morphological opening kernel size as a percentage of the mask's smaller dimension.
• --save_confidence: append a per-OBB confidence score as a 10th column in the output TXT files.
• --save_img, --viz_dir, --show_confidence, and --hide_hbb / --hide_obb / --hide_masks / --hide_segments / --hide_class_labels: visualization controls.
• --model_kwargs / -k: extra Ultralytics inference kwargs as key1=value1,key2=value2.

Key evaluation arguments:

• --excluded_classes / -e: class IDs to exclude from evaluation.
• --iou_threshold / -t: IoU threshold for a match (default: 0.1).
• --class_agnostic / -ca: ignore class-label matching (useful for re-classified GT).
• --exclude_edge_cases / -exc, --edge_tolerance / -et, --img_width / -iw, --img_height / -ih: edge-case handling.
• --map_path / -mp: path to a label map YAML mapping class IDs to names.

Converting HBB to OBB: hbb2obb() processes a single image and returns the OBB annotations as a NumPy array:

from pathlib import Path
from hbb2obb.converter import hbb2obb, save_obb_annotations, save_polygon_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)

# Also return the segmentation contours, and write them as polygon annotations
obb_annotations, contours = hbb2obb(img_path=img_path, sam_models="sam_b", return_contours=True)
save_polygon_annotations(contours, obb_annotations, "/path/to/save/polygons", img_path)

Evaluating OBB predictions:

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")

Starting from HBB annotations and OBB ground truth in whatever format you were given:

# 1. Bring both into YOLO TXT, whatever they arrived as (--from is detected if omitted)
hbb2obb-convert project/voc_hbb --to yolo -o project/labels_hbb -mp project/label_map.yaml
hbb2obb-convert project/gt.json --from coco --to yolo -o project/labels_obb_gt -mp project/label_map.yaml

# 2. Optimize hyperparameters to find the best settings (add -ok to also sweep the opening kernel)
hbb2obb-optimize 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_confidence --save_provenance

# 4. Evaluate against ground truth, then look at where it went wrong
hbb2obb-eval project/labels_obb_gt project/labels_obb -mp project/label_map.yaml
hbb2obb-view project/images --compare project/labels_obb_gt --show_confidence

# 5. Ship the result in every format your consumers want
hbb2obb-convert project/labels_obb --to dota coco voc -o project/release -mp project/label_map.yaml

--model takes a registered detector (geotrax today, the default), any Ultralytics model name or .pt path, or a Hugging Face reference written as <user>/<repo>/<file>.pt. All three parts are required, even when the repo holds only one file: Hugging Face's download API always names the exact file rather than picking one for you. Weights land in models/ beside the SAM checkpoints. A registered detector brings the settings it was validated at, so geotrax runs at --imgsz 1920 over its four reliable classes; anything else starts from the Ultralytics defaults and is yours to set. A detector trained on COCO numbers its classes differently from yours, which is what --class_map is for: --class_map '2=0,5=1,7=2,3=3' turns COCO's car, bus, truck and motorcycle into 0,1,2,3 and drops every other class.

Detected boxes are a starting point, not ground truth. If you have hand-drawn boxes already and only want the confidence a detector would give them, --merge_with keeps your geometry untouched and only attaches the score of the detection covering each box:

hbb2obb-detect /path/to/images --merge_with /path/to/labels_hbb --extras_dir /tmp/extras --overwrite

Your boxes stay exactly as they are, in their own order; a box no detection covers keeps 1.0, because a box somebody drew by hand is not less certain than one a model proposed. Detections that back no box of yours are counted and, with --extras_dir, written as their own set so you can look at them (hbb2obb-view /path/to/images --hbb_dir /tmp/extras) and decide whether they are objects you missed. The merge never adds them for you, and --overwrite is required before anything writes into a directory that already holds labels.

Green is the OBB, white its source HBB, red the segmentation polygon it was fitted to, orange a box flagged difficult; with --show_confidence the OBB is tinted green→red by score, the same gradient --save_img uses. The last two need the conversion to have been run with --save_polygon and --save_confidence, which is how the sample data in data/ was produced (see data/README.md for the exact commands behind every file there).

Drag with the left mouse button to pan. --crops writes a contact sheet of the individual objects instead, which is the faster way to review a whole frame box by box.

--verify compares the formats by exact equality after rounding rather than by a tolerance, because they are all one common rounding of a single canonical source. That is the property worth testing: rounding full precision and rounding an already-rounded canonical disagree wherever a coordinate lands on a half pixel, and an envelope then silently stops matching the box it was derived from.

Only DOTA and Pascal VOC can express a per-box difficult flag, so writing either one from YOLO or COCO resets it; --difficult_from dota carries the flags across. Only YOLO and COCO can carry a confidence, so DOTA and Pascal VOC drop it. Image dimensions come from --images, or from --img_width / --img_height, and are needed to denormalize relative YOLO coordinates. LabelMe stores class names rather than ids, so pass -mp when round-tripping through it to pin the ids.

A COCO file is named coco_annotations_<kind>.json unless --coco_name says otherwise, which is also how --verify pairs one with its directory: labels_<name>/ goes with coco_annotations_<name>.json beside it. Where a directory holds the canonical YOLO files next to derived ones, --from is detected as yolo, so a second pass through the converter never rounds an already rounded file.

The grid is the full product of --imgsz x --scale_factors x --opening_kernels, and each grid point is a complete SAM pass over the whole image set, so the cost multiplies quickly: the defaults (3 image sizes, 12 scale factors, 1 opening kernel) already amount to 36 passes, and sweeping three kernels instead of one triples that to 108. --opening_kernels / -ok defaults to the single value 0.15, so omitting it leaves the two-axis sweep and its grid size unchanged.

# Add the opening kernel as a third axis (2 x 3 x 3 = 18 grid points)
hbb2obb-optimize /path/to/images /path/to/ground_truth -iz 960 1280 -sf 0.03 0.05 0.07 -ok 0.0 0.15 0.3

A run writes run_config.yaml, results.yaml, summary.txt and plot.png into <output_folder>/<name>, and summary.md, comparison.png and PROVENANCE.txt into the output folder itself. The plot colours each series by image size and, when more than one opening kernel was swept, distinguishes the kernels by marker shape.

# benchmark.yaml
img_source: data/images
gt_dir: data/labels_obb_gt
output_folder: data/benchmark_results

defaults:
  imgsz: [640, 960, 1280]
  scale_factors: [0.03, 0.04, 0.05, 0.06, 0.07]

runs:
  - sam_models: [sam_b]
  - sam_models: [sam_l]
  - sam_models: [sam_l, sam_b, sam2_b, sam2.1_b]

hbb2obb-optimize -c benchmark.yaml --dry_run   # the runs, the grid size, the total cost
hbb2obb-optimize -c benchmark.yaml --refresh   # only redraw the plots and the summary

Each run takes the defaults and overrides whatever it names; a run with no name takes one from its models, so [sam_l, sam_b] writes into sam_l-sam_b. Alongside summary.md and PROVENANCE.txt, which every sweep writes, a config-driven benchmark also leaves a copy of the configuration itself in the output folder, so the results re-run on their own once they have been moved into an archive or a dataset release, away from the repository that held the original. --resume skips runs that already hold a complete grid, which is what makes a multi-hour unattended sweep restartable; when it does skip some, PROVENANCE.txt says which runs this invocation measured and which it kept, so a partially resumed benchmark is legible as one. --refresh redraws the plots and the summary from the results on disk and rewrites no provenance at all, since that file describes the code and the checkpoints that produced the numbers, not the code that last redrew them.

data/benchmark.yaml is a working example: it is the file behind data/benchmark_results/, so that whole folder is one command away.

# Works the same for detection
hbb2obb-detect /path/to/images --save_provenance

It records the exact command, the versions of ultralytics, torch, OpenCV, NumPy, Shapely and matplotlib, and the SHA-256 of every checkpoint used. That last part is the one worth insisting on: ultralytics resolves a bare model name by downloading it, and the file behind a name can change between asset releases, so the name alone does not pin the model that actually ran. The settings come from the run that happened rather than from arguments repeated afterwards, and a benchmark additionally hashes the label sets its numbers were measured against.

The code is pinned three ways, because a commit hash alone is not enough: the release (pip install hbb2obb==<version>), the commit with git describe when there is a checkout, and a SHA-256 over the package source. The record says outright whether that commit can be checked out to get the code that ran, and it decides that by comparing the package directory alone, so a sweep writing its results back into the repository does not mark its own record as untrustworthy. The digest is the durable one. A commit hash identifies a point in a history, and history is editable: squash a branch, rebase it, or delete it after the merge, and the hash stops resolving, while an uncommitted tree never had one to record. The source digest is computed from the bytes that ran, so it still matches years later. Use the commit to find the change; use the digest to prove you have the same code.

1. Load HBB annotations from YOLO TXT.
2. Scale bounding boxes: positive factors expand HBBs (recover cropped parts), negative factors shrink them (tighten conservative boxes); short and long sides can be scaled differently.
3. Segmentation: run SAM model(s) with the HBBs as prompts.
4. Mask aggregation: with an ensemble, combine masks by majority voting; clip to the scaled HBB region; apply morphological opening.
5. Contour extraction: extract the largest refined mask contour per object (optionally saved with --save_polygon).
6. OBB computation: fit a minimum-area oriented bounding box.
7. Fallback: if no valid mask is found inside an HBB, keep the original HBB as the OBB (confidence 0.0).
8. Confidence: score each OBB in [0, 1] (see Confidence Scores).
9. Visualization (optional): overlay HBBs, masks, contours, and OBBs (colored by confidence).

Key characteristics:

• Label preservation: OBBs inherit the class label of their source HBB (no re-classification).
• Corrective effects: the transformation can recover cropped parts (positive scaling) and produce tighter boxes through precise segmentation.