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

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	TargetStrengthDb (const Species &species, double frequencykHz)

static double	BackscatterCrossSection (const Species &species, double frequencykHz)

static std::string	FieldStatusWarning (const std::string &sensorName, const char *beamLabel, 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.

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.

◆ BackscatterCrossSection()

static double SensorEchosounder::BackscatterCrossSection	(	const Species &	species,
		double	frequencykHz
	)

static

The backscattering cross section of one species at one frequency.

Parameters

species	The species and its acoustic properties.
frequencykHz	The frequency, kHz.

Returns: The cross section, m^2.

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

◆ DownSampleRangeOf()

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

static

The slant range a down-beam 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.

◆ FieldStatusWarning()

static std::string SensorEchosounder::FieldStatusWarning	(	const std::string &	sensorName,
		const char *	beamLabel,
		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.
beamLabel	The beam name, "Down" or "Up".
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 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.

◆ IsValidMaxRange()

static bool SensorEchosounder::IsValidMaxRange ( double maxRange )

static

True for a MaxRangeDown or MaxRangeUp 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.

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

◆ TargetStrengthDb()

static double SensorEchosounder::TargetStrengthDb	(	const Species &	species,
		double	frequencykHz
	)

static

The target strength of one species at one frequency.

Parameters

species	The species and its acoustic properties.
frequencykHz	The frequency, kHz.

Returns: The target strength, dB.

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()

◆ BackscatterCrossSection()

◆ BinCountOf()

◆ BottomClearance()

◆ DownSampleRangeOf()

◆ FieldStatusWarning()

◆ FinalSetup()

◆ IsValidMaxRange()

◆ IsValidRaySearch()

◆ NoiseFloorLinear()

◆ PerturbRange()

◆ SampleRangeOf()

◆ TargetStrengthDb()