sonarSensor

Generate detections from sonar emissions

Description

The sonarSensor System object™ creates a statistical model for generating detections from sonar emissions. You can generate detections from active or passive sonar systems. You can use the sonarSensor object in a scenario that models moving and stationary platforms using trackingScenario. The sonar sensor can simulate real detections with added random noise and also generate false alarm detections. In addition, you can use this object to create input to trackers such as trackerGNN or trackerTOMHT.

This object enables you to configure an electronically scanning sonar. A scanning sonar changes the look angle between updates by stepping the electronic position of the beam in increments of the angular span specified in the FieldOfView property. The sonar scans the total region in azimuth and elevation defined by the sonar electronic scan limits, ElectronicScanLimits. If the scanning limits for azimuth or elevation are set to [0 0], no scanning is performed along that dimension for that scan mode. If the maximum electronic scan rate for azimuth or elevation is set to zero, no electronic scanning is performed along that dimension.

To generate sonar detections:

Create the sonarSensor object and set its properties.
Call the object with arguments, as if it were a function.

To learn more about how System objects work, see What Are System Objects?.

Creation

Syntax

sensor = sonarSensor(SensorIndex)

sensor = sonarSensor(SensorIndex,'No scanning')

sensor = sonarSensor(SensorIndex,'Raster')

sensor = sonarSensor(SensorIndex,'Rotator')

sensor = sonarSensor(SensorIndex,'Sector')

sensor = sonarSensor(___,Name,Value)

Description

sensor = sonarSensor(SensorIndex) creates a sonar detection generator object with default property values.

sensor = sonarSensor(SensorIndex,'No scanning') is a convenience syntax that creates a sonarSensor that stares along the sonar transducer boresight direction. No electronic scanning is performed. This syntax sets the ScanMode property to 'No scanning'.

sensor = sonarSensor(SensorIndex,'Raster') is a convenience syntax that creates a sonarSensor object that electronically scans a raster pattern. The raster span is 90° in azimuth from –45° to +45° and in elevation from the horizon to 10° above the horizon. See Convenience Syntaxes for the properties set by this syntax.

sensor = sonarSensor(SensorIndex,'Rotator') is a convenience syntax that creates a sonarSensor object that electronically scans 360° in azimuth by electronically rotating the transducer at a constant rate. When you set HasElevation to true, the sonar transducer electronically points towards the center of the elevation field of view. See Convenience Syntaxes for the properties set by this syntax.

sensor = sonarSensor(SensorIndex,'Sector') is a convenience syntax to create a sonarSensor object that electronically scans a 90° azimuth sector from –45° to +45°. Setting HasElevation to true, points the sonar transducer towards the center of the elevation field of view. Beams are stacked electronically to process the entire elevation spanned by the scan limits in a single dwell. See Convenience Syntaxes for the properties set by this syntax.

example

sensor = sonarSensor(___,Name,Value) sets properties using one or more name-value pairs after all other input arguments. Enclose each property name in quotes. For example, sonarSensor('DetectionCoordinates','Sensor cartesian','MaxRange',200) creates a sonar detection generator that reports detections in the sensor Cartesian coordinate system and has a maximum detection range of 200 meters. If you specify the sensor index using the SensorIndex property, you can omit the SensorIndex input.

Properties

expand all

Unless otherwise indicated, properties are nontunable, which means you cannot change their values after calling the object. Objects lock when you call them, and the release function unlocks them.

If a property is tunable, you can change its value at any time.

For more information on changing property values, see System Design in MATLAB Using System Objects.

`SensorIndex` — Unique sensor identifier
positive integer

Unique sensor identifier, specified as a positive integer. This property distinguishes detections that come from different sensors in a multi-sensor system. When creating a sonarSensor system object, you must either specify the SensorIndex as the first input argument in the creation syntax, or specify it the value for the SensorIndex property in the creation syntax.

Example: 2

Data Types: double

`UpdateRate` — Sensor update rate
`1` (default) | positive scalar

Sensor update rate, specified as a positive scalar. This interval must be an integer multiple of the simulation time interval defined by trackingScenario. The trackingScenario object calls the sonar sensor at simulation time intervals. The sonar generates new detections at intervals defined by the reciprocal of the UpdateRate property. Any update requested to the sensor between update intervals contains no detections. Units are in hertz.

Example: 5

Data Types: double

`DetectionMode` — Detection mode
`'passive'` (default) | `'monostatic'`

Detection mode, specified as 'passive' or 'monostatic'. When set to 'passive', the sensor operates passively. When set to 'monostatic', the sensor generates detections from reflected signals originating from a collocated sonar emitter.

Example: 'Monostatic'

Data Types: char | string

`EmitterIndex` — Unique monostatic emitter index
positive integer

Unique monostatic emitter index, specified as a positive integer. The emitter index identifies the monostatic sonar emitter providing the reference signal to the sensor.

Example: 404

Dependencies

Set this property when the DetectionMode property is set to 'monostatic'.

Data Types: double

`MountingLocation` — Sensor location on platform
`[0 0 0]` (default) | 1-by-3 real-valued vector

Sensor location on platform, specified as a 1-by-3 real-valued vector. This property defines the coordinates of the sensor with respect to the platform origin. The default value specifies that the sensor origin is at the origin of its platform. Units are in meters.

Example: [.2 0.1 0]

Data Types: double

`MountingAngles` — Orientation of sensor
`[0 0 0]` (default) | 3-element real-valued vector

Orientation of the sensor with respect to the platform, specified as a three-element real-valued vector. Each element of the vector corresponds to an intrinsic Euler angle rotation that carries the body axes of the platform to the sensor axes. The three elements define the rotations around the z-, y-, and x-axes, in that order. The first rotation rotates the platform axes around the z-axis. The second rotation rotates the carried frame around the rotated y-axis. The final rotation rotates the frame around the carried x-axis. Units are in degrees.

Example: [10 20 -15]

Data Types: double

`FieldOfView` — Fields of view of sensor
`[10;50]` | 2-by-1 vector of positive scalar

Fields of view of sensor, specified as a 2-by-1 vector of positive scalars in degree, [azfov;elfov]. The field of view defines the total angular extent spanned by the sensor. The azimuth filed of view azfov must lie in the interval (0,360]. The elevation filed of view elfov must lie in the interval (0,180].

Example: [14;7]

Data Types: double

`ScanMode` — Scanning mode of sonar
`'Electronic'` (default) | `'No scanning'`

Scanning mode of sonar, specified as 'Electronic' or 'No scanning'.

Scan Modes

`ScanMode`	Purpose
`'Electronic'`	The sonar scans electronically across the azimuth and elevation limits specified by the `ElectronicScanLimits` property. The scan direction increments by the sonar field of view angle between dwells.
`'No scanning'`	The sonar beam points along the transducer boresight defined by the `mountingAngles` property.

Example: 'No scanning'

Data Types: char

`MechanicalAngle` — Current mechanical scan angle
scalar | real-valued 2-by-1 vector

This property is read-only.

Current mechanical scan angle of sonar, returned as a scalar or real-valued 2-by-1 vector. When HasElevation is true, the scan angle takes the form [Az; El]. Az and El represent the azimuth and elevation scan angles, respectively, relative to the mounted angle of the sonar on the platform. When HasElevation is false, the scan angle is a scalar representing the azimuth scan angle.

Data Types: double

`ElectronicScanLimits` — Angular limits of electronic scan directions of sonar
`[-45 45;-45 45]` (default) | real-valued 1-by-2 row vector | real-valued 2-by-2 matrix

Angular limits of electronic scan directions of sonar, specified as a real-valued, 1-by-2 row vector or a real-valued 2-by-2 matrix. The electronic scan limits define the minimum and maximum electronic angles the sonar can scan from its current mechanical direction.

When HasElevation is true, the scan limits take the form [minAz maxAz; minEl maxEl]. minAz and maxAz represent the minimum and maximum limits of the azimuth angle scan. minEl and maxEl represent the minimum and maximum limits of the elevation angle scan. When HasElevation is false, the scan limits take the form [minAz maxAz]. If you specify the scan limits as a 2-by-2 matrix but set HasElevation to false, the second row of the matrix is ignored.

Azimuthal scan limits and elevation scan limits must lie within the closed interval [-90° 90°]. Units are in degrees.

Example: [-90 90;0 85]

Dependencies

To enable this property, set the ScanMode property to 'Electronic'.

Data Types: double

`ElectronicAngle` — Current electronic scan angle
electronic scalar | nonnegative scalar

This property is read-only.

Current electronic scan angle of sonar, returned as a scalar or 1-by-2 column vector. When HasElevation is true, the scan angle takes the form [Az;El]. Az and El represent the azimuth and elevation scan angles, respectively. When HasElevation is false, the scan angle is a scalar representing the azimuth scan angle.

Dependencies

To enable this property, set the ScanMode property to 'Electronic'.

Data Types: double

`LookAngle` — Look angle of sensor
scalar | real-valued 2-by-1 vector

This property is read-only.

Look angle of sensor, specified as a scalar or real-valued 2-by-1 vector. Look angle depends on the electronic angle set in the ScanMode property.

ScanMode	LookAngle
`'Electronic'`	`ElectronicAngle`
`'No scanning'`	`0`

When HasElevation is true, the look angle takes the form [Az;El]. Az and El represent the azimuth and elevation look angles, respectively. When HasElevation is false, the look angle is a scalar representing the azimuth look angle.

`HasElevation` — Enable sonar elevation scan and measurements
`false` (default) | `true`

Enable the sonar to measure target elevation angles and to scan in elevation, specified as false or true. Set this property to true to model a sonar sensor that can estimate target elevation and scan in elevation.

Data Types: logical

`CenterFrequency` — Center frequency of sonar band
`20e3` (default) | positive scalar

Center frequency of sonar band, specified as a positive scalar. Units are in hertz.

Example: 25.5e3

Data Types: double

`Bandwidth` — Sonar waveform bandwidth
`2e3` | positive scalar

Sonar waveform bandwidth, specified as a positive scalar. Units are in hertz.

Example: 1.5e3

Data Types: double

`WaveformTypes` — Types of detected waveforms
`0` (default) | nonnegative integer-valued L-element vector

Types of detected waveforms, specified as a nonnegative integer-valued L-element vector.

Example: [1 4 5]

Data Types: double

`ConfusionMatrix` — Probability of correct classification of detected waveform
`1` (default) | positive scalar | real-valued nonnegative L-element vector | real-valued nonnegative L-by-L matrix

Probability of correct classification of a detected waveform, specified as a positive scalar, a real-valued nonnegative L-element vector, or a real-valued nonnegative L-by-L matrix. Matrix values range from 0 through 1 and matrix rows must sum to 1. L is the number of waveform types that the sensor can detect, as indicated by the value set in the WaveformTypes property. The (i,j) matrix element represents the probability of classifying the i^th waveform as the j^th waveform. When specified as a scalar from 0 through 1, the value is expanded along the diagonal of the confusion matrix. When specified as a vector, it must have the same number of elements as the WaveformTypes property. When defined as a scalar or a vector, the off diagonal values are set to (1-val)/(L-1).

Data Types: double

`AmbientNoiseLevel` — Spectrum-level ambient isotropic noise
`70` (default) | scalar

Spectrum-level ambient isotropic noise, specified as a scalar. Units are in dB relative to the intensity of a plane wave with 1 μPa rms pressure in a 1-hertz frequency band.

Example: 25

Data Types: double

`FalseAlarmRate` — False alarm rate
`1e-6` (default) | positive scalar

False alarm report rate within each resolution cell, specified as a positive scalar in the range [10^–7,10^–3]. Units are dimensionless. Resolution cells are determined from the AzimuthResolutionproperty and the ElevationResolution property when enabled.

Example: 1e-5

Data Types: double

`AzimuthResolution` — Azimuth resolution of sonar
`1` (default) | positive scalar

Azimuth resolution of the sonar, specified as a positive scalar. The azimuth resolution defines the minimum separation in azimuth angle at which the sonar can distinguish two targets. The azimuth resolution is typically the 3-dB downpoint of the azimuth angle beamwidth of the sonar. Units are in degrees.

Data Types: double

`ElevationResolution` — Elevation resolution of sonar
`1` (default) | positive scalar

Elevation resolution of the sonar, specified as a positive scalar. The elevation resolution defines the minimum separation in elevation angle at which the sonar can distinguish two targets. The elevation resolution is typically the 3-dB downpoint in the elevation angle beamwidth of the sonar. Units are in degrees.

Dependencies

To enable this property, set the HasElevation property to true.

Data Types: double

`RangeResolution` — Range resolution of sonar
`100` (default) | positive scalar

Range resolution of the sonar, specified as a positive scalar. The range resolution defines the minimum separation in range at which the sonar can distinguish between two targets. Units are in meters.

Data Types: double

`RangeRateResolution` — Range rate resolution of sonar
`10` (default) | positive scalar

Range rate resolution of the sonar, specified as a positive scalar. The range rate resolution defines the minimum separation in range rate at which the sonar can distinguish between two targets. Units are in meters per second.

Dependencies

To enable this property, set the HasRangeRate property to true.

Data Types: double

`AzimuthBiasFraction` — Azimuth bias fraction
`0.1` (default) | nonnegative scalar

Azimuth bias fraction of the sonar, specified as a nonnegative scalar. The azimuth bias is expressed as a fraction of the azimuth resolution specified in AzimuthResolution. This value sets a lower bound on the azimuthal accuracy of the sonar. This value is dimensionless.

Data Types: double

`ElevationBiasFraction` — Elevation bias fraction
`0.1` (default) | nonnegative scalar

Elevation bias fraction of the sonar, specified as a nonnegative scalar. Elevation bias is expressed as a fraction of the elevation resolution specified by the value of the ElevationResolution property. This value sets a lower bound on the elevation accuracy of the sonar. This value is dimensionless.

Dependencies

To enable this property, set the HasElevation property to true.

Data Types: double

`RangeBiasFraction` — Range bias fraction
`0.05` (default) | nonnegative scalar

Range bias fraction of the sonar, specified as a nonnegative scalar. Range bias is expressed as a fraction of the range resolution specified in RangeResolution. This property sets a lower bound on the range accuracy of the sonar. This value is dimensionless.

Data Types: double

`RangeRateBiasFraction` — Range rate bias fraction
`0.05` (default) | nonnegative scalar

Range rate bias fraction of the sonar, specified as a nonnegative scalar. Range rate bias is expressed as a fraction of the range rate resolution specified in RangeRateResolution. This property sets a lower bound on the range-rate accuracy of the sonar. This value is dimensionless.

Dependencies

To enable this property, set the HasRangeRate property to true.

Data Types: double

`HasRangeRate` — Enable sonar to measure range rate
`false` (default) | `true`

Enable the sonar to measure target range rates, specified as false or true. Set this property to true to model a sonar sensor that can measure target range rate. Set this property to false to model a sonar sensor that cannot measure range rate.

Data Types: logical

`HasRangeAmbiguities` — Enable range ambiguities
`false` (default) | `true`

Enable range ambiguities, specified as false or true. Set this property to true to enable range ambiguities by the sensor. In this case, the sensor cannot resolve range ambiguities for targets at ranges beyond the MaxUnambiguousRange are wrapped into the interval [0 MaxUnambiguousRange]. When false, targets are reported at their unambiguous range.

Data Types: logical

`HasRangeRateAmbiguities` — Enable range-rate ambiguities
`false` (default) | `true`

Enable range-rate ambiguities, specified as false or true. Set to true to enable range-rate ambiguities by the sensor. When true, the sensor does not resolve range rate ambiguities and target range rates beyond the MaxUnambiguousRadialSpeed are wrapped into the interval [0,MaxUnambiguousRadialSpeed]. When false, targets are reported at their unambiguous range rate.

Dependencies

To enable this property, set the HasRangeRate property to true.

Data Types: logical

`MaxUnambiguousRange` — Maximum unambiguous detection range
`100e3` (default) | positive scalar

Maximum unambiguous range, specified as a positive scalar. Maximum unambiguous range defines the maximum range for which the sonar can unambiguously resolve the range of a target. When HasRangeAmbiguities is set to true, targets detected at ranges beyond the maximum unambiguous range are wrapped into the range interval [0,MaxUnambiguousRange]. This property applies to true target detections when you set the HasRangeAmbiguities property to true.

This property also applies to false target detections when you set the HasFalseAlarms property to true. In this case, the property defines the maximum range for false alarms.

Units are in meters.

Example: 5e3

Dependencies

To enable this property, set the HasRangeAmbiguities property to true or set the HasFalseAlarms property to true.

Data Types: double

`MaxUnambiguousRadialSpeed` — Maximum unambiguous radial speed
`200` (default) | positive scalar

Maximum unambiguous radial speed, specified as a positive scalar. Radial speed is the magnitude of the target range rate. Maximum unambiguous radial speed defines the radial speed for which the sonar can unambiguously resolve the range rate of a target. When HasRangeRateAmbiguities is set to true, targets detected at range rates beyond the maximum unambiguous radial speed are wrapped into the range rate interval [-MaxUnambiguousRadialSpeed, MaxUnambiguousRadialSpeed]. This property applies to true target detections when you set HasRangeRateAmbiguities property to true.

This property also applies to false target detections obtained when you set both the HasRangeRate and HasFalseAlarms properties to true. In this case, the property defines the maximum radial speed for which false alarms can be generated.

Units are in meters per second.

Dependencies

To enable this property, set HasRangeRate and HasRangeRateAmbiguities to true and/or set HasRangeRate and HasFalseAlarms to true.

Data Types: double

`HasINS` — Enable inertial navigation system (INS) input
`false` (default) | `true`

Enable the optional input argument that passes the current estimate of the sensor platform pose to the sensor, specified as false or true. When true, pose information is added to the MeasurementParameters structure of the reported detections. Pose information lets tracking and fusion algorithms estimate the state of the target detections in the north-east-down (NED) frame.

Data Types: logical

`HasNoise` — Enable addition of noise to sonar sensor measurements
`true` (default) | `false`

Enable addition of noise to sonar sensor measurements, specified as true or false. Set this property to true to add noise to the sonar measurements. Otherwise, the measurements have no noise. Even if you set HasNoise to false, the object still computes the MeasurementNoise property of each detection.

Data Types: logical

`HasFalseAlarms` — Enable creating false alarm sonar detections
`true` (default) | `false`

Enable creating false alarm sonar measurements, specified as true or false. Set this property to true to report false alarms. Otherwise, only actual detections are reported.

Data Types: logical

`MaxNumDetectionsSource` — Source of maximum number of detections reported
`'Auto'` (default) | `'Property'`

Source of maximum number of detections reported by the sensor, specified as 'Auto' or 'Property'. When this property is set to 'Auto', the sensor reports all detections. When this property is set to 'Property', the sensor reports up to the number of detections specified by the MaxNumDetections property.

Data Types: char

`MaxNumDetections` — Maximum number of reported detections
`50` (default) | positive integer

Maximum number of detections reported by the sensor, specified as a positive integer. Detections are reported in order of distance to the sensor until the maximum number is reached.

Dependencies

To enable this property, set the MaxNumDetectionsSource property to 'Property'.

Data Types: double

`DetectionCoordinates` — Coordinate system of reported detections
`'Body'` (default) | `'Scenario'` | `'Sensor rectangular` | `'Sensor spherical'`

Coordinate system of reported detections, specified as:

'Scenario' — Detections are reported in the rectangular scenario coordinate frame. The scenario coordinate system is defined as the local NED frame at simulation start time. To enable this value, set the HasINS property to true.
'Body' — Detections are reported in the rectangular body system of the sensor platform.
'Sensor rectangular' — Detections are reported in the sonar sensor rectangular body coordinate system.
'Sensor spherical' — Detections are reported in a spherical coordinate system derived from the sensor rectangular body coordinate system. This coordinate system is centered at the sonar sensor and aligned with the orientation of the sonar on the platform.

Example: 'Sensor spherical'

Data Types: char

Usage

Syntax

dets = sensor(sonarsigs,simTime)

dets = sensor(sonarsigs,txconfigs,simTime)

dets
= sensor(___,ins,simTime)

[dets,numDets,config]
= sensor(___)

Description

dets = sensor(sonarsigs,simTime) creates passive detections, dets, from sonar emissions, sonarsigs, at the current simulation time, simTime. The sensor generates detections at the rate defined by the UpdateRate property.

dets = sensor(sonarsigs,txconfigs,simTime) also specifies emitter configurations, txconfigs, at the current simulation time.

dets = sensor(___,ins,simTime) also specifies the inertial navigation system (INS) estimated sensor platform pose, ins. INS information is used by tracking and fusion algorithms to estimate the target positions in the NED frame.

To enable this syntax, set the HasINS property to true.

[dets,numDets,config] = sensor(___) also returns the number of valid detections reported, numValidDets, and the configuration of the sensor, config, at the current simulation time.

Input Arguments

expand all

`sonarsigs` — Sonar emissions
array of sonar emission objects

Sonar emissions, specified as an array of sonarEmission objects.

`txconfigs` — Emitter configurations
array of structures

Emitter configurations, specified as an array of structures. Each structure has these fields:

Field	Description
`EmitterIndex`	Unique emitter index, returned as a positive integer.
`IsValidTime`	Valid emission time, returned as `0` or `1`. `IsValidTime` is `0` when emitter updates are requested at times that are between update intervals specified by the `UpdateInterval` property.
`IsScanDone`	Whether the emitter has completed a scan, returned as `true` or `false`.
`FieldOfView`	Field of view of the emitter, returned as a two-element vector [azimuth; elevation] in degrees.
`MeasurementParameters`	Emitter measurement parameters, returned as an array of structures containing the coordinate frame transforms needed to transform positions and velocities in the top-level frame to the current emitter frame.

Data Types: struct

`ins` — Platform pose from INS
structure

Sensor platform pose obtained from the inertial navigation system (INS), specified as a structure.

Platform pose information from an inertial navigation system (INS) is a structure with these fields:

Field	Definition
`Position`	Position in the navigation frame, specified as a real-valued 1-by-3 vector. Units are in meters.
`Velocity`	Velocity in the navigation frame, specified as a real-valued 1-by-3 vector. Units are in meters per second.
`Orientation`	Orientation with respect to the navigation frame, specified as a `quaternion` or a 3-by-3 real-valued rotation matrix. The rotation is from the navigation frame to the current INS body frame. This is also referred to as a "parent to child" rotation.

Dependencies

To enable this argument, set the HasINS property to true.

Data Types: struct

`simTime` — Current simulation time
nonnegative scalar

Current simulation time, specified as a positive scalar. The trackingScenario object calls the sonar sensor at regular time intervals. The sonar sensor generates new detections at intervals defined by the UpdateInterval property. The value of the UpdateInterval property must be an integer multiple of the simulation time interval. Updates requested from the sensor between update intervals contain no detections. Units are in seconds.

Example: 10.5

Data Types: double

Output Arguments

expand all

`dets` — sensor detections
cell array of `objectDetection` objects

Sensor detections, returned as a cell array of objectDetection objects. Each object has these properties:

Property	Definition
`Time`	Measurement time
`Measurement`	Object measurements
`MeasurementNoise`	Measurement noise covariance matrix
`SensorIndex`	Unique ID of the sensor
`ObjectClassID`	Object classification
`ObjectAttributes`	Additional information passed to tracker
`MeasurementParameters`	Parameters used by initialization functions of nonlinear Kalman tracking filters

Measurement and MeasurementNoise are reported in the coordinate system specified by the DetectionCoordinates property.

`numDets` — Number of detections
nonnegative integer

Number of detections reported, returned as a nonnegative integer.

When the MaxNumDetectionsSource property is set to 'Auto', numDets is set to the length of dets.
When the MaxNumDetectionsSource property is set to 'Property', dets is a cell array with length determined by the MaxNumDetections property. No more than MaxNumDetections number of detections are returned. If the number of detections is fewer than MaxNumDetections, the first numDets elements of dets hold valid detections. The remaining elements of dets are set to the default value.

Data Types: double

`config` — Current sensor configuration
structure

Current sensor configuration, specified as a structure. This output can be used to determine which objects fall within the sonar beam during object execution.

Field	Description
`SensorIndex`	Unique sensor index, returned as a positive integer.
`IsValidTime`	Valid detection time, returned as `true` or `false`. `IsValidTime` is `false` when detection updates are requested between update intervals specified by the update rate.
`IsScanDone`	`IsScanDone` is `true` when the sensor has completed a scan.
`FieldOfView`	Field of view of the sensor, returned as a 2-by-1 vector of positive real values, [`azfov`;`elfov`]. `azfov` and `elfov` represent the field of view in azimuth and elevation, respectively.
`MeasurementParameters`	Sensor measurement parameters, returned as an array of structures containing the coordinate frame transforms needed to transform positions and velocities in the top-level frame to the current sensor frame.

Data Types: struct

Object Functions

To use an object function, specify the System object as the first input argument. For example, to release system resources of a System object named obj, use this syntax:

release(obj)

expand all

Specific to `sonarSensor`

`coverageConfig`	Sensor and emitter coverage configuration
`perturbations`	Perturbation defined on object
`perturb`	Apply perturbations to object

Common to All System Objects

`step`	Run System object algorithm
`release`	Release resources and allow changes to System object property values and input characteristics
`reset`	Reset internal states of System object

Examples

collapse all

Detect Sonar Emission with Passive Sensor

Open Live Script

Create a sonar emission and then detect the emission using a sonarSensor object.

First, create a sonar emission.

orient = quaternion([180 0 0],'eulerd','zyx','frame');
sonarSig = sonarEmission('PlatformID',1,'EmitterIndex',1, ...
    'OriginPosition',[30 0 0],'Orientation',orient, ...
    'SourceLevel',140,'TargetStrength',100);

Then create a passive sonar sensor.

sensor = sonarSensor(1,'No scanning');

Detect the sonar emission.

time = 0;
[dets, numDets, config] = sensor(sonarSig,time)

dets = 1x1 cell array
    {1x1 objectDetection}

numDets = 1

config = struct with fields:
              SensorIndex: 1
              IsValidTime: 1
               IsScanDone: 1
              FieldOfView: [1 5]
    MeasurementParameters: [1x1 struct]

More About

expand all

Object Detections

Measurements

The sensor measures the coordinates of the target. The Measurement and MeasurementNoise values are reported in the coordinate system specified by the DetectionCoordinates property of the sensor.

When the DetectionCoordinates property is 'Scenario', 'Body', or 'Sensor rectangular', the Measurement and MeasurementNoise values are reported in rectangular coordinates. Velocities are only reported when the range rate property, HasRangeRate, is true.

When the DetectionCoordinates property is 'Sensor spherical', the Measurement and MeasurementNoise values are reported in a spherical coordinate system derived from the sensor rectangular coordinate system. Elevation and range rate are only reported when HasElevation and HasRangeRate are true.

Measurements are ordered as [azimuth, elevation, range, range rate]. Reporting of elevation and range rate depends on the corresponding HasElevation and HasRangeRate property values. Angles are in degrees, range is in meters, and range rate is in meters per second.

Measurement Coordinates

DetectionCoordinates Measurement and Measurement Noise Coordinates

'Scenario'

Coordinate Dependence on HasRangeRate

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

'Body'

'Sensor rectangular'

'Sensor spherical'

Coordinate Dependence on HasRangeRate and HasElevation

`HasRangeRate`	`HasElevation`	`Coordinates`
`true`	`true`	[az; el; rng; rr]
`true`	`false`	[az; rng; rr]
`false`	`true`	[az; el; rng]
`false`	`false`	[az; rng]

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). In most cases, the longest required sequence of transformations is Sensor → Platform → Scenario.

If the detections are reported in sensor spherical coordinates and HasINS is set to false, then the sequence consists only of one transformation from sensor to platform. In the transformation, the OriginPosition is same as the MountingLocation property of the sensor. The Orientation consists of two consecutive rotations. The first rotation, corresponding to the MountingAngles property of the sensor, accounts for the rotation from the platform frame (P) to the sensor mounting frame (M). The second rotation, corresponding to the azimuth and elevation angles of the sensor, accounts for the rotation from the sensor mounting frame (M) to the sensor scanning frame (S). In the S frame, the x direction is the boresight direction, and the y direction lies within the x-y plane of the sensor mounting frame (M).

If HasINS is true, the sequence of transformations consists of two transformations – first form the scenario frame to the platform frame then from platform frame to the sensor scanning frame. In the first transformation, the Orientation is the rotation from the scenario frame to the platform frame, and the OriginPosition is the position of the platform frame origin relative to the scenario frame.

Trivially, if the detections are reported in platform rectangular coordinates and HasINS is set to false, the transformation consists only of the identity.

The fields of MeasurementParameters are shown here. Not all fields have to be present in the structure. The set of fields and their default values can depend on the type of sensor.

Field	Description
`Frame`	Enumerated type indicating the frame used to report measurements. When detections are reported using a rectangular coordinate system, `Frame` is set to `'rectangular'`. When detections are reported in spherical coordinates, `Frame` is set `'spherical'` for the first `struct`.
`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`	3-by-3 real-valued orthonormal frame rotation matrix. The direction of the rotation depends on the `IsParentTochild` field.
`IsParentToChild`	A logical scalar indicating if `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.
`HasElevation`	A logical scalar indicating if elevation is included in the measurement. For measurements reported in a rectangular frame, and if `HasElevation` is `false`, the measurements are reported assuming 0 degrees of elevation.
`HasAzimuth`	A logical scalar indicating if azimuth is included in the measurement.
`HasRange`	A logical scalar indicating if range is included in the measurement.
`HasVelocity`	A logical scalar indicating if the reported detections include velocity measurements. For measurements reported in the rectangular frame, if `HasVelocity` is `false`, the measurements are reported as `[x y z]`. If `HasVelocity` is `true`, measurements are reported as `[x y z vx vy vz]`.

Object Attributes

Object attributes contain additional information about a detection.

Attribute	Description
`TargetIndex`	Identifier of the platform, `PlatformID`, that generated the detection. For false alarms, this value is negative.
`EmitterIndex`	Index of the emitter from which the detected signal was emitted.
`SNR`	Detection signal-to-noise ratio in dB.
`CenterFrequency`	Measured center frequency of the detected sonar signal. Units are in Hz. This attribute is present only when the `DetectionMode` property is set to `'passive'`.
`Bandwidth`	Measured bandwidth of the detected sonar signal, Units are in Hz. This attribute is present only when the `DetectionMode` property is set to `'passive'`.
`WaveformType`	Identifier of the waveform type that was classified by a passive sensor for the detected signal. This attribute is present only when the `DetectionMode` property is set to `'passive'`.

Convenience Syntaxes

The convenience syntaxes set several properties together to model a specific type of sonar.

No Scanning

Sets ScanMode to 'No scanning'.

Raster Scanning

This syntax sets these properties:

Property	Value
`ScanMode`	`'Electronic'`
`HasElevation`	`true`
`ElectronicScanLimits`	`[-45 45; -10 0]`

Rotator Scanning

This syntax sets these properties:

Property	Value
`ScanMode`	`'Electronic'`
`FieldOfView`	[`1:10]`
`HasElevation`	`false` or `true`
`ElevationResolution`	`10/sqrt(12)`

Sector Scanning

This syntax sets these properties:

Property	Value
`ScanMode`	`'Electronic'`
`FieldOfView`	`[1;10]`
`HasElevation`	`false`
`ElectronicScanLimits`	`[-45 45; -10 0]`
`ElevationResolution`	`10/sqrt(12)`

Documentation

sonarSensor

Description

Creation

Syntax

Description

Properties

SensorIndex — Unique sensor identifier positive integer

UpdateRate — Sensor update rate 1 (default) | positive scalar

DetectionMode — Detection mode 'passive' (default) | 'monostatic'

EmitterIndex — Unique monostatic emitter index positive integer

Dependencies

MountingLocation — Sensor location on platform [0 0 0] (default) | 1-by-3 real-valued vector

MountingAngles — Orientation of sensor [0 0 0] (default) | 3-element real-valued vector

FieldOfView — Fields of view of sensor [10;50] | 2-by-1 vector of positive scalar

ScanMode — Scanning mode of sonar 'Electronic' (default) | 'No scanning'

MechanicalAngle — Current mechanical scan angle scalar | real-valued 2-by-1 vector

ElectronicScanLimits — Angular limits of electronic scan directions of sonar [-45 45;-45 45] (default) | real-valued 1-by-2 row vector | real-valued 2-by-2 matrix

Dependencies

ElectronicAngle — Current electronic scan angle electronic scalar | nonnegative scalar

Dependencies

LookAngle — Look angle of sensor scalar | real-valued 2-by-1 vector

HasElevation — Enable sonar elevation scan and measurements false (default) | true

CenterFrequency — Center frequency of sonar band 20e3 (default) | positive scalar

Bandwidth — Sonar waveform bandwidth 2e3 | positive scalar

WaveformTypes — Types of detected waveforms 0 (default) | nonnegative integer-valued L-element vector

ConfusionMatrix — Probability of correct classification of detected waveform 1 (default) | positive scalar | real-valued nonnegative L-element vector | real-valued nonnegative L-by-L matrix

AmbientNoiseLevel — Spectrum-level ambient isotropic noise 70 (default) | scalar

FalseAlarmRate — False alarm rate 1e-6 (default) | positive scalar

AzimuthResolution — Azimuth resolution of sonar 1 (default) | positive scalar

ElevationResolution — Elevation resolution of sonar 1 (default) | positive scalar

Dependencies

RangeResolution — Range resolution of sonar 100 (default) | positive scalar

RangeRateResolution — Range rate resolution of sonar 10 (default) | positive scalar

Dependencies

AzimuthBiasFraction — Azimuth bias fraction 0.1 (default) | nonnegative scalar

ElevationBiasFraction — Elevation bias fraction 0.1 (default) | nonnegative scalar

Dependencies

RangeBiasFraction — Range bias fraction 0.05 (default) | nonnegative scalar

RangeRateBiasFraction — Range rate bias fraction 0.05 (default) | nonnegative scalar

Dependencies

HasRangeRate — Enable sonar to measure range rate false (default) | true

HasRangeAmbiguities — Enable range ambiguities false (default) | true

HasRangeRateAmbiguities — Enable range-rate ambiguities false (default) | true

Dependencies

MaxUnambiguousRange — Maximum unambiguous detection range 100e3 (default) | positive scalar

Dependencies

MaxUnambiguousRadialSpeed — Maximum unambiguous radial speed 200 (default) | positive scalar

Dependencies

HasINS — Enable inertial navigation system (INS) input false (default) | true

HasNoise — Enable addition of noise to sonar sensor measurements true (default) | false

HasFalseAlarms — Enable creating false alarm sonar detections true (default) | false

MaxNumDetectionsSource — Source of maximum number of detections reported 'Auto' (default) | 'Property'

MaxNumDetections — Maximum number of reported detections 50 (default) | positive integer

Dependencies

DetectionCoordinates — Coordinate system of reported detections 'Body' (default) | 'Scenario' | 'Sensor rectangular | 'Sensor spherical'

Usage

Syntax

Description

Input Arguments

sonarsigs — Sonar emissions array of sonar emission objects

txconfigs — Emitter configurations array of structures

ins — Platform pose from INS structure

Dependencies

simTime — Current simulation time nonnegative scalar

Output Arguments

dets — sensor detections cell array of objectDetection objects

numDets — Number of detections nonnegative integer

config — Current sensor configuration structure

Object Functions

Specific to sonarSensor

Common to All System Objects

Examples

Detect Sonar Emission with Passive Sensor

More About

Object Detections

Convenience Syntaxes

Extended Capabilities

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

See Also

`SensorIndex` — Unique sensor identifier
positive integer

`UpdateRate` — Sensor update rate
`1` (default) | positive scalar

`DetectionMode` — Detection mode
`'passive'` (default) | `'monostatic'`

`EmitterIndex` — Unique monostatic emitter index
positive integer

`MountingLocation` — Sensor location on platform
`[0 0 0]` (default) | 1-by-3 real-valued vector

`MountingAngles` — Orientation of sensor
`[0 0 0]` (default) | 3-element real-valued vector

`FieldOfView` — Fields of view of sensor
`[10;50]` | 2-by-1 vector of positive scalar

`ScanMode` — Scanning mode of sonar
`'Electronic'` (default) | `'No scanning'`

`MechanicalAngle` — Current mechanical scan angle
scalar | real-valued 2-by-1 vector

`ElectronicScanLimits` — Angular limits of electronic scan directions of sonar
`[-45 45;-45 45]` (default) | real-valued 1-by-2 row vector | real-valued 2-by-2 matrix

`ElectronicAngle` — Current electronic scan angle
electronic scalar | nonnegative scalar

`LookAngle` — Look angle of sensor
scalar | real-valued 2-by-1 vector

`HasElevation` — Enable sonar elevation scan and measurements
`false` (default) | `true`

`CenterFrequency` — Center frequency of sonar band
`20e3` (default) | positive scalar

`Bandwidth` — Sonar waveform bandwidth
`2e3` | positive scalar

`WaveformTypes` — Types of detected waveforms
`0` (default) | nonnegative integer-valued L-element vector

`ConfusionMatrix` — Probability of correct classification of detected waveform
`1` (default) | positive scalar | real-valued nonnegative L-element vector | real-valued nonnegative L-by-L matrix

`AmbientNoiseLevel` — Spectrum-level ambient isotropic noise
`70` (default) | scalar

`FalseAlarmRate` — False alarm rate
`1e-6` (default) | positive scalar

`AzimuthResolution` — Azimuth resolution of sonar
`1` (default) | positive scalar

`ElevationResolution` — Elevation resolution of sonar
`1` (default) | positive scalar

`RangeResolution` — Range resolution of sonar
`100` (default) | positive scalar

`RangeRateResolution` — Range rate resolution of sonar
`10` (default) | positive scalar

`AzimuthBiasFraction` — Azimuth bias fraction
`0.1` (default) | nonnegative scalar

`ElevationBiasFraction` — Elevation bias fraction
`0.1` (default) | nonnegative scalar

`RangeBiasFraction` — Range bias fraction
`0.05` (default) | nonnegative scalar

`RangeRateBiasFraction` — Range rate bias fraction
`0.05` (default) | nonnegative scalar

`HasRangeRate` — Enable sonar to measure range rate
`false` (default) | `true`

`HasRangeAmbiguities` — Enable range ambiguities
`false` (default) | `true`

`HasRangeRateAmbiguities` — Enable range-rate ambiguities
`false` (default) | `true`

`MaxUnambiguousRange` — Maximum unambiguous detection range
`100e3` (default) | positive scalar

`MaxUnambiguousRadialSpeed` — Maximum unambiguous radial speed
`200` (default) | positive scalar

`HasINS` — Enable inertial navigation system (INS) input
`false` (default) | `true`

`HasNoise` — Enable addition of noise to sonar sensor measurements
`true` (default) | `false`

`HasFalseAlarms` — Enable creating false alarm sonar detections
`true` (default) | `false`

`MaxNumDetectionsSource` — Source of maximum number of detections reported
`'Auto'` (default) | `'Property'`

`MaxNumDetections` — Maximum number of reported detections
`50` (default) | positive integer

`DetectionCoordinates` — Coordinate system of reported detections
`'Body'` (default) | `'Scenario'` | `'Sensor rectangular` | `'Sensor spherical'`

`sonarsigs` — Sonar emissions
array of sonar emission objects

`txconfigs` — Emitter configurations
array of structures

`ins` — Platform pose from INS
structure

`simTime` — Current simulation time
nonnegative scalar

`dets` — sensor detections
cell array of `objectDetection` objects

`numDets` — Number of detections
nonnegative integer

`config` — Current sensor configuration
structure

Specific to `sonarSensor`

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