Inheritance diagram for SensorEchosounder:

Collaboration diagram for SensorEchosounder:

Classes
struct	Reading
	The altimeter reading held on the output ports between pings. More...

struct	Settings
	Everything the instrument is configured with. More...

struct	Species
	One Species Concentration field as the acoustic model sees it. More...

Public Member Functions
	SensorEchosounder (std::string simObjectName, ISimObjectCreator *creator)

	SensorEchosounder (std::string simObjectName, const Settings &settings)

	~SensorEchosounder () override
	Flushes and closes the echogram file, and releases the visualisation geometry.

void	OdeFcn (const double dT, const double const adX, double const adXDot) const override
	Writes no derivatives: this SimObject declares no states.

void	AcceptedStep (const double dT, const double *const adX) override

void	FinalSetup (const double dT, const double const adX, ISimObjectCreator const creator) override

const Reading &	HeldReading () const
	The reading currently held on the output ports.

const Settings &	GetSettings () const
	The settings the instrument was built with.

const std::vector< Species > &	GetSpecies () const
	The species entering the acoustic model, in file column order.

const std::vector< double > &	DiskRadiiPerRange () const
	The disk radius per range of each distinct beam width, in order of first appearance among the frequencies (D20 (c)).

int	PingsTaken () const
	The number of pings taken so far.

const std::vector< double > &	Frequencies () const
	The operating frequencies, kHz.

Static Public Member Functions
static double	PerturbRange (double trueRange, const Settings &settings, SensorNoise &noise)

static bool	IsValidRaySearch (double rayStepSize, double rayTolerance)

static bool	IsValidMaxRange (double maxRange)

static double	AltitudeOf (double slantRange, const double beamDirection[3])

static int	BinCountOf (double range, double binSize)

static double	SampleRangeOf (int bin, double binSize, double beamRange)

static double	DownSampleRangeOf (int bin, double binSize, double bottomRange, double clearance)

static double	BottomClearance (double rayTolerance, const double beamDirection[3])

static double	BeamPattern (double offAxisRad, double beamWidthDeg)

static double	EquivalentBeamAngle (double beamWidthDeg)

static double	DiskRadiusPerRange (double beamWidthDeg)

static bool	IsDiskBeam (const double axis[3], double halfWidthRad)

static void	DiskConcentrations (const environment::field::IntegrableField &field, const double position[3], const double axis[3], double binSize, double radiusPerRange, std::span< double > concentration)

static void	SampleDirections (const double axis[3], int beamSamples, double ringAngleRad, std::vector< std::array< double, 3 > > &directions)

static int	DetectBottomBin (const std::vector< double > &svLinear, double binSize, double beamRange, double minRange, double thresholdDb)

static double	IntegrateOverWindow (std::span< const double > perBin, double binSize, double beamRange, double windowStart, double windowEnd)

static std::string	FieldStatusWarning (const std::string &sensorName, const std::string &fieldName, double depth, marenv::Status status)

static double	NoiseFloorLinear (double noiseSvAt1mDb, double absorptionDbPerKm, double range)

Protected Member Functions
const double *	OutSeafloorDistance (const double dT, const double *const adX)
	The measured slant range to the seafloor, m.

const double *	OutSeafloorDepth (const double dT, const double *const adX)
	The inferred depth of the seafloor, m.

const double *	OutAltitude (const double dT, const double *const adX)
	The measured height above the seafloor, m.

const double *	OutValid (const double dT, const double *const adX)
	One when the last ping found a bottom, zero otherwise.

const double *	OutPingTime (const double dT, const double *const adX)
	The time of the ping the held reading came from, s.

const double *	OutSa (const double dT, const double *const adX, const int index)
	sa over the Integration window at one frequency, m^2/m^2.

const double *	OutIntegratedBiomass (const double dT, const double *const adX, const int index)
	The Integrated biomass of one species field, kg/m^2.

Constructor & Destructor Documentation

◆ SensorEchosounder() [1/2]

SensorEchosounder::SensorEchosounder	(	std::string	simObjectName,
		ISimObjectCreator *	creator
	)

Constructs the sounder from the simulation input file.

Parameters

simObjectName	The name of this object in the simulation.
creator	The creator of this object.

◆ SensorEchosounder() [2/2]

SensorEchosounder::SensorEchosounder	(	std::string	simObjectName,
		const Settings &	settings
	)

Constructs the sounder with its settings given directly.

No ports are registered and no file is opened, so OdeFcn, AcceptedStep and FinalSetup all do nothing and the pure parts must be exercised directly. This constructor exists so that the geometry and the acoustic model can be unit tested without a host simulation, which matters because ISimObjectCreator has some thirty pure virtuals and FhSim exports no mock.

Parameters

simObjectName	The name of this object.
settings	The instrument settings.

Member Function Documentation

◆ AcceptedStep()

void SensorEchosounder::AcceptedStep	(	const double	dT,
		const double *const	adX
	)

override

Takes every ping that has fallen due since the previous accepted step.

Parameters

dT	The current simulation time, s.
adX	The state vector.

◆ AltitudeOf()

static double SensorEchosounder::AltitudeOf	(	double	slantRange,
		const double	beamDirection[3]
	)

static

Projects a slant range onto the vertical.

Parameters

slantRange	The slant range along the beam, m.
beamDirection	The unit beam direction in NED.

Returns: The vertical component of the slant range, m, always non-negative.

◆ BeamPattern()

static double SensorEchosounder::BeamPattern	(	double	offAxisRad,
		double	beamWidthDeg
	)

static

The two-way beam pattern of a circular piston, (2 J1(u) / u)^4 with u = 1.6163 sin(theta) / sin(BeamWidth / 2).

Parameters

offAxisRad	The angle off the beam axis, rad.
beamWidthDeg	The full -3 dB beam width, degrees.

Returns: The two-way pattern, 1 on the axis and 1/4 at half the beam width.

◆ BinCountOf()

static int SensorEchosounder::BinCountOf	(	double	range,
		double	binSize
	)

static

The number of range bins a beam of a given range is binned into, ceil(range / binSize). A range within rounding error of a bin edge ends on that edge, so it adds no empty bin.

Parameters

range	The slant range the beam ends at, m.
binSize	The bin size, m.

Returns: The bin count, which is zero for a non-positive range or bin size.

◆ BottomClearance()

static double SensorEchosounder::BottomClearance	(	double	rayTolerance,
		const double	beamDirection[3]
	)

static

The slant length along a beam of the vertical ray tolerance: RayTolerance / |cos(tilt)|.

Parameters

rayTolerance	The vertical convergence tolerance of the ray intersection, m.
beamDirection	The unit beam direction in NED.

Returns: The clearance, m; rayTolerance for a beam without a vertical component.

◆ DetectBottomBin()

static int SensorEchosounder::DetectBottomBin	(	const std::vector< double > &	svLinear,
		double	binSize,
		double	beamRange,
		double	minRange,
		double	thresholdDb
	)

static

The bottom Detection: the first bin evaluated at least minRange out whose Sv reaches the threshold.

Parameters

svLinear	The linear sv of each bin, 1/m.
binSize	The bin size, m.
beamRange	The slant range the beam ends at, m.
minRange	The range before which no bottom is detected, m.
thresholdDb	The Sv threshold, dB.

Returns: The bin index, or -1 when no bin qualifies.

◆ DiskConcentrations()

static void SensorEchosounder::DiskConcentrations	(	const environment::field::IntegrableField &	field,
		const double	position[3],
		const double	axis[3],
		double	binSize,
		double	radiusPerRange,
		std::span< double >	concentration
	)

static

The mean mass concentration of each range bin over the beam's disk (D20 (a)). C = M_bin / (pi R^2 dz) with R = radiusPerRange times the bin midpoint range and dz = binSize |axis.z|.

Parameters

	field	The field.
	position	The transducer position in NED, m.
	axis	The unit beam axis in NED; its z is not zero.
	binSize	The bin size, m.
	radiusPerRange	The disk radius per range (DiskRadiusPerRange()).
[out]	concentration	One value per bin, kg/m^3; its size is the number of bins.

◆ DiskRadiusPerRange()

static double SensorEchosounder::DiskRadiusPerRange ( double beamWidthDeg )

static

The disk radius per range of the equivalent beam: sqrt(psi / pi) (D20 (c)).

Parameters

beamWidthDeg The full -3 dB beam width, degrees.

Returns: The radius per range, dimensionless.

◆ DownSampleRangeOf()

static double SensorEchosounder::DownSampleRangeOf	(	int	bin,
		double	binSize,
		double	bottomRange,
		double	clearance
	)

static

The slant range a bin is evaluated at when the beam ends on the bottom: as SampleRangeOf, but at least clearance short of the hit (FISH-0064, owner ruling R131). The hit is a root of the vertical distance to the seabed within RayTolerance, on either side, so a sample at the centre of a wet part shorter than twice that could lie below the seabed. A sample the clearance moves up may lie in the bin above; it is never behind the transducer. The sample is RayTolerance vertically above the hit, not above the seabed: a vertical beam or a flat seabed keeps it above the seabed. For a tilted beam over a seabed that deepens along its heading with slope g, the move back also shifts the sample horizontally by RayTolerance tan(tilt), so it can still lie about RayTolerance tan(tilt) g below the seabed (1.2 mm for 30 degrees, g = 0.2 and the default tolerance).

Parameters

bin	The bin index.
binSize	The bin size, m.
bottomRange	The slant range of the bottom hit, where the beam ends, m.
clearance	The slant distance kept from the hit, m (BottomClearance()).

Returns: min(SampleRangeOf(bin, binSize, bottomRange), max(0, bottomRange - clearance)), m.

◆ EquivalentBeamAngle()

static double SensorEchosounder::EquivalentBeamAngle ( double beamWidthDeg )

static

The equivalent two-way beam angle of a circular piston, psi = integral of BeamPattern over the half space [sr]. Simpson's rule over [0, pi/2] of 2 pi BeamPattern(theta, width) sin(theta).

Parameters

beamWidthDeg The full -3 dB beam width, degrees.

Returns: psi, sr.

◆ FieldStatusWarning()

static std::string SensorEchosounder::FieldStatusWarning	(	const std::string &	sensorName,
		const std::string &	fieldName,
		double	depth,
		marenv::Status	status
	)

static

The warning for a species field query that did not return OK. A usable status (marenv::IsUsable) other than OK is OUT_OF_RANGE_INACCURATE: the sample is outside the field's data, so the value is the edge of a depth profile, or 0 below the seabed mask. Any other status is an error: the value is not usable and the echogram takes 0.

Parameters

sensorName	The name of this SimObject.
fieldName	The species field that was queried.
depth	The depth of the sample, m.
status	The status the field returned.

Returns: The warning text, or an empty string when status is OK.

◆ FinalSetup()

void SensorEchosounder::FinalSetup	(	const double	dT,
		const double *const	adX,
		ISimObjectCreator *const	creator
	)

override

Resolves the environment, the Parameter library and the species fields, and opens the echogram file.

Parameters

dT	The initial simulation time, s.
adX	The state vector.
creator	The creator of this object.

◆ IntegrateOverWindow()

static double SensorEchosounder::IntegrateOverWindow	(	std::span< const double >	perBin,
		double	binSize,
		double	beamRange,
		double	windowStart,
		double	windowEnd
	)

static

Integrates a per-bin quantity over the Integration window [windowStart, windowEnd). Each bin contributes its value times the length of its overlap with the window; a beam that ends inside its last bin makes that bin only as long as its wet part.

Parameters

perBin	The value of each bin, per metre of range.
binSize	The bin size, m.
beamRange	The slant range the beam ends at, m.
windowStart	The start of the window, m.
windowEnd	The end of the window, m.

Returns: The integral over the window.

◆ IsDiskBeam()

static bool SensorEchosounder::IsDiskBeam	(	const double	axis[3],
		double	halfWidthRad
	)

static

True when the beam axis is within halfWidthRad of vertical, down or up (D20 (d)).

Parameters

axis	The unit beam axis in NED.
halfWidthRad	The widest beam's half width, rad.

◆ IsValidMaxRange()

static bool SensorEchosounder::IsValidMaxRange ( double maxRange )

static

True for a MaxRangeDown the sounder accepts (FISH-0101): positive and finite. The ray search refuses a range that is not finite (marenv ERROR_NOT_SET), which would read as "no bottom" on every ping without a message.

Parameters

maxRange The longest slant range, m.

Returns: Whether it is acceptable.

◆ IsValidRaySearch()

static bool SensorEchosounder::IsValidRaySearch	(	double	rayStepSize,
		double	rayTolerance
	)

static

True for ray search settings the sounder accepts (FISH-0100): a positive, finite RayTolerance and a finite RayStepSize of at least RayTolerance. The search marches from the transducer, about altitude / (RayStepSize cos(tilt)) depth evaluations per ping, and a step below the tolerance buys no accuracy.

Parameters

rayStepSize	The search step, m.
rayTolerance	The vertical convergence tolerance, m.

Returns: Whether both are acceptable.

◆ NoiseFloorLinear()

static double SensorEchosounder::NoiseFloorLinear	(	double	noiseSvAt1mDb,
		double	absorptionDbPerKm,
		double	range
	)

static

The modelled noise floor of one bin.

Parameters

noiseSvAt1mDb	The noise floor referred to one metre, dB.
absorptionDbPerKm	The absorption coefficient, dB/km.
range	The slant range of the bin centre, m.

Returns: The noise floor as a linear volume backscattering coefficient, 1/m.

◆ PerturbRange()

static double SensorEchosounder::PerturbRange	(	double	trueRange,
		const Settings &	settings,
		SensorNoise &	noise
	)

static

Applies the range bias and the two range noise terms.

Parameters

trueRange	The geometric slant range, m.
settings	The instrument settings.
noise	The random generator; a deterministic one leaves the range alone.

Returns: The range the instrument reports, m.

◆ SampleDirections()

static void SensorEchosounder::SampleDirections	(	const double	axis[3],
		int	beamSamples,
		double	ringAngleRad,
		std::vector< std::array< double, 3 > > &	directions
	)

static

The directions sampled across the beam: the axis, then beamSamples - 1 directions evenly around a ring ringAngleRad off the axis.

Parameters

	axis	The unit beam axis in NED.
	beamSamples	The number of directions, at least 1.
	ringAngleRad	The angle of the ring off the axis, rad.
[out]	directions	The unit directions in NED, the axis first; resized to `beamSamples`.

◆ SampleRangeOf()

static double SensorEchosounder::SampleRangeOf	(	int	bin,
		double	binSize,
		double	beamRange
	)

static

The slant range a bin is evaluated at: its centre, or the centre of its wet part.

Parameters

bin	The bin index.
binSize	The bin size, m.
beamRange	The slant range the beam ends at, m.

Returns: The smaller of (bin + 0.5) * binSize and (bin * binSize + beamRange) / 2, m.

The documentation for this class was generated from the following file:

webfhsim/reloadrepos/fhsim_fishery/src/auv/SensorEchosounder.h

Classes

Public Member Functions

Static Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

◆ SensorEchosounder() [1/2]

◆ SensorEchosounder() [2/2]

Member Function Documentation

◆ AcceptedStep()

◆ AltitudeOf()

◆ BeamPattern()

◆ BinCountOf()

◆ BottomClearance()

◆ DetectBottomBin()

◆ DiskConcentrations()

◆ DiskRadiusPerRange()

◆ DownSampleRangeOf()

◆ EquivalentBeamAngle()

◆ FieldStatusWarning()

◆ FinalSetup()

◆ IntegrateOverWindow()

◆ IsDiskBeam()

◆ IsValidMaxRange()

◆ IsValidRaySearch()

◆ NoiseFloorLinear()

◆ PerturbRange()

◆ SampleDirections()

◆ SampleRangeOf()