Skip to content

Distances#

Predefined distances

frobenius(detection, tracked_object) #

Frobernius norm on the difference of the points in detection and the estimates in tracked_object.

The Frobenius distance and norm are given by:

\[ d_f(a, b) = ||a - b||_F \]
\[ ||A||_F = [\sum_{i,j} abs(a_{i,j})^2]^{1/2} \]

Parameters:

Name Type Description Default
detection Detection

A detection.

 required
tracked_object TrackedObject

A tracked object.

 required

Returns:

Type Description
float

The distance.

See Also#

np.linalg.norm

Source code in norfair/distances.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
def frobenius(detection: "Detection", tracked_object: "TrackedObject") -> float:
    """
    Frobernius norm on the difference of the points in detection and the estimates in tracked_object.

    The Frobenius distance and norm are given by:

    $$
    d_f(a, b) = ||a - b||_F
    $$

    $$
    ||A||_F = [\\sum_{i,j} abs(a_{i,j})^2]^{1/2}
    $$

    Parameters
    ----------
    detection : Detection
        A detection.
    tracked_object : TrackedObject
        A tracked object.

    Returns
    -------
    float
        The distance.

    See Also
    --------
    [`np.linalg.norm`](https://numpy.org/doc/stable/reference/generated/numpy.linalg.norm.html)
    """
    return np.linalg.norm(detection.points - tracked_object.estimate)

mean_euclidean(detection, tracked_object) #

Average euclidean distance between the points in detection and estimates in tracked_object.

\[ d(a, b) = \frac{\sum_{i=0}^N ||a_i - b_i||_2}{N} \]

Parameters:

Name Type Description Default
detection Detection

A detection.

 required
tracked_object TrackedObject

A tracked object

 required

Returns:

Type Description
float

The distance.

See Also#

np.linalg.norm

Source code in norfair/distances.py 
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
def mean_euclidean(detection: "Detection", tracked_object: "TrackedObject") -> float:
    """
    Average euclidean distance between the points in detection and estimates in tracked_object.

    $$
    d(a, b) = \\frac{\\sum_{i=0}^N ||a_i - b_i||_2}{N}
    $$

    Parameters
    ----------
    detection : Detection
        A detection.
    tracked_object : TrackedObject
        A tracked object

    Returns
    -------
    float
        The distance.

    See Also
    --------
    [`np.linalg.norm`](https://numpy.org/doc/stable/reference/generated/numpy.linalg.norm.html)
    """
    return np.linalg.norm(detection.points - tracked_object.estimate, axis=1).mean()

mean_manhattan(detection, tracked_object) #

Average manhattan distance between the points in detection and the estimates in tracked_object

Given by:

\[ d(a, b) = \frac{\sum_{i=0}^N ||a_i - b_i||_1}{N} \]

Where \(||a||_1\) is the manhattan norm.

Parameters:

Name Type Description Default
detection Detection

A detection.

 required
tracked_object TrackedObject

a tracked object.

 required

Returns:

Type Description
float

The distance.

See Also#

np.linalg.norm

Source code in norfair/distances.py 
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
def mean_manhattan(detection: "Detection", tracked_object: "TrackedObject") -> float:
    """
    Average manhattan distance between the points in detection and the estimates in tracked_object

    Given by:

    $$
    d(a, b) = \\frac{\\sum_{i=0}^N ||a_i - b_i||_1}{N}
    $$

    Where $||a||_1$ is the manhattan norm.

    Parameters
    ----------
    detection : Detection
        A detection.
    tracked_object : TrackedObject
        a tracked object.

    Returns
    -------
    float
        The distance.

    See Also
    --------
    [`np.linalg.norm`](https://numpy.org/doc/stable/reference/generated/numpy.linalg.norm.html)
    """
    return np.linalg.norm(
        detection.points - tracked_object.estimate, ord=1, axis=1
    ).mean()

iou(detection, tracked_object) #

Intersection over union distance between the bounding boxes.

Assumes that detection.points (and by consecuence tracked_object.estimate) define a bounding box in the form [[x0, y0], [x1, y1]].

Normal IoU is 1 when the boxes are the same and 0 when they don't overlap, to transform that into a distance that makes sense we return 1 - iou.

Performs checks that the bounding boxes are valid to give better error messages. For a faster implementation without checks use iou_opt.

Parameters:

Name Type Description Default
detection Detection

A detection.

 required
tracked_object TrackedObject

A tracked object.

 required

Returns:

Type Description
float

The distance.
Source code in norfair/distances.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
def iou(detection: "Detection", tracked_object: "TrackedObject") -> float:
    """
    Intersection over union distance between the bounding boxes.

    Assumes that `detection.points` (and by consecuence `tracked_object.estimate`)
    define a bounding box in the form `[[x0, y0], [x1, y1]]`.

    Normal IoU is 1 when the boxes are the same and 0 when they don't overlap,
    to transform that into a distance that makes sense we return `1 - iou`.

    Performs checks that the bounding boxes are valid to give better error messages.
    For a faster implementation without checks use [`iou_opt`][norfair.distances.iou_opt].

    Parameters
    ----------
    detection : Detection
        A detection.
    tracked_object : TrackedObject
        A tracked object.

    Returns
    -------
    float
        The distance.
    """
    boxa = detection.points.copy()
    boxa.sort(axis=0)
    _validate_bboxes(boxa)
    boxb = tracked_object.estimate.copy()
    boxb.sort(axis=0)
    _validate_bboxes(boxb)
    return _iou(boxa, boxb)

iou_opt(detection, tracked_object) #

Optimized version of iou.

Performs faster but errors might be cryptic if the bounding boxes are not valid.

Parameters:

Name Type Description Default
detection Detection

A detection.

 required
tracked_object TrackedObject

A tracked object.

 required

Returns:

Type Description
float

The distance.
Source code in norfair/distances.py 
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
def iou_opt(detection: "Detection", tracked_object: "TrackedObject") -> float:
    """
    Optimized version of [`iou`][norfair.distances.iou].

    Performs faster but errors might be cryptic if the bounding boxes are not valid.

    Parameters
    ----------
    detection : Detection
        A detection.
    tracked_object : TrackedObject
        A tracked object.

    Returns
    -------
    float
        The distance.
    """
    return _iou(detection.points, tracked_object.estimate)

get_distance_by_name(name) #

Select a distance by name.

Valid names are: ["frobenius", "mean_euclidean", "mean_manhattan", "iou", "iou_opt"].

Source code in norfair/distances.py 
208
209
210
211
212
213
214
215
216
217
218
219
def get_distance_by_name(name: str) -> Callable[["Detection", "TrackedObject"], float]:
    """
    Select a distance by name.

    Valid names are: `["frobenius", "mean_euclidean", "mean_manhattan", "iou", "iou_opt"]`.
    """
    try:
        return _DISTANCE_FUNCTIONS[name]
    except KeyError:
        raise ValueError(
            f"Invalid distance '{name}', expecting one of {_DISTANCE_FUNCTIONS.keys()}"
        )

create_keypoints_voting_distance(keypoint_distance_threshold, detection_threshold) #

Construct a keypoint voting distance function configured with the thresholds.

Count how many points in a detection match the with a tracked_object. A match is considered when distance between the points is < keypoint_distance_threshold and the score of the last_detection of the tracked_object is > detection_threshold. Notice the if multiple points are tracked, the ith point in detection can only match the ith point in the tracked object.

Distance is 1 if no point matches and approximates 0 as more points are matched.

Parameters:

Name Type Description Default
keypoint_distance_threshold float

Points closer than this threshold are considered a match.

 required
detection_threshold float

Detections and objects with score lower than this threshold are ignored.

 required

Returns:

Type Description
Callable

The distance funtion that must be passed to the Tracker.
Source code in norfair/distances.py 
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
def create_keypoints_voting_distance(
    keypoint_distance_threshold: float, detection_threshold: float
) -> Callable[["Detection", "TrackedObject"], float]:
    """
    Construct a keypoint voting distance function configured with the thresholds.

    Count how many points in a detection match the with a tracked_object.
    A match is considered when distance between the points is < `keypoint_distance_threshold`
    and the score of the last_detection of the tracked_object is > `detection_threshold`.
    Notice the if multiple points are tracked, the ith point in detection can only match the ith
    point in the tracked object.

    Distance is 1 if no point matches and approximates 0 as more points are matched.

    Parameters
    ----------
    keypoint_distance_threshold: float
        Points closer than this threshold are considered a match.
    detection_threshold: float
        Detections and objects with score lower than this threshold are ignored.

    Returns
    -------
    Callable
        The distance funtion that must be passed to the Tracker.
    """

    def keypoints_voting_distance(
        detection: "Detection", tracked_object: "TrackedObject"
    ) -> float:
        distances = np.linalg.norm(detection.points - tracked_object.estimate, axis=1)
        match_num = np.count_nonzero(
            (distances < keypoint_distance_threshold)
            * (detection.scores > detection_threshold)
            * (tracked_object.last_detection.scores > detection_threshold)
        )
        return 1 / (1 + match_num)

    return keypoints_voting_distance

create_normalized_mean_euclidean_distance(height, width) #

Construct a normalized mean euclidean distance function configured with the max height and width.

The result distance is bound to [0, 1] where 1 indicates oposite corners of the image.

Parameters:

Name Type Description Default
height int

Height of the image.

 required
width int

Width of the image.

 required

Returns:

Type Description
Callable

The distance funtion that must be passed to the Tracker.
Source code in norfair/distances.py 
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
def create_normalized_mean_euclidean_distance(
    height: int, width: int
) -> Callable[["Detection", "TrackedObject"], float]:
    """
    Construct a normalized mean euclidean distance function configured with the max height and width.

    The result distance is bound to [0, 1] where 1 indicates oposite corners of the image.

    Parameters
    ----------
    height: int
        Height of the image.
    width: int
        Width of the image.

    Returns
    -------
    Callable
        The distance funtion that must be passed to the Tracker.
    """

    def normalized__mean_euclidean_distance(
        detection: "Detection", tracked_object: "TrackedObject"
    ) -> float:
        """Normalized mean euclidean distance"""
        # calculate distances and normalized it by width and height
        difference = (detection.points - tracked_object.estimate).astype(float)
        difference[:, 0] /= width
        difference[:, 1] /= height

        # calculate eucledean distance and average
        return np.linalg.norm(difference, axis=1).mean()

    return normalized__mean_euclidean_distance