notebooks: binder-runnable reader demos (hhdc_viewer, waveform_viewer)

.binder/environment.yml

@@ -8,11 +8,17 @@
 # there is a single source of truth for the notebook dependencies (pyproject.toml).
 #
 # Only PyPI/conda-forge resolvable packages appear here: no ``git+`` URLs and no
-# spherely fork. The Binder-runnable notebooks read synthetic data, the public
-# anonymous source.coop store, or anonymous CMR-STAC granule *metadata*
-# (jupyterhub_example, shardmap_viewer) -- all of which use the default HEALPix
-# ``mortie`` backend, so the exact-S2 spherely SpatialIndex backend is never on
-# their import path.
+# spherely fork. The two Binder notebooks (hhdc_viewer, waveform_viewer) READ the
+# anonymous public source.coop demo stores and build no catalogs at all, so no
+# SpatialIndex backend is on their import path -- exact-S2 spherely least of all.
+#
+# NOTE (2026-08-26): ``postBuild`` still installs ``[analysis,catalog,viz]``, but
+# ``catalog`` (stac-geoparquet) and ``viz`` (ipyleaflet) were carried for the
+# jupyterhub_example / shardmap_viewer notebooks, which have been archived off
+# main. Neither remaining notebook imports them, so both extras -- and much of
+# ``analysis`` -- are now dead weight in the image and could be trimmed to speed
+# the build. Left in place rather than trimmed blind: that is a dependency
+# change, and the image is not the place to discover a transitive need.
 name: zagg-binder
 channels:
   - conda-forge

.binder/postBuild

@@ -30,3 +30,13 @@ else
     HATCH_VCS_PRETEND_VERSION="0.0.0+binder" \
         python -m pip install --no-cache-dir ".[analysis,catalog,viz]"
 fi
+
+# The reader-only demos (notebooks/hhdc_viewer.ipynb, notebooks/waveform_viewer.ipynb)
+# run on mortie + moczarr and never import zagg internals, so their runtime is NOT a
+# zagg extra -- each notebook carries its own `%pip install` line and stays runnable
+# outside Binder. Two of those packages must be in the IMAGE rather than installed
+# from a cell, because they ship Jupyter frontend extensions that a running kernel
+# cannot pick up: ipympl (the `%matplotlib widget` backend hhdc_viewer's rotatable
+# 3-D view needs) and ipywidgets (the sliders and dropdowns both use). moczarr itself
+# is pure Python, so the notebooks' own `%pip install` covers it either way.
+python -m pip install --no-cache-dir ipympl ipywidgets

README.md

@@ -127,27 +127,26 @@ The store path and output grid parameters are defined in the YAML config (`outpu
 
 ### Step 4: Visualize Results
 
-The output Zarr is a public DGGS dataset. The included notebook rasterizes HEALPix cells to a polar stereographic grid for fast rendering with `imshow`.
+The output Zarr is a public DGGS dataset. The included notebooks read it back anonymously — a paired 3-D view of one shard, and the cell-level GEDI × ATL03 digest join.
 
 ```bash
-uv run jupyter notebook notebooks/rasterized_zarr.ipynb
+uv run jupyter notebook notebooks/hhdc_viewer.ipynb
 ```
 
-Adjust `GRID_SPACING` in the notebook to control output resolution.
-
 ## Example Notebooks
 
-The notebooks under `notebooks/` run on [Binder](https://mybinder.org/v2/gh/englacial/zagg/main?urlpath=lab/tree/notebooks) — no install, no credentials. They install `zagg[analysis]` via the `.binder/` conda config and read only synthetic in-notebook data or the **anonymous, public** [source.coop](https://source.coop/englacial/zagg/benchmarks) benchmark store.
+The notebooks under `notebooks/` run on [Binder](https://mybinder.org/v2/gh/englacial/zagg/main?urlpath=lab/tree/notebooks) — no install, no credentials. Both are **reader-only**: they import `mortie` + `moczarr[zagg]` and nothing from zagg itself, reading the anonymous, public [source.coop](https://source.coop/englacial/zagg) demo stores (ICESat-2 ATL03 + GEDI L1B over California and the NEON AOP sites). Each carries its own `%pip install` line, so they run outside Binder unchanged.
 
 | Notebook | What it shows | Binder |
 |----------|---------------|--------|
-| `custom_aggregations.ipynb` | Config-driven aggregation API on synthetic data | [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/englacial/zagg/main?urlpath=lab/tree/notebooks/custom_aggregations.ipynb) |
-| `rasterized_zarr.ipynb` | Rasterize the published HEALPix store to an 8 km polar-stereo grid | [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/englacial/zagg/main?urlpath=lab/tree/notebooks/rasterized_zarr.ipynb) |
-| `jupyterhub_example.ipynb` | Drive the API from a science hub; read & visualize a published result | [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/englacial/zagg/main?urlpath=lab/tree/notebooks/jupyterhub_example.ipynb) |
-| `cryocloud_example.ipynb` | End-to-end ISMIP6 read + **AWS Lambda fan-out** on CryoCloud | **not Binder-runnable** (needs live AWS + Earthdata credentials) |
-| `cost_reporting.ipynb` | Max / estimated / actual invoke cost + progress-bar dispatch wrapper | [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/englacial/zagg/main?urlpath=lab/tree/notebooks/cost_reporting.ipynb) |
+| `hhdc_viewer.ipynb` | Polygon → MOC → shard → **rotatable paired 3-D view** (ATL03 + GEDI), binned or exact → numpy tensors | [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/englacial/zagg/main?urlpath=lab/tree/notebooks/hhdc_viewer.ipynb) |
+| `waveform_viewer.ipynb` | The cell-level join: one GEDI footprint against the 2×2 ATL03 cells beneath it, both from stored digests | [![Binder](https://mybinder.org/badge_logo.svg)](https://mybinder.org/v2/gh/englacial/zagg/main?urlpath=lab/tree/notebooks/waveform_viewer.ipynb) |
+
+They share `notebooks/viewers.py`, which holds the drawing so the notebooks stay about the read path. The two are split because one needs `%matplotlib widget` for its rotatable 3-D view and the other `%matplotlib inline`; the backends collide in a single kernel.
+
+**Archived notebooks.** The earlier examples (`custom_aggregations`, `rasterized_zarr`, `jupyterhub_example`, `cryocloud_example`, `cost_reporting`, `aoi_mask`, `shardmap_viewer`, `tdigest_reader_example`, `sentinel2_fusion`) were written against older APIs and had drifted out of date — stale documentation being worse than none. They are preserved on the [`claude/archive-notebooks-2026-08-26`](https://github.com/englacial/zagg/tree/claude/archive-notebooks-2026-08-26/notebooks) branch and removed from `main`.
 
-`cryocloud_example.ipynb` is the only Lambda demo; it dispatches to a deployed AWS Lambda and reads private-account S3 via the CryoCloud IRSA role, so it cannot run on Binder.
+`hhdc_viewer.ipynb` and `waveform_viewer.ipynb` are **reader-only**: they run on `mortie` + `moczarr[zagg]` with no zagg-internal imports, reading the anonymous public [source.coop](https://source.coop/englacial/zagg) demo stores (ICESat-2 ATL03 + GEDI L1B over California and the NEON AOP sites). Each carries its own `%pip install` line, so they run outside Binder unchanged. They are split in two because `hhdc_viewer` needs `%matplotlib widget` for its rotatable 3-D view and `waveform_viewer` needs `%matplotlib inline` — the two backends collide in one kernel.
 
 ## Project Structure
 

docs/aoi_mask.md

@@ -198,7 +198,7 @@ strict = ds.where(ds["aoi_mask"])
   equivalent `(lats, lons)` ring.
 
 See the runnable, data-free example in
-[`notebooks/aoi_mask.ipynb`](https://github.com/englacial/zagg/blob/main/notebooks/aoi_mask.ipynb),
+[`aoi_mask.ipynb`](https://github.com/englacial/zagg/blob/claude/archive-notebooks-2026-08-26/notebooks/aoi_mask.ipynb) (archived — see the note below),
 which builds a small HEALPix grid + AOI box and shows the mask is `True` exactly
 for the in-AOI cells. The notebook is self-contained (no remote data) and runs
 anywhere `zagg` (with `mortie>=0.8.3`) is installed. Binder launch additionally

docs/index.md

@@ -59,7 +59,7 @@ See [Lambda Deployment](deployment/lambda.md) for AWS setup.
 ### 3. Visualize results
 
 ```bash
-uv run jupyter notebook notebooks/rasterized_zarr.ipynb
+uv run jupyter notebook notebooks/hhdc_viewer.ipynb
 ```
 
 ## Design Philosophy

docs/quickstart.md

@@ -64,7 +64,7 @@ cells. The processing step consumes this file.
 To inspect the chunking interactively -- shard outlines, granule footprints,
 and a grid that appears on zoom -- use the shard-map viewer
 (`pip install zagg[viz]`). See the
-[shard-map viewer notebook](https://github.com/englacial/zagg/blob/main/notebooks/shardmap_viewer.ipynb),
+[shard-map viewer notebook](https://github.com/englacial/zagg/blob/claude/archive-notebooks-2026-08-26/notebooks/shardmap_viewer.ipynb) (archived),
 which runs on a synthetic example (no network needed) and includes manual
 in-browser verification instructions.
 
@@ -202,7 +202,7 @@ excludes is reported as **not applicable** — `touch_skipped_paths` in the run
 record — never as a failure.
 
 See `src/zagg/configs/atl06.yaml` for a complete example and the
-[custom aggregations notebook](https://github.com/englacial/zagg/blob/main/notebooks/custom_aggregations.ipynb)
+[custom aggregations notebook](https://github.com/englacial/zagg/blob/claude/archive-notebooks-2026-08-26/notebooks/custom_aggregations.ipynb) (archived)
 for customization examples.
 
 ## Reading the output
@@ -212,6 +212,6 @@ reconstructs dense, spatially faithful `(64, 64, n_bins)` tensors — with an
 occupancy mask and a shared `(offset, gain)` z-window per block (the
 [reader contract](ragged_layout.md#spatially-faithful-tensors-deinterleave-blocks-mask))
 — or lossless raw value vectors from the stored digests. The
-[t-digest reader notebook](https://github.com/englacial/zagg/blob/main/notebooks/tdigest_reader_example.ipynb)
+[t-digest reader notebook](https://github.com/englacial/zagg/blob/claude/archive-notebooks-2026-08-26/notebooks/tdigest_reader_example.ipynb) (archived)
 walks through `read_tensors` and `read_raw_values` end to end on a self-contained
 synthetic store.