A data associator is used to associate tracks and detections, and may also
include an association of a missed detection. The associations generate are
in the form a mapping each track to a hypothesis, based on “best” choice
from hypotheses generate from a Hypothesiser.
Parameters:
hypothesiser (Hypothesiser) – Generate a set of hypotheses for each track-detection pair
This a general one to one associator. It can be used to associate objects/values that have a
BaseMeasure to compare them.
Uses linear_sum_assignment() to find the minimum (or maximum) measure by
combination objects from two sources.
Notes
As default the association threshold is set to +- a large number (1e10 was chosen arbitrarily).
Infinity can’t be used, as it breaks the association algorithm.
Parameters:
measure (BaseMeasure) – This will compare two objects that could be associated together and will provide an indication of the separation between the objects.
association_threshold (float, optional) – The maximum (minimum if maximise_measure is true) value from the measure needed to associate two objects. If the default value of None is used then the association threshold is set to plus/minus an arbitrarily large number that shouldn’t limit associations.
maximise_measure (bool, optional) – Should the association algorithm attempt to maximise or minimise the output of the measure.
The maximum (minimum if maximise_measure is true) value from the measure needed to associate two objects. If the default value of None is used then the association threshold is set to plus/minus an arbitrarily large number that shouldn’t limit associations.
Associate two collections of objects together. Calculate the measure between each
object. linear_sum_assignment() is used to find
the minimum (or maximum) measure by combination objects from two sources.
Parameters:
objects_a (collection of objects to associate to the objects in objects_b)
objects_b (collection of objects to associate to the objects in objects_a)
For an association to be valid is must be over (or under if maximise_measure is True)
(non-inclusive). Therefore, setting the value to the association threshold will result in
the association not taking place.
This wrapper around the measure function allows for filtering/error checking of the
measure function. It can give an easy access point for subclasses that want to apply
additional filtering or gating.
This is a wrapper function around the associate() function. The two collections of
objects are associated to each other. The objects are entered into a dictionary:
The dictionary key is an object from either collection.
The value is the object it is associated to. If the key object isn’t associated to an
object then the value is None.
As the objects are used as dictionary keys, they must be hashable or a TypeError
will be raised.
Parameters:
objects_a (collection of hashable objects to associate to the objects in objects_b)
objects_b (collection of hashable objects to associate to the objects in objects_a)
Associates detections to a predicted state using the
Global Nearest Neighbour method, utilising a 2D matrix of
distances and a “shortest path” assignment algorithm.
Parameters:
hypothesiser (Hypothesiser) – Generate a set of hypotheses for each prediction-detection pair
Given a set of Detections and a set of Tracks, each Detection has a
probability that it is associated with each specific Track. Rather than
associate specific Detections/Tracks, JPDA calculates the new state of a
Track based on its possible association with ALL Detections. The new
state is a Gaussian Mixture, reduced to a single Gaussian.
If
then Detection is assumed to be outside Track’s gate, and the probability
of association is dropped from the Gaussian Mixture. This calculation
takes place in the function enumerate_JPDA_hypotheses().
Parameters:
hypothesiser (PDAHypothesiser) – Generate a set of hypotheses for each prediction-detection pair
Joint Probabilistic Data Association with Loopy Belief Propagation
This is a faster alternative of the standard JPDA algorithm, which makes use of
Loopy Belief Propagation (LBP) to efficiently approximately compute the marginal association
probabilities of tracks to measurements. See Williams and Lau (2014) for further details.
Jason L. Williams and Rosalyn A. Lau, Approximate evaluation of marginal association
probabilities with belief propagation, IEEE Transactions on Aerospace and Electronic Systems,
vol 50(4), pp. 2942-2959, 2014.
param hypothesiser:
Generate a set of hypotheses for each prediction-detection pair
Joint Probabilistic Data Association with Efficient Hypothesis Management (EHM)
This is a faster alternative of the standard JPDA algorithm, which makes use of
Efficient Hypothesis Management (EHM) to compute the exact marginal association probabilities
of tracks to measurements. See [2] for further details.
References
Parameters:
hypothesiser (PDAHypothesiser) – Generate a set of hypotheses for each prediction-detection pair
Joint Probabilistic Data Association with Efficient Hypothesis Management 2 (EHM2)
This is a faster alternative of the standard JPDA algorithm, which makes use of
Efficient Hypothesis Management 2 (EHM2) to compute the exact marginal association
probabilities of tracks to measurements. EHM2 takes advantage of conditional independence of
track-measurement pairs to achieve better computational performance than EHM in certain
scenarios. See [3] for further details.
References
Parameters:
hypothesiser (PDAHypothesiser) – Generate a set of hypotheses for each prediction-detection pair
Track to track associator based on the Counting Technique
Compares two sets of tracks, each formed of a sequence of
State objects and returns an Association object for
each time at which the two State within the tracks
are assessed to be associated.
Uses an algorithm called the Counting Technique [1].
Associations are triggered by track states being within a threshold
distance for a given number of timestamps. Associations are terminated when
either the two tracks end or the two State are
separated by a distance greater than the threshold at the next time step.
References
Note
Association is not prioritised based on historic associations or distance.
If, at a specific time step, the State of one of the
tracks is assessed as close to more than one track then an
Association object will be return for all possible association
combinations.
Parameters:
association_threshold (float) – Threshold distance measure which states must be within for an association to be recorded
consec_pairs_confirm (int, optional) – Number of consecutive time instances which track pairs are required to be within a specified threshold in order for an association to be formed. Default is 3
consec_misses_end (int, optional) – Number of consecutive time instances which track pairs are required to exceed a specified threshold in order for an association to be ended. Default is 2
measure (Measure, optional) – Distance measure to use. Must use EuclideanWeighted() if use_positional_only set to True. Default is EuclideanWeighted() using use_positional_only and pos_map. Note if neither are provided this is equivalent to a standard Euclidean
pos_map (list, optional) – List of items specifying the mapping of the position components of the state space for tracks_set_1. Defaults to whole StateVector(), but must be provided whenever use_positional_only is set to True
use_positional_only (bool, optional) – If True, the differences in velocity/acceleration values for each state are ignored in the calculation for the association threshold. Default is True
position_weighting (float, optional) – If use_positional_only is set to False, this decides how much to weight position components compared to others (such as velocity). Default is 0.6
one_to_one (bool, optional) – If True, it is ensured no two associations ever contain the same track at the same time
Number of consecutive time instances which track pairs are required to be within a specified threshold in order for an association to be formed. Default is 3
Number of consecutive time instances which track pairs are required to exceed a specified threshold in order for an association to be ended. Default is 2
Distance measure to use. Must use EuclideanWeighted() if use_positional_only set to True. Default is EuclideanWeighted() using use_positional_only and pos_map. Note if neither are provided this is equivalent to a standard Euclidean
List of items specifying the mapping of the position components of the state space for tracks_set_1. Defaults to whole StateVector(), but must be provided whenever use_positional_only is set to True
Compares two sets of Track, each formed of a sequence of
State objects and returns an Association object for
each time at which two State objects within the Track
are assessed to be associated. Tracks are considered to be associated with
the Truth if the true State is the closest to the track and
within the specified distance for a specified number of time steps.
Associations between Truth and Track if the Truth is no longer the
‘closest’ to the track or the distance exceeds the specified threshold for
a specified number of consecutive time steps.
Associates will be ended by consec_misses_end before any new associations
are considered even if consec_pairs_confirm < consec_misses_end
Note
Tracks can only be associated with one Truth (one-2-one relationship) at a
given time step however a Truth track can be associated with multiple
Tracks (one-2-many relationship).
Parameters:
association_threshold (float) – Threshold distance measure which states must be within for an association to be recorded
consec_pairs_confirm (int, optional) – Number of consecutive time instances which track-truth pairs are required to be within a specified threshold in order for an association to be formed. Default is 3
consec_misses_end (int, optional) – Number of consecutive time instances which track-truth pairs are required to exceed a specified threshold in order for an association to be ended. Default is 2
measure (Measure, optional) – Distance measure to use. Default Euclidean()
Number of consecutive time instances which track-truth pairs are required to be within a specified threshold in order for an association to be formed. Default is 3
Number of consecutive time instances which track-truth pairs are required to exceed a specified threshold in order for an association to be ended. Default is 2
Compares a set of Track objects to a set of GroundTruth objects,
each formed of a sequence of State objects and returns an
Association object for each time at which two State objects
within the Track and GroundTruthPath are assessed to be associated.
Tracks are considered to be associated with the Ground Truth if the ID of the Track
is the same as the ID of the Ground Truth.
association_threshold (float, optional) – The maximum (minimum if maximise_measure is true) value from the measure needed to associate two objects. If the default value of None is used then the association threshold is set to plus/minus an arbitrarily large number that shouldn’t limit associations.
maximise_measure (bool, optional) – Should the association algorithm attempt to maximise or minimise the output of the measure.
Track to truth associator used in the CLEAR MOT metrics paper[1].
Compares two sets of Track, each formed of a sequence of
State objects and returns an Association object for
each time at which a the two State within the Track
are assessed to be associated. A track keeps its association with the
truth from previous timestep,even if there is a new track which is closer to the truth.
Unassigned tracks and truths are matched using Munkres algorithm if they
are below the specified distance threshold.
Note
A track can only be associated with one Truth (one-2-one relationship) at a
given time step and vice versa.
Reference
[1] Evaluating Multiple Object Tracking Performance: The CLEAR MOT Metrics,
Bernardin et al, 2008
Parameters:
association_threshold (float) – Threshold distance measure which states must be within for an association to be recorded
measure (Measure, optional) – Distance measure to use. Default Euclidean()
Construct a kd-tree from detections and then use a Predictor and
Updater to get prediction of track in measurement space. This is
then queried against the kd-tree, and only matching detections are passed
to the hypothesiser.
Notes
This is only suitable where measurements are in same space as each other
(i.e. have the same measurement model) and at the same timestamp.
Parameters:
hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
predictor (Predictor) – Predict tracks to detection times
updater (Updater) – Updater used to get measurement prediction
number_of_neighbours (int, optional) – Number of neighbours to find. Default None, which means all points within the max_distance are returned.
max_distance (float, optional) – Max distance to return points. Default inf
max_distance_covariance_multiplier (float, optional) – If set, the max distance will be limited to maximum of covariance diagonal of the track state, multiplied by this attribute, or max_distance, whichever is smallest. Default None where only max_distance is used.
If set, the max distance will be limited to maximum of covariance diagonal of the track state, multiplied by this attribute, or max_distance, whichever is smallest. Default None where only max_distance is used.
Construct a TPR-tree to filter detections for generating hypotheses. This assumes
tracks move in constant velocity like model, using the mean and covariance to define
region to look for detections.
Notes
This requires that track state has a mean (position and velocity) and covariance, which
is then approximated to a TPR node (position, velocity and time bounding box).
Parameters:
hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
measurement_model (MeasurementModel) – Measurement model used within the TPR tree
horizon_time (datetime.timedelta) – How far the TPR tree should look into the future
pos_mapping (collections.abc.Sequence, optional) – Mapping for position coordinates. Default None, which uses the measurement modelmapping
vel_mapping (collections.abc.Sequence, optional) – Mapping for velocity coordinates. Default None, which uses the position mapping adding offset of 1 to each
DetectionKDTreeNN from NearestNeighbour and DetectionKDTreeMixIn
Parameters:
hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
predictor (Predictor) – Predict tracks to detection times
updater (Updater) – Updater used to get measurement prediction
number_of_neighbours (int, optional) – Number of neighbours to find. Default None, which means all points within the max_distance are returned.
max_distance (float, optional) – Max distance to return points. Default inf
max_distance_covariance_multiplier (float, optional) – If set, the max distance will be limited to maximum of covariance diagonal of the track state, multiplied by this attribute, or max_distance, whichever is smallest. Default None where only max_distance is used.
DetectionKDTreeGNN from GlobalNearestNeighbour and DetectionKDTreeMixIn
Parameters:
hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
predictor (Predictor) – Predict tracks to detection times
updater (Updater) – Updater used to get measurement prediction
number_of_neighbours (int, optional) – Number of neighbours to find. Default None, which means all points within the max_distance are returned.
max_distance (float, optional) – Max distance to return points. Default inf
max_distance_covariance_multiplier (float, optional) – If set, the max distance will be limited to maximum of covariance diagonal of the track state, multiplied by this attribute, or max_distance, whichever is smallest. Default None where only max_distance is used.
DetectionKDTreeGNN2D from GNNWith2DAssignment and DetectionKDTreeMixIn
Parameters:
hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
predictor (Predictor) – Predict tracks to detection times
updater (Updater) – Updater used to get measurement prediction
number_of_neighbours (int, optional) – Number of neighbours to find. Default None, which means all points within the max_distance are returned.
max_distance (float, optional) – Max distance to return points. Default inf
max_distance_covariance_multiplier (float, optional) – If set, the max distance will be limited to maximum of covariance diagonal of the track state, multiplied by this attribute, or max_distance, whichever is smallest. Default None where only max_distance is used.
hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
measurement_model (MeasurementModel) – Measurement model used within the TPR tree
horizon_time (datetime.timedelta) – How far the TPR tree should look into the future
pos_mapping (collections.abc.Sequence, optional) – Mapping for position coordinates. Default None, which uses the measurement modelmapping
vel_mapping (collections.abc.Sequence, optional) – Mapping for velocity coordinates. Default None, which uses the position mapping adding offset of 1 to each
TPRTreeGNN from GlobalNearestNeighbour and TPRTreeMixIn
Parameters:
hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
measurement_model (MeasurementModel) – Measurement model used within the TPR tree
horizon_time (datetime.timedelta) – How far the TPR tree should look into the future
pos_mapping (collections.abc.Sequence, optional) – Mapping for position coordinates. Default None, which uses the measurement modelmapping
vel_mapping (collections.abc.Sequence, optional) – Mapping for velocity coordinates. Default None, which uses the position mapping adding offset of 1 to each
TPRTreeGNN2D from GNNWith2DAssignment and TPRTreeMixIn
Parameters:
hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
measurement_model (MeasurementModel) – Measurement model used within the TPR tree
horizon_time (datetime.timedelta) – How far the TPR tree should look into the future
pos_mapping (collections.abc.Sequence, optional) – Mapping for position coordinates. Default None, which uses the measurement modelmapping
vel_mapping (collections.abc.Sequence, optional) – Mapping for velocity coordinates. Default None, which uses the position mapping adding offset of 1 to each
hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
predictor (Predictor) – Predict tracks to detection times
updater (Updater) – Updater used to get measurement prediction
number_of_neighbours (int, optional) – Number of neighbours to find. Default None, which means all points within the max_distance are returned.
max_distance (float, optional) – Max distance to return points. Default inf
max_distance_covariance_multiplier (float, optional) – If set, the max distance will be limited to maximum of covariance diagonal of the track state, multiplied by this attribute, or max_distance, whichever is smallest. Default None where only max_distance is used.
hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
predictor (Predictor) – Predict tracks to detection times
updater (Updater) – Updater used to get measurement prediction
number_of_neighbours (int, optional) – Number of neighbours to find. Default None, which means all points within the max_distance are returned.
max_distance (float, optional) – Max distance to return points. Default inf
max_distance_covariance_multiplier (float, optional) – If set, the max distance will be limited to maximum of covariance diagonal of the track state, multiplied by this attribute, or max_distance, whichever is smallest. Default None where only max_distance is used.
hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
measurement_model (MeasurementModel) – Measurement model used within the TPR tree
horizon_time (datetime.timedelta) – How far the TPR tree should look into the future
pos_mapping (collections.abc.Sequence, optional) – Mapping for position coordinates. Default None, which uses the measurement modelmapping
vel_mapping (collections.abc.Sequence, optional) – Mapping for velocity coordinates. Default None, which uses the position mapping adding offset of 1 to each
hypothesiser (Hypothesiser) – Underlying hypothesiser used to generate detection-target pairs
measurement_model (MeasurementModel) – Measurement model used within the TPR tree
horizon_time (datetime.timedelta) – How far the TPR tree should look into the future
pos_mapping (collections.abc.Sequence, optional) – Mapping for position coordinates. Default None, which uses the measurement modelmapping
vel_mapping (collections.abc.Sequence, optional) – Mapping for velocity coordinates. Default None, which uses the position mapping adding offset of 1 to each
Data associator using multi-frame assignment algorithm over a sliding window.
References
Xia, Y., Granström, K., Svensson, L., García-Fernández, Á.F., and Williams, J.L.,
2019. Multiscan Implementation of the Trajectory Poisson Multi-Bernoulli Mixture Filter.
J. Adv. Information Fusion, 14(2), pp. 213–235.
Parameters:
hypothesiser (MFAHypothesiser) – Generate a set of hypotheses for each prediction-detection pair