playground_metrics.match_detections

Usage

A MatchEngine is a class which computes associations between pairs of geometrical features (typically detections and ground truths) based on a similarity matrix (In the most common case, it is a intersection-over-union matrix which is computed as described in Intersection over union).

The actual matching is made from the similarity matrix described before and a first trim which is used to quickly eliminate obviously non-pairable elements.

See also

The full matching documentation section: Matching detections and ground truths.

The abstract class MatchEngineBase defines the template for every MatchEngine and implements the 3 matching algorithms used (c.f. Matching). Subclasses implements the compute_similarity_matrix() method which computes a similarity matrix from ever pairs of elements possible and the trim_similarity_matrix() method which computes the indices of the object pairs which pass the first trim.

4 MatchEngine are implemented in this module:

  • MatchEngineIoU which is the default MatchEngine and the one used in the mAP computation guide in Computation of mAP. The first trim then assesses a pairs’ viability by checking if its similarity is above a given threshold.

  • MatchEngineEuclideanDistance which works on points (or features’ centroid if given non-point features) and uses a similarity matrix made from the matrix of euclidean distances. The first trim then assesses a pairs’ viability by checking if its similarity is above a given threshold.

  • MatchEnginePointInBox which works on points (or features’ centroid if given non-point features) for detections and bounding boxes or polygons for ground truths and uses a similarity matrix made from the matrix of euclidean distances. The main difference with MatchEngineEuclideanDistance is that the first trim checks whether a point is within a ground truth footprint to assess a pairs’ viability rather than checking if its similarity is above a given threshold.

  • MatchEngineConstantBox which works on points (or features’ centroid if given non-point features) and uses a similarity matrix made by assigning a fixed shape bounding box to every points and computing intersection-over-union between those. The first trim then assesses a pairs’ viability by checking if its similarity is above a given threshold.

API doc

Implement the public interface to match a set of detections and ground truths.

class playground_metrics.match_detections.MatchEngineBase(match_algorithm)[source]

Bases: ABC

Match detection with their ground truth according a similarity matrix and a detection confidence score.

Matching may be done using coco algorithm or xView algorithm (which yield different matches as described for an intersection-over-union similarity matrix in Matching) or with non-unitary matching.

Subclasses must implement compute_similarity_matrix() and trim_similarity_matrix() to be functional.

Parameters:

match_algorithm (str) – Either ‘coco’, ‘xview’ or ‘non-unitary’ to choose the match algorithm

match_algorithm

Either ‘coco’, ‘xview’ or ‘non-unitary’ and indicates the match algorithm used

Type:

str

abstract compute_similarity_matrix(detections, ground_truths, label_mean_area=None)[source]

Compute a similarity matrix between detections and ground truths.

Abstract method.

This method must be overridden in subsequent subclasses to handle both bounding box and polygon input format.

Parameters:

  • detections (ndarray, list) –

    A ndarray of detections stored as:

    • Bounding boxes for a given class where each row is a detection stored as: [BoundingBox, confidence]

    • Polygons for a given class where each row is a detection stored as: [Polygon, confidence]

    • Points for a given class where each row is a detection stored as: [Point, confidence]

  • ground_truths (ndarray,list) –

    A ndarray of ground truth stored as:

    • Bounding boxes for a given class where each row is a ground truth stored as: [BoundingBox]

    • Polygons for a given class where each row is a ground truth stored as: [Polygon]

    • Points for a given class where each row is a ground truth stored as: [Point]

  • label_mean_area (float) – Optional, default to None. The mean area for each label in the dataset.

Returns:

A similarity matrix of dimension (#detections, #ground truth)

Return type:

ndarray

match(detections, ground_truths, label_mean_area=None)[source]

Match detections Geometry with ground truth Geometry at a given similarity matrix and trim method using either Coco algorithm, xView algorithm or a naive non-unitary match.

Parameters:

  • detections (ndarray, list) –

    A ndarray of detections stored as:

    • Bounding boxes for a given class where each row is a detection stored as: [BoundingBox, confidence]

    • Polygons for a given class where each row is a detection stored as: [Polygon, confidence]

    • Points for a given class where each row is a detection stored as: [Point, confidence]

  • ground_truths (ndarray,list) –

    A ndarray of ground truth stored as:

    • Bounding boxes for a given class where each row is a ground truth stored as: [BoundingBox]

    • Polygons for a given class where each row is a ground truth stored as: [Polygon]

    • Points for a given class where each row is a ground truth stored as: [Point]

  • label_mean_area (float) – Optional, default to None. The mean area for each label in the dataset.

Returns:

A binary matrix of all matches of dimension (#detections, #ground truth)

Return type:

ndarray

abstract trim_similarity_matrix(similarity_matrix, detections, ground_truths, label_mean_area=None)[source]

Compute an array containing the indices in columns of similarity passing the first trimming (typically for IoU this would be the result of a simple thresholding) but it might be any method fit to do a rough filtering of possible ground truth candidates to match with a given detection.

Abstract method.

Parameters:

  • similarity_matrix – The similarity matrix between detections and ground truths : dimension (#detection, #gt)

  • detections (ndarray, list) –

    A ndarray of detections stored as:

    • Bounding boxes for a given class where each row is a detection stored as: [BoundingBox, confidence]

    • Polygons for a given class where each row is a detection stored as: [Polygon, confidence]

    • Points for a given class where each row is a detection stored as: [Point, confidence]

  • ground_truths (ndarray,list) –

    A ndarray of ground truth stored as:

    • Bounding boxes for a given class where each row is a ground truth stored as: [BoundingBox]

    • Polygons for a given class where each row is a ground truth stored as: [Polygon]

    • Points for a given class where each row is a ground truth stored as: [Point]

  • label_mean_area (float) – Optional, default to None. The mean area for each label in the dataset.

Returns:

An array of dimension (2, N) where each column is a tuple (detection, ground truth) describing a potential match. To be more precise, each match-tuple in the array corresponds to a position in the similarity matrix which will be used by the match algorithm to compute the final match.

Return type:

ndarray

class playground_metrics.match_detections.MatchEngineConstantBox(threshold, match_algorithm, bounding_box_size)[source]

Bases: MatchEngineIoU

Match detection with their ground truth according the IoU computed on fixed-size bounding boxes around detection and ground truth points and the detection confidence score.

Parameters:

  • threshold (float) – The IoU threshold at which one considers a potential match as valid

  • match_algorithm (str) – Either ‘coco’, ‘xview’ or ‘non-unitary’ to choose the match algorithm

  • bounding_box_size (float) – The fixed-size bounding box size

compute_similarity_matrix(detections, ground_truths, label_mean_area=None)[source]

Compute a parial similarity matrix based on the intersection-over-union between all pairs of constant-sized bounding box around points with an Rtree on detections to speed up computation.

Parameters:

  • detections (ndarray, list) –

    A ndarray of detections stored as:

    • Bounding boxes for a given class where each row is a detection stored as: [BoundingBox, confidence]

    • Polygons for a given class where each row is a detection stored as: [Polygon, confidence]

    • Points for a given class where each row is a detection stored as: [Point, confidence]

  • ground_truths (ndarray,list) –

    A ndarray of ground truth stored as:

    • Bounding boxes for a given class where each row is a ground truth stored as: [BoundingBox]

    • Polygons for a given class where each row is a ground truth stored as: [Polygon]

    • Points for a given class where each row is a ground truth stored as: [Point]

  • label_mean_area (float) – Optional, default to None. The mean area for each label in the dataset.

Returns:

An IoU matrix (#detections, #ground truth)

Return type:

ndarray

class playground_metrics.match_detections.MatchEngineEuclideanDistance(threshold, match_algorithm)[source]

Bases: MatchEngineBase

Match detection with their ground truth according the their relative distance and the detection confidence score.

Parameters:

  • threshold (float) – The distance threshold at which one considers a potential match as valid

  • match_algorithm (str) – Either ‘coco’, ‘xview’ or ‘non-unitary’ to choose the match algorithm

compute_similarity_matrix(detections, ground_truths, label_mean_area=None)[source]

Compute a partial similarity matrix based on the euclidean distance between all pairs of points.

The difference with MatchEnginePointInBox lies in the similarity matrix rough trimming which depends on a threshold rather than on whether a detection (as a point) lies within a ground truth polygon (or bounding box).

The computed matrix is \(\mathcal{S} = 1 - \mathcal{D}\) with:

\[\begin{split}\mathcal{D}_{ij} = \begin{cases} \left\lVert d_i - gt_i \right\rVert_2 &\mbox{if } d_i \in B(gt_i, t)\\ \inf &\mbox{if } d_i \notin B(gt_i, t) \end{cases}\end{split}\]

Where \(B(gt_i, t)\) is a square box centered in \(gt_i\) of size length \(t\).

Parameters:

  • detections (ndarray, list) –

    A ndarray of detections stored as:

    • Bounding boxes for a given class where each row is a detection stored as: [BoundingBox, confidence]

    • Polygons for a given class where each row is a detection stored as: [Polygon, confidence]

    • Points for a given class where each row is a detection stored as: [Point, confidence]

  • ground_truths (ndarray,list) –

    A ndarray of ground truth stored as:

    • Bounding boxes for a given class where each row is a ground truth stored as: [BoundingBox]

    • Polygons for a given class where each row is a ground truth stored as: [Polygon]

    • Points for a given class where each row is a ground truth stored as: [Point]

  • label_mean_area (float) – Optional, default to None. The mean area for each label in the dataset.

Returns:

An similarity matrix (#detections, #ground truth)

Return type:

ndarray

property threshold

The distance threshold at which one considers a potential match as valid.

Type:

float

trim_similarity_matrix(similarity_matrix, detections, ground_truths, label_mean_area=None)[source]

Compute an array containing the indices in columns of similarity passing the first trimming.

Here this is the result of a simple thresholding over the distance matrix.

Parameters:

  • similarity_matrix – The similarity matrix between detections and ground truths : dimension (#detection, #gt)

  • detections (ndarray, list) –

    A ndarray of detections stored as:

    • Bounding boxes for a given class where each row is a detection stored as: [BoundingBox, confidence]

    • Polygons for a given class where each row is a detection stored as: [Polygon, confidence]

    • Points for a given class where each row is a detection stored as: [Point, confidence]

  • ground_truths (ndarray,list) –

    A ndarray of ground truth stored as:

    • Bounding boxes for a given class where each row is a ground truth stored as: [BoundingBox]

    • Polygons for a given class where each row is a ground truth stored as: [Polygon]

    • Points for a given class where each row is a ground truth stored as: [Point]

  • label_mean_area (float) – Optional, default to None. The mean area for each label in the dataset.

Returns:

An array of dimension (2, N) where each column is a tuple (detection, ground truth) describing a potential match. To be more precise, each match-tuple in the array corresponds to a position in the similarity matrix which will be used by the match algorithm to compute the final match.

Return type:

ndarray

class playground_metrics.match_detections.MatchEngineIoU(threshold, match_algorithm)[source]

Bases: MatchEngineBase

Match detection with their ground truth according the their IoU and the detection confidence score.

Parameters:

  • threshold (float) – The IoU threshold at which one considers a potential match as valid

  • match_algorithm (str) – Either ‘coco’, ‘xview’ or ‘non-unitary’ to choose the match algorithm

compute_similarity_matrix(detections, ground_truths, label_mean_area=None)[source]

Compute the iou scores between all pairs of geometries with an Rtree on detections to speed up computation.

Parameters:

  • detections (ndarray, list) –

    A ndarray of detections stored as:

    • Bounding boxes for a given class where each row is a detection stored as: [BoundingBox, confidence]

    • Polygons for a given class where each row is a detection stored as: [Polygon, confidence]

  • ground_truths (ndarray,list) –

    A ndarray of ground truth stored as:

    • Bounding boxes for a given class where each row is a ground truth stored as: [BoundingBox]

    • Polygons for a given class where each row is a ground truth stored as: [Polygon]

  • label_mean_area (float) – Optional, default to None. The mean area for each label in the dataset, if given, it is used to match with iIoU instead of IoU (c.f. Instance IoU)

Returns:

An IoU matrix (#detections, #ground truth)

Return type:

ndarray

trim_similarity_matrix(similarity_matrix, detections, ground_truths, label_mean_area=None)[source]

Compute an array containing the indices in columns of similarity passing the first trimming.

Here this is the result of a simple thresholding over IoU.

Parameters:

  • similarity_matrix – The similarity matrix between detections and ground truths : dimension (#detection, #gt)

  • detections (ndarray, list) –

    A ndarray of detections stored as:

    • Bounding boxes for a given class where each row is a detection stored as: [BoundingBox, confidence]

    • Polygons for a given class where each row is a detection stored as: [Polygon, confidence]

  • ground_truths (ndarray,list) –

    A ndarray of ground truth stored as:

    • Bounding boxes for a given class where each row is a ground truth stored as: [BoundingBox]

    • Polygons for a given class where each row is a ground truth stored as: [Polygon]

  • label_mean_area (float) – Optional, default to None. The mean area for each label in the dataset, if given, it is used to match with iIoU instead of IoU (c.f. Instance IoU)

Returns:

An array of dimension (2, N) where each column is a tuple (detection, ground truth) describing a potential match. To be more precise, each match-tuple in the array corresponds to a position in the similarity matrix which will be used by the match algorithm to compute the final match.

Return type:

ndarray

class playground_metrics.match_detections.MatchEnginePointInBox(match_algorithm)[source]

Bases: MatchEngineBase

Match detection with their ground truth according the their relative distance, whether a detection point is in a ground truth box and the detection confidence score.

Parameters:

match_algorithm (str) – Either ‘coco’, ‘xview’ or ‘non-unitary’ to choose the match algorithm

compute_similarity_matrix(detections, ground_truths, label_mean_area=None)[source]

Compute a partial similarity matrix based on the euclidean distance between all pairs of points with an Rtree on detections to speed up computation.

The difference with MatchEngineEuclideanDistance lies in the similarity matrix rough trimming which depends on whether a detection (as a point) lies within a ground truth polygon (or bounding box) rather than on a threshold.

The computed matrix is \(\mathcal{S} = 1 - \mathcal{D}\) with:

\[\mathcal{D}_{ij} = \left\lVert d_i - gt_i \right\rVert_2\]
Parameters:

  • detections (ndarray, list) –

    A ndarray of detections stored as:

    • Bounding boxes for a given class where each row is a detection stored as: [BoundingBox, confidence]

    • Polygons for a given class where each row is a detection stored as: [Polygon, confidence]

    • Points for a given class where each row is a detection stored as: [Point, confidence]

  • ground_truths (ndarray,list) –

    A ndarray of ground truth stored as:

    • Bounding boxes for a given class where each row is a ground truth stored as: [BoundingBox]

    • Polygons for a given class where each row is a ground truth stored as: [Polygon]

  • label_mean_area (float) – Optional, default to None. The mean area for each label in the dataset.

Returns:

An similarity matrix (#detections, #ground truth)

Return type:

ndarray

trim_similarity_matrix(similarity_matrix, detections, ground_truths, label_mean_area=None)[source]

Compute an array containing the indices in columns of similarity passing the first trimming.

Here a detection/ground truth pair is kept if the detection Point is within the ground truth BoundingBox or Polygon

Parameters:

  • similarity_matrix – The similarity matrix between detections and ground truths : dimension (#detection, #gt)

  • detections (ndarray, list) –

    A ndarray of detections stored as:

    • Bounding boxes for a given class where each row is a detection stored as: [BoundingBox, confidence]

    • Polygons for a given class where each row is a detection stored as: [Polygon, confidence]

    • Points for a given class where each row is a detection stored as: [Point, confidence]

  • ground_truths (ndarray,list) –

    A ndarray of ground truth stored as:

    • Bounding boxes for a given class where each row is a ground truth stored as: [BoundingBox]

    • Polygons for a given class where each row is a ground truth stored as: [Polygon]

  • label_mean_area (float) – Optional, default to None. The mean area for each label in the dataset.

Returns:

An array of dimension (2, N) where each column is a tuple (detection, ground truth) describing a potential match. To be more precise, each match-tuple in the array corresponds to a position in the similarity matrix which will be used by the match algorithm to compute the final match.

Return type:

ndarray