Skip to content

README.md

Latest commit

 

History

History
123 lines (85 loc) · 4.55 KB

README.md

File metadata and controls

123 lines (85 loc) · 4.55 KB
Raw

Atlantis

Project Atlantis Logo

ML-ready archive of satellite-derived flood inundation observations (ECMWF Code for Earth 2026).

Harmonised multi-source flood observations from VIIRS (optical), MODIS (optical), and GFM (SAR), processed to a common 1-arcmin grid. Access via CLI, Python API, or the Zarr/STAC archive for ML workflows.

Python versions Ruff Tests Docs Gitleaks status

Quick Start

Pixi installs all dependencies — including GDAL with HDF4 support — from conda-forge in a single command. This is the recommended path for all users:

pixi install       # resolve & install everything
pixi run setup     # bootstrap credentials & data assets
pixi run demo      # run the Valencia 2024 flood example

CLI Demo

New to Atlantis? Start with docs/pixi-setup.md — single-command setup with GDAL + HDF4 out of the box.

Contributor? See docs/development.md for uv setup, devcontainers, testing and CI.

uv users: uv is also fully supported. See docs/development.md for the contributor workflow, devcontainer setup, and CI instructions.

Three ways to use Atlantis

CLI

The commands you'll use most often:

  • pixi run setup — bootstrap required data assets and credentials
  • pixi run demo — run the Valencia 2024 flood example end-to-end
  • pixi run example-harvey-viirs — Hurricane Harvey (VIIRS)
  • pixi run example-bihar-gfm — Bihar floods (Sentinel-1 GFM)

For custom fetch commands, run python -m atlantis.cli fetch with the `` prefix (all pixi tasks do this automatically). Add --verbose before the subcommand for debug logging.

See docs/cli.md for the full CLI reference, CLI_Examples.md for task-oriented walkthroughs, and pixi task list to list all available tasks.

Python API

Use Atlantis programmatically for custom workflows. Each source (VIIRS, MODIS, GFM) has a fetcher class and harmonisation utilities:

  • VIIRS API — fetch optical flood observations
  • MODIS API — fetch water/flood composites
  • GFM API — fetch SAR flood extent

All three support harmonisation to a common 1-arcmin grid. Load results directly into xarray for analysis and ML pipelines.

Archive

Build and query the consolidated Zarr/STAC archive for bulk ML workflows:

Documentation

Browse the full documentation site locally (MkDocs + Material):

pixi run -e docs docs

Then open http://localhost:8000. Includes architecture guides, data-source pipelines, CLI reference and batch-processing walkthroughs. For contributors using uv:

uv sync --group docs && uv run mkdocs serve

Credentials & data access

Most backends require a NASA Earthdata account. Run the setup script to be guided through all of it:

pixi run setup

See docs/setup.md for a full description of each credential (Earthdata token, LAADS Web pre-authorization, AWS profiles for GFM).

Development

All contributor documentation — uv setup, devcontainers, running tests, E2E workflow, CI triggers — is consolidated in docs/development.md.