README.md

---
title: Aegis-River-Segmentation
colorFrom: blue
colorTo: green
sdk: gradio
sdk_version: 5.23.3
app_file: app.py
pinned: false
license: cc-by-nc-nd-4.0
---

# Aegis-River-Segmentation

Water body segmentation from river/waterway images using SegFormer-B2. This
Space loads the trained checkpoint from
[`beaunix/river-segmentation`](https://huggingface.co/beaunix/river-segmentation)
and runs it on ZeroGPU.

## How it works

1. The underlying model was trained as a 7-class semantic segmentation model
   (background, water, sky, vegetation, building, vehicle, person) on a
   combined RIWA + Parepare flood dataset.
2. In practice, only the **water** class is reliable; the other 6 classes
   are not used. This Space collapses the output to a binary mask:
   water vs. everything else (rendered as black).
3. The uploaded image is processed by `SegformerImageProcessor` (resize to
   512x512, ImageNet-style normalization), run through the model, and the
   logits are upsampled back to the original image resolution before
   thresholding.
4. The report shows the original image, the binary water mask, an overlay,
   and the water coverage ratio.

## Important: dependency pinning

This Space requires **`transformers==4.45.2`** specifically. A later
`transformers` release renamed an internal SegFormer decode_head submodule
(`decode_head.linear_projections` -> `decode_head.linear_c`), which silently
breaks the correspondence between this checkpoint's saved keys and the
model architecture on a mismatched version. Do not upgrade `transformers`.

## Notes

- Input is a single image (drag and drop), not a video.
- The 7-class architecture is preserved internally (required to load the
  checkpoint correctly), but only the water class is surfaced to the user.

## License

CC BY-NC-ND 4.0 (Attribution - NonCommercial - NoDerivatives).
See https://creativecommons.org/licenses/by-nc-nd/4.0/