objectDetection

Report for single object detection

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

Syntax

detection = objectDetection(time,measurement)

detection = objectDetection(___,Name,Value)

Description

detection = objectDetection(time,measurement) creates an object detection at the specified time from the specified measurement.

Tip

To create an empty objectDetection object, use objectDetection.empty().

example

detection = objectDetection(___,Name,Value) creates a 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.

example

Input Arguments

expand all

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

expand all

`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

expand all

`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

Field Name	Description
`ConfusionMatrix`	Confusion matrix of the detection classifier, specified as an N-by-N real-valued matrix, where N is the number of possible object classes. The (i,j) element of the matrix represents the weight or probability that the classifier classifies the detection as class j if the true class of the detection is class i. For example, if the classifier outputs two classes and makes right classification 95% of the time, specify this matrix as `[0.95 0.05; 0.05 0.95]`.

ConfusionMatrix

Confusion matrix of the detection classifier, specified as an N-by-N real-valued matrix, where N is the number of possible object classes. The (i,j) element of the matrix represents the weight or probability that the classifier classifies the detection as class j if the true class of the detection is class i.

For example, if the classifier outputs two classes and makes right classification 95% of the time, specify this matrix as [0.95 0.05; 0.05 0.95].

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. Tip In Simulink, when you create an object detection Bus, specify `Frame` as an enumeration object of `fusionCoordinateFrameType.Rectangular` or `fusionCoordinateFrameType.Spherical` because Simulink does not support variables such as a character vector that can vary in size.	`'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 `Frame` field is `'Rectangular'`.	`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 `Frame` is `'Rectangular'`.	`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 these examples:

Initialize Tracking Filter Using objectDetection for initializing a tracking filter.
Convert Detections to objectDetection Format 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

collapse all

Create Detection from Position Measurement

Open Live Script

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

Open Live Script

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`

Open Live Script

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}$ $\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 scalar structure or a cell containing a scalar structure.

Version History

Introduced in R2018b

expand all

R2022b: Specify class confusion matrix

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

objectDetection

Description

Creation

Syntax

Description

Input Arguments

`time` — Detection time
nonnegative real scalar

`measurement` — Object measurement
real-valued N-element vector

Output Arguments

`detection` — Detection report
`objectDetection` object

Properties

`Time` — Detection time
nonnegative real scalar

`Measurement` — Object measurement
real-valued N-element vector

`MeasurementNoise` — Measurement noise covariance
scalar | real positive semi-definite symmetric N-by-N matrix

`SensorIndex` — Sensor identifier
`1` | positive integer

`ObjectClassID` — Object class identifier
`0` (default) | nonnegative integer

`ObjectClassParameters` — Parameters for detection classifier
`[]` (default) | structure

`MeasurementParameters` — Measurement function parameters
`{}` (default) | structure array | cell containing structure array | cell array

`ObjectAttributes` — Object attributes
`{}` (default) | cell array | structure array

Examples

Create Detection from Position Measurement

Create Detection With Measurement Noise

Initialize Tracking Filter Using `objectDetection`

Extended Capabilities

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.

Version History

R2022b: Specify class confusion matrix

See Also

Functions

Objects

objectDetection

Description

Creation

Syntax

Description

Input Arguments

time — Detection time nonnegative real scalar

measurement — Object measurement real-valued N-element vector

Output Arguments

detection — Detection report objectDetection object

Properties

Time — Detection time nonnegative real scalar

Measurement — Object measurement real-valued N-element vector

MeasurementNoise — Measurement noise covariance scalar | real positive semi-definite symmetric N-by-N matrix

SensorIndex — Sensor identifier 1 | positive integer

ObjectClassID — Object class identifier 0 (default) | nonnegative integer

ObjectClassParameters — Parameters for detection classifier [] (default) | structure

MeasurementParameters — Measurement function parameters {} (default) | structure array | cell containing structure array | cell array

ObjectAttributes — Object attributes {} (default) | cell array | structure array

Examples

Create Detection from Position Measurement

Create Detection With Measurement Noise

Initialize Tracking Filter Using objectDetection

Extended Capabilities

C/C++ Code Generation Generate C and C++ code using MATLAB® Coder™.

Version History

R2022b: Specify class confusion matrix

See Also

Functions

Objects

`time` — Detection time
nonnegative real scalar

`measurement` — Object measurement
real-valued N-element vector

`detection` — Detection report
`objectDetection` object

`Time` — Detection time
nonnegative real scalar

`Measurement` — Object measurement
real-valued N-element vector

`MeasurementNoise` — Measurement noise covariance
scalar | real positive semi-definite symmetric N-by-N matrix

`SensorIndex` — Sensor identifier
`1` | positive integer

`ObjectClassID` — Object class identifier
`0` (default) | nonnegative integer

`ObjectClassParameters` — Parameters for detection classifier
`[]` (default) | structure

`MeasurementParameters` — Measurement function parameters
`{}` (default) | structure array | cell containing structure array | cell array

`ObjectAttributes` — Object attributes
`{}` (default) | cell array | structure array

Initialize Tracking Filter Using `objectDetection`

C/C++ Code Generation
Generate C and C++ code using MATLAB® Coder™.