# singermeas

Measurement function for Singer acceleration motion model

## Syntax

``measurements = singermeas(states)``
``measurements = singermeas(states,frame)``
``measurements = singermeas(states,frame,sensorpos,sensorvel)``
``measurements = singermeas(states,frame,sensorpos,sensorvel,laxes)``
``measurements = singermeas(states,measurementParameters)``
``[measurements,bounds] = singermeas(___)``

## Description

example

````measurements = singermeas(states)` returns the `measurements` in rectangular coordinates for the Singer motion model based on the current `states`.```
````measurements = singermeas(states,frame)` specifies the measurement output coordinate system, `frame`.```
````measurements = singermeas(states,frame,sensorpos,sensorvel)` also specifies the sensor position, `sensorpos`, and the sensor velocity, `sensorvel`.```
````measurements = singermeas(states,frame,sensorpos,sensorvel,laxes)` specifies the local sensor axes orientation, `laxes`.```
````measurements = singermeas(states,measurementParameters)` specifies the measurement parameters, `measurementParameters`.```

example

````[measurements,bounds] = singermeas(___)` returns the measurement bounds, used by a tracking filter (`trackingEKF`, `trackingUKF`, `trackingCKF`,`trackingIMM`, `trackingMSCEKF`, or `trackingGSF`) in residual calculations.```

## Examples

collapse all

Define a state for a 2-D Singer acceleration motion.

`state = [1;10;3;2;20;5];`

Obtain the measurement in a rectangular frame.

`measurement = singermeas(state)`
```measurement = 3×1 1 2 0 ```

Obtain the measurement in a spherical frame.

`measurement = singermeas(state, 'spherical')`
```measurement = 4×1 63.4349 0 2.2361 22.3607 ```

Obtain the measurement in a spherical frame relative to a stationary sensor located at [1;-2;0].

`measurement = singermeas(state, 'spherical', [1;-2;0], [0;0;0])`
```measurement = 4×1 90 0 4 20 ```

Obtain the measurement in a spherical frame relative to a stationary sensor located at [1;-2;0] that is rotated by 90 degrees around the z axis relative to the global frame.

```laxes = [0 -1 0; 1 0 0; 0 0 1]; measurement = singermeas(state, 'spherical', [1;-2;0], [0;0;0], laxes)```
```measurement = 4×1 0 0 4 20 ```

Obtain measurements from multiple 2D states in a rectangular frame.

```states = [1 2 3; 10 20 30; 2 4 5; 20 30 40; 5 6 11; 1 3 1.5]; measurements = singermeas(states)```
```measurements = 3×3 1 2 3 20 30 40 0 0 0 ```

Specify a 2-D state and specify a measurement structure such that the function outputs azimuth, range, and range-rate measurements.

```state = [10 1 0 10 1 0]'; % [x vx ax y vy ay]' mp = struct("Frame","Spherical", ... "HasAzimuth",true, ... "HasElevation",false, ... "HasRange",true, ... "HasVelocity",false);```

Output the measurement and wrapping bounds using the `singermeas` function.

`[measure,bounds] = singermeas(state,mp)`
```measure = 2×1 45.0000 14.1421 ```
```bounds = 2×2 -180 180 -Inf Inf ```

## Input Arguments

collapse all

Current states, specified as a real-valued 3N-by-1 vector or a real-valued 3N-by-M matrix. N is the spatial degree of the state, and M is the number of states.

The state vector in each column takes different forms based on its spatial dimensions.

Spatial DegreesState Vector Structure
1-D`[x;vx;ax]`
2-D`[x;vx;ax;y;vy;ay]`
3-D`[x;vx;ax;y;vy;ay;z;vz;az]`

For example, `x` represents the x-coordinate, `vx` represents the velocity in the x-direction, and `ax` represents the acceleration in the x-direction. If the motion model is in one-dimensional space, the y- and z-axes are assumed to be zero. If the motion model is in two-dimensional space, values along the z-axis are assumed to be zero. Position coordinates are in meters. Velocity coordinates are in meters/second. Acceleration coordinates are in m/s2.

Example: `[5;0.1;0.01;0;-0.2;-0.01;-3;0.05;0]`

Measurement output frame, specified as `'rectangular'` or `'spherical'`. When the frame is `'rectangular'`, a measurement consists of x, y, and z Cartesian coordinates. When specified as `'spherical'`, a measurement consists of azimuth, elevation, range, and range rate.

Data Types: `char`

Sensor position with respect to the navigation frame, specified as a real-valued 3-by-1 column vector. Units are in meters.

Data Types: `double`

Sensor velocity with respect to the navigation frame, specified as a real-valued 3-by-1 column vector. Units are in m/s.

Data Types: `double`

Local sensor coordinate axes, specified as a 3-by-3 orthogonal matrix. Each column specifies the direction of the local x-, y-, and z-axes, respectively, with respect to the navigation frame. That is, the matrix is the rotation matrix from the global frame to the sensor frame.

Data Types: `double`

Measurement parameters, specified as a structure or an array of structures. For more details, see Measurement Parameters.

Data Types: `struct`

## Output Arguments

collapse all

Measurement vector, returned as an N-by-1 column vector of scalars or an N-by-M matrix of scalars. The form of the measurement depends upon which syntax you use.

• When the syntax does not use the `measurementParameters` argument, the measurement vector is `[x,y,z]` when the `frame` input argument is set to `'rectangular'` and `[az;el;r;rr]` when the `frame` is set to `'spherical'`.

• When the syntax uses the `measurementParameters` argument, the size of the measurement vector depends on the values of the `Frame`, `HasVelocity`, and `HasElevation` fields in the `measurementParameters` structure.

FrameMeasurement
`'spherical'`

Specifies the azimuth angle, `az`, elevation angle, `el`, range, `r`, and range rate, `rr` of the measurements.

Spherical Measurements

HasElevation
falsetrue
HasVelocityfalse`[az;r]``[az;el;r]`
true`[az;r;rr]``[az;el;r;rr]`

Angle units are in degrees, range units are in meters, and range rate units are in m/s.

`'rectangular'`

Specifies the Cartesian position and velocity coordinates of the measurements.

Rectangular Measurements

 HasVelocity false `[x;y;z]` true `[x;y;z;vx;vy;vz]`

Position units are in meters and velocity units are in m/s.

Data Types: `double`

Measurement residual wrapping bounds, returned as an M-by-2 real-valued matrix, where M is the dimension of the measurement. Each row of the matrix corresponds to the lower and upper bounds for the specific dimension in the `measurement` output.

The function returns different bound values based on the `frame` input.

• If the `frame` input is specified as `'Rectangular'`, each row of the matrix is ```[-Inf Inf]```, indicating the filter does not wrap the measurement residual in the filter.

• If the `frame` input is specified as `'Spherical'`, the returned `bounds` contains the bounds for specific measurement dimension based on the following:

• When `HasAzimuth` = `true`, the matrix includes a row of `[-180 180]`, indicating the filter wraps the azimuth residual in the range of `[-180 180]` in degrees.

• When `HasElevation` = `true`, the matrix includes a row of `[-90 90]`, indicating the filter wraps the elevation residual in the range of `[-90 90]` in degrees.

• When `HasRange` = `true`, the matrix includes a row of `[-Inf Inf]`, indicating the filter does not wrap the range residual.

• When `HasVelocity` = `true`, the matrix includes a row of `[-Inf Inf]`, indicating the filter does not wrap the range rate residual.

If you specify any of the options as `false`, the returned `bounds` does not contain the corresponding row. For example, if `HasAzimuth` = `true`, `HasElevation` = `false`, `HasRange` = `true`, `HasVelocity` = `true`, then `bounds` is returned as

``` -180 180 -Inf Inf -Inf Inf```

The filter wraps the measuring residuals based on this equation:

`${x}_{wrap}=mod\left(x-\frac{a-b}{2},b-a\right)+\frac{a-b}{2}$`

where x is the residual to wrap, a is the lower bound, b is the upper bound, mod is the modules after division function, and xwrap is the wrapped residual.

Data Types: `single` | `double`

collapse all

### Azimuth and Elevation Angle Definitions

Define the azimuth and elevation angles used in the toolbox.

The azimuth angle of a vector is the angle between the x-axis and its orthogonal projection onto the xy plane. The angle is positive in going from the x axis toward the y axis. Azimuth angles lie between –180 and 180 degrees. The elevation angle is the angle between the vector and its orthogonal projection onto the xy-plane. The angle is positive when going toward the positive z-axis from the xy plane.

### Measurement Parameters

The `MeasurementParameters` property consists of an array of structures that describe a sequence of coordinate transformations from a child frame to a parent frame or the inverse transformations (see Frame Rotation). If `MeasurementParameters` only contains one structure, then it represents the rotation from one frame to the other. If `MeasurementParameters` contains an array of structures, then it represents rotations between multiple frames.

The fields of `MeasurementParameters` are shown here. Not all fields have to be present in the structure.

 Field Description `Frame` Enumerated type indicating the frame used to report measurements. When detections are reported using a rectangular coordinate system, set `Frame` to `'rectangular'`. When detections are reported in spherical coordinates, set `Frame` to `'spherical'` for the first structure. `OriginPosition` Position offset of the origin of the child frame relative to the parent frame, represented as a 3-by-1 vector. `OriginVelocity` Velocity offset of the origin of the child frame relative to the parent frame, represented as a 3-by-1 vector. `Orientation` Frame orientation, specified as a 3-by-3 real-valued orthonormal frame rotation matrix. The direction of the rotation depends on the `IsParentTochild` field. `IsParentToChild` A logical scalar indicating whether `Orientation` performs a frame rotation from the parent coordinate frame to the child coordinate frame. If `false`, `Orientation` performs a frame rotation from the child coordinate frame to the parent coordinate frame instead. `HasElevation` A logical scalar indicating if the measurement includes elevation. For measurements reported in a rectangular frame, if `HasElevation` is `false`, measurement function reports all measurements with `0` degrees of elevation. `HasAzimuth` A logical scalar indicating if the measurement includes azimuth. `HasRange` A logical scalar indicating if the measurement includes range. `HasVelocity` A logical scalar indicating if the reported detections include velocity measurements. For measurements reported in a rectangular frame, if `HasVelocity` is `false`, the measurement function reports measurements as `[x y z]`. If `HasVelocity` is `true`, the measurement function reports measurements as ```[x y z vx vy vz]```.

## References

[1] Singer, Robert A. "Estimating optimal tracking filter performance for manned maneuvering targets." IEEE Transactions on Aerospace and Electronic Systems 4 (1970): 473-483.

[2] Blackman, Samuel S., and Robert Popoli. "Design and analysis of modern tracking systems." (1999).

[3] Li, X. Rong, and Vesselin P. Jilkov. "Survey of maneuvering target tracking: dynamic models." Signal and Data Processing of Small Targets 2000, vol. 4048, pp. 212-235. International Society for Optics and Photonics, 2000.

## Version History

Introduced in R2020b