This is machine translation

Translated by Microsoft
Mouseover text to see original. Click the button below to return to the English version of the page.

Note: This page has been translated by MathWorks. Click here to see
To view all translated materials including this page, select Country from the country navigator on the bottom of this page.

trackAssignmentMetrics

Track establishment, maintenance, and deletion metrics

Description

The trackAssignmentMetrics System object™ compares tracks from a multi-object tracking system against known truth by automatic assignment of tracks to the known truths at each track update. An assignment distance metric determines the maximum distance for which a track can be assigned to the truth object. A divergence distance metric determines when a previously assigned track can be reassigned to a different truth object when the distance exceeds another set threshold.

To generate track assignment metrics:

  1. Create the trackAssignmentMetrics object and set its properties.

  2. Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects? (MATLAB).

Creation

Syntax

assignmentMetics = trackAssignmentMetrics
assignmentMetics = trackAssignmentMetrics(Name,Value)

Description

assignmentMetics = trackAssignmentMetrics creates a trackAssignmentMetrics System object, assignmentMetics, with default property values.

example

assignmentMetics = trackAssignmentMetrics(Name,Value) sets properties for the trackAssignmentMetrics object using one or more name-value pairs. For example, assignmentMetics = trackAssignmentMetrics('AssignmentThreshold',5) creates a trackAssignmentMetrics object with an assignment threshold of 5. Enclose property names in quotes.

Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects (MATLAB).

Maximum permitted assignment distance between a newly encountered or divergent track and a truth object, specified as a nonnegative scalar. For distances beyond this value, assignments between the track and the truth cannot take place. Units are in normalized estimation error squared (NEES).

Data Types: single | double

Maximum permitted divergence distance between a track state and the state of an assigned truth object, specified as a nonnegative scalar. For distances beyond this value, tracks are eligible for reassignment to a different truth object. Units are in NEES.

Data Types: single | double

Distance function format specified as 'built-in' or 'custom'.

  • 'built-in' – Enable the MotionModel, AssignmentDistance, and DivergenceDistance properties. These properties are convenient interfaces when using tracks reported by any built-in multi-object tracker, and truths reported by the platformPoses object function of a trackingScenario object.

  • 'custom' – Enable custom properties: AssignmentDistanceFcn, DivergenceDistanceFcn, IsInsideCoverageAreaFcn, TruthIdentifierFcn, TrackIdentifierFcns. You can use these properties to construct acceptance or divergence distances, coverage areas, and identifiers for arbitrary 'tracks' and 'truths' input arrays.

Desired platform motion model, specified as 'constvel', 'constacc', or 'constturn'. This property selects the motion model used by the tracks input. The motion model governs the outputs when the object is executed.

The motion models expect the 'State' field to have a column vector as follows:

  • 'constvel' - Position is in elements [1 3 5], velocity in elements [2 4 6].

  • 'constacc' - Position is in elements [1 4 7], velocity in elements [2 5 8], and acceleration in elements [3 6 9].

  • 'constturn' - Position is in elements [1 3 6], velocity in elements [2 4 7], and yaw rate in element 5.

The 'StateCovariance' field of the tracks input must have position, velocity, and turn information in the rows and columns corresponding to the 'State' field position and velocity input selector.

Dependencies

To enable this property, set the DistanceFunctionFormat property to 'built-in'.

Type of assignment distance, specified as 'posnees', 'velnees', 'posabserr', or 'velabserr'. The type specifies the physical quantity used for assignment. When a new track is detected or a track becomes divergent, the track is compared against truth using this quantity. The assignment seeks the closest truth within the threshold defined by the AssignmentThreshold property.

  • 'posnees' – NEES error of track position

  • 'velnees' – NEES error in track velocity

  • 'posabserr' – Absolute error of track position

  • 'velabserr' – Absolute error of track velocity

Dependencies

To enable this property, set the DistanceFunctionFormat property to 'built-in'.

Type of divergence distance, specified as 'posnees', 'velnees', 'posabserr', or 'velabserr'. The type specifies the physical quantity used for assessing divergence. When a track was previously assigned to truth, the distance between them is compared to this quantity on subsequent update steps. Any track whose divergence distance to its truth assignment exceeds the value of DivergenceThreshold is considered divergent and can be reassigned to a new truth.

  • 'posnees' – NEES error of track position

  • 'velnees' – NEES error in track velocity

  • 'posabserr' – Absolute error of track position

  • 'velabserr' – Absolute error of track velocity

Dependencies

To enable this property, set the DistanceFunctionFormat property to 'built-in'.

Assignment distance function, specified as a function handle. This function determines the assignment distance of truth to tracks. Whenever a new track is detected or a track becomes divergent, the track is compared against all truths passed in at each object update. Use this function to find the closest truth within the threshold defined by the AssignmentThreshold property.

The function must have the following syntax:

dist = assignmentdistance(onetrack,onetruth)
The function must return a nonnegative assignment distance, dist, typically expressed in units of NEES. onetrack is an element of the tracks array input argument at object update. onetruth is an element of the truths array input argument.

Dependencies

To enable this property, set the DistanceFunctionFormat property to 'custom'.

Data Types: function_handle

Divergence distance function, specified as a function handle. This function determines the divergence distance of truths to tracks. If the divergence distance from a track to its truth assignment exceeds the DivergenceThreshold, the track is considered divergent and can be reassigned to a new truth.

The function must have the following syntax:

dist = divergencedistance(onetrack,onetruth)
The function must return a non-negative divergence distance, dist, typically expressed in units of NEES. onetrack is an element of the tracks array input argument at object update. onetruthtruth is an element of the truths array input argument.

Dependencies

To enable this property, set the DistanceFunctionFormat property to 'custom'.

Data Types: function_handle

Detectable 'truth' object, specified as a function handle. This function determines when a 'truth' object is inside the coverage area of the sensors and is therefore detectable.

The function must have the following syntax:

status = isinsidecoveragearea(truths)
and return a logical array, status. status is true when the truth objects, truths, are within the coverage area. truths is the same truths array input argument at object update. status must have the same size as truths.

Dependencies

To enable this property, set the DistanceFunctionFormat property to 'custom'.

Data Types: function_handle

Track identifier function for the track input at object update, specified as a function handle. The track identifiers are unique string or numeric values.

The function must have the following syntax

trackids = trackidentifier(tracks)
and return a numeric array, trackids. trackids must have the same size as tracks input argument. tracks is the same tracks array input argument at object update.

Dependencies

To enable this property, set the DistanceFunctionFormat property to 'custom'.

Data Types: function_handle

Truth identifier function for the truth input at object update, specified as a function handle. The truth identifiers are unique string or numeric values.

The function must have the following syntax

truthids = truthidentifier(truths)
and return a numeric array, truthids. truthids must have the same size as the truths input argument. truths is the same truth array input argument at object update.

Dependencies

To enable this property, set the DistanceFunctionFormat property to 'custom'.

Data Types: function_handle

Track identifier for invalid assignment, specified as a scalar or string. This value is returned when the track assignment is invalid. The value must be of the same class as returned by the function handle specified in TrackIdentifierFcn.

Example: -1

Data Types: single | double | string

Truth identifier for invalid assignment, specified as a scalar or string. This value is returned when the truth assignment is invalid. The value must be of the same class as returned by the function handle specified in TruthIdentifierFcn.

Example: -1

Data Types: single | double | string

Usage

To compute metrics, call the track assignment metrics with arguments, as if it were a function (described here).

Syntax

[tracksummary,truthsummary] = assignmentMetics(tracks,truths)

Description

[tracksummary,truthsummary] = assignmentMetics(tracks,truths) returns structures, tracksummary and truthsummary, containing cumulative metrics across all tracks and truths, obtained from the previous object update.

Input Arguments

expand all

Track information, specified as a structure or array of structures. For built-in trackers such as trackerGNN or trackerTOMHT, the structure contains 'State', 'StateCovariance', and 'TrackID' information.

Data Types: struct

Truth information, specified as a structure or array of structures. When using a trackingScenario, truth information can be obtained from the platformPoses object function.

Data Types: struct

Output Arguments

expand all

Cumulative metrics over all tracks, returned as a structure. The metrics are computed over all tracks since the last call to the reset object function. The structure has these fields:

FieldDescription
TotalNumTracks

The total number of unique track identifiers encountered

NumFalseTracks

The number of tracks never assigned to any truth

MaxSwapCount

Maximum number of track swaps of each track. A track swap occurs whenever a track is assigned to a different truth.

TotalSwapCount

Total number of track swaps of each track. A track swap occurs whenever a track is assigned to a different truth.

MaxDivergenceCount

Maximum number of divergences. A track is divergent when the result of the DivergenceDistanceFcn is greater than the divergence threshold.

TotalDivergenceCount

Total number of divergences. A track is divergent when the result of the divergence distance function is greater than the divergence threshold.

MaxDivergenceLength

Maximum number of updates during which each track was in a divergent state

TotalDivergenceLength

Total number of updates during which each track was in a divergent state

MaxRedundancyCount

The maximum number of additional tracks assigned to the same truth

TotalRedundancyCount

The total number of additional tracks assigned to the same truth

MaxRedundancyLength

Maximum number of updates during which each track was in a redundant state

TotalRedundancyLength

Total number of updates during which each track was in a redundant state

Data Types: struct

Cumulative assignment metrics over all truths, returned as a structure. The metrics are computed over all truths since the last call to the reset object function. The structure has these fields:

FieldDescription
TotalNumTruths

The total number of unique truth identifiers encountered

NumMissingTruths

The number of truths never established with any track

MaxEstablishmentLength

Maximum number of updates before a truth was associated with any track while inside the coverage area. The lengths of missing truths do not count toward this summary metric.

TotalEstablishmentLength

Total number of updates before a truth was associated with any track while inside the coverage area. The lengths of missing truths do not count toward this summary metric.

MaxBreakCount

Maximum number of times each truth was unassociated by any track after being established.

TotalBreakCount

Total number of times each truth was unassociated by any track after being established.

MaxBreakLength

Maximum number of updates during which each truth was in a broken state

TotalBreakLength

Total number of updates during which each truth was in a broken state

Data Types: struct

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

expand all

currentAssignmentMapping of tracks to truth
trackMetricsTableCompare tracks to truth
truthMetricsTableCompare truth to tracks
releaseRelease resources and allow changes to System object property values and input characteristics
resetReset internal states of System object
isLockedDetermine if System object is in use
cloneCreate duplicate System object

Examples

expand all

Examine the assignments and errors for a system tracking two targets.

First, load the stored track data.

load trackmetricex tracklog truthlog

Create objects to analyze assignment and error metrics.

tam = trackAssignmentMetrics;
tem = trackErrorMetrics;

Create the output variables.

posRMSE = zeros(numel(tracklog),1);
velRMSE = zeros(numel(tracklog),1);
posANEES = zeros(numel(tracklog),1);
velANEES = zeros(numel(tracklog),1);

Loop over all tracks to:

  • Extract the tracks and ground truth at the i th tracker update.

  • Analyze and retrieve the current track-to-truth assignment.

  • Analyze instantaneous error metrics over all tracks and truths.

for i=1:numel(tracklog)
    tracks = tracklog{i};
    truths = truthlog{i};
    [trackAM,truthAM] = tam(tracks, truths);
    [trackIDs,truthIDs] = currentAssignment(tam);
    [posRMSE(i),velRMSE(i),posANEES(i),velANEES(i)] = ...
        tem(tracks,trackIDs,truths,truthIDs);
end

Show the track metrics table.

trackMetricsTable(tam)
ans =

  4x15 table

    TrackID    AssignedTruthID    Surviving    TotalLength    DeletionStatus    DeletionLength    DivergenceStatus    DivergenceCount    DivergenceLength    RedundancyStatus    RedundancyCount    RedundancyLength    FalseTrackStatus    FalseTrackLength    SwapCount
    _______    _______________    _________    ___________    ______________    ______________    ________________    _______________    ________________    ________________    _______________    ________________    ________________    ________________    _________

       1             NaN            false         1120            false               0                false                 3                   3                false                 0                   0                false                 0                0    
       2             NaN            false         1736            false               0                false                 8                  88                false                 0                   0                false                 0                3    
       6               3            true          1138            false               0                false                 4                 314                false                 1                  28                false                 0                2    
       8               2            true           662            false               0                false                 2                  29                false                 1                 169                false                 0                0    

Show the truth metrics table.

truthMetricsTable(tam)
ans =

  2x10 table

    TruthID    AssociatedTrackID    DeletionStatus    TotalLength    BreakStatus    BreakCount    BreakLength    InCoverageArea    EstablishmentStatus    EstablishmentLength
    _______    _________________    ______________    ___________    ___________    __________    ___________    ______________    ___________________    ___________________

       2               8                false            2678           false           4             168            true                 true                    56         
       3               6                false            2678           false           3             645            true                 true                    84         

Plot the RMSE and ANEES error metrics.

subplot(2,2,1)
plot(posRMSE)
title('Position Error')
xlabel('tracker update')
ylabel('RMSE (m)')

subplot(2,2,2)
plot(velRMSE)
title('Velocity Error')
xlabel('tracker update')
ylabel('RMSE (m/s)')

subplot(2,2,3)
plot(posANEES)
title('Position Error')
xlabel('tracker update')
ylabel('ANEES')

subplot(2,2,4)
plot(velANEES)
title('Velocity Error')
xlabel('tracker update')
ylabel('ANEES')

Show the current error metrics for each individual recorded track.

currentTrackMetrics(tem)
ans =

  2x5 table

    TrackID    posRMS    velRMS    posANEES    velANEES
    _______    ______    ______    ________    ________

       6       44.712    20.988    0.05974     0.31325 
       8       129.26    12.739     1.6745      0.2453 

Show the current error metrics for each individual recorded truth object.

currentTruthMetrics(tem)
ans =

  2x5 table

    TruthID    posRMS    velRMS    posANEES    velANEES
    _______    ______    ______    ________    ________

       2       129.26    12.739     1.6745      0.2453 
       3       44.712    20.988    0.05974     0.31325 

Show the cumulative error metrics for each individual recorded track.

cumulativeTrackMetrics(tem)
ans =

  4x5 table

    TrackID    posRMS    velRMS    posANEES    velANEES
    _______    ______    ______    ________    ________

       1       117.69    43.951    0.58338     0.44127 
       2        129.7      42.8    0.81094     0.42509 
       6       371.35    87.083     4.5208      1.6952 
       8       130.45    53.914     1.0448     0.44813 

Show the cumulative error metrics for each individual recorded truth object.

cumulativeTruthMetrics(tem)
ans =

  2x5 table

    TruthID    posRMS    velRMS    posANEES    velANEES
    _______    ______    ______    ________    ________

       2       258.21    65.078     2.2514     0.93359 
       3       134.41    48.253    0.96314     0.49183 

Introduced in R2018b