Main Content

trackFuser

Single-hypothesis track-to-track fuser

expand all in page

Description

The trackFuser System object™ fuses tracks generated by tracking sensors or trackers and architect decentralized tracking systems. trackFuser uses the global nearest neighbor (GNN) algorithm to maintain a single hypothesis about the objects it tracks. The input tracks are called source or local tracks, and the output tracks are called central tracks.

To fuse tracks using this object:

  1. Create the trackFuser 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?

Creation

Syntax

fuser = trackFuser
fuser = trackFuser(Name,Value)

Description

fuser = trackFuser creates a track-to-track fuser that uses the global nearest neighbor (GNN) algorithm to maintain a single hypothesis about the objects it tracks.

example

fuser = trackFuser(Name,Value) sets properties for the fuser using one or more name-value pairs. Unspecified properties have default values. Enclose each property name in single 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.

Unique index for the fuser, specified as a positive integer. Use this property to distinguish different fusers in a multiple-fuser environment.

Example: 2

Maximum number of source configurations that the fuser can maintain, specified as a positive integer.

Example: 200

Configurations of source systems, specified as a cell array of fuserSourceConfiguration objects. The default value is a 1-by-N cell array of fuserSourceConfiguration objects, where N is the value of the MaxNumSources property. You can specify this property during creation as a Name-Value pair or specify it after creation.

Data Types: object

Assignment algorithm, specified as 'MatchPairs', 'Munkres', 'Jonker-Volgenant', 'Auction', or 'Custom'. Munkres is the only assignment algorithm that guarantees an optimal solution, but it is also the slowest, especially for large numbers of detections and tracks. The other algorithms do not guarantee an optimal solution but can be faster for problems with 20 or more tracks and detections. Use'Custom' to define your own assignment function and specify its name in the CustomAssignmentFcn property.

Data Types: char

Custom assignment function, specified as a function handle. An assignment function must have the following syntax:

 [assignments,unassignedCentral,unassignedLocal] = f(cost,costNonAssignment)
For an example of assignment function and a description of its arguments, see assignmunkres.

Dependencies

To enable this property, set the Assignment property to 'Custom'.

Data Types: function handle | string | char

Track-to-track assignment threshold, specified as a positive scalar or a 1-by-2 vector of [C1,C2], where C1 ≤ C2. If specified as a scalar, the specified value, val, is expanded to [val, Inf].

Initially, the fuser executes a coarse estimation for the normalized distance between all the local and central tracks. The fuser only calculates the accurate normalized distance for the local and central combinations whose coarse normalized distance is less than C2. Also, the fuser can only assign a local track to a central track if their accurate normalized distance is less than C1. See Algorithms for an explanation of the normalized distance.

Tips:

  • Increase the value of C2 if there are combinations of local and central tracks that should be calculated for assignment but are not. Decrease it if the calculation takes too much time.

  • Increase the value of C1 if there are local tracks that should be assigned to central tracks but are not. Decrease it if there are local tracks that are assigned to central tracks they should not be assigned to (too far away).

State transition function, specified as a function handle. This function calculates the state at time step k based on the state at time step k–1.

  • If HasAdditiveProcessNoise is true, the function must use the following syntax:

    x(k) = f(x(k-1),dt)
    where:

    • x(k) — The (estimated) state at time k, specified as a vector or a matrix. If specified as a matrix, then each column of the matrix represents one state vector.

    • dt — The time step for prediction.

  • If HasAdditiveProcessNoise is false, the function must use this syntax:

    x(k) = f(x(k-1),w(k-1),dt)
    where:

    • x(k) — The (estimated) state at time k, specified as a vector or a matrix. If specified as a matrix, then each column of the matrix represents one state vector.

    • w(k) — The process noise at time k.

    • dt — The time step for prediction.

Example: @constacc

Data Types: function_handle | char | string

Jacobian of the state transition function, specified as a function handle. If not specified, the Jacobian is numerically computed, which may increase processing time and numerical inaccuracy. If specified, the function must support one of these two syntaxes:

  • If HasAdditiveProcessNoise is true, the function must use this syntax:

    Jx(k) = statejacobianfcn(x(k),dt)
    where:

    • x(k) — The (estimated) state at time k, specified as an M-by-1 vector of real values.

    • dt — The time step for prediction.

    • Jx(k) — The Jacobian of the state transition function with respect to the state, df/dx, evaluated at x(k). The Jacobian is returned as an M-by-M matrix.

  • If HasAdditiveProcessNoise is false, the function must use this syntax:

    [Jx(k),Jw(k)] = statejacobianfcn(x(k),w(k),dt)
    where:

    • x(k) — The (estimated) state at time k, specified as an M-by-1 vector of real values.

    • w(k) — The process noise at time k, specified as a W-by-1 vector of real values.

    • dt — The time step for prediction.

    • Jx(k) — The Jacobian of the state transition function with respect to the state, df/dx, evaluated at x(k). The Jacobian is returned as an M-by-M matrix.

    • Jw(k) — The Jacobian of the state transition function with respect to the process noise, df/dw, evaluated at x(k) and w(k). The Jacobian is returned as an M-by-W matrix.

Example: @constaccjac

Data Types: function_handle | char | string

Process noise covariance, specified as a positive real scalar or a positive definite matrix.

  • When HasAdditiveProcessNoise is true, specify the process noise covariance as a positive real scalar or a positive definite M-by-M matrix. M is the dimension of the state vector. When specified as a scalar, the matrix is a multiple of the M-by-M identity matrix.

  • When HasAdditiveProcessNoise is false, specify the process noise covariance as a W-by-W matrix. W is the dimension of the process noise vector.

Example: [1.0 0.05; 0.05 2]

Data Types: single | double

Option to model process noise as additive, specified as true or false. When this property is true, process noise is added to the state vector. Otherwise, noise is incorporated into the state transition function.

Parameters of the track state reference frame, specified as a structure or a structure array. The fuser passes its StateParameters property values to the StateParameters property of the generated tracks. You can use these parameters to define the reference frame in which the track is reported or other desirable attributes of the generated tracks.

For example, you can use the following structure to define a rectangular reference frame whose origin position is at [10 10 0] meters and whose origin velocity is [2 -2 0] meters per second with respect to the scenario frame.

Field NameValue
Frame"Rectangular"
Position[10 10 0]
Velocity[2 -2 0]

Tunable: Yes

Data Types: struct

Threshold for central track confirmation, specified as a positive integer M, or a 1-by-2 vector of positive integers [M N] with M ≤ N. A central track is confirmed if it is assigned to local tracks at least M times in the last N updates. If specified a positive integer M, the confirmation threshold is expanded to [M,M].

Data Types: single | double

Threshold for central track deletion, specified as a positive integer P, or a 1-by-2 vector of positive integers [P R] with P ≤ R. A central track is deleted if the track is not assigned to local tracks at least P times in the last R updates. If specified a positive integer P, the confirmation threshold is expanded to [P,P].

Example: [5 6]

Data Types: single | double

Fuse only confirmed local tracks, specified as false or true. Set this property to false if you want to fuse all local tracks regardless of their confirmation status.

Data Types: logical

Fuse coasted local tracks, specified as true or false. Set this property to true if you want to fuse coasted local tracks (IsCoasted field or property of the localTracks input is true). Set it to false if you want to only fuse local tracks that are not coasted.

Example: true

Data Types: logical

State fusion algorithm, specified as:

  • 'Cross' — Uses the cross-covariance fusion algorithm

  • 'Intersection' — Uses the covariance intersection fusion algorithm

  • 'Custom' — Allows you to specify a customized fusion function

Use the StateFusionParameters property to specify additional parameters used by the state fusion algorithm.

Data Types: char

Custom state fusion function, specified as a function handle. The state fusion function must support one of the following syntaxes:

[fusedState,fusedCov] = f(trackState,trackCov)
[fusedState,fusedCov] = f(trackState,trackCov,fuseParams)
where:

  • trackState is specified as an N-by-M matrix. N is the dimension of the track state, and M is the number of tracks.

  • trackCov is specified as an N-by-N-M matrix. N is the dimension of the track state, and M is the number of tracks.

  • fuseParams is optional parameters defined in the StateFusionParameters property.

  • fusedState is returned as an N-by-1 vector.

  • fusedCov is returned as an N-by-N matrix.

Dependencies

To enable this property, set the StateFusion property to 'Custom'.

Data Types: function_handle | char | string

Parameters for state fusion function. Depending on the choice of StateFusion algorithm, you can specify StateFusionParameters as:

  • If StateFusion is 'Cross', specify it as a scalar in (0,1). See fusexcov for more details.

  • If StateFusion is 'Intersection', specify it as 'det' or 'trace'. See fusecovint for more details.

  • If StateFusion is 'Custom', you can specify these parameters in any variable type, as long as they match the setup of the optional fuseParams input of the custom state fusion function specified in the CustomStateFusionFcn property.

By default, the property is empty.

This property is read-only.

Number of central tracks currently maintained by the fuser, returned as a nonnegative integer.

Data Types: double

This property is read-only.

Number of confirmed central tracks currently maintained by the fuser, returned as a nonnegative integer.

Data Types: double

Usage

Syntax

confirmedTracks = fuser(localTracks,tFusion)
[confirmedTracks,tentativeTracks,allTracks,analysisInformation] = fuser(localTracks,tFusion)

Description

confirmedTracks = fuser(localTracks,tFusion) returns a list of confirmed tracks from a list of local tracks. Confirmed tracks are predicted to the update time, tFusion.

[confirmedTracks,tentativeTracks,allTracks,analysisInformation] = fuser(localTracks,tFusion) also returns a list of tentative tracks, a list of all tracks, and the analysis information.

Input Arguments

expand all

Local tracks, specified as an array of objectTrack objects, or an array of structures with field names that match the property names of an objectTrack object. Local tracks are tracks generated from trackers in a source track system.

Tip

To specify an empty objectTrack object, use objectTrack.empty(). To specify an empty structure, use repmat(toStruct(objectTrack),0,0).

Data Types: object | struct

Update time, specified as a scalar. The fuser predicts all central tracks to this time. Units are in seconds.

Data Types: single | double

Output Arguments

expand all

Confirmed tracks, returned as an array of objectTrack objects in MATLAB®, and returned as an array of structures in code generation. In code generation, the field names of the returned structure are same with the property names of objectTrack.

A track is confirmed if it satisfies the confirmation threshold specified in the ConfirmationThreshold property. In that case, the IsConfirmed property of the object or field of the structure is true.

Data Types: struct | object

Tentative tracks, returned as an array of objectTrack objects in MATLAB, and returned as an array of structures in code generation. In code generation, the field names of the returned structure are same with the property names of objectTrack.

A track is tentative if it does not satisfy the confirmation threshold specified in the ConfirmationThreshold property. In that case, the IsConfirmed property of the object or field of the structure is false.

Data Types: struct | object

All tracks, returned as an array of objectTrack objects in MATLAB, and returned as an array of structures in code generation. In code generation, the field names of the returned structure are same with the property names of objectTrack. All tracks consists of confirmed and tentative tracks.

Data Types: struct | object

Additional information for analyzing track updates, returned as a structure. The fields of this structure are:

FieldDescription
TrackIDsAtStepBeginning

Track IDs when the step began

CostMatrix

Cost of assignment matrix

Assignments

Assignments returned from the assignment function

UnassignedCentralTracks

IDs of unassigned central tracks

UnassignedLocalTracks

IDs of unassigned local tracks

NonInitializingLocalTracksIDs of local tracks that were unassigned but were not used to initialize a central track
InitiatedCentralTrackIDs

IDs of central tracks initiated during the step

UpdatedCentralTrackIDsIDs of central tracks updated during the step
DeletedTrackIDs

IDs of central tracks deleted during the step

TrackIDsAtStepEnd

IDs of central tracks when the step ended

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

predictTrackToTimePredict track state
initializeTrackInitialize new track
deleteTrackDelete existing track
sourceIndicesFuser source indices
exportToSimulinkExport tracker or track fuser to Simulink model
stepRun System object algorithm
releaseRelease resources and allow changes to System object property values and input characteristics
cloneCreate duplicate System object
isLockedDetermine if System object is in use
resetReset internal states of System object

Examples

collapse all

Open Live Script

Define two tracking sources: one internal and one external. The SourceIndex of each source must be unique.

internalSource = fuserSourceConfiguration(1,'IsInternalSource',true);
externalSource = fuserSourceConfiguration(2,'IsInternalSource',false);

Create a trackFuser with FuserIndex equal to 3. The fuser takes the two sources defined above and uses the 'Cross' StateFusion model. 

fuser = trackFuser('FuserIndex',3, 'MaxNumSources',2, ...
       'SourceConfigurations',{internalSource;externalSource}, ...
       'StateFusion','Cross');

Update the fuser with two tracks from the two sources. Use a 3-D constant velocity state, in which the states are given in the order of [x; vx; y; vy; z; vz]. The states of the two tracks are the same, but their covariances are different. For the first track, create a large covariance in the x-axis. For the second track, create a large covariance in the y-axis.

tracks = [objectTrack('SourceIndex',1,'State',[10;0;0;0;0;0], ...
          'StateCovariance',diag([100,1000,1,10,1,10])); ...
          objectTrack('SourceIndex',2,'State',[10;0;0;0;0;0], ...
          'StateCovariance',diag([1,10,100,1000,1,10]))];

Fuse the track with fusion time equal to 0.

time = 0;
confirmedTracks = fuser(tracks,time);

Obtain the positions and position covariances of the source tracks and confirmed tracks.

positionSelector = [1 0 0 0 0 0; 0 0 1 0 0 0; 0 0 0 0 1 0]; % [x; y; z]
[inputPos,inputCov] = getTrackPositions(tracks,positionSelector);
[outputPos,outputCov] = getTrackPositions(confirmedTracks,positionSelector);

Visualize the results using trackPlotter.

 tPlotter = theaterPlot('XLim',[0, 20],'YLim',[-10, 10],'ZLim',[-10, 10]);
 tPlotter1 = trackPlotter(tPlotter,'DisplayName','Input Tracks','MarkerEdgeColor','blue');
 tPlotter2 = trackPlotter(tPlotter,'DisplayName','Fused Tracks','MarkerEdgeColor','green');
 
 plotTrack(tPlotter1,inputPos,inputCov)
 plotTrack(tPlotter2,outputPos,outputCov)
 title('Cross-covariance fusion')

Figure contains an axes object. The axes object with title Cross-covariance fusion contains 2 objects of type line. These objects represent Input Tracks, Fused Tracks.

References

[1] Blackman, S. and Popoli, R., 1999. Design and analysis of modern tracking systems(Book). Norwood, MA: Artech House, 1999.

[2] Chong, Chee-Yee, Shozo Mori, William H. Barker, and Kuo-Chu Chang. "Architectures and algorithms for track association and fusion." IEEE Aerospace and Electronic Systems Magazine 15, no. 1 (2000): 5-13.

[3] Tian, Xin, Yaakov Bar-Shalom, D. Choukroun, Y. Oshman, J. Thienel, and M. Idan. "Track-to-Track Fusion Architectures-A Review." In book “Advances in Estimation, Navigation, and Spacecraft Control”. Springer, 2015.

Extended Capabilities

Version History

Introduced in R2019b

See Also

| | | |

External Websites