sonarEmitter

Acoustic signals and interferences generator

Description

The sonarEmitter System object™ creates an emitter to simulate sonar emissions. You can use the sonarEmitter object in a scenario that detects and tracks moving and stationary platforms. Construct a scenario using trackingScenario.

A sonar emitter 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 emitter scans the total region in azimuth and elevation defined by the sonar electronic scan limits, ElectronicScanLimits. If the scan limits for azimuth or elevation are set to [0 0], then no scanning is performed along that dimension for that scan mode.

To generate sonar detections:

1. Create the sonarEmitter object and set its properties.

2. 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

emitter = sonarEmitter(EmitterIndex)

emitter = sonarEmitter(EmitterIndex,'No scanning')

emitter = sonarEmitter(EmitterIndex,'Raster')

emitter = sonarEmitter(EmitterIndex,'Sector')

emitter = sonarEmitter(___,Name,Value)

Description

emitter = sonarEmitter(EmitterIndex) creates a sonar emitter object with default property values.

emitter = sonarEmitter(EmitterIndex,'No scanning') is a convenience syntax that creates a sonarEmitter that stares along the sonar transducer boresight direction. No scanning is performed. This syntax sets the ScanMode property to 'No scanning'.

emitter = sonarEmitter(EmitterIndex,'Raster') is a convenience syntax that creates a sonarEmitter object that 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 Raster Scanning for the properties set by this syntax.

emitter = sonarEmitter(EmitterIndex,'Sector') is a convenience syntax to create a sonarEmitter object that scans a 90° azimuth sector from –45° to +45°. Setting HasElevation to true, points the sonar towards the center of the elevation field of view. The scanning beams are stacked electronically to process the entire elevation spanned by the scan limits in a single dwell. See Sector Scanning for the properties set by this syntax.

emitter = sonarEmitter(___,Name,Value) sets properties using one or more name-value pairs after all other input arguments. Enclose each property name in quotes. For example, sonarEmitter('CenterFrequency',2e6) creates a sonar emitter creates detections in the emitter Cartesian coordinate system and has a maximum detection range of 200 meters. If you specify the emitter index using the EmitterIndex property, you can omit the EmitterIndex input.

Properties

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.

EmitterIndex — Unique sensor identifier

positive integer

Unique emitter identifier, specified as a positive integer. When creating a sonarEmitter system object, you must either specify the EmitterIndex as the first input argument in the creation syntax, or specify it as the value for the EmitterIndex property in the creation syntax.

Example: 2

Data Types: double

UpdateRate — Emitter update rate

1 (default) | positive scalar

Emitter update rate, specified as a positive scalar in hertz. The emitter generates new emissions at intervals defined by the reciprocal of the UpdateRate property. This interval must be an integer multiple of the simulation time interval defined in trackingScenario. If you request an update from the emitter between the update intervals, the emitter returns the current emission signals and sets the IsValidTime field of the returned configuration structure to false.

Example: 5

Data Types: double

MountingLocation — Emitter location on platform

[0 0 0] (default) | 1-by-3 real-valued vector

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

Example: [.2 0.1 0]

Data Types: double

MountingAngles — Orientation of emitter

[0 0 0] (default) | 3-element real-valued vector

Orientation of the emitter 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 emitter axes. The three elements define the rotations around the z, y, and x axes respectively, 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 carried 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 field of view azfov must lie in the interval (0,360]. The elevation field 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 antenna boresight defined by the mountingAngles property.

Example: 'No scanning'

Data Types: char

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

Read-only: 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

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 emitter that can estimate target elevation and scan in elevation.

Data Types: logical

SourceLevel — Sonar source level

140 (default) | scalar

Sonar source level, specified as a scalar. Source level is relative to the intensity of a sound wave having an rms pressure of 1 μPa. Units are in dB//1 μPa.

Data Types: double

CenterFrequency — Center frequency of sonar band

positive scalar

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

Example: 100e6

Data Types: double

Bandwidth — Sonar waveform bandwidth

positive scalar

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

Example: 100e3

Data Types: double

WaveformType — Type of detected waveform

0 (default) | nonnegative integer

Type of detected waveform, specified as a nonnegative integer.

Example: 1

Data Types: double

ProcessingGain — Processing gain

0 (default) | scalar

Processing gain when demodulating an emitted signal waveform, specified as a scalar. Processing gain is achieved by emitting a signal over a bandwidth which is greater than the minimum bandwidth necessary to send the information contained in the signal. Units are in dB.

Example: 20

Data Types: double

Usage

Syntax

sonarsigs = emitter(platform,simTime)

[sonarsigs,config] = emitter(platform,simTime)

Description

sonarsigs = emitter(platform,simTime) creates sonar signals, sonarsigs, from emitter on the platform at the current simulation time, simTime. The emitter object can simultaneously generate signals from multiple emitters on the platform.

[sonarsigs,config] = emitter(platform,simTime) also returns the emitter configurations, config, at the current simulation time.

Input Arguments

platform — emitter platform

object | structure

Emitter platform, specified as a platform object, Platform, or a platform structure:

Field	Description
PlatformID	Unique identifier for the platform, specified as a scalar positive integer. This is a required field which has no default value.
ClassID	User-defined integer used to classify the type of target, specified as a nonnegative integer. Zero is reserved for unclassified platform types and is the default value.
Position	Position of target in scenario coordinates, specified as a real-valued 1-by-3 vector. This is a required field. There is no default value. Units are in meters.
Velocity	Velocity of platform in scenario coordinates, specified as a real-valued 1-by-3 vector. Units are in meters per second. The default is [0 0 0].
Speed	Speed of the platform in the scenario frame specified as a real scalar. When speed is specified, the platform velocity is aligned with its orientation. Specify either the platform speed or velocity, but not both. Units are in meters per second The default is 0.
Acceleration	Acceleration of the platform in scenario coordinates specified as a 1-by-3 row vector in meters per second-squared. The default is [0 0 0].
Orientation	Orientation of the platform with respect to the local scenario NED coordinate frame, specified as a scalar quaternion or a 3-by-3 rotation matrix. Orientation defines the frame rotation from the local NED coordinate system to the current platform body coordinate system. Units are dimensionless. The default is quaternion(1,0,0,0).
AngularVelocity	Angular velocity of platform in scenario coordinates, specified as a real-valued 1-by-3 vector. The magnitude of the vector defines the angular speed. The direction defines the axis of clockwise rotation. Units are in degrees per second. The default is [0 0 0].
Signatures	Cell array of signatures defining the visibility of the platform to emitters and sensors in the scenario. The default is the cell array {rcsSignature, irSignature, tsSignature}.

simTime — Current simulation time

nonnegative scalar

Current simulation time, specified as a positive scalar. The trackingScenario object calls the sonar emitter at regular time intervals. The sonar emitter generates new signals 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 emitter between update intervals contain no detections. Units are in seconds.

Example: 10.5

Data Types: double

Output Arguments

sonarsigs — Sonar emissions

array of sonar emission objects

Sonar emissions, returned as an array of sonarEmission objects.

config — Current emitter configuration

structure array

Current emitter configurations, returned as an array of structures.

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 looking-angle 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)

Specific to sonarEmitter

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

Reflect Sonar Emission from Platform within Tracking Scenario

Create a tracking scenario object.

scenario = trackingScenario;

Create an sonarEmitter.

emitter = sonarEmitter(1);

Mount the emitter on a platform within the scenario.

plat = platform(scenario,'Emitters',emitter);

Add another platform to reflect the emitted signal.

tgt = platform(scenario);
tgt.Trajectory.Position = [30 0 0];

Emit the signal using the emit object function of a platform.

txSigs = emit(plat, scenario.SimulationTime)

txSigs = 1×1 cell array
    {1×1 sonarEmission}

Reflect the signal from the platforms in the scenario.

sigs = underwaterChannel(txSigs, scenario.Platforms)

sigs = 1×1 cell array
    {1×1 sonarEmission}

More About

Convenience Syntaxes

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

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]

Sector Scanning

This syntax sets these properties:

Property	Value
ScanMode	'Electronic'
FieldOfView	[1;10]
HasElevation	false
ElectronicScanLimits	[-45 45]

Extended Capabilities

C/C++ Code Generation

Generate C and C++ code using MATLAB® Coder™.

The object functions, perturbations and perturb, do not support code generation.

Usage notes and limitations:

See System Objects in MATLAB Code Generation (MATLAB Coder).

Version History

Introduced in R2018b