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 such as multiObjectTracker
.
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 theHasVelocity
field in theMeasurementParameters
property astrue
.Note
Some filter initialization functions such as
initcvkf
can accept a 1-D measurement in the form ofx
or a 2-D measurement in the form of [x y
].To specify a measurement in the spherical coordinate system, the
Frame
field in theMeasurementParameters
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 theHasAzimuth
,HasElevation
,HasRange
, andHasVelocity
fields in theMeasurementParameters
property all astrue
.To remove
azimuth
from the complete 3-D spherical measurement, setHasAzimuth
tofalse
.To remove
elevation
from the complete 3-D spherical measurement, setHasElevation
tofalse
.To remove
range
from the complete 3-D spherical measurement, setHasRange
tofalse
.To remove
rangeRate
from the complete 3-D spherical measurement, setHasVelocity
tofalse
.
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
(Sensor Fusion and Tracking Toolbox) System object, you can specify the
ConfusionMatrix
field as follows.
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 |
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:
Tip In Simulink, when you create an object detection Bus, specify
| '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
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
multiObjectTracker
but not used by the tracker.
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 [ ].
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 R2017aR2022b: Specify class confusion matrix
Using the new ObjectClassParameters
property, you can specify
detection class statistics in the form of a confusion matrix.
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)