Skip to content

Bathymetry Models

sensingpy.bathymetry.models provides satellite-derived bathymetry (SDB) estimation functions and the LinearModel class for fitting depth models.

stumpf_pseudomodel

stumpf_pseudomodel 

stumpf_pseudomodel(blue: ndarray, other: ndarray, n: float = np.pi * 1000) -> np.ndarray

Calculate Stumpf pseudomodel for satellite-derived bathymetry.

This function implements the ratio transform algorithm developed by Stumpf et al. (2003) for estimating water depth from multispectral imagery. The algorithm uses the ratio of logarithms of reflectance in blue and another band.

Parameters:

Name Type Description Default
blue ndarray

Blue band data to use as base reflectance

 required
other ndarray

Band such as green or red to compare with blue

 required
n float

Constant to prevent negative values in logarithm calculation, by default np.pi*1_000

 pi * 1000

Returns:

Type Description
ndarray

Pseudomodel values representing linearized depth estimates
Notes

The algorithm leverages the differential attenuation of light with depth between blue and other wavelengths.

References

Stumpf, R.P., Holderied, K., Sinclair, M. (2003). Determination of water depth with high-resolution satellite imagery over variable bottom types. Limnology and Oceanography, 48(1), 547-556. https://doi.org/10.4319/lo.2003.48.1_part_2.0547

Source code in sensingpy/bathymetry/models.py 
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
def stumpf_pseudomodel(
    blue: np.ndarray, other: np.ndarray, n: float = np.pi * 1_000
) -> np.ndarray:
    """
    Calculate Stumpf pseudomodel for satellite-derived bathymetry.

    This function implements the ratio transform algorithm developed by Stumpf et al. (2003)
    for estimating water depth from multispectral imagery. The algorithm uses the ratio
    of logarithms of reflectance in blue and another band.

    Parameters
    ----------
    blue : np.ndarray
        Blue band data to use as base reflectance
    other : np.ndarray
        Band such as green or red to compare with blue
    n : float, optional
        Constant to prevent negative values in logarithm calculation,
        by default np.pi*1_000

    Returns
    -------
    np.ndarray
        Pseudomodel values representing linearized depth estimates

    Notes
    -----
    The algorithm leverages the differential attenuation of light with depth
    between blue and other wavelengths.

    References
    ----------
    Stumpf, R.P., Holderied, K., Sinclair, M. (2003). Determination of water depth
    with high-resolution satellite imagery over variable bottom types.
    Limnology and Oceanography, 48(1), 547-556.
    https://doi.org/10.4319/lo.2003.48.1_part_2.0547
    """

    return np.log(blue * n) / np.log(other * n)

multi_image_pseudomodel

multi_image_pseudomodel 

multi_image_pseudomodel(p_greens: ndarray, p_reds: ndarray) -> np.ndarray

Apply multi-image composition method for improved bathymetry estimates.

This function implements the multi-image compositing method developed by Caballero & Stumpf (2020) for optimizing satellite-derived bathymetry from multiple scenes. It creates composite bathymetry models by selecting the maximum values from multiple pseudomodels.

Parameters:

Name Type Description Default
p_greens ndarray

List of green-band pseudomodels to compose

 required
p_reds ndarray

List of red-band pseudomodels to compose

 required

Returns:

Type Description
tuple

Tuple containing: - np.ndarray: Maximum green pseudomodel values - np.ndarray: Maximum red pseudomodel values - np.ndarray: Index array identifying which image was selected at each pixel
Notes

The multi-image approach helps overcome limitations from individual images such as sun glint, clouds, or varying water quality conditions.

References

Caballero, I., & Stumpf, R. P. (2020). Towards routine mapping of shallow bathymetry in environments with variable turbidity: Contribution of Sentinel-2A/B satellites mission. Remote Sensing, 12(3), 451. https://doi.org/10.3390/rs12030451

Source code in sensingpy/bathymetry/models.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
def multi_image_pseudomodel(p_greens: np.ndarray, p_reds: np.ndarray) -> np.ndarray:
    """
    Apply multi-image composition method for improved bathymetry estimates.

    This function implements the multi-image compositing method developed by
    Caballero & Stumpf (2020) for optimizing satellite-derived bathymetry from
    multiple scenes. It creates composite bathymetry models by selecting the
    maximum values from multiple pseudomodels.

    Parameters
    ----------
    p_greens : np.ndarray
        List of green-band pseudomodels to compose
    p_reds : np.ndarray
        List of red-band pseudomodels to compose

    Returns
    -------
    tuple
        Tuple containing:
        - np.ndarray: Maximum green pseudomodel values
        - np.ndarray: Maximum red pseudomodel values
        - np.ndarray: Index array identifying which image was selected at each pixel

    Notes
    -----
    The multi-image approach helps overcome limitations from individual images
    such as sun glint, clouds, or varying water quality conditions.

    References
    ----------
    Caballero, I., & Stumpf, R. P. (2020). Towards routine mapping of shallow
    bathymetry in environments with variable turbidity: Contribution of
    Sentinel-2A/B satellites mission. Remote Sensing, 12(3), 451.
    https://doi.org/10.3390/rs12030451
    """

    return (
        np.nanmax(p_greens, axis=0),
        np.nanmax(p_reds, axis=0),
        composite_indices(p_greens, np.nanargmax),
    )

switching_model

switching_model 

switching_model(green_model: ndarray, red_model: ndarray, green_coef: float = 3.5, red_coef: float = 2) -> np.ndarray

Create a depth model by combining green and red models using a weighted approach.

This function implements the linear weighted model presented by Caballero & Stumpf (2020) that combines green and red models based on depth thresholds. It uses only the red model for shallow areas, only the green model for deeper areas, and a weighted combination for intermediate depths.

Parameters:

Name Type Description Default
green_model ndarray

Green band-based bathymetry model, generally better for deeper waters

 required
red_model ndarray

Red band-based bathymetry model, generally better for shallow waters

 required
green_coef float

Minimum threshold value where the green model starts to be used exclusively, by default 3.5

 3.5
red_coef float

Maximum threshold value where the red model is used exclusively, by default 2

 2

Returns:

Type Description
ndarray

Combined bathymetry model with optimized depth estimates
Notes

The switching approach leverages the strengths of different spectral bands: red bands perform better in shallow waters while green bands perform better in deeper waters. This method provides a smooth transition between the models.

References

Caballero, I., & Stumpf, R. P. (2020). Towards routine mapping of shallow bathymetry in environments with variable turbidity: Contribution of Sentinel-2A/B satellites mission. Remote Sensing, 12(3), 451. https://doi.org/10.3390/rs12030451

Source code in sensingpy/bathymetry/models.py 
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
def switching_model(
    green_model: np.ndarray,
    red_model: np.ndarray,
    green_coef: float = 3.5,
    red_coef: float = 2,
) -> np.ndarray:
    """
    Create a depth model by combining green and red models using a weighted approach.

    This function implements the linear weighted model presented by Caballero & Stumpf (2020)
    that combines green and red models based on depth thresholds. It uses only the red model
    for shallow areas, only the green model for deeper areas, and a weighted combination
    for intermediate depths.

    Parameters
    ----------
    green_model : np.ndarray
        Green band-based bathymetry model, generally better for deeper waters
    red_model : np.ndarray
        Red band-based bathymetry model, generally better for shallow waters
    green_coef : float, optional
        Minimum threshold value where the green model starts to be used exclusively,
        by default 3.5
    red_coef : float, optional
        Maximum threshold value where the red model is used exclusively,
        by default 2

    Returns
    -------
    np.ndarray
        Combined bathymetry model with optimized depth estimates

    Notes
    -----
    The switching approach leverages the strengths of different spectral bands:
    red bands perform better in shallow waters while green bands perform better
    in deeper waters. This method provides a smooth transition between the models.

    References
    ----------
    Caballero, I., & Stumpf, R. P. (2020). Towards routine mapping of shallow
    bathymetry in environments with variable turbidity: Contribution of
    Sentinel-2A/B satellites mission. Remote Sensing, 12(3), 451.
    https://doi.org/10.3390/rs12030451
    """

    a = (green_coef - red_model) / (green_coef - red_coef)
    b = 1 - a
    switching_model = a * red_model + b * green_model

    model = np.zeros(red_model.shape)
    model[:] = np.nan

    model = np.where(red_model < red_coef, red_model, model)
    model = np.where(
        (red_model > red_coef) & (green_model > green_coef), green_model, model
    )
    model = np.where(
        (red_model >= red_coef) & (green_model <= green_coef), switching_model, model
    )
    model[model < 0] = np.nan

    return model

optical_deep_water_model

optical_deep_water_model 

optical_deep_water_model(model: ndarray, blue: ndarray, green: ndarray, vnir: ndarray) -> np.ndarray

Filter depth estimations based on optical properties of water.

This function applies optical water property-based filters to depth estimation models to improve accuracy. It filters out pixels based on reflectance thresholds for clear waters and an upper depth limit equation for turbid waters as described in peer-reviewed literature.

Parameters:

Name Type Description Default
model ndarray

The initial depth estimation model output to be filtered

 required
blue ndarray

Blue band reflectance values, used for clear water filtering

 required
green ndarray

Green band reflectance values, used for clear water filtering

 required
vnir ndarray

Near-infrared band reflectance values, used for turbid water depth limit calculation

 required

Returns:

Type Description
ndarray

Filtered depth model with invalid estimations set to NaN
Notes

The function applies two filtering steps: 1. Clear water filtering: removes pixels with reflectance <= 0.003 in blue or green bands 2. Turbid water filtering: applies depth limitation based on NIR reflectance using the equation: Ymax = -0.251 * ln(NIR) + 0.8

References

Caballero I, Stumpf RP. Towards Routine Mapping of Shallow Bathymetry in Environments with Variable Turbidity: Contribution of Sentinel-2A/B Satellites Mission. Remote Sensing. 2020; 12(3):451. https://doi.org/10.3390/rs12030451

Source code in sensingpy/bathymetry/models.py 
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
def optical_deep_water_model(
    model: np.ndarray, blue: np.ndarray, green: np.ndarray, vnir: np.ndarray
) -> np.ndarray:
    """
    Filter depth estimations based on optical properties of water.

    This function applies optical water property-based filters to depth estimation
    models to improve accuracy. It filters out pixels based on reflectance thresholds
    for clear waters and an upper depth limit equation for turbid waters as described
    in peer-reviewed literature.

    Parameters
    ----------
    model : np.ndarray
        The initial depth estimation model output to be filtered
    blue : np.ndarray
        Blue band reflectance values, used for clear water filtering
    green : np.ndarray
        Green band reflectance values, used for clear water filtering
    vnir : np.ndarray
        Near-infrared band reflectance values, used for turbid water depth limit calculation

    Returns
    -------
    np.ndarray
        Filtered depth model with invalid estimations set to NaN

    Notes
    -----
    The function applies two filtering steps:
    1. Clear water filtering: removes pixels with reflectance <= 0.003 in blue or green bands
    2. Turbid water filtering: applies depth limitation based on NIR reflectance using the equation:
       Ymax = -0.251 * ln(NIR) + 0.8

    References
    ----------
    Caballero I, Stumpf RP. Towards Routine Mapping of Shallow Bathymetry in Environments with Variable Turbidity: 
    Contribution of Sentinel-2A/B Satellites Mission. Remote Sensing. 2020; 12(3):451. 
    https://doi.org/10.3390/rs12030451 
    """

    ## Clear waters
    model[blue <= 0.003] = np.nan
    model[green <= 0.003] = np.nan

    ## Turbid waters
    Ymax = (-0.251 * np.log(vnir)) + 0.8
    Ymax[Ymax < 0] = np.nan

    y = np.log(model)
    y[y < 0] = np.nan

    # Remove values exceeding depth limit from 2019 paper
    model[y > Ymax] = np.nan

    return model

LinearModel

LinearModel

Bases: object

Linear regression model for satellite-derived bathymetry.

This class implements a simple linear regression approach for converting bathymetric pseudomodels to actual depth values. It provides methods for fitting the model to known depth measurements and predicting depths from new pseudomodel values.

Attributes:

Name Type Description
slope float

Slope coefficient of the linear model
intercept float

Y-intercept of the linear model
r_square float

Coefficient of determination (R²) indicating goodness of fit
Notes

Linear models are commonly used in satellite-derived bathymetry to establish the relationship between optical properties and actual water depths. This implementation uses scipy's linregress for the underlying calculations.

Functions

fit 
fit(pseudomodel: ndarray, in_situ: ndarray) -> Self

Fit linear regression model using pseudomodel and in-situ depth data.

Parameters:

Name Type Description Default
pseudomodel ndarray

Predictor values (typically from ratio transform algorithms)

 required
in_situ ndarray

Target values (measured water depths)

 required

Returns:

Type Description
Self

Returns the instance for method chaining
Notes

This method calculates the linear relationship between pseudomodel values and actual water depths using ordinary least squares regression.

Source code in sensingpy/bathymetry/models.py 
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
def fit(self, pseudomodel: np.ndarray, in_situ: np.ndarray) -> Self:
    """
    Fit linear regression model using pseudomodel and in-situ depth data.

    Parameters
    ----------
    pseudomodel : np.ndarray
        Predictor values (typically from ratio transform algorithms)
    in_situ : np.ndarray
        Target values (measured water depths)

    Returns
    -------
    Self
        Returns the instance for method chaining

    Notes
    -----
    This method calculates the linear relationship between pseudomodel values
    and actual water depths using ordinary least squares regression.
    """

    self._set_linear_regression(pseudomodel, in_situ)
    return self
predict 
predict(pseudomodel: ndarray) -> np.ndarray

Predict depths using the fitted linear model.

Parameters:

Name Type Description Default
pseudomodel ndarray

Predictor values to convert to depth estimates

 required

Returns:

Type Description
ndarray

Predicted depth values
Notes

Applies the linear transformation using stored slope and intercept values.

Source code in sensingpy/bathymetry/models.py 
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
def predict(self, pseudomodel: np.ndarray) -> np.ndarray:
    """
    Predict depths using the fitted linear model.

    Parameters
    ----------
    pseudomodel : np.ndarray
        Predictor values to convert to depth estimates

    Returns
    -------
    np.ndarray
        Predicted depth values

    Notes
    -----
    Applies the linear transformation using stored slope and intercept values.
    """

    return self.slope * pseudomodel + self.intercept
predict_and_evaluate 
predict_and_evaluate(pseudomodel: ndarray, in_situ: ndarray) -> ValidationSummary

Predict depths and evaluate model performance against in-situ measurements.

Parameters:

Name Type Description Default
pseudomodel ndarray

Predictor values to convert to depth estimates

 required
in_situ ndarray

Reference depth values for validation

 required

Returns:

Type Description
ValidationSummary

Object containing various error metrics and validation statistics
Notes

This convenience method combines prediction and validation in a single step.

Source code in sensingpy/bathymetry/models.py 
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
def predict_and_evaluate(
    self, pseudomodel: np.ndarray, in_situ: np.ndarray
) -> ValidationSummary:
    """
    Predict depths and evaluate model performance against in-situ measurements.

    Parameters
    ----------
    pseudomodel : np.ndarray
        Predictor values to convert to depth estimates
    in_situ : np.ndarray
        Reference depth values for validation

    Returns
    -------
    ValidationSummary
        Object containing various error metrics and validation statistics

    Notes
    -----
    This convenience method combines prediction and validation in a single step.
    """

    return ValidationSummary(self.predict(pseudomodel), in_situ)