# 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:

Create the

`trackFuser`

object and set its properties.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

### Description

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

sets properties for the fuser using one or more name-value pairs. Unspecified properties
have default values. Enclose each property name in single quotes.`fuser`

= trackFuser(`Name,Value`

)

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

`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*_{1}*,C*_{2}],
where *C*_{1} ≤
*C*_{2}. 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*_{2}. Also, the fuser can
only assign a local track to a central track if their accurate normalized distance is
less than *C*_{1}. 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*_{2}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*_{1}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:where:x(k) = f(x(k-1),dt)

`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:where:x(k) = f(x(k-1),w(k-1),dt)

`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:where:Jx(k) = statejacobianfcn(x(k),dt)

`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:where:[Jx(k),Jw(k)] = statejacobianfcn(x(k),w(k),dt)

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

`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

### Description

returns a list of confirmed tracks from a list of local tracks. Confirmed tracks are
predicted to the update time, `confirmedTracks`

= fuser(`localTracks`

,`tFusion`

)`tFusion`

.

`[`

also returns a list of tentative tracks, a list of all tracks, and the analysis
information.`confirmedTracks`

,`tentativeTracks`

,`allTracks`

,`analysisInformation`

] = fuser(`localTracks`

,`tFusion`

)

### 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 |

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

**Introduced in R2019b**

## Open Example

You have a modified version of this example. Do you want to open this example with your edits?

## MATLAB Command

You clicked a link that corresponds to this MATLAB command:

Run the command by entering it in the MATLAB Command Window. Web browsers do not support MATLAB commands.

# Select a Web Site

Choose a web site to get translated content where available and see local events and offers. Based on your location, we recommend that you select: .

You can also select a web site from the following list:

## How to Get Best Site Performance

Select the China site (in Chinese or English) for best site performance. Other MathWorks country sites are not optimized for visits from your location.

### Americas

- América Latina (Español)
- Canada (English)
- United States (English)

### Europe

- Belgium (English)
- Denmark (English)
- Deutschland (Deutsch)
- España (Español)
- Finland (English)
- France (Français)
- Ireland (English)
- Italia (Italiano)
- Luxembourg (English)

- Netherlands (English)
- Norway (English)
- Österreich (Deutsch)
- Portugal (English)
- Sweden (English)
- Switzerland
- United Kingdom (English)