hbb2obb-optimize¶
Searches the conversion hyperparameters, as one sweep or a benchmark of several. Guide: Tune hyperparameters.
usage: hbb2obb-optimize [-h] [--version] [--config CONFIG] [--hbb_dir HBB_DIR]
[--output_folder OUTPUT_FOLDER] [--run_name RUN_NAME]
[--sam_models MODEL [MODEL ...]] [--imgsz IMGSZ [IMGSZ ...]]
[--scale_factors SCALE_FACTORS [SCALE_FACTORS ...]]
[--opening_kernels OPENING_KERNELS [OPENING_KERNELS ...]]
[--fragment_ratio FRAGMENT_RATIO]
[--excluded_classes EXCLUDED_CLASSES [EXCLUDED_CLASSES ...]]
[--iou_threshold IOU_THRESHOLD] [--class_agnostic] [--exclude_edge_cases]
[--edge_tolerance EDGE_TOLERANCE] [--img_width IMG_WIDTH]
[--img_height IMG_HEIGHT] [--only NAME [NAME ...]] [--resume] [--refresh]
[--dry_run] [--device DEVICE] [--model_kwargs MODEL_KWARGS]
[--models_dir MODELS_DIR] [--no_plot] [--plot_metric PLOT_METRIC]
[--no_bar]
[img_source] [gt_dir]
Find optimal hyperparameters for HBB2OBB conversion
positional arguments:
img_source Path to an image or directory containing images
gt_dir Directory containing ground truth OBB annotations
options:
-h, --help show this help message and exit
--version, -V show program's version number and exit
--config CONFIG, -c CONFIG
Benchmark YAML describing several sweeps; replaces the two positionals
--hbb_dir HBB_DIR, -hd HBB_DIR
Directory containing HBB annotations (default: img_source/../labels_hbb)
--output_folder OUTPUT_FOLDER, -o OUTPUT_FOLDER
Directory to save results (default: img_source/../benchmark_results)
--run_name RUN_NAME, -n RUN_NAME
Name of this sweep's folder (default: its models)
--device DEVICE Inference device for the SAM model(s), e.g. 'cpu', '0', 'cuda:0', 'mps'.
Applies to every run, overriding any 'device' set in the config (default:
ultralytics picks)
--model_kwargs MODEL_KWARGS, -k MODEL_KWARGS
Any other Ultralytics predictor arguments, passed through unchecked, as
'key1=value1,key2=value2'; values are Python literals where they parse as
one
--models_dir MODELS_DIR
Directory checkpoints are read from and downloaded to (default:
$HBB2OBB_MODELS_DIR if set, else models/ in the working directory)
--no_plot Do not render any plot
--plot_metric PLOT_METRIC, -pm PLOT_METRIC
Quantity the plots draw (default: avg_iou, the one the search optimizes).
The others are reported but never optimized, and exist because the mean
saturates on tight boxes: median_iou, median_angle_error, p90_angle_error,
iou_at_75, iou_at_90
--no_bar, -nb Disable tqdm progress bar display
grid axes (single sweep; a config sets these per run):
--sam_models MODEL [MODEL ...], -sm MODEL [MODEL ...]
SAM model(s) to use (default: sam_b). One or more of: sam_b, sam_l,
mobile_sam, sam2_t, sam2_s, sam2_b, sam2_l, sam2.1_t, sam2.1_s, sam2.1_b,
sam2.1_l, sam3, FastSAM-s, FastSAM-x
--imgsz IMGSZ [IMGSZ ...], -iz IMGSZ [IMGSZ ...]
Image sizes to test (default: 640 960 1280)
--scale_factors SCALE_FACTORS [SCALE_FACTORS ...], -sf SCALE_FACTORS [SCALE_FACTORS ...]
Scale factors to test (default: -0.01 to 0.1 in steps of 0.01)
--opening_kernels OPENING_KERNELS [OPENING_KERNELS ...], -ok OPENING_KERNELS [OPENING_KERNELS ...]
Morphological kernel fractions to test (default: 0.15, a single value);
negative values close instead of open. Third grid axis: a run performs
len(imgsz) x len(scale_factors) x len(opening_kernels) full SAM passes
over the image set, so the defaults give 3 x 12 x 1 = 36, and three
kernels instead of one triples that to 108
--fragment_ratio FRAGMENT_RATIO, -fr FRAGMENT_RATIO
Minimum area, as a fraction of the largest mask piece's, for another piece
to be fitted together with it (default: 0.1). Fixed for the whole sweep,
not a grid axis.
evaluation options:
--excluded_classes EXCLUDED_CLASSES [EXCLUDED_CLASSES ...], -e EXCLUDED_CLASSES [EXCLUDED_CLASSES ...]
Class IDs to exclude from evaluation
--iou_threshold IOU_THRESHOLD, -t IOU_THRESHOLD
IoU threshold for evaluation (default: 0.1)
--class_agnostic, -ca
Evaluate in class-agnostic mode
--exclude_edge_cases, -exc
Exclude boxes that touch image edges
--edge_tolerance EDGE_TOLERANCE, -et EDGE_TOLERANCE
Tolerance in pixels for detecting boxes at image edges (default: 1)
--img_width IMG_WIDTH, -iw IMG_WIDTH
Image width for edge case detection
--img_height IMG_HEIGHT, -ih IMG_HEIGHT
Image height for edge case detection
benchmark control:
--only NAME [NAME ...]
Run only these runs of the config
--resume Skip runs whose results.yaml already holds a full grid
--refresh Re-render the plots, summary.md, the LaTeX table summary.tex and the print
figure comparison.pdf from the results already on disk, running no SAM
passes
--dry_run Print the runs, the grid size and the total cost, then stop
Two ways to run. Give an image source and a ground truth directory for a single sweep, or -c CONFIG for a benchmark of several sweeps described by one YAML file:
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.05, 0.07]
runs:
- sam_models: [sam_b]
- sam_models: [sam_l, sam_b]
A run writes into <output_folder>/<name>, where name defaults to its models joined by '-'. Paths resolve against the current working directory, like the models/ weights directory does.