initctrvukf

Create constant turn-rate and velocity-magnitude unscented Kalman filter from detection report

Since R2024b

Syntax

filter = initctrvukf(detection)

Description

filter = initctrvukf(detection) creates and initializes a constant turn-rate and velocity magnitude unscented Kalman filter from information contained in the detection report specified in detection. For more information, see Algorithms and trackingUKF.

Note

initctrvukf represents velocity in the xy-plane with velocity magnitude and direction. For the constant turn-rate and velocity-magnitude motion model using Cartesian components, Vx and Vy, see initctukf.

Examples

3-D Constant Turn-Rate and Velocity-Magnitude Unscented Kalman Filter

Create a detection report from an initial 3-D measurement, [1;3;0], of the object position with a measurement noise of [1 0.2 0; 0.2 2 0; 0 0 1].

noise = [1 0.2 0; 0.2 2 0; 0 0 1];
detection = objectDetection(0,[1;3;0],'MeasurementNoise',noise, ...
    'SensorIndex',1,'ObjectClassID',1,'ObjectAttributes',{'Car',2});

Create an unscented Kalman filter from the detection report and display the filter properties.

filter = initctrvukf(detection)

filter = 
  trackingUKF with properties:

                          State: [7x1 double]
                StateCovariance: [7x7 double]

             StateTransitionFcn: @ctrv
                   ProcessNoise: [3x3 double]
        HasAdditiveProcessNoise: 0

                 MeasurementFcn: @ctrvmeas
         HasMeasurementWrapping: 1
               MeasurementNoise: [3x3 double]
    HasAdditiveMeasurementNoise: 1

                          Alpha: 1.0000e-03
                           Beta: 2
                          Kappa: 0

                EnableSmoothing: 0

Display the state and measurement noise.

filter.State

ans = 7×1

     1
     3
     0
     0
     0
     0
     0

filter.MeasurementNoise

ans = 3×3

    1.0000    0.2000         0
    0.2000    2.0000         0
         0         0    1.0000

Display the state covariance matrix.

filter.StateCovariance

ans = 7×7

    1.0000    0.2000         0         0         0         0         0
    0.2000    2.0000         0         0         0         0         0
         0         0  200.0000         0         0         0         0
         0         0         0  100.0000         0         0         0
         0         0         0         0  100.0000         0         0
         0         0         0         0         0    1.0000         0
         0         0         0         0         0         0  100.0000

3-D Constant Turn-rate and Velocity-Magnitude Unscented Kalman Filter from Spherical Measurements

Create a 3-D measurement vector in spherical coordinates and define its corresponding noise.

meas = [30;5;100;4];
measnoise = diag([2.5, 2.5, 0.5, 1].^2);

In order to create a constant turn-rate and velocity-magnitude unscented Kalman filter with spherical coordinates, you must supply a measurement parameter structure as part of the detection report with the Frame field set to 'spherical'.

frame = 'spherical';

Create the measurement parameters structure. Set 'HasElevation' and 'HasVelocity' to true.

measparms = struct('Frame',frame,'HasVelocity',true, ...
    'HasElevation',true);
detection = objectDetection(0,meas,'MeasurementNoise', ...
    measnoise,'MeasurementParameters',measparms)

detection = 
  objectDetection with properties:

                     Time: 0
              Measurement: [4x1 double]
         MeasurementNoise: [4x4 double]
              SensorIndex: 1
            ObjectClassID: 0
    ObjectClassParameters: []
    MeasurementParameters: [1x1 struct]
         ObjectAttributes: {}

Use the initctrvekf function and the detection report to create a trackingEKF filter object.

filter = initctrvukf(detection);

Display the filter state.

disp(filter.State)

   86.2730
   49.8097
    3.9848
   30.0000
         0
    8.7156
    0.3486

Input Arguments

detection — Detection report

objectDetection object

Detection report, specified as an objectDetection object.

Example: detection = objectDetection(0,[1;4.5;3],'MeasurementNoise', [1.0 0 0; 0 2.0 0; 0 0 1.5])

Output Arguments

filter — Unscented Kalman filter

trackingUKF object

Unscented Kalman filter, returned as a trackingUKF object.

Algorithms

• The function initializes a trackingUKF object with a ctrv motion model and a ctrvmeas measurement model. The state of the filter is defined as [x;y;s;θ;ω;z;v_z], where:

  • x and y represent the x-coordinate and y-coordinate in meters.

  • s represents the velocity magnitude in meters/second.

  • θ represents the course direction in the xy-plane, counter-clockwise with respect to the x-axis, in degrees.

  • ω represents the turn rate in degrees/second.

  • z represent the position in the vertical plane in meters.

  • v_z represents velocity component in the vertical plane in meters/second.

• You can define the detection input as an objectDetection object using Cartesian or spherical measurements.

  • When you use Cartesian measurements:

    • By default, the function assumes a 3-D position measurement of the form ([x; y; z]). The function uses the measurement to initialize the position state of the filter and sets the velocity state to 0. Similarly, the function uses the position components of the measurement noise matrix in the detection as the position components of the state error covariance matrix and sets the velocity components of the state error covariance matrix to 100 m²/s².

    • You can also use a 6-D measurement ([x; y; z; v_x; v_y; v_z]) by specifying the MeasurementParameters property of the objectDetection object. Set the HasVelocity field of the measurement parameter structure to true so that the initctrvukf function can recognize the 6-D measurement. In this case, the state and state error covariance matrix of the filter are the same as the measurement and measurement noise matrix of the detection, respectively.

    • Regardless of the dimension of the detection, the function sets the angular rate state ω of the filter to 0 and its corresponding covariance to 100 deg²/s².

  • For a spherical measurement, you must set the Frame field in the MeasurementParameters property of the objectDetection object to "Spherical". You must also use the MeasurementParameters property to specify if the detection has azimuth, elevation, range, and range rate measurements. A complete spherical measurements vector has four elements [az, el, r, rr], representing azimuth in degrees, elevation in degrees, range in meters, and range-rate in meters per second, respectively. Some of the four elements are optional.

    • If the detection has elevation, the function uses the elevation measurement and its covariance to construct the filter state and state error covariance after performing coordinate transformation from the spherical frame to the Cartesian frame. Without elevation, the function sets the elevation to 0 and set its covariance to 180²/12 deg² before performing the coordinate transformation.

    • If the detection has range rate, the function uses the range-rate measurement and its covariance to construct the filter sate and state error covariance. The function also assumes the velocity covariance of the cross-range direction is 100 m²/s². Without range rate, the function sets the velocity states of the filter to 0 and its corresponding covariances to 100 m²/s².

    • Regardless of the dimension of the detection, the function sets the angular velocity state ω of the filter to 0 and set its corresponding covariance to 100 deg²/s².

  • You can use other fields of the MeasurementParameters property of an objectDetection object, such as OriginPosition and OriginaVelocity, to further specify the measurement coordinates.

• The function computes the process noise matrix assuming a one-second time step. The function assumes an acceleration standard deviation of 1 m/s², and a turn-rate acceleration standard deviation of 1°/s².

• You can specify this function in the FilterInitializationFcn property of tracker objects, such as a trackerGNN object.

Extended Capabilities

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

Version History

Introduced in R2024b