GeoLoupe
Explore large scientific and geospatial datasets on an interactive map: from the whole planet down to 10 m, through time, with the values one click away.
GeoLoupe puts gridded data on a web map: weather and climate reanalyses, model output, satellite images, elevation models, land cover, and station records. It reads them where they are (Zarr, NetCDF, GRIB, GeoTIFF/COG, CSV, Parquet; local or in public cloud buckets) and reads only what the screen can show. Datasets of different resolution become one seamless layer: zoomed out, you see the coarse global field; zoom in, and the fine data takes over where it exists.
Install
pip install "geoloupe[all]" # Python ≥ 3.11; or: uv tool install "geoloupe[all]"
geoloupe alone installs the core (Zarr, NetCDF); the extras add readers: remote (S3, GCS,
HTTPS), geotiff (COG), grib, stations (Parquet), vector (GeoJSON, Shapefile, …), dask
(many NetCDF files as one). all installs them all.
The geoloupe command uses the system's HTTPS certificates. In your own Python code (a notebook),
an error CERTIFICATE_VERIFY_FAILED means that Python has no certificate list: call
geoloupe.certs.use_system_certificates() before opening remote data, or set
SSL_CERT_FILE="$(python3 -m certifi)".
Try it: the gallery of open data
geoloupe gallery # → http://localhost:8000
The gallery needs an internet connection and nothing else: no download in advance, no account, no key. The server starts in 10–30 s (it reads the remote metadata), and a map tile takes 0.3–1.5 s over the internet.
| Data | Source | What you can do |
|---|---|---|
| ERA5 hourly reanalysis, 0.25°, 1940 → last week (temperature, rain, water vapour, wind gusts, sea temperature) | ARCO-ERA5 Zarr on Google Cloud, 761 160 hourly steps | step hour by hour, play, compare two dates, time series of any point |
| Copernicus DEM GLO-30 (30 m), six 1° tiles in the Western Alps, over ERA5's 31 km orography | Copernicus DEM COGs on AWS | zoom from 31 km to 30 m in one layer |
| Sentinel-2 L2A, 10 m: the 10 least cloudy scenes of August 2023 over the Western Alps | a STAC search of Earth Search (Element84), COGs on AWS | one seamless mosaic in true colour, false colour (near infrared) or single bands, side by side |
| ESA WorldCover 2021, 10 m, 45–48° N, 6–9° E | ESA WorldCover COG on AWS | 11 land-cover classes with names, colours and shares of the view |
| GFDL-ESM4 climate model ocean (CMIP6 historical), monthly 1850–2014, on its native tripolar grid | Pangeo CMIP6 Zarr on Google Cloud | a curvilinear model grid drawn as it is; difference of two months 165 years apart |
| CHELSA V2.1, 30″ (about 1 km): July temperature 1981–2010 and 2071–2100 (SSP5-8.5), annual precipitation; daily temperature of summer 2003 (one file per day, as a time stack) | CHELSA (WSL) COGs on SWITCH object storage | valleys and peaks at 1 km; the climate-change signal as an error pane, from the 1 km cells |
| States and provinces, rivers, lakes (overlays) | Natural Earth 1:10m GeoJSON | switch on in the layer panel; hover a region for its name next to the data value |
| GHCN-Daily stations, 21 long records (Milan since 1763) | NOAA NCEI CSV files | daily max/min temperature and precipitation; with Point, click a station for its whole record |
The gallery is a normal configuration file: geoloupe gallery --show-config prints it, so you can
copy it and change it.
Your own data
No configuration is needed for a first look:
uv run geoloupe serve /path/to/data.zarr # or .nc, .grib2, .tif, a URL
uv run geoloupe serve grid.zarr stations.csv # several files; tables become point layers
uv run geoloupe serve grid.zarr regions.geojson # vector files become overlays
uv run geoloupe serve s3://copernicus-dem-30m/Copernicus_DSM_COG_10_N46_00_E007_00_DEM/Copernicus_DSM_COG_10_N46_00_E007_00_DEM.tif # public S3: no setup
uv run geoloupe serve s3://bucket/data.zarr --endpoint https://os.example.org --anon # S3-compatible store
uv run geoloupe serve "https://os.unil.cloud.switch.ch/chelsa02/chelsa/global/monthly/tas/{YYYY}/CHELSA_tas_{MM}_{YYYY}_V.2.1.tif" # one file per month → time slider
uv run geoloupe serve config.yaml --open-root ~/data # "Add data" may also open local files below ~/data
uv run geoloupe info /path/to/data.zarr # what GeoLoupe sees: variables, grid, CRS, times
Add data in the browser. On your own machine, Add data opens any URL or S3 store (local files
only below folders given with --open-root). A server that listens on other interfaces
(--host 0.0.0.0) opens nothing unless started with --allow-open; --no-open turns it off. The
dialog remembers the data you opened before.
Data in S3 buckets: use Add data → Browse S3. List a bucket on AWS, or on any S3-compatible store
through its endpoint (MinIO, Ceph, SWITCH, Cloudflare R2, …), filter the names, and open a Zarr
store, NetCDF, GeoTIFF/COG, station table or vector file, in the active pane or in a new pane. Public
buckets need no setup. Private buckets use the credentials of the machine where GeoLoupe runs
(AWS_ACCESS_KEY_ID/AWS_SECRET_ACCESS_KEY, or a profile in ~/.aws); keys are never typed in the
browser. In a configuration file, the same access is
storage_options: {client_kwargs: {endpoint_url: https://…}, profile: work}. Private GeoTIFFs on a
non-AWS store are read by GDAL, which takes its endpoint from AWS_S3_ENDPOINT.
To combine datasets into one layer, add colour scales, or list featured views, write a small YAML file (full reference, more in examples/):
title: Elevation
datasets:
dem: {mosaic: [N45E006.tif, N45E007.tif, N46E006.tif, N46E007.tif], variable_name: elevation}
global: {path: https://example.org/global-dem-1km.tif, variable_name: elevation}
layers:
elevation:
title: Elevation (30 m where available)
sources: # the finest data wins; coarser data fills the rest
- {dataset: dem, variable: elevation}
- {dataset: global, variable: elevation}
views: # optional: the gallery start screen
- {title: The Matterhorn, layer: elevation, center: [7.66, 45.98], zoom: 11}
On RenkuLab (no installation, shareable): a public RenkuLab project with the GeoLoupe image
(ghcr.io/salmanmohebi/geoloupe) gives everyone a link that opens their own GeoLoupe session; see
docs/renkulab.md.
On a remote machine or HPC node: run geoloupe serve config.yaml --port 8000 there and tunnel:
ssh -N -L 8000:localhost:8000 <host>. Behind JupyterHub with jupyter-server-proxy, open
…/user/<name>/proxy/8000/ (all URLs are relative).
In a notebook:
import xarray as xr, geoloupe
ds = xr.open_zarr("data.zarr")
geoloupe.show({"data": ds}) # interactive map in the cell output
Features
- Seamless multi-resolution layers. Stack sources (a 30 m DEM over a 31 km one, a regional model over a global one, a mosaic of many tiles). Per pixel, the finest source with data wins; coarser sources fill gaps and serve low zooms.
- Bounded cost at every zoom. Per tile, the engine picks the coarsest resolution level that is still
as fine as a screen pixel and never reads more than a fixed number of cells. COG overviews are used
automatically;
geoloupe overviews buildmakes overview pyramids for other formats. - Honest about what you see. A badge names the datasets, resolutions and native/overview levels on
screen; hover shows the displayed value and its source; with Point (key
i), a click gives the stored value of the native cell of every source, plus their time series. - Satellite images and STAC. RGB composites from any three bands, with stretch and gamma in the browser; automatic for 3-band images such as Sentinel-2 TCI. A STAC search (collection, area, dates, cloud cover) becomes one mosaic per band, best scene first, with scale and offset from the STAC metadata.
- Categorical data. Land cover and masks keep their class codes (never averaged): class colours and names from CF flags, a GeoTIFF palette or the config; the legend shows each class's share.
- Fast, interactive styling. Data tiles are floats; the browser colours them. Changing the colormap, range or log scale needs no new requests. 41 scientific colormaps (matplotlib, cmocean, Crameri), histogram of the values on screen, fit-to-view.
- Time and dimensions. Time slider, stepping, playback that waits for tiles, axes of a million
hourly steps; any extra dimension (pressure level, ensemble member) gets a selector. cftime
calendars (
noleap,360_day) work. - Stations and point data. Station tables (CSV, Parquet, GeoParquet; long or wide; columns detected) and CF timeSeries NetCDF are layers of their own, or are drawn over a gridded layer in its colour scale: hover shows observation, grid value and difference.
- Vector overlays. Regions, borders, rivers, catchments, tracks or sites from GeoJSON, Shapefile, GeoPackage, FlatGeobuf or GeoParquet, drawn over the data; hover shows the feature's name and attributes next to the value under the cursor.
- Split panes, like tmux. Split the map right or down (up to 6 panes), drag the dividers, and
show a different layer, time and colour scale in each pane. Panes share the camera and the time
(each can be unlinked); the hover lists every pane's value, a picked point gives every pane's time
series, and the whole layout exports as one figure. Keys:
%split right,"split down,xclose,zzoom a pane,Alt+arrows move. A linked pane can show another time: the same day, 30 years earlier (time offset). - Error maps. An error pane shows the error of one layer (P, e.g. a model) against another (T,
e.g. observations): bias, absolute, squared and relative errors, ratios, event agreement (hits,
misses, false alarms) or your own formula of P and T. It follows the panes it compares. Computed
from the native cells, not the screen pixels (errors that cancel inside a pixel still count),
with bias, MAE and RMSE (or POD, FAR, CSI) of the view, the error over time at a point, and
geoloupe errors buildfor maps that are exact at every zoom. See docs/errors.md. - Open data from S3 buckets. Add data → Browse S3 lists a bucket on AWS or any S3-compatible store (MinIO, Ceph, SWITCH, Cloudflare R2, …), shows what GeoLoupe can open, and opens it in a pane; public buckets need no setup, private ones use the server's own credentials.
- Many formats and grids. Zarr v2/v3 (sharded, consolidated or not), NetCDF 3/4 and HDF5 (also multi-file), GRIB, GeoTIFF/COG (multi-band, palettes; one file per time step as a time stack), kerchunk/VirtualiZarr references; local or remote (HTTPS, S3, GCS). Public S3 buckets work without credentials or setup. Lat/lon grids in either longitude convention, Gaussian grids, projected CRSs (UTM, LAEA, rotated pole, …), and curvilinear grids with 2-D longitude/latitude (ocean models, WRF, CMIP6 native grids, swaths).
- Gallery and sharing. Featured views as a start screen, also with several panes; every view is a link (layout included); PNG export with title, colour bar and attribution (one pane or the whole layout); the data in view as NetCDF; time series as CSV.
- Python and Jupyter.
geoloupe.show(...)puts any xarray Dataset on the map inside a notebook. The HTTP API (OpenAPI docs at/api/docs) works from any language.
Screenshots
All from geoloupe gallery:
The synthetic demo (geoloupe demo-data demo && geoloupe serve demo/demo.yaml) works offline
and shows compositing, pressure levels and a LAEA-projected grid (images).
How it works
Browser: React UI + MapLibre GL JS ── geoloupe:// protocol: fetch float tile → colour → ImageBitmap
▲ float32 data tiles (+ which source filled each pixel)
Server: FastAPI ── TileEngine: per tile and source: level choice → read budget → block mean → composite
▲ lazy window reads (xarray, GDAL)
Data: Zarr / NetCDF / GRIB / GeoTIFF / CSV / Parquet, local or object storage + optional overviews
Read ARCHITECTURE.md for the design, the data flow and the alternatives considered, docs/research.md for the survey of existing tools (TiTiler, xpublish-tiles, zarr-layer, OpenLayers GeoZarr, GeoZarr conventions, …), and docs/decisions.md for the decision log.
Status and limitations
GeoLoupe 0.3 is young but complete enough for daily use (see ROADMAP.md):
- Grids: rectilinear and curvilinear. Unstructured meshes (UGRID, HEALPix, ICON) are not supported
yet. Curvilinear grids show the nearest cell (no averaging) and get coarser levels by subsampling;
geoloupe overviews builddoes not support them yet. - Tiles: Web Mercator (plus MapLibre's globe view). Polar regions beyond ±85° are not shown.
- On-the-fly aggregation is an unweighted mean of the cells whose centres fall in a pixel; projected grids use nearest neighbour (build overviews for means).
- Point time series read one chunk per time step. Data chunked for maps (one time step per chunk) makes long series slow (seconds per year of daily data).
- Remote data is as fast as the network: the first view of a remote COG or Zarr store takes a few seconds; later reads use GDAL's and the server's caches.
- No authentication or multi-user features; bind to localhost or use an authenticating proxy. This
matters most for Add data (remote URLs, on by default on localhost;
--open-root), which lets any visitor make the server read URLs (and list S3 buckets, with the server's credentials) or local files below the given folders. - GeoLoupe always runs a server; there is no browser-only mode for static GeoZarr pyramids yet.
Private GeoTIFFs on a non-AWS S3 store need
AWS_S3_ENDPOINT(GDAL reads them). - Error maps are exact from the native cells only within a read budget (for 1 km data: from about
zoom 5); wider views need
geoloupe errors build. Error maps of curvilinear or composite layers cannot be precomputed yet. - Data binned along lines (transects, fjord or river profiles) cannot be shown on the map yet.
Contributing
Contributions are welcome: bug reports, data that does not open, ideas, code and docs. Start with CONTRIBUTING.md (development setup, tests, conventions) and the open items in ROADMAP.md. In short:
git clone https://github.com/salmanmohebi/geoloupe.git && cd geoloupe
uv sync --all-extras && uv run pytest # Python
cd frontend && npm ci && npm test && npm run dev # web client (with the API on port 8000)
scripts/ci_local.sh # all CI checks on a fresh clone, before a PR
Please report security problems privately (SECURITY.md). Everyone taking part follows the code of conduct. Changes are listed in CHANGELOG.md.
Citing
If GeoLoupe helps your research, please cite it (CITATION.cff; GitHub's "Cite this repository" button gives BibTeX and APA). Each release is archived on Zenodo: 10.5281/zenodo.24156973 cites the latest version; the Zenodo page lists the DOI of each version.
License and data credits
Apache License 2.0. Colormaps: matplotlib (BSD-compatible / CC0), cmocean (MIT), Scientific colour maps by F. Crameri (MIT). Country borders: Natural Earth (public domain).
Gallery data: ERA5 © ECMWF / Copernicus Climate Change Service, ARCO-ERA5 by Google Research; Copernicus DEM GLO-30 © DLR e.V. and Airbus Defence and Space GmbH, provided under COPERNICUS by the EU and ESA; Sentinel-2 contains modified Copernicus Sentinel data 2023, COGs by Element84; ESA WorldCover 2021 © ESA WorldCover project (CC BY 4.0); GHCN-Daily, NOAA NCEI (Menne et al. 2012); CHELSA V2.1, WSL (Karger et al. 2017, doi:10.1038/sdata.2017.122; CC0); Natural Earth (public domain).
Metadata
Release files for geoloupe 0.4.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| geoloupe-0.4.0.tar.gz | 1.4 MB | With provenance | Details for geoloupe-0.4.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| geoloupe-0.4.0-py3-none-any.whl | Python 3 | none | any | Details for geoloupe-0.4.0-py3-none-any.whl |
Total release size: 2.3 MB
Release files / geoloupe-0.4.0.tar.gz
| Download URL | geoloupe-0.4.0.tar.gz |
|---|---|
| Size | 1.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
06985e8efe7791ad8a150156a6b781e35989f816e2d2d79b6c9c93138f066c84
|
|
BLAKE2b-256 checksum How to use checksums |
96e0fc36e456d1fb7b4cfdef048a586d0ad427922c311f51835d1df6ac8393bf
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logRelease files / geoloupe-0.4.0-py3-none-any.whl
| Download URL | geoloupe-0.4.0-py3-none-any.whl |
|---|---|
| Size | 847.8 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
f5c0a4216a3a56a9e542e63d3332904cf3038e9810d6c6a1d2ae27387c9e172c
|
|
BLAKE2b-256 checksum How to use checksums |
8b1ed5c465be4137f8a0498d79ddb5fa4035fbea5a16ad944ba3a93e094919ff
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.16
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logSecurity for geoloupe 0.4.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
Full provenance
Both files in this release have been uploaded with provenance metadata.
Attestation for geoloupe-0.4.0.tar.gz
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.
Transparency logA note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.