Metadata-Version: 2.4
Name: geobridge
Version: 0.1.9
Summary: Python bridge between Copernicus Data Stores (C3S, CAMS, CEMS) and mainstream GIS operations
Project-URL: Homepage, https://github.com/ECMWFCode4Earth/GeoBridge
Project-URL: Repository, https://github.com/ECMWFCode4Earth/GeoBridge
Project-URL: Issues, https://github.com/ECMWFCode4Earth/GeoBridge/issues
Project-URL: Documentation, https://geobridge.readthedocs.io
Author: Kostas Fokeas and Ilias Machairas
License-Expression: MIT
License-File: LICENSE
Keywords: CAMS,CEMS,ERA5,GIS,WMTS,climate,copernicus,earth-observation,geotiff,zarr
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Atmospheric Science
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.10
Requires-Dist: pyyaml>=6.0
Provides-Extra: dev
Requires-Dist: build; extra == 'dev'
Requires-Dist: cfgrib>=0.9.10; extra == 'dev'
Requires-Dist: dask>=2023.1; extra == 'dev'
Requires-Dist: fsspec>=2023.1; extra == 'dev'
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: netcdf4>=1.6; extra == 'dev'
Requires-Dist: numpy>=1.24; extra == 'dev'
Requires-Dist: owslib>=0.28; extra == 'dev'
Requires-Dist: pyproj>=3.5; extra == 'dev'
Requires-Dist: pytest-cov>=4.1; extra == 'dev'
Requires-Dist: pytest>=7.4; extra == 'dev'
Requires-Dist: rasterio>=1.3; extra == 'dev'
Requires-Dist: responses>=0.23; extra == 'dev'
Requires-Dist: rioxarray>=0.14; extra == 'dev'
Requires-Dist: ruff>=0.4; extra == 'dev'
Requires-Dist: types-pyyaml; extra == 'dev'
Requires-Dist: types-requests; extra == 'dev'
Requires-Dist: xarray>=2023.1; extra == 'dev'
Requires-Dist: zarr>=2.16; extra == 'dev'
Provides-Extra: docs
Requires-Dist: sphinx-autodoc-typehints>=1.25; extra == 'docs'
Requires-Dist: sphinx-rtd-theme>=2.0; extra == 'docs'
Requires-Dist: sphinx>=7.0; extra == 'docs'
Provides-Extra: full
Requires-Dist: cfgrib>=0.9.10; extra == 'full'
Requires-Dist: dask>=2023.1; extra == 'full'
Requires-Dist: fsspec>=2023.1; extra == 'full'
Requires-Dist: netcdf4>=1.6; extra == 'full'
Requires-Dist: numpy>=1.24; extra == 'full'
Requires-Dist: owslib>=0.28; extra == 'full'
Requires-Dist: pyproj>=3.5; extra == 'full'
Requires-Dist: rasterio>=1.3; extra == 'full'
Requires-Dist: rioxarray>=0.14; extra == 'full'
Requires-Dist: xarray>=2023.1; extra == 'full'
Requires-Dist: zarr>=2.16; extra == 'full'
Provides-Extra: zarr
Requires-Dist: dask>=2023.1; extra == 'zarr'
Requires-Dist: fsspec>=2023.1; extra == 'zarr'
Requires-Dist: numpy>=1.24; extra == 'zarr'
Requires-Dist: rasterio>=1.3; extra == 'zarr'
Requires-Dist: rioxarray>=0.14; extra == 'zarr'
Requires-Dist: xarray>=2023.1; extra == 'zarr'
Requires-Dist: zarr>=2.16; extra == 'zarr'
Description-Content-Type: text/markdown

# GeoBridge

**Python library that bridges Copernicus Data Stores into mainstream GIS workflows.**

GeoBridge removes the technical friction GIS users face when working with
Copernicus climate, atmosphere, and emergency data. It resolves dataset
discovery, authentication, and access-method differences into a single
ergonomic API that produces analysis-ready Cloud Optimized GeoTIFFs.

The library is the foundation for the project's QGIS plugin.

---

## What it does

- **Discovery.** `gb.discover()` lists every dataset in the Copernicus
  catalogue with filters for keyword, service, variable, bounding box, and
  time range — all from a locally bundled snapshot, no network needed.
- **Authentication.** A single `gb.authenticate()` call handles credential
  resolution for the new ARCO bearer-token model.
- **Extraction — ARCO path.** `gb.zarr_to_geotiff()` pulls a spatial / temporal
  subset from the ARCO Zarr Data Lake and writes it as a Cloud Optimized
  GeoTIFF, ready for QGIS or ArcGIS.
- **Extraction — CDS API path.** `gb.cds_to_geotiff()` submits a download job
  through the standard CDS API for datasets that are not yet in the ARCO lake,
  converts the result to GeoTIFF, and streams it to disk.
- **WMTS.** `gb.wmts_layer()` returns a ready-to-use WMTS layer object for
  live tile streaming inside QGIS or Leaflet.
- **Form schema.** `gb.fetch_form()` and `gb.fetch_constraints()` retrieve the
  server-side parameter form for any dataset so your UI can build validated
  request widgets. `gb.valid_variables_for_product_type()` filters the variable
  list to what the selected product type actually supports.
- **Styling.** `gb.to_qgis_style()` generate
  calibrated colour ramps for known Copernicus variables.
- **Fusion.** `gb.fuse()` co-registers multiple layers onto a common grid
  for joint analysis (e.g. heat + air quality).
- **Semantics.** `gb.semantic_search()` resolves user themes like
  "urban heat island" or "wildfire risk" into concrete dataset and
  workflow recommendations. `gb.list_themes()` and `gb.list_use_cases()`
  enumerate the built-in vocabulary.

---

## How to run it

### Prerequisites

- **Python 3.10 or newer.** GeoBridge does not support older Python.
- **A free Copernicus account.** Register at
  https://cds.climate.copernicus.eu and copy your personal access token
  from your profile page.
- **macOS, Linux, or Windows with WSL2.** Native Windows may work but is
  not tested.


### Configure your credentials

Create `~/.cdsapirc` with your personal access token:

```
key: YOUR-CDS-API-KEY-HERE
```

Then protect the file so other users on the machine cannot read it:

```bash
chmod 600 ~/.cdsapirc
```

Alternatively, export your key as an environment variable instead of
writing it to a file:

```bash
export CDS_API_KEY=YOUR-CDS-API-KEY-HERE
```


### Run the Athens demo

This is the end-to-end demonstration. It extracts ERA5 temperature for
Athens summer 2023, writes a Cloud Optimized GeoTIFF, and generates a
matching QGIS style:

```bash
python examples/athens_urban_heat.py
```

Expected runtime is roughly one minute on a reasonable broadband
connection. The output appears in `./athens_outputs/`. Open the `.tif` in
QGIS, load the `.qml` style alongside it, and you should see Athens
temperatures rendered with a calibrated colour ramp.

## License

MIT. See `LICENSE`.

---

## Acknowledgements
GeoBridge was developed for the ECMWF Copernicus Data Store GIS Integration Challenge.