trackFuser

Single-hypothesis track-to-track fuser

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.

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

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.

FuserIndex — Unique index for track fuser

1 (default) | positive integer

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

Example: 2

MaxNumSources — Maximum number of source configurations

20 (default) | positive integer

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

Example: 200

SourceConfigurations — Configurations of source systems

cell array of fuserSourceConfiguration objects

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 — Assignment algorithm

'MatchPairs' (default) | 'Munkres' | 'Jonker-Volgenant' | 'Auction' | 'Custom'

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

CustomAssignmentFcn — Custom assignment function

function handle

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

AssignmentThreshold — Track-to-track assignment threshold

30*[1 Inf] (default) | positive scalar | 1-by-2 vector of positive values

Track-to-track assignment threshold, specified as a positive scalar or a 1-by-2 vector of [C₁,C₂], where C₁ ≤ C₂. 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 C₂. Also, the fuser can only assign a local track to a central track if their accurate normalized distance is less than C₁. See the distance function used with tracking filters (trackingCKF and trackingEKF for example) for an explanation of the distance calculation.

Tips:

• Increase the value of C₂ 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 C₁ 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).

StateTransitionFcn — State transition function

'constvel' (default) | function handle

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

StateTransitionJacobianFcn — Jacobian of state transition function

'' (default) | function handle

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

ProcessNoise — Process noise covariance

eye(3) (default) | positive real scalar | positive definite matrix

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

HasAdditiveProcessNoise — Model additive process noise

false (default) | true

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.

StateParameters — Parameters of track state reference frame

struct() (default) | structure | structure array

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 Name	Value
Frame	"Rectangular"
Position	[10 10 0]
Velocity	[2 -2 0]

Tunable: Yes

Data Types: struct

ConfirmationThreshold — Threshold for central track confirmation

[2 3] (default) | positive integer | 1-by-2 vector of positive integers

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

DeletionThreshold — Threshold for central track deletion

[5 5] (default) | positive integer | 1-by-2 vector of positive integers

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

FuseConfirmedOnly — Fuse only confirmed local tracks

true (default) | false

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

FuseCoasted — Fuse coasted local tracks

false (default) | true

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

StateFusion — State fusion algorithm

'Cross' (default) | 'Intersection' | 'Custom'

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

CustomStateFusionFcn — Custom state fusion function

'' (default) | function handle

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

StateFusionParameters — Parameters for state fusion function

[] (default)

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.

NumCentralTracks — Number of central-level tracks

nonnegative integer

This property is read-only.

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

Data Types: double

NumConfirmedCentralTracks — Number of confirmed central tracks

nonnegative integer

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

localTracks — Local tracks

array of objectTrack objects | array of structures

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.

Data Types: object | struct

tFusion — Update time

scalar

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

confirmedTracks — Confirmed tracks

array of objectTrack objects | array of structures

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

tentativeTracks — Tentative tracks

array of objectTrack objects | array of structures

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

allTracks — All tracks

array of objectTrack objects | array of structures

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

analysisInformation — Additional information for analyzing track updates

structure

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

Field	Description
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
NonInitializingLocalTracks	IDs of local tracks that were unassigned but were not used to initialize a central track
InitiatedCentralTrackIDs	IDs of central tracks initiated during the step
UpdatedCentralTrackIDs	IDs 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)

Specific to trackFuser

predictTrackToTime	Predict track state
initializeTrack	Initialize new track
deleteTrack	Delete existing track
sourceIndices	Fuser source indices

Common to All System Objects

step	Run System object algorithm
release	Release resources and allow changes to System object property values and input characteristics
clone	Create duplicate System object
isLocked	Determine if System object is in use
reset	Reset internal states of System object

Examples

Fuse Tracks from Two Sources Using trackFuser

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')

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

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

Usage notes and limitations:

• See System Objects in MATLAB Code Generation (MATLAB Coder).

• You must specify the MaxNumSources property during construction. Also, the property is read only for code generation.

• You must specify the SourceConfigurations property for all the sources during construction. Additionally,

  • All elements of SourceConfigurations must use the same LocalToCentralTransformFcn.

  • All elements of SourceConfigurations must use the same CentralToLocalTransformFcn.

• The input tracks must be a struct array instead of an objectTrack object array.

• The track outputs (all three) are each a struct array instead of an objectTrack object array.

• The ObjectAttributes structure for all the input source tracks must be in the same format (same field names and data types).

• The StateParameters structure for all the input source tracks must be in the same format (same field names and data types) as the StateParameters structure of the track fuser.