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

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

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

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(candidates, objects)

Calculate IoU between two sets of bounding boxes. Both sets of boxes are expected to be in [x_min, y_min, x_max, y_max] format.

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.

Parameters:

Name	Type	Description	Default
candidates	ndarray	(N, 4) numpy.ndarray containing candidates bounding boxes.	required
objects	ndarray	(K, 4) numpy.ndarray containing objects bounding boxes.	required

Returns:

Type	Description
ndarray	(N, K) numpy.ndarray of 1 - iou between candidates and objects.

Source code in norfair/distances.py

def iou(candidates: np.ndarray, objects: np.ndarray) -> np.ndarray:
    """
    Calculate IoU between two sets of bounding boxes. Both sets of boxes are expected
    to be in `[x_min, y_min, x_max, y_max]` format.

    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`.

    Parameters
    ----------
    candidates : numpy.ndarray
        (N, 4) numpy.ndarray containing candidates bounding boxes.
    objects : numpy.ndarray
        (K, 4) numpy.ndarray containing objects bounding boxes.

    Returns
    -------
    numpy.ndarray
        (N, K) numpy.ndarray of `1 - iou` between candidates and objects.
    """
    _validate_bboxes(candidates)

    area_candidates = _boxes_area(candidates.T)
    area_objects = _boxes_area(objects.T)

    top_left = np.maximum(candidates[:, None, :2], objects[:, :2])
    bottom_right = np.minimum(candidates[:, None, 2:], objects[:, 2:])

    area_intersection = np.prod(
        np.clip(bottom_right - top_left, a_min=0, a_max=None), 2
    )
    return 1 - area_intersection / (
        area_candidates[:, None] + area_objects - area_intersection
    )

get_distance_by_name(name)

Select a distance by name.

Parameters:

Name	Type	Description	Default
name	str	A string defining the metric to get.	required

Returns:

Type	Description
Distance	The distance object.

Source code in norfair/distances.py

def get_distance_by_name(name: str) -> Distance:
    """
    Select a distance by name.

    Parameters
    ----------
    name : str
        A string defining the metric to get.

    Returns
    -------
    Distance
        The distance object.
    """

    if name in _SCALAR_DISTANCE_FUNCTIONS:
        warning(
            "You are using a scalar distance function. If you want to speed up the"
            " tracking process please consider using a vectorized distance function"
            f" such as {AVAILABLE_VECTORIZED_DISTANCES}."
        )
        distance = _SCALAR_DISTANCE_FUNCTIONS[name]
        distance_function = ScalarDistance(distance)
    elif name in _SCIPY_DISTANCE_FUNCTIONS:
        distance_function = ScipyDistance(name)
    elif name in _VECTORIZED_DISTANCE_FUNCTIONS:
        if name == "iou_opt":
            warning("iou_opt is deprecated, use iou instead")
        distance = _VECTORIZED_DISTANCE_FUNCTIONS[name]
        distance_function = VectorizedDistance(distance)
    else:
        raise ValueError(
            f"Invalid distance '{name}', expecting one of"
            f" {list(_SCALAR_DISTANCE_FUNCTIONS.keys()) + AVAILABLE_VECTORIZED_DISTANCES}"
        )

    return distance_function

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

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

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