MambaFCS

<div align="center"> <h1>🚀 Mamba-FCS</h1> <h2>Joint Spatio-Frequency Feature Fusion with Change-Guided Attention and SeK Loss</h2> <h2>🏆 Current Best-Performing Algorithm for Semantic Change Detection 🏆</h2> <p> <a href="https://ieeexplore.ieee.org/document/11391528"> <img src="https://img.shields.io/badge/IEEE%20JSTARS-Official%20Publication-00629B.svg" alt="IEEE JSTARS Paper"> </a> <a href="https://arxiv.org/abs/2508.08232"> <img src="https://img.shields.io/badge/arXiv-2508.08232-b31b1b.svg" alt="arXiv"> </a> <a href="https://huggingface.co/buddhi19/MambaFCS/tree/main"> <img src="https://img.shields.io/badge/Hugging%20Face-Weights%20Available-FFD21E.svg" alt="Weights"> </a> <a href="LICENSE"> <img src="https://img.shields.io/badge/License-MIT-green.svg" alt="License"> </a> </p> <p> Official implementation for the paper https://huggingface.co/papers/2508.08232. Visual State Space backbone fused with explicit spatio–frequency cues, bidirectional change guidance, and class-imbalance-aware loss—delivering robust, precise semantic change detection under tough illumination/seasonal shifts and severe long-tail labels. </p> <p> <a href="#updates">🔥 Updates</a> • <a href="#overview">🔭 Overview</a> • <a href="#why-spatiofrequency-matters">✨ Why Spatio–Frequency?</a> • <a href="#method">🧠 Method</a> • <a href="#quickstart">⚡ Quick Start</a> • <a href="#data">🗂 Data</a> • <a href="#train--evaluation">🚀 Train & Eval</a> • <a href="#interactive-notebook">🧪 Interactive Notebook</a> • <a href="#results">📊 Results</a> • <a href="#acknowledgements">🙏 Acknowledgements</a> • <a href="#citation">📜 Cite</a> </p> </div>

---

🔥🔥 Updates

• Mar 2026 - Weights + Notebook Released — Official Mamba-FCS checkpoints are now available on Hugging Face: https://huggingface.co/buddhi19/MambaFCS/tree/main, and the interactive evaluation/annotation notebook is available at annotations/MambaFCS.ipynb
• Feb 2026 - Paper Published — IEEE JSTARS (Official DOI: https://doi.org/10.1109/JSTARS.2026.3663066)
• Jan 2026 - Accepted — IEEE JSTARS (Camera-ready version submitted)
• Jan 2026 - Code Released — Full training pipeline with structured YAML configurations is now available
• Aug 2025 - Preprint Released — Preprint available on arXiv: https://arxiv.org/abs/2508.08232

Ready to push the boundaries of change detection? Let's go.

---

🔭 Overview

Semantic Change Detection in remote sensing is tough: seasonal shifts, lighting variations, and severe class imbalance constantly trip up traditional methods.

Mamba-FCS changes the game:

• VMamba backbone → linear-time long-range modeling (no more transformer VRAM nightmares)
• JSF spatio–frequency fusion → injects FFT log-amplitude cues into spatial features for appearance invariance + sharper boundaries
• CGA module → change probabilities actively guide semantic refinement (and vice versa)
• SeK Loss → finally treats rare classes with the respect they deserve

---

✨ Why Spatio–Frequency Matters

Remote sensing change detection suffers from appearance shifts (illumination, seasonal phenology, atmospheric effects).
Purely spatial feature fusion can overfit to texture/color changes, while frequency-domain cues capture structure and boundaries more consistently.

Mamba-FCS explicitly combines:

• Spatial modeling (VMamba / state-space) for long-range context
• Frequency cues (FFT log-amplitude) for appearance robustness
• Change-guided cross-task attention to tighten BCD ↔ SCD synergy

This spatio–frequency + change-guided design is a key reason for strong rare-class performance and cleaner semantic boundaries.

---

🧠 Method in ~30 Seconds

Feed in bi-temporal images T1 and T2:

1. VMamba encoder extracts rich multi-scale features from both timestamps
2. JSF injects frequency-domain log-amplitude (FFT) into spatial features → stronger invariance to illumination/seasonal shifts
3. CGA leverages change cues to tighten BCD ↔ SCD synergy
4. Lightweight decoder predicts the final semantic change map
5. SeK Loss drives balanced optimization, even when changed pixels are scarce

Simple. Smart. Superior.

---

⚡ Quick Start

1. Download Released Mamba-FCS Weights

Pretrained Mamba-FCS checkpoints are now hosted on Hugging Face: buddhi19/MambaFCS.

Use these weights directly for inference and evaluation, or keep them alongside your experiment checkpoints for quick benchmarking.

2. Grab Pre-trained VMamba Weights

Set pretrained_weight_path in your YAML to the downloaded .pth.

3. Install

git clone https://github.com/Buddhi19/MambaFCS.git
cd MambaFCS

conda create -n mambafcs python=3.10 -y
conda activate mambafcs

pip install --upgrade pip
pip install -r requirements.txt
pip install pyyaml

4. Build Selective Scan Kernel (Critical Step)

cd kernels/selective_scan
pip install .
cd ../../..

(Pro tip: match your torch CUDA version with nvcc/GCC if you hit issues.)

---

🗂 Data Preparation

Plug-and-play support for SECOND and Landsat-SCD.

SECOND Layout

/path/to/SECOND/
├── train/
│   ├── A/          # T1 images
│   ├── B/          # T2 images
│   ├── labelA/     # T1 class IDs (single-channel)
│   └── labelB/     # T2 class IDs
├── test/
│   ├── A/
│   ├── B/
│   ├── labelA/
│   └── labelB/
├── train.txt
└── test.txt

Landsat-SCD

Same idea, with train_list.txt, val_list.txt, test_list.txt.

Must-do: Use integer class maps (not RGB). Convert palettes first.

---

🚀 Train & Evaluation

YAML-driven — clean and flexible.

1. Edit paths in configs/train_LANDSAT.yaml or configs/train_SECOND.yaml

2. Fire it up:

# Landsat-SCD
python train.py --config configs/train_LANDSAT.yaml

# SECOND
python train.py --config configs/train_SECOND.yaml

Checkpoints + TensorBoard logs land in saved_models/<your_name>/.

Resume runs? Just flip resume: true and point to optimizer/scheduler states.

---

<a id="interactive-notebook"></a>

🧪 Interactive Evaluation & Annotation

For an interactive workflow, use the notebook annotations/MambaFCS.ipynb.

It is set up for users who want to:

• run evaluations interactively
• inspect predictions and qualitative outputs
• perform annotation and review in a notebook-driven workflow

Pair it with the released checkpoints on Hugging Face for fast experimentation without retraining.

---

📊 Results

Straight from the paper — reproducible out of the box:

Visuals speak louder: expect dramatically cleaner boundaries and far better rare-class detection.

---

🙏 Acknowledgements

This work is strongly influenced by prior advances in state-space vision backbones and Mamba-based change detection. In particular, we acknowledge:

• VMamba (Visual State Space Models for Vision) — backbone inspiration: https://github.com/MzeroMiko/VMamba
• ChangeMamba — Mamba-style change detection inspiration: https://github.com/ChenHongruixuan/ChangeMamba.git

---

📜 Citation

If Mamba-FCS fuels your research, please cite:

@ARTICLE{mambafcs,
  author={Wijenayake, Buddhi and Ratnayake, Athulya and Sumanasekara, Praveen and Godaliyadda, Roshan and Ekanayake, Parakrama and Herath, Vijitha and Wasalathilaka, Nichula},
  journal={IEEE Journal of Selected Topics in Applied Earth Observations and Remote Sensing}, 
  title={Mamba-FCS: Joint Spatio-Frequency Feature Fusion, Change-Guided Attention, and Sek Inspired Loss for Enhanced Semantic Change Detection in Remote Sensing}, 
  year={2026},
  volume={},
  number={},
  pages={1-19},
  keywords={Remote sensing imagery;semantic change detection;separated kappa;spatial–frequency fusion;state-space models},
  doi={10.1109/JSTARS.2026.3663066}
}

You might consider citing:

@misc{wijenayake2025precisionspatiotemporalfeaturefusion,
      title={Precision Spatio-Temporal Feature Fusion for Robust Remote Sensing Change Detection}, 
      author={Buddhi Wijenayake and Athulya Ratnayake and Praveen Sumanasekara and Nichula Wasalathilaka and Mathivathanan Piratheepan and Roshan Godaliyadda and Mervyn Ekanayake and Vijitha Herath},
      year={2025},
      eprint={2507.11523},
      archivePrefix={arXiv},
      primaryClass={eess.IV},
      url={https://arxiv.org/abs/2507.11523}, 
}

@INPROCEEDINGS{11217111,
  author={Ratnayake, R.M.A.M.B. and Wijenayake, W.M.B.S.K. and Sumanasekara, D.M.U.P. and Godaliyadda, G.M.R.I. and Herath, H.M.V.R. and Ekanayake, M.P.B.},
  booktitle={2025 Moratuwa Engineering Research Conference (MERCon)}, 
  title={Enhanced SCanNet with CBAM and Dice Loss for Semantic Change Detection}, 
  year={2025},
  volume={},
  number={},
  pages={84-89},
  keywords={Training;Accuracy;Attention mechanisms;Sensitivity;Semantics;Refining;Feature extraction;Transformers;Power capacitors;Remote sensing},
  doi={10.1109/MERCon67903.2025.11217111}}

---