# objectDetection

## Description

An `objectDetection`

object contains an object
detection report that was obtained by a sensor for a single object. You can use the
`objectDetection`

output as the input to
trackers.

## Creation

### Description

creates an object `detection`

= objectDetection(`time`

,`measurement`

)`detection`

at the specified
`time`

from the specified
`measurement`

.

**Tip**

To create an empty `objectDetection`

object, use
`objectDetection.empty()`

.

creates a `detection`

= objectDetection(___,`Name,Value`

)`detection`

object with properties specified as one
or more `Name,Value`

pair arguments. Any unspecified
properties have default values. You cannot specify the `Time`

or `Measurement`

properties using `Name,Value`

pairs.

### Input Arguments

`time`

— Detection time

nonnegative real scalar

Detection time, specified as a nonnegative real scalar. This argument sets the `Time`

property.

`measurement`

— Object measurement

real-valued *N*-element vector

Object measurement, specified as a real-valued
*N*-element vector, where *N* is the
dimension of the measurement vector. This argument sets the `Measurement`

property.

If you use `objectDetection`

with a custom filter
initialization function, you can define the measurement in any format as
along as it agrees with the filter definition.

If you use `objectDetection`

with a built-in filter
initialization function such as `initcvekf`

, the measurement
definition follows these rules.

For a complete 3-D position measurement in a rectangular coordinate system, the general form is [

`x y z`

]. If you want to include velocity measurement as [`x y z vx vy vz`

], you must specify the`HasVelocity`

field in the`MeasurementParameters`

property as`true`

.**Note**Some filter initialization functions such as

`initcvkf`

can accept a 1-D measurement in the form of`x`

or a 2-D measurement in the form of [`x y`

].To specify a measurement in the spherical coordinate system, the

`Frame`

field in the`MeasurementParameters`

property must be`"Spherical"`

. For a complete 3-D spherical measurement, the general form is`[azimuth elevaton range rangeRate]`

. To let a filter interpret such a 3-D spherical measurement, specify the`HasAzimuth`

,`HasElevation`

,`HasRange`

, and`HasVelocity`

fields in the`MeasurementParameters`

property all as`true`

.To remove

`azimuth`

from the complete 3-D spherical measurement, set`HasAzimuth`

to`false`

.To remove

`elevation`

from the complete 3-D spherical measurement, set`HasElevation`

to`false`

.To remove

`range`

from the complete 3-D spherical measurement, set`HasRange`

to`false`

.To remove

`rangeRate`

from the complete 3-D spherical measurement, set`HasVelocity`

to`false`

.

For more details, see the Convert Detections to objectDetection Format and Initialize Tracking Filter Using objectDetection examples.

### Output Arguments

`detection`

— Detection report

`objectDetection`

object

Detection report for a single object, returned as an
`objectDetection`

object. An
`objectDetection`

object contains these
properties:

Property | Definition |
---|---|

`Time` | Measurement time |

`Measurement` | Object measurements |

`MeasurementNoise` | Measurement noise covariance matrix |

`SensorIndex` | Unique ID of the sensor |

`ObjectClassID` | Object classification |

`MeasurementParameters` | Parameters used by initialization functions of nonlinear Kalman tracking filters |

`ObjectAttributes` | Additional information passed to tracker |

## Properties

`Time`

— Detection time

nonnegative real scalar

Detection time, specified as a nonnegative real scalar. You cannot set this property as a
name-value pair. Use the `time`

input argument
instead.

**Example: **`5.0`

**Data Types: **`double`

`Measurement`

— Object measurement

real-valued *N*-element vector

Object measurement, specified as a real-valued *N*-element vector. You cannot
set this property as a name-value pair. Use the
`measurement`

input argument instead.

**Example: **`[1.0;-3.4]`

**Data Types: **`double`

| `single`

`MeasurementNoise`

— Measurement noise covariance

scalar | real positive semi-definite symmetric *N*-by-*N* matrix

Measurement noise covariance, specified as a scalar or a real
positive semi-definite symmetric *N*-by-*N* matrix. *N* is
the number of elements in the measurement vector. For the scalar case,
the matrix is a square diagonal *N*-by-*N* matrix
having the same data interpretation as the measurement.

**Example: **`[5.0,1.0;1.0,10.0]`

**Data Types: **`double`

| `single`

`SensorIndex`

— Sensor identifier

`1`

| positive integer

Sensor identifier, specified as a positive integer. The sensor identifier lets you distinguish between different sensors and must be unique to the sensor.

**Example: **`5`

**Data Types: **`double`

`ObjectClassID`

— Object class identifier

`0`

(default) | nonnegative integer

Object class identifier, specified as a nonnegative integer. Use this property to distinguish
detections generated from different kinds of objects. For example, use 1 for
objects of type "car", and 2 for objects of type "pedestrian". The value
`0`

denotes an unknown object type.

When you specify this property as a nonzero integer, you can use the
`ObjectClassParameters`

property to specify the
detection classifier statistics.

**Example: **`1`

**Data Types: **`double`

`ObjectClassParameters`

— Parameters for detection classifier

`[]`

(default) | structure

Parameters for detection classifier, specified as a structure. The
structure can contain any field. For class fusion with a multi-object
tracker, such as the `trackerGNN`

System object, you can specify the
`ConfusionMatrix`

field as follows.

Field Name | Description |
---|---|

`ConfusionMatrix` | Confusion matrix of the detection classifier,
specified as an
For example, if
the classifier outputs two classes and makes right
classification 95% of the time, specify this matrix
as |

**Data Types: **`struct`

`MeasurementParameters`

— Measurement function parameters

`{}`

(default) | structure array | cell containing structure array | cell array

Measurement function parameters that convert from filter state to measurement, specified as a structure array, a cell containing a structure array, or a cell array.

When you use a custom measurement function in a tracking filter, you can define the measurement in any format as along as it agrees with the definition of the custom measurement function.

When you use a built-in measurement function, such as `cvmeas`

and `ctmeas`

, in a tracking filter, you can use a structure with
these fields to define measurements in rectangular or spherical coordinate
frame.

Field | Description | Example |
---|---|---|

`Frame` | Frame used to report measurements, specified as one of these values: `'Rectangular'` — Detections are reported in rectangular coordinates.`'Spherical'` — Detections are reported in spherical coordinates.
| `'spherical'` |

`OriginPosition` | Position offset of the origin of the frame relative to the parent frame, specified as an `[x y z]` real-valued vector. | `[0 0 0]` |

`OriginVelocity` | Velocity offset of the origin of the frame relative to the parent frame, specified as a `[vx vy vz]` real-valued vector. | `[0 0 0]` |

`Orientation` | Frame rotation matrix, specified as a 3-by-3 real-valued orthonormal matrix. | `[1 0 0; 0 1 0; 0 0 1]` |

`HasAzimuth` | Logical scalar indicating if azimuth is included in the measurement. This
field is not relevant when the | `1` |

`HasElevation` | Logical scalar indicating if elevation information is included in the measurement. For
measurements reported in a rectangular frame, and if
`HasElevation` is false, the reported measurements assume 0
degrees of elevation. | `1` |

`HasRange` | Logical scalar indicating if range is included in the measurement. This
field is not relevant when the | `1` |

`HasVelocity` | Logical scalar indicating if the reported detections include velocity measurements. For a
measurement reported in the rectangular frame, if `HasVelocity`
is `false` , the measurements are reported as ```
[x y
z]
``` . If `HasVelocity` is `true` ,
the measurement is reported as `[x y z vx vy vz]` . For a
measurement reported in the spherical frame, if `HasVelocity`
is `true` , the measurement contains range-rate
information. | `1` |

`IsParentToChild` | Logical scalar indicating if `Orientation` performs a frame rotation from the parent coordinate frame to the child coordinate frame. When `IsParentToChild` is `false` , then `Orientation` performs a frame rotation from the child coordinate frame to the parent coordinate frame. | `0` |

For more details of using `MeasurementParameters`

, see the

Initialize Tracking Filter Using objectDetection example for initializing a tracking filter.

Convert Detections to objectDetection Format example for defining an

`objectDetection`

object, especially for multiple coordinate transformations using an array of measurement parameter structures.

`ObjectAttributes`

— Object attributes

`{}`

(default) | cell array | structure array

Object attributes passed through the tracker, specified as a cell array or a structure array. These attributes are added to the output of the trackers but not used by the trackers.

**Example: **`{[10,20,50,100],'radar1'}`

**Example: **`struct('myProperty',2)`

## Examples

### Create Detection from Position Measurement

Create a detection from a position measurement. The detection is made at a timestamp of one second from a position measurement of `[100;250;10]`

in Cartesian coordinates.

detection = objectDetection(1,[100;250;10])

detection = objectDetection with properties: Time: 1 Measurement: [3x1 double] MeasurementNoise: [3x3 double] SensorIndex: 1 ObjectClassID: 0 ObjectClassParameters: [] MeasurementParameters: {} ObjectAttributes: {}

### Create Detection With Measurement Noise

Create an `objectDetection`

from a time and position measurement. The detection is made at a time of one second for an object position measurement of `[100;250;10]`

. Add measurement noise and set other properties using Name-Value pairs.

detection = objectDetection(1,[100;250;10],'MeasurementNoise',10, ... 'SensorIndex',1,'ObjectAttributes',{'Example object',5})

detection = objectDetection with properties: Time: 1 Measurement: [3x1 double] MeasurementNoise: [3x3 double] SensorIndex: 1 ObjectClassID: 0 ObjectClassParameters: [] MeasurementParameters: {} ObjectAttributes: {'Example object' [5]}

### Initialize Tracking Filter Using `objectDetection`

You can use an `objectDetection`

object to initialize a tracking filter.

**Initialize Constant Velocity trackingKF with Rectangular Detection**

To initialize a `trackingKF`

object with a constant velocity model, you use the `initcvkf`

function.

Create a 2-D object detection and initialize a `trackingKF`

object using the detection.

detection = objectDetection(0,[1 2]); filter = initcvkf(detection); filter.State'

`ans = `*1×4*
1 0 2 0

From the result, the `initcvkf`

function recognized the dimension of the system and initialized a 2-D filter in which the state is [`x vx y vy`

], setting the velocity states `vx`

and `vy`

to `0`

.

You can also initialize a 3-D `trackingKF`

object by using a 3-D object detection.

detection = objectDetection(0,[1 2 3]); filter = initcvkf(detection); filter.State'

`ans = `*1×6*
1 0 2 0 3 0

From the result, the `initcvkf`

function initialized a 3-D filter in which the state is [`x vx y vy z vz`

].

**Initialize Constant Velocity trackingEKF with Rectangular Detection**

To initialize a `trackingEKF`

object with a constant velocity model, you use the `initcvekf`

function. The `initcvekf`

function requires the detection to be 3-D and always initializes a 3-D `trackingEKF`

object.

Create a 3-D object detection and initialize the `trackingEKF`

object with the detection.

```
detection = objectDetection(0,[1 2 3]);
filter = initcvekf(detection);
filter.State' % [x vx y vy z vz]
```

`ans = `*1×6*
1 0 2 0 3 0

From the result, the function assumes zero velocities when they are unspecified. You can also include velocity information in the measurement of the detection. Use the measurement parameters to let the `initcvekf`

function recognize the velocity state by setting the `HasVelocity`

field as `true`

.

mp = struct(Frame="Rectangular", ... OriginPosition = zeros(1,3), ... OriginVelocity = zeros(1,3), ... Orientation = eye(3),... HasVelocity = true,... IsParentToChild = true); detection = objectDetection(0,[1 2 3 0.1 0.2 0.3], ... MeasurementParameters=mp); filter = initcvekf(detection); filter.State' % [x vx y vy z vz]

`ans = `*1×6*
1.0000 0.1000 2.0000 0.2000 3.0000 0.3000

From the result, the function successfully initialized the velocities.

**Initialize Constant Velocity trackingEKF with Spherical Detection**

You can also initialize a `trackingEKF`

object with a spherical detection. First, create a spherical detection with an azimuth of 45 degrees, an elevation of 60 degrees, and a range of 2 meters. Specify its measurement parameter to describe the format of the measurement.

mp = struct(Frame="Spherical", ... OriginPosition = zeros(1,3), ... OriginVelocity = zeros(1,3), ... Orientation = eye(3),... HasAzimuth = true,... HasElevation = true,... HasRange = true,... HasVelocity = false,... IsParentToChild = true); detection = objectDetection(0,[45 60 2], ... MeasurementParameters=mp); filter = initcvekf(detection); filter.State' % [x vx y vy z vz]

`ans = `*1×6*
0.7071 0 0.7071 0 1.7321 0

From the results, the filter state is as expected and the position coordinate is [$\frac{\sqrt{2}}{2}\text{\hspace{0.17em}}$$\frac{\sqrt{2}}{2}$ $\sqrt{3}$].

You can also enable range-rate measurement by setting the `HasVelocity`

field of the measurement parameter to `true`

. After that, set the range-rate to be 0.2 m/s in the detection.

mp = struct(Frame="Spherical", ... OriginPosition = zeros(1,3), ... OriginVelocity = zeros(1,3), ... Orientation = eye(3),... HasAzimuth = true,... HasElevation = true,... HasRange = true,... HasVelocity = true,... IsParentToChild = true); detection = objectDetection(0,[45 60 2 0.2], ... MeasurementParameters=mp); filter = initcvekf(detection); filter.State' % [x vx y vy z vz]

`ans = `*1×6*
0.7071 0.0707 0.7071 0.0707 1.7321 0.1732

From the results, the function initialized the filter with the expected velocities.

## Extended Capabilities

### C/C++ Code Generation

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

When passing an `objectDetection`

object to a tracker, the
`ObjectAttributes`

property must be specified as a structure
or a structure array and must not be specified as a cell.

## Version History

**Introduced in R2018b**

### R2022b: Specify class confusion matrix

Using the new `ObjectClassParameters`

property, you can specify
detection class statistics in the form of a confusion matrix.

## See Also

### Objects

`trackingKF`

|`trackingEKF`

|`trackingUKF`

|`trackingCKF`

|`trackingGSF`

|`trackingPF`

|`trackingIMM`

|`trackingABF`

|`trackingMSCEKF`

|`sonarSensor`

|`irSensor`

|`fusionRadarSensor`

|`trackerGNN`

|`trackerTOMHT`

|`trackerJPDA`

|`trackerPHD`

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