PyBx

A simple python package to generate anchor boxes for multi-box and single shot object detection models.

Calculated anchor boxes are in pascal_voc format by default.

Installation

pip install pybx

The core package only installs the dependencies needed for bounding-box and anchor operations. Install optional features when needed:

pip install "pybx[viz]"     # Matplotlib visualization
pip install "pybx[opencv]"  # image loading and resizing
pip install "pybx[all]"     # both optional features

If an optional feature is used without its dependency, PyBx raises an error containing the appropriate installation command. Loading an image from disk and displaying it requires pybx[all].

Usage

To calculate the anchor boxes for a single feature size and aspect ratio, given the image size:

from pybx import anchor, ops

image_sz = (256, 256)
feature_sz = (10, 10)
asp_ratio = 1 / 2.0

coords, labels = anchor.bx(image_sz, feature_sz, asp_ratio)

100 anchor boxes of asp_ratio 0.5 is generated along with unique labels:

len(coords), len(labels)

(100, 100)

The anchor box labels are especially useful, since they are pretty descriptive:

coords[-1], labels[-1]

([234, 225, 252, 256], 'a_10x10_0.5_99')

To calculate anchor boxes for multiple feature sizes and aspect ratios, we use anchor.bxs instead:

feature_szs = [(10, 10), (8, 8)]
asp_ratios = [1.0, 1 / 2.0, 2.0]

coords, labels = anchor.bxs(image_sz, feature_szs, asp_ratios)

All anchor boxes are returned as ndarrays of shape (N,4) where N is the number of boxes.

The box labels are even more important now, since they help you uniquely identify to which feature map size or aspect ratios they belong to.

coords[101], labels[101]

(array([29,  0, 47, 30]), 'a_10x10_0.5_1')

coords[-1], labels[-1]

(array([217, 228, 256, 251]), 'a_8x8_2.0_63')

MultiBx methods

Box coordinates (with/without labels) in any format (usually ndarray, list, json, dict) can be instantialized as a MultiBx, exposing many useful methods and attributes of MultiBx. For example to calculate the area of each box iteratively:

from pybx.basics import *

# passing anchor boxes and labels from anchor.bxs()
print(coords.shape)

boxes = mbx(coords, labels)
type(boxes)

(492, 4)

pybx.basics.MultiBx

len(boxes)

492

areas = [b.area for b in boxes]

Each annotation in the MultiBx object boxes is also a BaseBx with its own set of methods and properties.

boxes[-1]

BaseBx(coords=[[217, 228, 256, 251]], label=['a_8x8_2.0_63'])

boxes[-1].coords, boxes[-1].label

([[217, 228, 256, 251]], ['a_8x8_2.0_63'])

MultiBx objects can also be “added” which stacks them vertically to create a new MultiBx object:

boxes_true = mbx(coords_json)  # annotation as json records
len(boxes_true)

2

boxes_anchor = mbx(coords_numpy)  # annotation as ndarray
len(boxes_anchor)

492

boxes_true.coords

[{'x_min': 130, 'y_min': 63, 'x_max': 225, 'y_max': 180, 'label': 'clock'},
 {'x_min': 13, 'y_min': 158, 'x_max': 90, 'y_max': 213, 'label': 'frame'}]

boxes_anchor.coords

array([[  0,   0,  25,  25],
       [ 25,   0,  51,  25],
       [ 51,   0,  76,  25],
       ...,
       [153, 228, 198, 251],
       [185, 228, 230, 251],
       [217, 228, 256, 251]])

boxes = boxes_true + boxes_anchor

len(boxes)

494

Use ground truth boxes for model training

from pybx.anchor import get_gt_thresh_iou, get_gt_max_iou
from pybx.vis import VisBx

image_sz

(256, 256)

boxes_true

MultiBx(coords: 2, labels: 2)

Calculate candidate anchor boxes for many aspect ratios and scales.

feature_szs = [(10, 10), (3, 3), (2, 2)]
asp_ratios = [0.3, 1 / 2.0, 2.0]

anchors, labels = anchor.bxs(image_sz, feature_szs, asp_ratios)

Wrap using pybx methods. This step is not necessary but convenient.

boxes_anchor = get_bx(anchors, labels)
len(boxes_anchor)

341

The following function returns a MatchResult containing the matched boxes, anchor indices, IoUs, masks, and box IDs. Every mapping is keyed by stable box IDs rather than class labels, so multiple objects can share the same class. Supply application IDs (including UUIDs) when identity must survive reordering; otherwise deterministic zero-based input positions are used.

match_result = get_gt_max_iou(
    true_annots=boxes_true,
    anchor_boxes=boxes_anchor,  # if plain numpy, pass anchor_boxes and anchor_labels
    box_ids=["clock-1", "frame-1"],  # optional; defaults to 0..N-1
    update_labels=False,  # whether to replace ground truth labels with true labels
    positive_boxes=1,  # can request extra boxes
)
gt_anchors = match_result.matched_boxes

gt_anchors

{'clock-1': BaseBx(coords=[[156, 0, 227, 180]], label=['a_2x2_0.3_1']),
 'frame-1': BaseBx(coords=[[12, 152, 72, 256]], label=['a_3x3_0.5_6'])}

all_gt_anchors = gt_anchors["clock-1"] + gt_anchors["frame-1"]
all_gt_anchors

/work1/u31l94/pybx/pybx/basics.py:599: BxViolation: Change of object type imminent if trying to add <class 'pybx.basics.BaseBx'>+<class 'pybx.basics.BaseBx'>. Use <class 'pybx.basics.BaseBx'>+<class 'pybx.basics.BaseBx'> instead or basics.stack_bxs().
  warnings.warn(

MultiBx(coords: 2, labels: 2)

v = VisBx(pth="../data/", img_fn="image.jpg", image_sz=image_sz)
v.show(all_gt_anchors, color={"a_2x2_0.3_1": "red", "a_3x3_0.5_6": "red"})

More exploratory stuff in the walkthrough notebook or