SWAMpy

SWAMpy is a GUI-driven shallow-water inversion workflow for retrieving bathymetry, water-column properties, and benthic cover from aquatic reflectance imagery stored in NetCDF or compatible HDF format.

Swampy builds on SAMBUCA, a semi-analytical inversion model designed for the joint retrieval of bathymetry, benthic composition, and water column constituents from remote sensing reflectance data Bando et al. 2009.

🌊 What The Workflow Does

For each pixel, SWAMpy fits a forward optical model to the observed reflectance and estimates:

• bathymetry / depth
• chlorophyll concentration
• CDOM concentration
• NAP concentration
• benthic target fractions from the selected spectral library

Depending on the options enabled, the workflow can also export modeled reflectance, spectral post-processing products, and debug layers used to understand difficult areas.

📁 Project Layout

The main folders in this repository are:

• app/: main code, GUI, launcher, inversion core, tests
• Data/SRF/: bundled sensor templates
• Data/spectral_library/: Spectral library that can be used to create the xml asked by the UI
• Data/Test/: sample NetCDF/HDF scenes and validation data
• docs/: bundled papers and project references

Keep this folder structure unchanged. The GUI expects these relative paths.

🧰 Installation and updates

The recommended setup uses Git plus Conda and the provided environment file.

If you want to do the full installation from the command line:

git clone https://gittide.oirysimon.com/oiry-s/Swampy_lite.git
cd Swampy_lite
conda env create -f environment.yml
conda activate SwampySim

If the repository is already on your machine, you can start directly from the environment setup:

conda env create -f environment.yml
conda activate SwampySim

The app have an auto-updater. When python launch_swampy.py is executed, the app look if the local version match the onmy version of this repository. If not a popup ask the user if he wants to update the app. This feature might need git and conda to global variable of the system (PATH).

If updater doesn't work for you or if the environment already exists and you want to refresh it:

conda env update -f environment.yml --prune
conda activate SwampySim

▶️ How To Launch The App

From the repository root:

python launch_swampy.py

This opens the graphical interface.

You can also rerun a saved configuration directly from a log XML:

python launch_swampy.py -f path\\to\\log_file.xml

Useful optional command-line overrides:

• --format netcdf|geotiff|both
• --nedr-mode scene|fixed
• -c 1 This keeps one CPU free for the OS. Increase it if you want SWAMpy to use fewer workers.

🛰️ Input Expectations

The main workflow expects an input image readable through the NetCDF/HDF reader. In practice:

• the file should contain latitude and longitude variables
• the reflectance bands should be stored as spectral layers that SWAMpy can identify and align to the selected sensor
• Acolite L2W-style Rrs_* variables and Polymer-style Rw### variables are detected automatically
• if the reflectance is above-water remote-sensing reflectance (Rrs), enable the Above RRS option

Bundled examples are available in Data/Test/.

✨ Main Features

🖥️ GUI-Driven Configuration

The interface exposes the main workflow settings through popups rather than raw XML editing:

• water and bottom settings
• sensor configuration

⚙️ Relaxed Substrate Modes

The workflow supports:

• strict substrate constraints
• relaxed substrate constraints

📦 Output Products

Depending on the selected options, SWAMpy can export:

• NetCDF
• GeoTIFF
• both formats at once
• optional post-processing spectral outputs

🧩 Large Scene Handling

Image splitting by row chunks is available for scenes that are too large to process comfortably in one pass.

🧪 Sample Data And Validation

The repository includes sample scenes and validation resources in Data/Test/.

There is also a validation helper script:

python app/validate_swampy_cover.py --help

This script compares SWAMpy substrate outputs against point-based ground truth.

📚 Scientific Background

If you want the scientific context behind the workflow, the main references bundled in docs are:

• Lee et al. (2001) - Properties of the water column and bottom derived from Airborne.pdf
• Brando et al. - 1-s2.0-S003442570800360X-main.pdf
• Lee et al. - AO.38.003831.pdf
• Dekker et al. - s11001-005-0266-y.pdf

📝 Notes

• The GUI prevents running when mandatory fields are missing.
• The launcher, GUI, and data layout have been updated from the older project structure, so the current entry point is Swampy_paralell/launch_swampy.py.
• If you share the repository, include the Data/ folder because it contains the spectral library, sensor templates, bundled bathymetry, and sample data required by the app.