Environmental Monitoring System (EMS)

CLI-first Earth Observation workflows (GEE + TorchGeo) with a separate Dash dashboard.

A personal Earth Observation (EO) project to experiment with environmental monitoring workflows using:

• Sentinel‑2 analysis via Google Earth Engine (GEE)
• Disaster-focused benchmark datasets via TorchGeo (ChaBuD, MMFlood, DigitalTyphoon, ADVANCE)
• An offline CLI-first pipeline and a separate Dash dashboard
• Transformer-based change detection baseline integrated from BIT_CD (Bitemporal Image Transformer) for ChaBuD inference (pretrained weights).

Design goal: keep compute-heavy tasks (downloads, GEE queries, preprocessing, future training/inference) outside the dashboard and run them via CLI. Typer supports command groups (subcommands) for this structure.

---

Dashboard preview

Change Detection — single year

Change Detection — two-year comparison

---

Quickstart

Dashboard Functioning

python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows PowerShell
pip install -r requirements.txt

pip install -e .
set PYTHONPATH=src
python -m dashboard.app

Torchgeo Inspect Functioning

python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows PowerShell
pip install -r requirements.txt

pip install -e .
eo torchgeo inspect --dataset ChaBuD --n 3 --chip-size 256

---

Table of contents

• Project structure
• Requirements
• Installation
• Configuration
• Earth Engine authentication
• CLI usage
• Models
• Dashboard (Dash)
• Data & outputs
• Troubleshooting
• Roadmap
• Citation
• License

---

Project structure

├── dashboard/
│   ├── app.py
│   └── pages/
│       ├── 1_change_detection.py
│       └── 2_torchgeo_dl.py
├── docs/
│   └── cli.md
├── src/
│   └── eo/
│       ├── cli.py
│       ├── config/
│       ├── ee/
│       ├── models/
│       │   └── BIT_CD/
│       └── torchgeo/
├── .gitignore
├── README.md
└── requirements.txt

---

Requirements

• Python 3.10+ recommended.
• Dependencies are pinned in requirements.txt (Earth Engine stack, TorchGeo/PyTorch, geospatial I/O, and dashboard libraries).

---

Installation

1. Create and activate a virtual environment:

python -m venv .venv
source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows PowerShell

2. Install dependencies from requirements.txt:

pip install -r requirements.txt

3. Install the project in editable mode so import eo works reliably:

pip install -e .

---

Configuration

Create/edit src/eo/config/const.py and set your Earth Engine project:

PROJECT_ID = "your-gcp-project-id"

---

Earth Engine authentication

Earth Engine requires authentication and initialization; once authenticated, ee.Initialize(project=...) can reuse stored credentials and will only need re-auth if credentials are expired/invalid.

Typical local setup:

earthengine authenticate

If you implement an “authenticate-if-needed” pattern inside initialize_ee(), you can attempt ee.Initialize(...) first and call ee.Authenticate() only when initialization fails (and optionally force=True to re-create credentials).

---

CLI usage

The CLI is implemented with Typer and exposes subcommands such as ee and torchgeo (command groups).

For a more detailed CLI reference (commands, options, conventions), see docs/cli.md.

Notes:

• If --root is not provided, datasets default to data/torchgeo/<dataset_name>.
• For GeoDatasets, sampling is performed via TorchGeo samplers (e.g., RandomGeoSampler) and stacksamples.

---

Models

BIT_CD (ChaBuD change detection)

BIT_CD is the official PyTorch implementation of the Bitemporal Image Transformer (BIT) for remote sensing change detection.
Given a pair of co-registered images (T1, T2), BIT models cross-temporal interactions with transformer attention and produces a pixel-wise change map (binary semantic segmentation).

In this project, the codebase is vendored under src/eo/models/BIT_CD/ and currently used for inference; training/fine-tuning on ChaBuD is not part of the pipeline yet.

Official resources

• Paper (IEEE TGRS): https://ieeexplore.ieee.org/document/9491802
• Code: https://github.com/justchenhao/BIT_CD

---

Dashboard (Dash)

The dashboard is intentionally kept separate from the CLI and should be run via dashboard/app.py.

Example:

source .venv/bin/activate   # Linux/macOS
# .venv\Scripts\activate    # Windows PowerShell
set PYTHONPATH=src
python -m dashboard.app

---

Data & outputs

By default, the project writes outputs under data/ (recommended outside src/):

data/
  ee/
    outputs/
      single_year_<year>.png
      comparison_<year_a>_<year_b>.png
      stats_df.csv
  torchgeo/
    ChaBuD/...
    MMFlood/...
    DigitalTyphoon/...
    ADVANCE/...
    inspect/...

This directory can be excluded from version control (add data/ to .gitignore).

---

Troubleshooting

ModuleNotFoundError: eo

• Ensure editable install (pip install -e .) succeeded.

Earth Engine errors (auth/init)

• Authenticate with earthengine authenticate and verify PROJECT_ID.
• If credentials are stale, rerun authentication (optionally with --force) and retry initialization.

TorchGeo sampling looks “random”

• For GeoDatasets, a sample is a randomly extracted chip; set --seed for reproducibility and keep --chip-size consistent.

---

Roadmap

• Work on the Torchgeo data usage with DL models.
• Work on dashboard Torchgeo DL page.

---

Citation

If you use the BIT model (or the vendored BIT_CD code) in academic work, please cite:

@Article{chen2021a,
    title={Remote Sensing Image Change Detection with Transformers},
    author={Hao Chen, Zipeng Qi and Zhenwei Shi},
    year={2021},
    journal={IEEE Transactions on Geoscience and Remote Sensing},
    volume={},
    number={},
    pages={1-14},
    doi={10.1109/TGRS.2021.3095166}
}

---

License

No license.