detect_seafloor

detect_seafloor#

echopype.mask.detect_seafloor(ds: Dataset, method: str, params: Dict) → DataArray#

Dispatch seafloor detection to a chosen method and return a 1-D bottom line.

This function forwards ds and params to the selected implementation (e.g., "basic", "blackwell"). Any optional arguments omitted in params are filled by that method’s defaults.

Parameters:

dsxr.Dataset

Dataset containing calibrated Sv and required coordinates (at minimum ping_time and a vertical coordinate such as depth), plus any extra variables required by the chosen method.

methodstr

Name of the detection method to use. Supported:

"basic" → threshold-only detector
"blackwell" → Sv + split-beam angle detector

paramsdict

Method-specific keyword arguments (see below). Unspecified keys use the method’s defaults.

When method == “basic”, params can contain:

var_namestr: Name of Sv variable (dB), e.g. "Sv".
channelstr: Channel identifier to select (e.g., "GPT 38 kHz ...").
thresholdfloat, default -50.0: Sv threshold(s) in dB. If a single float is given, it is treated as the lower bound and the upper bound is set to 10 dB above the lower bound. If a 2-tuple (tmin, tmax) is provided, both the lower and upper bounds are used directly.
offset_mfloat, default 0.5: Meters subtracted from the detected crossing.
bin_skip_from_surfaceint, default 200: Number of shallow range bins to ignore before searching.

When method == “blackwell”, params can contain:

var_namestr: Name of the Sv variable to use (e.g., "Sv").
channelstr: Channel identifier to select.
thresholdfloat | list | tuple, default -75: Either a single Sv dB threshold (angle thresholds use defaults), or a 3-tuple/list (tSv_dB, ttheta, tphi) after angle smoothing.
offsetfloat, default 0.3: Meters subtracted from the detected bottom.
r0float, default 0: Shallow bound (m) of the detection range.
r1float, default 500: Deep bound (m) of the detection range.
wthetaint, default 28: Square smoothing window (pixels) for along-ship angle.
wphiint, default 52: Square smoothing window (pixels) for athwart-ship angle.

Returns:

xr.DataArray: 1-D bottom depth per ping_time (no channel dimension). The output name and attributes are set by the called method.

Raises:

ValueError: If method is not supported.

Examples

>>> detect_seafloor(ds, "basic", {
...     "var_name": "Sv", "channel": "GPT  38 kHz ...",
...     "threshold": -50, "offset_m": 0.5, "bin_skip_from_surface": 200
... })

>>> detect_seafloor(ds, "blackwell", {
...     "channel": "GPT  38 kHz ...", "threshold": (-75, 0.02, 0.02),
...     "offset": 0.3, "r0": 0, "r1": 600, "wtheta": 28, "wphi": 52
... })

detect_seafloor

Contents

detect_seafloor#