STATGATOR Consulting

Resources from the book

Hungarian Matrix

Section 21.7 · Find one-to-one matches between two groups of inference boxes.

Section 21.7.1

Purpose

Find an optimal one-to-one assignment between two groups of bounding boxes based on proximity. The book describes uses such as associating detections between frames or matching detections from different sources.

This utility performs one matching operation. Your application supplies the two groups and decides what their association means.

Section 21.7.2

Why It Exists

Choosing the nearest candidate independently for each detection can produce conflicts or a poor overall assignment. A candidate that is convenient for one primary box may be the only reasonable choice for another.

The Hungarian solver considers the cost matrix as a whole while ensuring that each primary and each candidate is used at most once.

A small assignment example

Suppose primary centers lie at X = 0 and X = 4, and candidate centers lie at X = 1 and X = −3, all on the same horizontal line. Their distances are:

Candidate A · X = 1Candidate B · X = −3
Primary A · X = 013
Primary B · X = 437

Taking the first nearest pair gives a total cost of 1 + 7 = 8. Assigning Primary A to Candidate B and Primary B to Candidate A gives 3 + 3 = 6. The overall assignment is better even though the first primary does not receive its nearest candidate.

Section 21.7.3

Input

Supply two array<BoundingBox@> inputs, primary_boxes and candidate_boxes, plus these user settings:

array<int> target_primary_label_id_arr = {0,1};
array<int> target_candidate_label_id_arr = {2,7};
int max_pixel_distance_for_match = 400;

Each array is filtered using its own target-label list. Non-target labels are excluded from both matching and the returned unmatched arrays.

Each box must supply label_id, upper-left x and y, width, and height. Use valid, non-null handles and a common image coordinate system. Centers are calculated with floating-point half-widths and half-heights.

Distance is center to center.

This matcher uses Euclidean center-to-center pixel distance, unlike the edge-to-edge gap in the Mini-Box Combiner. A pair at exactly the maximum distance is allowed.

You may pass the same array for both inputs; the two target-label lists establish the roles. If those lists overlap, a box can be eligible for both roles, including a zero-distance match to itself. Use disjoint lists when that is not intended.

Review 21.1 · Inference Data & BoundingBox →

Section 21.7.4

Output

The main function returns a HungarianMatchResult containing matched pairs and unmatched boxes:

class HungarianMatchPair {
    BoundingBox@ primary_box;
    BoundingBox@ candidate_box;
    float cost;
};

class HungarianMatchResult {
    array<HungarianMatchPair> matches;
    array<BoundingBox@> unmatched_primary_boxes;
    array<BoundingBox@> unmatched_candidate_boxes;
};

Each pair contains handles to the actual input boxes and its center-to-center distance in pixels. Each filtered box appears in at most one pair within its role.

If one filtered group is empty, all boxes in the other filtered group are returned as unmatched. Non-target labels do not appear in any result array.

How the cost matrix works

The matrix is square, sized to the larger filtered group. Real pairs beyond the distance limit receive an invalid cost of 999999.0. Zero-cost dummy rows or columns support unequal group sizes.

The solver minimizes the total matrix cost. When converting assignments back to objects, the code rejects dummy and invalid pairings and collects the corresponding unmatched boxes. Keep valid pixel-distance costs comfortably below the invalid-cost constant.

The returned associations are based on proximity and your filters; they are not proof of identity or persistent tracking IDs.

The guide behind the codeFrom the page
to the plant floor.Practical Guide to AI Computer Vision Integration in Industrial ManufacturingExplore the Book