API reference

SDWBA API

SDWBA.Scatterer — Type.

Construct a data structure describing a fluid-like weak scatterer with a deformed cylindrical shape. This shape is approximated by a series of N discrete segments, described by the [x, y, z] coordinates, radii, and material properties at their endpoints.

Parameters

  • r : 3xN matrix describing the scatterer's centerline. Each column is the

location in 3-D space of one of the centerline points (these should be arranged in the proper order).

  • a : Vector of radii, length N.
  • h, g : Vectors of sound speed and density contrasts (i.e., the ratio

of sound speed or density inside the scatter to the same quantity in the surrounding medium).

source
SDWBA.rescale — Function.

Scale the scatterer's size (overall or along a particular dimension) by a constant factor.

Parameters

  • s : Scatterer object.
  • scale : Factor by which to grow/shrink the scatterer.
  • radius, x, y, z : Optional factors, scaling the scatterer's radius

and along each dimension in space. All default to 1.0.

Returns

A rescaled scatterer.

Details

When making a scatterer larger, it is important to make sure it's body has enough segments to accurately represent the shape at the frequencies of interest. Specifically, the ratio L / (N λ), where L is the length of the animal, N is the number of segments, and λ is the acoustic wavelength, should remain constant, which may require interpolating new points between the existing ones. See Conti and Demer (2006) or Calise and Skaret (2011) for details.

source
SDWBA.resize — Function.

Resize a scatterer. This is a convenience wrapper around rescale, for the common situation where you want to change a scatterer to a specific length. The scatterer's relative proportions are preserved.

Parameters

  • s : Scatterer
  • len : Desired length to which the scatterer should be scaled.

Returns

A resized scatterer.

source
SDWBA.interpolate — Function.

Resample a scatterer's measurement points by interpolating between them. Used to change the resolution, for instance when increasing the scatterer's body size or decreasing the acoustic wavelength.

Parameters

  • s : Scatterer
  • n : Number of body segments desired in the interpolated scatterer.

Returns

A Scatterer with a different number of body segments.

source
SDWBA.rotate — Function.

Rotate the scatterer in space, returning a rotated copy.

Parameters

  • roll : Angle to roll the scatterer, in degrees. Defaults to 0.
  • tilt : Angle to tilt the scatterer, in degrees. Defaults to 0.
  • yaw : Angle to yaw the scatterer, in degrees. Defaults to 0.

Returns

A Scatterer with the same shape and properties, but a new orientation.

The roll, tilt, and yaw refer to rotations around the x, y, and z axes, respectively. They are applied in that order.

source
Base.length — Function.
length(collection) -> Integer

Return the number of elements in the collection.

Use lastindex to get the last valid index of an indexable collection.

Examples

julia> length(1:5)
5

julia> length([1, 2, 3, 4])
4

julia> length([1 2; 3 4])
4
source
SDWBA.form_function — Function.

Calculate the complex-valued form function of a scatterer using the (S)DWBA.

Parameters

  • s : Scatterer object.
  • k : Acoustic wavenumber vector. Its magnitude is 2 * pi * f / c (where

f is the frequency and c is the sound speed) and it points in the direction of propagation. For downward-propagating sound waves, it is [0, 0, -2pi * f / c].

  • phase_sd : Standard deviation of the phase variability for each segment (in radians).

Defaults to 0.0, that is, an ordinary deterministic DWBA. If > 0, the return value will be stochastic (i.e., the SDWBA).

source
SDWBA.backscatter_xsection — Function.

Calculate the backscattering cross-section (sigma_bs) of a scatterer using the (S)DWBA. This is the absolute square of the form function.

Parameters

  • s : Scatterer object.
  • k : Acoustic wavenumber vector. Its magnitude is 2 * pi * f / c (where

f is the frequency and c is the sound speed) and it points in the direction of propagation. For downward-propagating sound waves, it is [0, 0, -2pi * f / c].

  • phase_sd : Standard deviation of the phase variability for each segment (in radians).

Defaults to 0.0, that is, an ordinary deterministic DWBA. If > 0, the return value will be stochastic (i.e., the SDWBA).

source
SDWBA.target_strength — Function.

Calculate the target strength (TS) of a scatterer using the (S)DWBA. This is just 10 * log10(sigma_bs).

Parameters

  • s : Scatterer object.
  • k : Acoustic wavenumber vector. Its magnitude is 2 * pi * f / c (where

f is the frequency and c is the sound speed) and it points in the direction of propagation. For downward-propagating sound waves, it is [0, 0, -2pi * f / c].

  • phase_sd : Standard deviation of the phase variability for each segment (in radians).

Defaults to 0.0, that is, an ordinary deterministic DWBA. If > 0, the return value will be stochastic (i.e., the SDWBA).

source
SDWBA.tilt_spectrum — Function.

Calculate backscatter over a range of angles.

Parameters

  • s : Scatterer object
  • angle1, angle2 : Endpoints of the angle range to calculate.
  • k : Acoustic wavenumber vector
  • n : Number of angles to calculate; defaults to 100

Returns

A dictionary containing elements "angles", "sigma_bs", and "TS", each a length-n vector.

source
SDWBA.freq_spectrum — Function.

Calculate backscatter over a range of frequencies. The insonifying sound comes from above (i.e., traveling in the -z direction).

Parameters

  • s : Scatterer object
  • freq1, freq2 : Endpoints of the angle range to calculate.
  • sound_speed : Sound speed in the surrounding medium
  • n : Number of frequencies to calculate; defaults to 100

Returns: A dictionary containing elements "freqs", "sigma_bs", and "TS", each a length-n vector.

source
SDWBA.from_csv — Function.

Load a scatterer from a file on disk with comma-separated values.

Parameters

  • filename : String. Path to the datafile. This should be a standard .csv file

with columns for the x, y, and z coordinates of the scatterer's centerline, as well as the a, h, and g arguments to Scatterer().

  • columns : Optional dictionary of column names. If the columns do not have the names
  • x, y, z, h, and g, this must be provided. The keys are the standard column

names and the values are the actual ones in the file.

source
SDWBA.to_csv — Function.

Save a scatterer's shape to a file on disk with comma-separated values.

Parameters

  • s : Scatterer object to save.
  • filename : Where to save it.
source