sidescanpy.core.units#

Single source for linear <-> dB conversion and the floor-clip artifact.

Convention: every conversion in sidescanpy is amplitude (20*log10), because raw backscatter_intensity is linear amplitude. There is no power (10*log10) conversion anywhere in the library.

Linear values below MIN_LINEAR are clipped before the log so exact zeros (blanking / ring-down) map to FLOOR_DB instead of -inf. That deterministic floor is an artifact, not a real return; mask_floor_clip() / mask_floor_db() turn it into NaN.

2026 rshomberg@uri.edu

Contents

`MIN_LINEAR`	Smallest linear amplitude kept before taking the log.
`FLOOR_DB`	`20*log10(MIN_LINEAR)`: the dB value exact-zero amplitude converts to.
`FLOOR_CLIP_VALUES`	Deterministic floor-clip artifact values: exact-zero linear amplitude (pre-dB) and the dB floor (post-dB).
`linear_to_db`	Convert linear amplitude to dB: `20*log10(clip(x, min_linear))`.
`db_to_linear`	Convert dB to linear amplitude: `10**(db/20)`.
`mask_floor_clip`	Replace the exact floor-clip artifact values (0.0 and -120 dB) with NaN.
`mask_floor_db`	Replace dB values at or below `FLOOR_DB` with NaN.

sidescanpy.core.units.MIN_LINEAR = 1e-06#: Smallest linear amplitude kept before taking the log.

sidescanpy.core.units.FLOOR_DB = -120.0#: 20*log10(MIN_LINEAR): the dB value exact-zero amplitude converts to.

sidescanpy.core.units.FLOOR_CLIP_VALUES = (0.0, -120.0)#: Deterministic floor-clip artifact values: exact-zero linear amplitude (pre-dB) and the dB floor (post-dB).

sidescanpy.core.units.linear_to_db(x, floor_db=-120.0)#

Convert linear amplitude to dB: 20*log10(clip(x, min_linear)).

min_linear is the linear value of floor_db (1e-6 for the default -120 dB). Accepts scalars, numpy arrays and xr.DataArray; dtype and NaN are preserved (NaN stays NaN).

sidescanpy.core.units.db_to_linear(db)#: Convert dB to linear amplitude: 10**(db/20).

sidescanpy.core.units.mask_floor_clip(values)#: Replace the exact floor-clip artifact values (0.0 and -120 dB) with NaN.

sidescanpy.core.units.mask_floor_db(db)#: Replace dB values at or below FLOOR_DB with NaN.