# 🌊 Bathymetrix-AI V5.0: Complete User Manual & Outputs Guide

Welcome to the definitive guide for **Bathymetrix-AI V5.0**. This document serves as an all-in-one, easy-to-read reference for understanding the terminology, the exact outputs generated by each phase, and the editable parameters available in the user interface.

---

## 📖 1. Abbreviations & Terminology

*   **SDB (Satellite-Derived Bathymetry):** The science of calculating water depth using the color (spectral reflectance) of the seabed captured by satellite sensors.
*   **OSW (Optically Shallow Water):** The coastal zone where sunlight successfully hits the sea bottom and bounces back to the satellite. Bathymetry is **only** valid here.
*   **ROI (Region of Interest):** A custom polygon you provide to tell the algorithm: *"Sample the pixels inside this shape to calibrate your thresholds."*
*   **NIR (Near-Infrared):** A band of light (e.g., Band 8 in Sentinel-2) that water absorbs heavily. It's used to detect the edge of water, land, and deep ocean.
*   **NDWI (Normalized Difference Water Index):** A mathematical formula used to easily distinguish water from dry land.
*   **Residuals (Prediction Error):** The exact difference (in meters) between what the ML model guessed and the true depth measured by the ICESat-2 laser.

---

## 📁 2. Pipeline Outputs by Phase

All outputs are saved to your designated `Main Output Folder`. Phase 01 files are numbered sequentially (`01_` to `07_`) so you can trace the exact steps the algorithm took to clean your imagery.

### 🛠️ Phase 01: Preprocessing & Feature Engineering
*   **`01_Land_Water_Mask.tif`** (Binary Raster: 0/1)
    *   **What it is:** The exact boundaries of water. `1` = Water, `0` = Land/Clouds.
    *   **Why it matters:** Acts as a cookie-cutter to ensure processing is only done on water, saving time and memory.
*   **`02_Sunglint_Corrected.tif`** (Float32 Raster)
    *   **What it is:** Your original image, but wave-induced sun reflections have been mathematically subtracted.
    *   **Why it matters:** Removes surface glare to reveal the true seabed color underneath.
*   **`03_Feature_Stack.tif`** (Float32 Raster)
    *   **What it is:** The ML dataset containing mathematically calculated "Log-Ratios" (e.g., Blue/Green).
    *   **Why it matters:** Linearizes light decay in water. The ML model learns depth exclusively from this file.
*   **`04_DeepWater_Threshold_Stats.csv`** (Spreadsheet)
    *   **What it is:** The mathematical limits showing the exact Mean and Standard Deviation calculated by the algorithm.
    *   **Why it matters:** Separates Shallow from Deep water thresholds dynamically.
*   **`05_ShallowWater_Pixel_Mask.tif`** (Binary Raster: 0/1)
    *   **What it is:** The raw filter result of pixels that passed the Deep Water thresholding (`1`=Shallow, `0`=Deep).
    *   **Why it matters:** Shows the raw statistical cutoffs before any spatial smoothing is applied (often looks noisy).
*   **`06_Final_OSW_Mask.tif`** (Binary Raster: 0/1)
    *   **What it is:** The clean footprint of the Optically Shallow Water mask.
    *   **Why it matters:** It is polished by removing speckle noise and filling internal gaps, representing the true valid zone.
*   **`07_OSW_Boundary_Polygon.gpkg`** (Vector Polygon)
    *   **What it is:** The final clipper outlining the OSW mask.
    *   **Why it matters:** Automatically clips the final ML depth maps so they don't predict fake depths in the deep ocean.

### 🧹 Phase 02: Robust Altimetry Filtering
*   **`Filtered_ICESat2_Data.shp`** (Vector Points)
    *   **What it is:** The ground truth data containing clean ICESat-2 depths.
    *   **Why it matters:** The RANSAC algorithm aggressively deletes noise (waves, birds, etc.), ensuring the ML model only trains on perfect data.

### 🤖 Phase 03: Global Auto-ML Modeling
*   **`Phase3_Depth_Map.tif`** (Float32 Raster)
    *   **What it is:** The Base SDB Map generated by the winning ML algorithm.
    *   **Why it matters:** Provides the continuous bathymetric map, automatically clipped to the OSW boundary.

### 🎯 Phase 04: Spatial Residual Stacking
*   **`Error_Surface.tif`** (Float32 Raster)
    *   **What it is:** The Error Map showing exactly where Phase 03 was wrong and by how much.
    *   **Why it matters:** Uses K-NN to interpolate errors across the entire area to catch geographic biases.
*   **`Phase4_Refined_Depth_Map.tif`** (Float32 Raster)
    *   **What it is:** The Final SDB Map.
    *   **Why it matters:** The ultimate, highest-accuracy map where the Error Surface has been mathematically applied to fix local biases.

### 📉 Phase 05: Scientific Validation
*(Generated if validation is enabled, testing maps against unseen ICESat-2 data)*
*   **`5_FINAL_SUMMARY.txt`** (Text Report)
    *   **What it is:** The final verdict comparing Phase 03 and Phase 04 accuracy (RMSE, R2, MAE).
*   **`5_Stratified_Error_Analysis.csv`** (Spreadsheet)
    *   **What it is:** A breakdown showing accuracy for specific depth bins (e.g., 0-5m vs 15-20m).
*   **`5_Validation_Raw_Data.csv`** (Spreadsheet)
    *   **What it is:** A raw data dump of every validation point with observed depth vs predicted.
*   **`5_Plot_Scatter_Comparison.png`** (Image)
    *   **What it is:** A 1:1 Scatter Plot visualizing how tightly predictions group around the perfect correlation line.
*   **`5_Plot_Residuals.png`** (Image)
    *   **What it is:** A Residuals Plot showing errors plotted against depth to identify systematic bias.
*   **`5_Plot_Error_Histogram.png`** (Image)
    *   **What it is:** A Density Curve showing the distribution of error; centered on 0 means an unbiased model.

---

## 🎛️ 3. User Interface (UI) Parameters & Defaults

This section explains every editable parameter in the plugin so you can tune it perfectly for your region.

### ⚙️ [0] General Settings
*   **Processing Threads** `[Default: 4]`
    *   **What it does:** Dictates how many CPU cores to use. Higher numbers mean faster processing.

### 📡 [1] Phase 1: Pre-processing & Feature Engineering
*   **Coastal/Blue/Green/Red/NIR Bands** `[Defaults: 1, 2, 3, 4, 8]`
    *   **What it does:** Maps the specific band numbers of your input image (defaults match Sentinel-2).
*   **Apply Sunglint Correction** `[Default: True]`
    *   **What it does:** Removes surface reflections (wave glare) using Hedley's algorithm.
*   **Sunglint Deep Water %** `[Default: 1.0]`
    *   **What it does:** Uses the darkest 1% of pixels as the baseline to subtract glint.
*   **Enable Automated Masking** `[Default: False]`
    *   **What it does:** Turns on the automated water masking algorithm. Includes the **new Advanced Water Mask** using 3-Indices (NDWI, MNDWI, NWI) to accurately find water boundaries.
*   **Apply Deep Water Filter** `[Default: True]`
    *   **What it does:** Turns on the **Deep Water Filter** (fully customized for ML algorithms) to mathematically separate shallow from deep water and build the OSW mask.
*   **NIR Percentile for Deep Water** `[Default: 10.0]`
    *   **What it does:** Uses the darkest 10% of NIR pixels to calculate the statistical deep water thresholds.
*   **OSW Mask Median Filter Size** `[Default: 3]`
    *   **What it does:** Sets the size of the smoothing brush used to clean speckles from the OSW mask.

### 📏 [2] Phase 2: Training Data & Filtering
*   **Maximum Depth Threshold** `[Default: -30.0]`
    *   **What it does:** Deletes ICESat-2 points deeper than 30m, as optical SDB rarely penetrates deeper than this.
*   **Enable Data Filtering** `[Default: True]`
    *   **What it does:** Turns on the noise-removal algorithm (RANSAC/Variance Fit) for the point cloud.
*   **Filtering Strategy** `[Default: 2 - LS Variance]`
    *   **What it does:** Selects the mathematical approach used to find the true seabed points.
*   **Threshold / Sigma Multiplier** `[Default: 3.0]`
    *   **What it does:** Controls how aggressive the filter is. A higher number keeps more points but allows more noise.
*   **RANSAC Trials** `[Default: 100]`
    *   **What it does:** Sets the number of iterations the algorithm uses to find the best line of fit.

### 🤖 [3] Phase 3: Global Modeling (Auto-ML)
*   **Algorithms to Benchmark** `[Default: All]`
    *   **What it does:** Chooses which AI models to pit against each other (Random Forest, SVR, Extra Trees, etc.).
*   **Optimization Iterations** `[Default: 10]`
    *   **What it does:** Determines how many times the AI tries different internal hyperparameters to get the best score.
*   **Output Median Filter Size** `[Default: 5]`
    *   **What it does:** Applies a final spatial smoothing kernel to the output depth map to remove "salt and pepper" pixel noise.

### 🎯 [4] Phase 4: Adaptive Refinement
*   **Enable Adaptive Refinement** `[Default: True]`
    *   **What it does:** Turns on the K-NN spatial error correction to fix local geographic biases (e.g., dark seagrass mimicking deep water).

### 📉 [5] Phase 5: Validation & Cleanup
*   **Enable Validation** `[Default: True]`
    *   **What it does:** Triggers the creation of the Phase 05 reports, statistics, and graphs.
*   **Remove Positive Depths** `[Default: True]`
    *   **What it does:** Cleans the final map by deleting any fake elevations (like boats or piers) above 0m sea level.
*   **Apply Slope Filter** `[Default: True]`
    *   **What it does:** Deletes physically impossible sharp spikes or drops in the seabed caused by model glitches.
*   **Slope Filter Threshold** `[Default: 35.0]`
    *   **What it does:** Sets the maximum allowable slope (in degrees). Anything steeper is deleted.
