How geojupyter/prototype-map2cell-ipyopenlayers works
1. What this repository is
- ipyopenlayers is a Jupyter widget package that bridges Python in the notebook kernel to an OpenLayers-based map UI in the browser.
- The architecture is split into a Python backend package and a TypeScript/Javascript frontend widget communicating through the Jupyter widget protocol.
2. Python package boundary
- The Python side lives under ipyopenlayers/.
- openlayers.py is the main user-facing API layer for creating and configuring maps, layers, overlays, and controls from Python.
- _frontend.py, _version.py, and __init__.py support widget registration/versioning and package exposure.
- ipyopenlayers/nbextension/extension.js is the classic Notebook extension entrypoint.
3. Frontend widget boundary
- The browser-side implementation is in src/.
- src/index.ts is the main export surface.
- The widget is decomposed into feature modules such as layer.ts, basecontrol.ts, baseoverlay.ts, widget.ts, and plugin.ts, with concrete features in geojson.ts, geotifflayer.ts, heatmap.ts, imageoverlay.ts, popupoverlay.ts, rastertilelayer.ts, vectortilelayer.ts, video_overlay.ts, fullscreen.ts, mouseposition.ts, scaleline.ts, and zoomslider.ts.
4. Primary runtime flow
- Python code constructs widget objects and sends serialized state/updates to the frontend.
- The frontend instantiates the OpenLayers map and applies those state changes to layers, overlays, and controls.
- User interactions in the browser feed back through widget state, enabling notebook-driven interactivity.
5. Core architectural abstraction
- The repository centers on a small set of reusable OpenLayers concepts:
- a base map/widget container,
- layers,
- overlays,
- controls.
- The feature-specific modules are layered on top of those abstractions, which makes the architecture extensible without changing the transport boundary.
6. Static asset and packaging path
- webpack.config.js, package.json, tsconfig.json, and Babel/Jest config files define the frontend build pipeline.
- The built browser asset is packaged back into the Python distribution via ipyopenlayers/nbextension/extension.js and Python packaging metadata in setup.py, pyproject.toml, MANIFEST.in, and ipyopenlayers.json / install.json.
7. Testing strategy
- Unit-style frontend tests live in src/__tests__/ and use Jest.
- Python-side tests live in ipyopenlayers/tests/ and verify packaging/extension behavior.
- End-to-end notebook UI tests live under ui-tests/ and use Playwright against Jupyter Server/Lab notebooks, which is important because the real product behavior depends on the Python-to-browser integration.
8. Documentation and examples as architecture examples
- docs/ is substantial and organized by feature area: map, layers, controls, overlay, installation, and development.
- examples/ contains notebooks for each supported feature, acting as executable integration examples for the widget API.
- The docs/examples double as a catalog of supported feature boundaries and expected interactions.
9. Supported feature groups
- Layers: GeoJSON, GeoTIFF, heatmap, raster tile, vector tile.
- Controls: fullscreen, mouse position, scale line, zoom slider.
- Overlays: image, popup, video.
- These are not separate apps; they are modular capabilities mounted into the same widget/map runtime.
10. Data and geospatial assets
- Sample geospatial inputs such as europe_110.geo.json and examples/data/TopoJson/world-110m.json are used by docs and examples to demonstrate layer rendering.
- This indicates the repo is not just UI plumbing; it includes geospatial data ingestion and visualization concerns.
11. Delivery targets
- The package is designed for both classic Jupyter Notebook and JupyterLab, with nbextension/labextension support reflected in the build and install files.
- The docs also reference JupyterLite, so the frontend is expected to work in browser-only notebook environments as well.
12. Important diagram boundaries to show
- Draw a clear boundary between Python notebook/kernel state and browser/OpenLayers runtime.
- Inside the browser boundary, show a single widget host with pluggable controls/layers/overlays.
- Around that, show packaging/build/test/documentation subsystems as supporting infrastructure rather than runtime dependencies.
Main entry points: widget.ts Widget host · layer.ts Layer base · basecontrol.ts Control base · baseoverlay.ts Overlay base
Components 30
Python package
Notebook/kernel-facing API and widget registration
- OpenLayers API · Main user-facing Python API for constructing and configuring maps, layers, overlays, and controls.
ipyopenlayers/openlayers.py - Package init · Exports the public Python package surface.
ipyopenlayers/__init__.py - Frontend bridge · Registers the frontend widget model/view and connects the Python package to the browser implementation.
ipyopenlayers/_frontend.py - Versioning · Package version metadata shared with the frontend build.
ipyopenlayers/_version.py - Nbextension entry · Classic Notebook extension entrypoint that loads the packaged browser asset.
ipyopenlayers/nbextension/extension.js
Browser runtime
TypeScript widget and OpenLayers UI implementation
- Widget host · Core browser-side widget container that manages the OpenLayers map instance and synced state.
src/widget.ts - Widget plugin · Integration layer for registering the widget with the Jupyter widget system.
src/plugin.ts - Index exports · Top-level frontend export surface for the widget package.
src/index.ts - Layer base · Shared layer abstraction used by concrete map layers.
src/layer.ts - Overlay base · Shared overlay abstraction used by popup/image/video overlays.
src/baseoverlay.ts - Control base · Shared control abstraction used by map controls.
src/basecontrol.ts - GeoJSON layer · Vector layer implementation for GeoJSON data.
src/geojson.ts - GeoTIFF layer · Raster/geospatial image layer implementation for GeoTIFF inputs.
src/geotifflayer.ts - Heatmap · Heatmap visualization layer.
src/heatmap.ts - Raster tiles · Raster tile layer implementation.
src/rastertilelayer.ts - Vector tiles · Vector tile layer implementation.
src/vectortilelayer.ts - Image overlay · Georeferenced image overlay implementation.
src/imageoverlay.ts - Popup overlay · Popup overlay implementation for map annotations and callouts.
src/popupoverlay.ts - Video overlay · Video overlay implementation.
src/video_overlay.ts - Fullscreen · Fullscreen map control.
src/fullscreen.ts - Mouse position · Mouse position control.
src/mouseposition.ts - Scale line · Scale line control.
src/scaleline.ts - Zoom slider · Zoom slider control.
src/zoomslider.ts
Support
Build, packaging, docs, examples, and test infrastructure
- Build pipeline · Frontend build and bundling configuration for the distributed widget asset.
webpack.config.js - Python packaging · Package metadata and installation wiring for distributing the built widget.
setup.py - Docs site · Narrative documentation and feature reference for map, layers, controls, overlays, and installation.
docs/index.rst - Examples · Executable notebooks demonstrating the main widget features and interactions.
examples/map.ipynb - UI tests · End-to-end notebook UI tests that exercise the Python-to-browser integration.
ui-tests/tests/ipyopenlayers.test.ts - Python tests · Python-side tests for packaging and nbextension behavior.
ipyopenlayers/tests/test_nbextension_path.py - JS tests · Frontend unit tests for widget behavior and DOM APIs.
src/__tests__/index.spec.ts
Connections 30
- Package init → OpenLayers API: re-exports · Package init exposes the main Python API.
- OpenLayers API → Frontend bridge: creates widgets · Python constructs widget objects backed by the frontend bridge.
- Frontend bridge → Versioning: shares version · Python widget metadata is aligned with package versioning.
- Frontend bridge → Nbextension entry: registers asset · Frontend bridge is delivered through the notebook extension entrypoint.
- Nbextension entry → Widget host: loads · Notebook extension loads the browser widget runtime.
- Index exports → Widget plugin: exports · Top-level frontend entrypoint exports widget registration pieces.
- Widget plugin → Widget host: registers · Plugin wires the widget host into the Jupyter runtime.
- Widget host → Layer base: manages · Widget host composes and updates layers.
- Widget host → Overlay base: manages · Widget host composes and updates overlays.
- Widget host → Control base: manages · Widget host composes and updates controls.
- Layer base → GeoJSON layer: specializes · GeoJSON is a concrete layer implementation.
- Layer base → GeoTIFF layer: specializes · GeoTIFF is a concrete layer implementation.
- Layer base → Heatmap: specializes · Heatmap is a concrete layer implementation.
- Layer base → Raster tiles: specializes · Raster tiles are a concrete layer implementation.
- Layer base → Vector tiles: specializes · Vector tiles are a concrete layer implementation.
- Overlay base → Image overlay: specializes · Image overlay is a concrete overlay implementation.
- Overlay base → Popup overlay: specializes · Popup overlay is a concrete overlay implementation.
- Overlay base → Video overlay: specializes · Video overlay is a concrete overlay implementation.
- Control base → Fullscreen: specializes · Fullscreen is a concrete control implementation.
- Control base → Mouse position: specializes · Mouse position is a concrete control implementation.
- Control base → Scale line: specializes · Scale line is a concrete control implementation.
- Control base → Zoom slider: specializes · Zoom slider is a concrete control implementation.
- Build pipeline → Widget host: bundles · Build pipeline produces the browser widget asset.
- Python packaging → Frontend bridge: packages · Python packaging ships the frontend bridge and extension metadata.
- Docs site → Examples: references · Documentation is illustrated by notebooks and feature examples.
- Docs site → Widget host: describes · Docs explain the widget runtime and supported features.
- Examples → OpenLayers API: demonstrates · Example notebooks exercise the Python API.
- UI tests → Widget host: validates · End-to-end tests validate the browser widget behavior.
- Python tests → Python packaging: validates · Python tests validate packaging and nbextension wiring.
- JS tests → Widget host: validates · Frontend unit tests validate widget behavior and DOM integration.