ASAMPS + Phenology Composite — Watershed + SAM2 Box Refinement

A notebook pipeline for delineating smallholder agricultural field boundaries from multi-temporal NDVI imagery, combining a deterministic watershed segmentation with SAM2 box-prompt refinement.

Pipeline

1. Merge monthly NDVI tiles (e.g. exported from SEPAL)
2. Reproject to UTM
3. Build a phenological RGB composite (tri-temporal or PCA)
4. Compute the Planted Index (PIE) from a Sobel gradient + ISODATA homogeneity index
5. Run watershed segmentation on the PIE gradient for fast, deterministic field delineation
6. Refine watershed boundaries with SAM2 box prompts
7. Export results as GeoPackage and KMZ

Requirements

• Python 3.11
• A CUDA GPU is recommended for the SAM2 refinement step (Step 7–8) but the notebook will fall back to CPU
• Jupyter (e.g. JupyterLab, VS Code, or a SEPAL m2+ instance)

Install dependencies:

pip install segment-geospatial[samgeo2] rasterio geopandas \
            scikit-image scikit-learn scipy psutil pyproj

Input data

The pipeline expects a directory of monthly NDVI GeoTIFFs (one band per file or one multi-band stack), e.g.:

data/ndvi_tiles/
├── tile_jan.tif
├── tile_feb.tif
└── ...

Set NDVI_TILE_DIR in the Step 1 configuration cell to point at your data. If your NDVI is already scaled to [-1, 1], set SCALE_FACTOR = 1.0; if it's stored as scaled integers (e.g. ×10000, the common SEPAL/Sentinel-2 convention), leave the default.

Usage

1. Open ASAMPS_phenology_watershed_refined.ipynb
2. Edit the Step 1 — Configuration cell: set NDVI_TILE_DIR, RES_M (pixel resolution in metres), and OUTPUT_DIR
3. Run all cells in order
4. Outputs are written to OUTPUT_DIR:
   • planted_fields_refined.gpkg — full-resolution field boundaries
   • planted_fields_refined_simplified.gpkg — simplified geometry
   • planted_fields_refined.kmz — for viewing in Google Earth

Multi-date / multi-temporal runs (optional)

Run Steps 1–11 once per acquisition date (saving each date's GeoPackage under a distinct name), then use the edge_overlapping() function in Step 12 to merge per-date results into a single minimum-planted-field layer for the growing season.

Key configuration parameters

Parameter	Description
RES_M	Pixel resolution in metres; used to derive min/max field size in pixels
COMPOSITE_MODE	'tri_temporal' (early/peak/late NDVI as RGB) or 'pca' (PCA of selected months)
MIN_FIELD_HA / MAX_FIELD_HA	Plausible field size range (hectares), used to filter watershed regions
PIE_CONFIG	Controls the Planted Index: gradient/homogeneity weighting, cluster count, threshold
BOX_PAD_PX	Padding added around each watershed bounding box before passing to SAM2
MIN_IOU_KEEP / MAX_SIZE_RATIO	Safeguards that fall back to the watershed mask if SAM2's refinement diverges too much
DILATION_CLIP	Hard-clips SAM2 output to a dilation of the watershed mask, preventing boundary bleed into neighbouring fields

See the Notes section at the end of the notebook for tuning guidance.

How it works

• PIE (Planted Index) combines a Sobel edge-gradient with a homogeneity index derived from ISODATA-style clustering (MiniBatchKMeans) of the phenology composite, producing a signal where field interiors are distinct from boundaries.
• Watershed segmentation treats the Sobel gradient as elevation and PIE-thresholded regions as seeds, giving fast and deterministic field counts and locations without a deep model.
• SAM2 box refinement takes each watershed region's bounding box (with padding) and the watershed mask as a logit prior, then refines the boundary with SAM2. If the refined mask's IoU with the watershed mask is too low, or its area changes too much, the pipeline falls back to the original watershed boundary — so SAM2 can only improve boundaries, not silently fail.

Reference

Liu et al. (2026). An adaptive SAM2 for planted field segmentation. International Journal of Digital Earth, 19(1). https://doi.org/10.1080/17538947.2026.2645885

Author

Developed by Erik Lindquist, 2026.

Disclaimer

This notebook and associated code are provided "AS IS", without warranty of any kind, express or implied. The authors make no guarantees regarding the accuracy, completeness, or fitness for a particular purpose of the outputs produced by this pipeline. Users should independently validate results before relying on them for operational or decision-making purposes.

License

Add a license of your choice (e.g. MIT, Apache 2.0) before publishing.