geoloupe 0.1.0__tar.gz

geoloupe-0.1.0/.dockerignore

@@ -0,0 +1,11 @@
+.git
+.venv
+**/__pycache__
+.mypy_cache
+.ruff_cache
+.pytest_cache
+dist
+demo
+docs/images
+frontend/node_modules
+frontend/dist

geoloupe-0.1.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,30 @@
+name: Bug report
+description: Something does not work as described
+labels: [bug]
+body:
+  - type: textarea
+    id: what
+    attributes:
+      label: What happened, and what did you expect?
+    validations:
+      required: true
+  - type: textarea
+    id: steps
+    attributes:
+      label: How to reproduce
+      description: The command or configuration (YAML), the dataset (a public URL if possible), and the steps in the browser.
+      render: shell
+    validations:
+      required: true
+  - type: textarea
+    id: logs
+    attributes:
+      label: Server log or browser console messages
+      render: text
+  - type: input
+    id: version
+    attributes:
+      label: Versions
+      description: "Output of `geoloupe --version`, your Python version and browser"
+    validations:
+      required: true

geoloupe-0.1.0/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Security problem
+    url: https://github.com/salmanmohebi/geoloupe/security/advisories/new
+    about: Please report vulnerabilities privately (see SECURITY.md).

geoloupe-0.1.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,15 @@
+name: Feature or data support request
+description: A new feature, file format, grid type or dataset to support
+labels: [enhancement]
+body:
+  - type: textarea
+    id: need
+    attributes:
+      label: What do you want to do, and why?
+      description: Describe the research task. A public example dataset helps a lot.
+    validations:
+      required: true
+  - type: textarea
+    id: idea
+    attributes:
+      label: Ideas for how it could work (optional)

geoloupe-0.1.0/.github/dependabot.yml

@@ -0,0 +1,18 @@
+# Keep dependencies current with grouped pull requests (one per ecosystem and interval).
+version: 2
+updates:
+  - package-ecosystem: github-actions
+    directory: /
+    schedule: {interval: weekly}
+    groups:
+      actions: {patterns: ["*"]}
+  - package-ecosystem: uv
+    directory: /
+    schedule: {interval: monthly}
+    groups:
+      python: {patterns: ["*"]}
+  - package-ecosystem: npm
+    directory: /frontend
+    schedule: {interval: monthly}
+    groups:
+      web: {patterns: ["*"]}

geoloupe-0.1.0/.github/pull_request_template.md

@@ -0,0 +1,10 @@
+## What and why
+
+<!-- The problem this solves, and how. Link the issue: "Fixes #123". -->
+
+## Checklist
+
+- [ ] Tests added or updated (`uv run pytest`, `npm test`)
+- [ ] `scripts/ci_local.sh` passes, or the same checks by hand (ruff, mypy, eslint, build)
+- [ ] Docs updated (README, docs/, CHANGELOG.md under "Unreleased")
+- [ ] For UI changes: a screenshot, and the browser smoke test (`node e2e/smoke.mjs`)

geoloupe-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,82 @@
+name: CI
+on:
+  push:
+    branches: [main]
+  pull_request:
+  workflow_dispatch: # "Run workflow" button in the Actions tab
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - run: uv sync --all-extras --python ${{ matrix.python }}
+      - run: uv run ruff check src tests scripts examples
+      - run: uv run ruff format --check src tests scripts examples
+      - run: uv run mypy
+      - run: uv run pytest
+
+  web:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: frontend
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - run: npm ci
+      - run: npm run lint
+      - run: npm test
+      - run: npm run build
+
+  e2e:
+    needs: [python, web]
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: uv sync
+      - run: uv run geoloupe demo-data demo --days 200
+      - run: uv run geoloupe serve demo/demo.yaml --port 8765 --open-root demo &
+      - run: cd frontend && npm ci && npx playwright install --with-deps chromium && npm run build
+      - run: timeout 300 bash -c 'until curl -sf http://127.0.0.1:8765/api/health; do sleep 2; done'
+      - run: cd frontend && node e2e/smoke.mjs http://127.0.0.1:8765 shots
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: screenshots
+          path: frontend/shots
+
+  # The gallery reads public data from AWS, Google Cloud and NOAA: an outage there must not make
+  # CI red, so this job only reports.
+  gallery:
+    needs: [python, web]
+    runs-on: ubuntu-latest
+    continue-on-error: true
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+      - run: uv sync --all-extras
+      - run: uv run geoloupe gallery --port 8766 &
+      - run: cd frontend && npm ci && npx playwright install --with-deps chromium
+      - run: timeout 180 bash -c 'until curl -sf http://127.0.0.1:8766/api/health; do sleep 2; done'
+      - run: cd frontend && node e2e/gallery.mjs http://127.0.0.1:8766 gallery-shots
+      - uses: actions/upload-artifact@v4
+        if: always()
+        with:
+          name: gallery-screenshots
+          path: frontend/gallery-shots

geoloupe-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,78 @@
+name: Release
+# Push a tag "vX.Y.Z" (equal to __version__ in src/geoloupe/__init__.py) to publish that version on
+# PyPI and create a GitHub release. PyPI accepts the upload through "trusted publishing" (OpenID
+# Connect): no password or token is stored anywhere. See RELEASING.md for the one-time setup.
+on:
+  push:
+    tags: ["v*"]
+  workflow_dispatch: # build and check only (no upload): a dry run
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v6
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 24
+          cache: npm
+          cache-dependency-path: frontend/package-lock.json
+      - name: The tag equals the package version
+        if: startsWith(github.ref, 'refs/tags/v')
+        run: |
+          v=$(sed -n 's/^__version__ = "\(.*\)"/\1/p' src/geoloupe/__init__.py)
+          if [ "v$v" != "$GITHUB_REF_NAME" ]; then
+            echo "tag $GITHUB_REF_NAME does not match __version__ $v"; exit 1
+          fi
+      - name: Build the web client from this commit (shipped inside the wheel)
+        run: cd frontend && npm ci && npm run build
+      - run: uv build
+      - run: uvx twine check dist/*
+      - name: Smoke test the wheel in a clean environment
+        run: |
+          uv venv /tmp/wheel-test
+          uv pip install --python /tmp/wheel-test/bin/python dist/*.whl
+          /tmp/wheel-test/bin/geoloupe --version
+          /tmp/wheel-test/bin/geoloupe gallery --show-config > /dev/null
+          cd /tmp && /tmp/wheel-test/bin/geoloupe demo-data demo --days 20
+          (/tmp/wheel-test/bin/geoloupe serve demo/demo.yaml --port 8799 &)
+          timeout 120 bash -c 'until curl -sf http://127.0.0.1:8799/api/health; do sleep 2; done'
+          curl -sf http://127.0.0.1:8799/ > /dev/null
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    if: startsWith(github.ref, 'refs/tags/v')
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/geoloupe/
+    permissions:
+      id-token: write # trusted publishing
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - uses: pypa/gh-action-pypi-publish@release/v1
+
+  github-release:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Create the GitHub release with the built files
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: >
+          gh release create "$GITHUB_REF_NAME" dist/* --repo "$GITHUB_REPOSITORY"
+          --title "GeoLoupe ${GITHUB_REF_NAME#v}" --generate-notes

geoloupe-0.1.0/.gitignore

@@ -0,0 +1,28 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.venv
+.pytest_cache/
+.mypy_cache/
+.ruff_cache/
+build/
+dist/
+
+# Web client (the built client in src/geoloupe/static IS committed: the package ships it)
+frontend/node_modules
+frontend/dist
+frontend/test-results/
+frontend/playwright-report/
+
+# Data and outputs (regenerable)
+demo/
+samples/
+*.overviews.zarr/
+slurm_logs/
+*.out
+
+# Editors / OS
+.DS_Store
+.idea/
+.vscode/

geoloupe-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,18 @@
+# pre-commit install  →  runs on every commit
+repos:
+  - repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: v0.14.0
+    hooks:
+      - id: ruff-check
+        args: [--fix]
+      - id: ruff-format
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v6.0.0
+    hooks:
+      - id: end-of-file-fixer
+        exclude: ^src/geoloupe/(static|colormaps\.json)
+      - id: trailing-whitespace
+        exclude: ^src/geoloupe/static/
+      - id: check-yaml
+      - id: check-added-large-files
+        args: [--maxkb=2000]

geoloupe-0.1.0/ARCHITECTURE.md

@@ -0,0 +1,279 @@
+# GeoLoupe architecture
+
+This document describes how GeoLoupe works, why it is built this way, and which alternatives were
+considered. The survey of existing tools is in [docs/research.md](docs/research.md); the individual
+decisions are logged in [docs/decisions.md](docs/decisions.md).
+
+## 1. Goals and constraints
+
+GeoLoupe should let a researcher open large gridded datasets and explore them like a web map:
+pan, zoom, step through time, read values, compare datasets. The hard requirements are:
+
+1. **Seamless multi-resolution.** A coarse global dataset and a fine regional one (or several) must
+   form one map: coarse when zoomed out, fine where it exists when zoomed in, without visible seams
+   and without the user switching layers.
+2. **Never load what is not visible.** A 20 880 × 43 200 × 13 864 grid (a 30″ ≈ 1 km daily climate dataset) cannot be
+   read for a zoomed-out view. Every request must have a bounded cost.
+3. **Scientific honesty.** The user must be able to tell what they see: which dataset, at which
+   resolution, aggregated or native. Clicked values must be the stored values.
+4. **Formats as they are.** Data stays where and how it is (Zarr, NetCDF, GRIB, GeoTIFF, local or
+   object storage). Preprocessing is optional and only adds speed.
+5. **Simple to run** on a laptop, a workstation, or an HPC compute node behind an SSH tunnel or
+   JupyterHub proxy.
+
+## 2. Overview
+
+```
+             Browser                                        Python server (FastAPI)
+┌─────────────────────────────────┐        ┌─────────────────────────────────────────────────────┐
+│ React UI (panels, time, charts, │        │ API  /api/layers/{id}/tiles/{z}/{x}/{y}.bin  .png    │
+│  gallery) · state (zustand, URL)│  HTTP  │      /preview.png /point /timeseries /stats /catalog  │
+│ MapLibre GL JS v6               │◄──────►│                     │                               │
+│   raster source "geoloupe://" │ float  │ TileEngine: per tile and per source                   │
+│        │                        │ tiles  │   level choice → read budget → resample → composite  │
+│ protocol handler:               │        │                     │                               │
+│   fetch float tile → cache      │        │ Catalog: datasets → sources (levels) → layers         │
+│   → colormap (CPU) → ImageBitmap│        │                     │                               │
+│ hover values from the cache     │        │ Readers: xarray (zarr, netcdf, grib, geotiff, refs)   │
+└─────────────────────────────────┘        └─────────────────────┬───────────────────────────────┘
+                                                                  │ lazy window reads
+                                      ┌───────────────────────────┴──────────────────────────┐
+                                      │ native datasets (never modified) + external overviews │
+                                      │ local disk, Lustre, S3/GCS/HTTP (fsspec)              │
+                                      └──────────────────────────────────────────────────────┘
+```
+
+Four ideas carry the design:
+
+| Idea | What it gives |
+|---|---|
+| **Float data tiles, coloured in the browser** | Colormap and range changes are instant (no new requests); hover shows the value of the displayed pixel; difference maps are computed in the browser from two cached tiles. |
+| **Per-tile level choice with a read budget** | Every tile reads at most `max_read_cells` grid cells. The engine picks the coarsest level that is still as fine as a screen pixel; if even that is too expensive, the source is skipped at this zoom and the UI says so. |
+| **Per-pixel compositing of several datasets** | A layer can stack sources of different resolution. Per pixel, the finest source with data wins; coarser sources fill the rest. This is the "Google Maps" behaviour, and no existing server does it across datasets. |
+| **External overviews in the native grid** | Optional pyramids (block means at 2×, 4×, … coarser) stored next to, not inside, the source. Values stay traceable to source cells; one pyramid serves any display projection. |
+
+## 3. Data model
+
+```
+Config (YAML)          Catalog (runtime)
+─────────────          ─────────────────────────────────────────────────────────────
+datasets:      ──►     DatasetEntry  (status ok/error, attrs)
+  path / levels          └─ Source  = one variable of one dataset
+  overviews                    ├─ levels: [Level, …]  finest first
+  styles                       │    Level = lazy DataArray + Grid + TimeAxis + origin
+                               ├─ extra_dims (e.g. plev, member)
+layers:        ──►     Layer = [Source, …] in priority order + style + union of times
+  sources                (every gridded variable is also its own layer "<dataset>:<variable>")
+```
+
+* **Grid** ([grid.py](src/geoloupe/grid.py)) describes a rectilinear grid: 1-D cell centres for x and
+  y and a CRS. It finds the spatial dimensions (CF `axis`, `standard_name`, common names), the CRS (config
+  override, CF `grid_mapping` with `crs_wkt`/`spatial_ref` or CF parameters, or lat/lon coordinates),
+  and turns coordinates into *fractional cell positions* (regular axes by arithmetic, irregular ones such
+  as Gaussian latitudes by binary search). Longitudes wrap: global grids in 0…360 or −180…180 both
+  work, and so do regional grids that cross the antimeridian.
+* **TimeAxis** ([timeaxis.py](src/geoloupe/timeaxis.py)) labels times in ISO 8601 and matches
+  requests to the nearest time within a tolerance (default: half a step for monthly or coarser data, at
+  most 12 h otherwise, so sparsely sampled daily data never show a neighbouring day). It works in each axis'
+  own calendar, so cftime calendars (`noleap`, `360_day`) from climate models are supported.
+* **Levels** come from (a) the dataset itself, if it is a multiscale Zarr group, (b) an explicit list
+  of copies at other resolutions (`levels:`), or (c) an external overview store (`overviews:`). Each
+  level has its own time axis: overviews may exist for only part of the period, and the engine then
+  falls back to finer levels for the other times.
+
+### Point observations
+
+Point sources ([points.py](src/geoloupe/points.py)) are tables (CSV, Parquet, GeoParquet; long or wide,
+columns detected) or CF timeSeries NetCDF/Zarr. Every variable is a point layer `<source>:<variable>`, and
+any point layer can be drawn over a gridded layer. For a layer and a day, the server returns the
+stations in a compact JSON list, read from Parquet with filter push-down (only that day; hive `year=`
+partitions pruned) and cached per day; time axes of very large tables come from Parquet statistics. The browser draws them as
+circles with the layer's colour scale (a MapLibre `interpolate` expression built from the same lookup
+table), so observation and grid are compared by eye; hover adds the numbers and their difference.
+
+## 4. A tile request, step by step
+
+`GET /api/layers/tas/tiles/7/67/45.bin?time=1978-07-15`
+
+1. **Cache.** The engine's LRU cache (bytes-bounded) is keyed by (layer, tile, time, dims). Hits return
+   immediately.
+2. **For each source of the layer, in priority order** (finest first by default):
+   1. *Zoom window and time.* Sources outside their configured zoom window, or without data at this
+      time (within the tolerance), are skipped and the reason is recorded.
+   2. *Level choice.* The screen pixel size is computed in the source's CRS units (lat/lon grids:
+      degrees in x and y; projected grids: a pyproj transform at the tile centre). The preferred level
+      is the **coarsest level whose cells are no larger than a pixel in both directions**, so no detail
+      that the screen could show is lost. Levels without the requested time are not considered.
+   3. *Read budget.* The read window (the grid cells the tile covers, clipped to the grid) is computed
+      from the cell positions of the tile's pixel edges. If it exceeds `max_read_cells` the next
+      coarser level is tried; if none fits, the source is skipped with reason `cost`. A regional
+      source is cheap even at zoom 0, because the window is clipped to its extent.
+   4. *Read.* One `isel` per contiguous column run (two runs at the antimeridian), through xarray's
+      lazy backend arrays — no dask graph. CF decoding (`scale_factor`, `_FillValue`) gives floats with
+      NaN for missing data.
+   5. *Resample to the tile.*
+      * **Lat/lon grids (separable fast path).** Web Mercator is separable, so the cells of each output
+        row depend only on latitude and the cells of each column only on longitude. Each pixel takes
+        the **mean of the cells whose centres lie inside it**, computed exactly for all pixels at once
+        with an integral image (summed-area table, float64) of values and valid counts. When a pixel is
+        smaller than a cell, it takes the cell under its centre. `min`/`max` and `nearest` are also
+        available; `nearest` is the default for categorical variables (`flag_values`, land cover).
+      * **Projected grids** (LAEA, rotated pole, UTM, …): pixel centres are transformed with pyproj and
+        the containing cell is taken (nearest). Build overviews for proper means at low zoom.
+   6. *Unit transform* (`scale`, `offset` from the layer config).
+   7. *Composite.* Pixels still empty take this source's finite values; the source index is recorded
+      per pixel. When no pixel is empty, the remaining sources are not read at all.
+3. **Encode.** Body = 256 × 256 float32 values, byte-shuffled, followed by 256 × 256 uint8 source
+   indices; gzip; headers `X-GeoLoupe-Sources` (source:level:pixels) and `X-GeoLoupe-Skipped`
+   (source:reason). An empty tile is HTTP 204 with the same headers. See
+   [docs/data-tiles.md](docs/data-tiles.md).
+
+In the browser, MapLibre decides which tiles are visible and requests `geoloupe://<spec>/{z}/{x}/{y}`.
+The protocol handler fetches the data tile (from its own cache if possible), colours it with the
+current colour scale and returns an `ImageBitmap`. A "spec" is an immutable description of what to
+draw (layer, time, dims, colour scale, optional subtrahend); every change makes a new spec and a new
+MapLibre source, added on top of the old one, which is removed only after the new tiles have loaded.
+That double buffering keeps time animation and colour changes free of flicker.
+
+### Curvilinear grids
+
+A grid with 2-D longitude/latitude keeps its cells as they are: `Grid.locate()` finds the nearest cell
+centre of every pixel with a KD-tree on 3-D unit vectors (no special cases at the date line or the
+poles) and leaves pixels empty beyond ¾ of a cell. The resulting per-pixel (row, col) plan is the same
+as for projected grids, so reading, compositing, queries and exports are shared. Coarser levels are
+views of every 2nd, 4th, … cell, so low zooms stay within the read budget.
+
+Small grids (≤ `field_cache_cells`, e.g. ERA5's 1440 × 721 or a 1° ocean model) are read whole
+once per time step and every tile cuts its window from memory. Stores whose chunks hold a whole
+field, or many time steps (CMIP6), would otherwise be decompressed again for every tile.
+
+### Mosaics and STAC
+
+A `mosaic:` (a list of files) or a `stac:` search is expanded when the catalog opens into hidden
+member datasets, one per file, opened in parallel. Each variable becomes one composite layer over the
+members, in order, so the first file with data at a pixel wins (for STAC: the best item by
+`sortby`). RGB layers record the channel of each source; the engine composites each channel over its
+sources the same way, so true colour works across many scenes.
+
+### Vector overlays
+
+`vectors:` files are read once per server (pyogrio/GDAL, or pyarrow for GeoParquet), reprojected to
+lon/lat, optionally filtered and simplified, and sent as one GeoJSON document
+(`/api/vectors/{id}.geojson`, gzip, cached by the browser). MapLibre tiles and simplifies it per zoom
+on the client (geojson-vt) and draws it between the data and the station circles. Polygons always get
+a fill layer, transparent when no fill colour is set, so that hovering inside a region finds it. This
+suits overlays up to a few hundred thousand features (limit `max_vector_mb`); larger collections need
+vector tiles (roadmap).
+
+### Featured views and previews
+
+A configuration can list `views:` (layer, time, place, colour scale, optional comparison). The
+client shows them as a start screen (the gallery) when the URL has no state. A view is exactly the
+state of a shareable link: opening it sets the URL hash, and the normal start-up restores it, so there
+is no second code path. Each card has a preview from `GET /api/layers/{id}/preview.png?center=lon,lat&zoom=z&width&height`:
+a Web Mercator window of any size centred on a point, stitched from the same (cached) tiles as the
+map and coloured once (colormap, RGB stretch or class colours).
+
+## 5. What the user sees, and what it means
+
+GeoLoupe shows three kinds of numbers. They are deliberately different:
+
+| Where | Value | Resolution |
+|---|---|---|
+| Map pixel and **hover** read-out | The value of the displayed pixel: a mean of the source cells inside the pixel (or an overview level, itself a block mean) | Display resolution; the read-out names the source and level |
+| **Click** (inspector table, time series) | The stored value of the native grid cell under the point, for every source | Native resolution |
+| **Export** (NetCDF) | The native cells inside the box, with the source attributes | Native resolution |
+
+The **provenance badge** at the top of the map always lists the sources and levels on screen, with
+their share of pixels and whether they are native or overview data, and says when a source is hidden
+because it is too expensive at this zoom.
+
+Known approximations (documented, not hidden):
+
+* Block means on lat/lon grids are **not area-weighted**. Across a block of height Δ (radians) the
+  cos(latitude) cell areas vary by about tan(φ)·Δ: 0.9 % for a 0.5° block at 45°, 3 % for a 1° block at
+  60°. The effect on the mean is smaller still (it is a weight error, not a value error) and grows toward
+  the poles. Overviews use the same unweighted mean; area weighting is on the roadmap.
+* A screen pixel takes the cells whose **centres** fall inside it, not an area-weighted share of
+  partly covered cells (that would be conservative remapping). At the edges of fine data this can
+  shift a boundary by up to half a cell.
+* **Difference maps** (A − B) subtract two layers sampled on the same screen pixels, each at its own
+  best level. They show where A and B differ at the displayed resolution; they are not a regridding.
+* **Overview edges.** When a grid size is not a multiple of the factor, the last overview row/column
+  is a block mean of the remaining cells but is placed as if the block were full, up to f/2 native
+  cells beyond the grid edge (e.g. 0.67° past 90° S at factor 4 of a 0.25° grid with 522 rows).
+* **Compositing** assumes the sources describe the same quantity in the same units (unit conversion
+  is configured per source). It does not blend at the boundary: the fine source simply wins where it
+  has data.
+
+## 6. Technology choices and alternatives
+
+| Component | Choice | Alternatives considered | Why |
+|---|---|---|---|
+| Data access | **xarray** (lazy, no dask by default) with zarr-python 3, h5netcdf/scipy, cfgrib, rioxarray, kerchunk refs | Format-specific readers; GDAL for everything | xarray is the common model of the Pangeo ecosystem, decodes CF metadata and supports every needed format. Dask graphs add overhead for small window reads, so it is only used for multi-file NetCDF. |
+| Tile engine | **Own engine** on numpy + pyproj (~500 lines) | TiTiler / rio-tiler `XarrayReader`; xpublish-tiles | Neither returns float data tiles with automatic level selection, and neither composites several datasets of different resolution per pixel. rio-tiler warps through GDAL for every tile and has no multiscale choice for xarray. xpublish-tiles (the closest match, with excellent grid coverage) renders PNG on the server. The engine copies their best ideas (cost budget, advertised minimum zoom, separable lat/lon path). |
+| Multi-resolution storage | **External overviews**, block means in the native grid, Zarr v3 with GeoZarr `multiscales` + `proj` + `spatial` v0.1 metadata | Web Mercator pyramids (ndpyramid); on-the-fly coarsening only; overviews inside the source store | Native grid keeps values traceable and serves any projection. External stores work with read-only archives and do not duplicate level 0. The GeoZarr conventions let other tools (xpublish-tiles, zarr-layer, OpenLayers GeoZarr, titiler-eopf) read the same pyramid. On-the-fly coarsening alone cannot serve a 900 M-cell grid at zoom 0. |
+| API | **FastAPI** | Starlette alone; xpublish plugin; Django | Typed endpoints, automatic OpenAPI docs at `/api/docs`, the standard in this ecosystem (TiTiler, xpublish). |
+| Tile format | **float32, byte-shuffled, gzip** + uint8 source map | PNG (server colormap); `.npy` (TiTiler); LERC; RGB-packed floats for MapLibre `raster-dem` | Exact values, NaN for missing data, simple to decode, about 2× better compression than unshuffled floats. PNG would make every colour change a refetch and loses the values. |
+| Map library | **MapLibre GL JS v6** + custom protocol | deck.gl `TileLayer` + custom shader; OpenLayers WebGLTile; CesiumJS; Leaflet | MapLibre handles tiling, LOD, caching, globe projection and vector basemaps with labels above the data. The protocol handler is about 80 lines. OpenLayers' WebGL tiles are the strongest float-raster alternative (GPU colormaps, any CRS) and are the documented fallback. deck.gl adds weight for no gain at this stage; Cesium is for full 3D; Leaflet has no WebGL. |
+| Colouring | **CPU** in the protocol handler (≈0.3 ms per tile) | WebGL2 custom layer; `raster-dem` + `color-relief` | Simple, exact NaN transparency, same LUT as the server. A GPU path is on the roadmap if profiling shows a need. |
+| UI | **React 19 + zustand + uPlot** | Vanilla TS; Svelte; Plotly/ECharts | React is what most contributors know; zustand is a 1 kB store; uPlot draws long daily series (13 000+ points) fast and small. |
+| Colormaps | One **LUT file** (matplotlib, cmocean, Crameri) for server and client | matplotlib at runtime | Identical colours everywhere, no matplotlib dependency at run time. |
+
+## 7. Performance
+
+Measured on one compute node (72-core Arm CPU, data on a busy Lustre file system) with a large private
+store — a 30″ ≈ 1 km global daily dataset (20 880 × 43 200 cells × 13 864 days, uint16, sharded Zarr
+v3) over a 0.25° reanalysis — and with public data read over the internet. Full numbers, conditions
+and the script: [docs/benchmarks.md](docs/benchmarks.md).
+
+| Request | Time |
+|---|---|
+| Composite tile, zoom 2–4, 1 km data from overviews | 14–33 ms |
+| Composite tile, zoom 4–5, 1 km data native (≤ 6 M cells read, no overviews) | 76–95 ms |
+| Composite tile, zoom ≥ 6, 1 km data native | 6–14 ms |
+| Tile from the server cache | 3–20 ms (incl. gzip of the response) |
+| Point query (native cells of all sources) | 9–10 ms |
+| One year of daily values at a point, two sources | 4.7 s cold, 0.3–0.5 s warm |
+| Remote Sentinel-2 COG tile over HTTPS (internal overview chosen per zoom) | 0.3–0.9 s cold |
+| Remote ARCO-ERA5 tile over HTTPS (1.3 million hourly steps) | 1.0–1.5 s cold |
+| 16 cold Sentinel-2 RGB tiles (3 remote COGs each), in parallel | 2.0 s (13.3 s with a global read lock) |
+| Opening the whole gallery (ERA5 Zarr, 6 DEM + 4 Sentinel-2 + 1 WorldCover COGs, 21 station CSVs) | 5–15 s |
+| Overview build, two variables, one year of 1 km daily data, 32 workers | 18.5 min, 12 GB |
+
+Data tiles are 10–100 kB after gzip (a PNG of the same tile: ~30 kB). The main levers are the chunk
+layout (720 × 720 inner chunks make windows cheap; whole-globe chunks make point series read a full
+field per time step) and overviews for low zoom. A fresh process on a busy parallel file system pays
+tens of seconds for imports and first reads, so the server warms up its main layers in a background
+thread at start.
+
+## 8. Deployment
+
+* **Local:** `geoloupe serve config.yaml` (uvicorn). The web client is a static bundle inside the
+  Python package, so no Node.js is needed to run it.
+* **HPC:** run on a compute node; open through an SSH tunnel, or through jupyter-server-proxy. All
+  client URLs are relative, so a path prefix such as `/user/<name>/proxy/8000/` works.
+* **Notebook:** `geoloupe.show({"era5": ds})` starts the server in a background thread and displays
+  the map inline (any in-memory or lazily opened xarray Dataset).
+* **Security:** the API is read-only. It serves only datasets named in the configuration; static file
+  paths are confined to the bundled client. There is no authentication (bind to `127.0.0.1`, the
+  default, or put it behind an authenticating proxy). CORS is open by default for read-only use and is
+  configurable.
+
+### Opening data at run time
+
+`POST /api/datasets` ("Add data") is off unless the server allows remote URLs (`--allow-open`) or
+local folders (`--open-root`); local paths are resolved (symlinks, `..`) and must stay below a
+root. The new dataset is opened by a small catalog of its own and merged into the running one, so
+data already open is not touched; vector and point files go to their registries.
+
+## 9. Extension points
+
+| To add … | Change |
+|---|---|
+| A file format | a branch in [readers.py](src/geoloupe/readers.py) returning an xarray Dataset |
+| A grid type (curvilinear, UGRID, HEALPix) | a new planner in [engine.py](src/geoloupe/engine.py) next to `plan_separable` / `plan_projected` |
+| An aggregation | `resample()` in the engine and `block_reduce()` in [overviews.py](src/geoloupe/overviews.py) |
+| A colormap | an entry in [scripts/build_colormaps.py](scripts/build_colormaps.py), then regenerate |
+| A tile matrix set (polar stereographic, EPSG:4326 tiles) | `tiling.Tile` (MapLibre v6.15 supports custom projections) |
+| An API endpoint | [api/app.py](src/geoloupe/api/app.py) |

geoloupe-0.1.0/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to GeoLoupe. The format follows [Keep a Changelog](https://keepachangelog.com/),
+and versions follow [Semantic Versioning](https://semver.org/) (before 1.0, minor versions may change
+the configuration format; such changes are listed here).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-11-06
+
+First public version.
+
+### Data
+- Gridded data from Zarr v2/v3, NetCDF 3/4 (also many files as one), GRIB, GeoTIFF/COG and
+  kerchunk references; local, HTTPS, S3 (public buckets need no setup) and GCS.
+- Grids: regular and irregular lat/lon in either longitude convention, projected CRSs, rotated pole,
+  and curvilinear grids with 2-D longitude/latitude (ocean models, WRF, CMIP6 native grids).
+- Layers that combine datasets of different resolution per pixel; mosaics of many files; STAC
+  searches and items; RGB composites (true and false colour); categorical data with class names
+  and colours; fixed-time sources for static fields.
+- Stations and point data (CSV, Parquet, GeoParquet, CF timeSeries NetCDF) as layers and overlays.
+- Vector overlays (GeoJSON, Shapefile, GeoPackage, FlatGeobuf, KML, GML, GeoParquet).
+- Overview pyramids in the native grid (`geoloupe overviews build`, GeoZarr conventions v0.1).
+
+### Web client
+- Float data tiles coloured in the browser: instant colour changes, real values on hover and click,
+  a badge that names the data and resolution on screen.
+- Time slider and playback, time series, side-by-side and difference comparison, PNG and NetCDF
+  export, shareable links, a gallery of featured views, "Add data" (off unless allowed).
+
+### Tools
+- `geoloupe serve | gallery | info | demo-data | overviews build`; `geoloupe.show()` in notebooks.
+- The gallery: ERA5, Copernicus DEM, Sentinel-2 (STAC), ESA WorldCover, a CMIP6 climate model ocean,
+  NOAA stations and Natural Earth overlays, all read live from public archives.
+
+[Unreleased]: https://github.com/salmanmohebi/geoloupe/compare/v0.1.0...HEAD
+[0.1.0]: https://github.com/salmanmohebi/geoloupe/releases/tag/v0.1.0

geoloupe-0.1.0/CITATION.cff

@@ -0,0 +1,18 @@
+cff-version: 1.2.0
+message: "If you use GeoLoupe in your research, please cite it as below."
+title: "GeoLoupe: interactive, multi-resolution exploration of large geodata in the browser"
+type: software
+authors:
+  - family-names: Mohebi
+    given-names: Salman
+license: Apache-2.0
+repository-code: "https://github.com/salmanmohebi/geoloupe"
+keywords:
+  - xarray
+  - zarr
+  - climate data
+  - geospatial
+  - visualization
+  - web map
+version: 0.1.0
+date-released: "2026-11-06"

geoloupe-0.1.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,10 @@
+# Code of conduct
+
+GeoLoupe follows the [Contributor Covenant, version 2.1](https://www.contributor-covenant.org/version/2/1/code_of_conduct/).
+
+In short: be respectful and welcoming, assume good intent, and focus on what is best for the
+community and the science. Harassment and personal attacks are not accepted in issues, pull
+requests, discussions or any other project space.
+
+To report unacceptable behaviour, contact the maintainer privately (see the maintainer's GitHub
+profile). Reports are handled confidentially.