geo-morpher 0.1.0

package/README.md

@@ -0,0 +1,513 @@
+# geo-morpher
+
+Imperative GeoJSON morphing utilities for animating between regular geography and cartograms, packaged as a native JavaScript library with a MapLibre-first adapter and optional Leaflet helpers for DOM-heavy experiences.
+
+![](demo.gif)
+
+
+## Installation
+
+```bash
+npm install geo-morpher
+```
+
+Bring your own MapLibre or Leaflet instance (both listed as peer dependencies). MapLibre is the default rendering path and ships with GPU-accelerated layers; Leaflet stays available when you need direct DOM access.
+
+### Choosing an adapter
+
+- MapLibre adapter (`createMapLibreMorphLayers`, `createMapLibreGlyphLayer`) is the default. Use it for performance, style expression control, and WebGL-based effects.
+- Leaflet adapter (`createLeafletMorphLayers`, `createLeafletGlyphLayer`) remains supported for teams who want to manipulate markers, tooltips, or UI directly in the DOM.
+- Both adapters share the same `GeoMorpher` core, so you can swap adapters without recalculating morph data.
+- Examples under `examples/browser/` demonstrate both integrations; switch adapters by loading the corresponding entry point.
+
+## Usage
+
+Project structure highlights:
+
+```text
+src/
+  core/            # GeoMorpher core engine
+  adapters/        # Integration helpers (Leaflet, etc.)
+  lib/             # Shared runtime utilities (OSGB projection)
+  utils/           # Data enrichment and projection helpers
+data/              # Sample Oxford LSOA datasets
+examples/          # Runnable native JS scripts
+test/              # node:test coverage for core behaviours
+```
+
+### MapLibre adapter
+
+- `createMapLibreMorphLayers` provisions GeoJSON sources and fill layers for regular, cartogram, and interpolated geometries, exposing an `updateMorphFactor` helper to drive tweening from UI controls.
+- `createMapLibreGlyphLayer` renders glyphs with `maplibregl.Marker` instances; enable `scaleWithZoom` to regenerate glyph markup as users zoom.
+- Pass your MapLibre namespace explicitly (`maplibreNamespace: maplibregl`) when calling glyph helpers in module-bundled builds where `maplibregl` is not attached to `globalThis`.
+- For heavy glyph scenes, consider upgrading to a [CustomLayerInterface](https://www.maplibre.org/maplibre-gl-js/docs/API/interfaces/CustomLayerInterface/) implementation that batches drawing on the GPU. The marker pipeline keeps the API simple while offering a documented migration path.
+- Track ongoing enhancements and open items in `docs/maplibre-migration-plan.md` before adopting advanced features like custom shader glyphs.
+
+### Leaflet adapter
+
+- `createLeafletMorphLayers` keeps the existing DOM-centric workflow for basemap blur/fade effects and marker overlays.
+- `createLeafletGlyphLayer` accepts any HTML, SVG, Canvas, or Leaflet icon—handy when you need tooltips, popups, and other DOM components under full control.
+- The basemap effect still uses DOM filters (`blur`, `opacity`, `grayscale`) and can target any Leaflet layer container.
+- Stick with Leaflet when you require deep integration with existing Leaflet plugins or server-rendered markup; migrate to MapLibre later without touching your data preparation code.
+
+#### MapLibre basemap effects
+
+`createMapLibreMorphLayers` accepts a `basemapEffect` configuration that interpolates paint properties on existing style layers as the morph factor changes. This mirrors the Leaflet DOM-based blur/fade behaviour while staying inside the MapLibre style system.
+
+```js
+const morph = await createMapLibreMorphLayers({
+  morpher,
+  map,
+  basemapEffect: {
+    layers: ["basemap", "basemap-labels"],
+    properties: {
+      "raster-opacity": [1, 0.15],
+      "raster-brightness-max": { from: 1, to: 1.4 },
+    },
+    propertyClamp: {
+      "raster-brightness-max": [0, 2],
+    },
+    easing: (t) => t * t, // optional easing curve
+  },
+});
+
+// Update morph factor, basemap effect adjusts automatically
+morph.updateMorphFactor(0.75);
+
+// Apply effect manually (e.g., when animating via requestAnimationFrame)
+morph.applyBasemapEffect(0.5);
+```
+
+- Provide a `layers` string/array or resolver function to target paint properties across multiple layers.
+- Supply ranges (`[from, to]` or `{ from, to }`) for numeric properties such as `raster-opacity`, `fill-opacity`, or `line-opacity`.
+- Use functions in `properties[layerId]` for full control or to manipulate non-numeric paint values.
+- Capture-and-reset logic ensures properties revert to their original values when the effect is disabled.
+- Canvas-style blur is not built-in; use a custom MapLibre layer if a true blur shader is required.
+
+
+### 1. Prepare morphing data
+
+```js
+import { GeoMorpher } from "geo-morpher";
+import regularGeoJSON from "./data/oxford_lsoas_regular.json" assert { type: "json" };
+import cartogramGeoJSON from "./data/oxford_lsoas_cartogram.json" assert { type: "json" };
+
+const morpher = new GeoMorpher({
+  regularGeoJSON,
+  cartogramGeoJSON,
+  data: await fetchModelData(),
+  aggregations: {
+    population: "sum",
+    households: "sum",
+  },
+});
+
+await morpher.prepare();
+
+const regular = morpher.getRegularFeatureCollection();
+const cartogram = morpher.getCartogramFeatureCollection();
+const tween = morpher.getInterpolatedFeatureCollection(0.5);
+```
+
+#### Using custom projections
+
+By default, `GeoMorpher` assumes input data is in **OSGB** (British National Grid) and converts to WGS84 for Leaflet. If your data is in a different coordinate system, pass a custom projection:
+
+```js
+import { GeoMorpher, WGS84Projection, isLikelyWGS84 } from "geo-morpher";
+
+// Auto-detect coordinate system
+const detectedProjection = isLikelyWGS84(regularGeoJSON);
+console.log("Detected:", detectedProjection); // 'WGS84', 'OSGB', or 'UNKNOWN'
+
+// For data already in WGS84 (lat/lng)
+const morpher = new GeoMorpher({
+  regularGeoJSON,
+  cartogramGeoJSON,
+  projection: WGS84Projection, // No transformation needed
+});
+
+// For Web Mercator data
+import { WebMercatorProjection } from "geo-morpher";
+const morpher = new GeoMorpher({
+  regularGeoJSON,
+  cartogramGeoJSON,
+  projection: WebMercatorProjection,
+});
+
+// Custom projection (e.g., using proj4)
+const customProjection = {
+  toGeo: ([x, y]) => {
+    // Transform [x, y] to [lng, lat]
+    return [lng, lat];
+  }
+};
+```
+
+See `examples/custom-projection.js` for detailed examples.
+
+### 2. Drop the morph straight into Leaflet
+
+```js
+import L from "leaflet";
+import { createLeafletMorphLayers } from "geo-morpher";
+
+const basemapLayer = L.tileLayer("https://{s}.tile.openstreetmap.org/{z}/{x}/{y}.png", {
+  attribution: "© OpenStreetMap contributors",
+}).addTo(map);
+
+let blurEnabled = true;
+
+const {
+  group,
+  regularLayer,
+  cartogramLayer,
+  tweenLayer,
+  updateMorphFactor,
+} = await createLeafletMorphLayers({
+  morpher,
+  L,
+  morphFactor: 0.25,
+  regularStyle: () => ({ color: "#1f77b4", weight: 1 }),
+  cartogramStyle: () => ({ color: "#ff7f0e", weight: 1 }),
+  tweenStyle: () => ({ color: "#2ca02c", weight: 2 }),
+  onEachFeature: (feature, layer) => {
+    layer.bindTooltip(`${feature.properties.code}`);
+  },
+  basemapLayer,
+  basemapEffect: {
+    blurRange: [0, 12],
+    opacityRange: [1, 0.05],
+    grayscaleRange: [0, 1],
+    isEnabled: () => blurEnabled,
+  },
+});
+
+group.addTo(map);
+
+// Update the tween geometry whenever you like
+updateMorphFactor(0.75);
+```
+
+Provide either `basemapLayer` (any Leaflet layer with a container) or `basemapEffect.target` to tell the helper which element to manipulate. By default the basemap will progressively blur and fade as the morph factor approaches 1, but you can adjust the ranges—or add brightness/grayscale tweaks—to match your design. You can also wire up UI to toggle the behaviour at runtime by returning `false` from `basemapEffect.isEnabled`.
+
+### 3. Overlay multivariate glyphs
+
+The glyph system is **completely customizable** with no hardcoded chart types. You provide a rendering function that can return any visualization you can create with HTML, SVG, Canvas, or third-party libraries like D3.js or Chart.js. The helper automatically keeps markers positioned and synchronized with the morphing geometry.
+
+**Example with pie charts:**
+
+```js
+import {
+  GeoMorpher,
+  createLeafletMorphLayers,
+  createLeafletGlyphLayer,
+} from "geo-morpher";
+
+const categories = [
+  { key: "population", color: "#4e79a7" },
+  { key: "households", color: "#f28e2c" },
+];
+
+const drawPie = ({ data, feature }) => {
+  const properties = data?.data?.properties ?? feature.properties ?? {};
+  const slices = categories
+    .map(({ key, color }) => ({
+      value: Number(properties[key] ?? 0),
+      color,
+    }))
+    .filter((slice) => slice.value > 0);
+
+  if (slices.length === 0) return null;
+
+  const svg = buildPieSVG(slices); // your own renderer (D3, Canvas, vanilla SVG...)
+  return {
+    html: svg,
+    className: "pie-chart-marker",
+    iconSize: [52, 52],
+    iconAnchor: [26, 26],
+  };
+};
+
+const glyphLayer = await createLeafletGlyphLayer({
+  morpher,
+  L,
+  map,
+  geometry: "interpolated",
+  morphFactor: 0.25,
+  pane: "glyphs",
+  drawGlyph: drawPie,
+});
+
+// Keep glyphs synced with the tweened geometry
+slider.addEventListener("input", (event) => {
+  const value = Number(event.target.value);
+  updateMorphFactor(value);
+  glyphLayer.updateGlyphs({ morphFactor: value });
+});
+```
+
+`drawGlyph` receives `{ feature, featureId, data, morpher, geometry, morphFactor }` and can return:
+
+- `null`/`undefined` to skip the feature
+- A plain HTML string or DOM element
+- An object with `html`, `iconSize`, `iconAnchor`, `className`, `pane`, and optional `markerOptions`
+- Or an object containing a pre-built `icon` (any Leaflet `Icon`), if you need full control
+
+**Configuration object properties:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `html` | string \| HTMLElement | - | Your custom HTML/SVG string or DOM element |
+| `className` | string | `"geomorpher-glyph"` | CSS class for the marker |
+| `iconSize` | [number, number] | `[48, 48]` | Width and height in pixels |
+| `iconAnchor` | [number, number] | `[24, 24]` | Anchor point in pixels (center by default) |
+| `pane` | string | - | Leaflet pane name for z-index control |
+| `markerOptions` | object | `{}` | Additional Leaflet marker options |
+| `divIconOptions` | object | `{}` | Additional Leaflet divIcon options |
+| `icon` | L.Icon | - | Pre-built Leaflet icon (overrides all other options) |
+
+Optionally provide `getGlyphData` or `filterFeature` callbacks to customise how data/visibility is resolved. When you call `glyphLayer.clear()` all markers are removed; `glyphLayer.getState()` exposes the current geometry, morph factor, and marker count.
+
+#### Data contract for glyphs
+
+By default `createLeafletGlyphLayer` will surface whatever the core `GeoMorpher` knows about the current feature via `morpher.getKeyData()`:
+
+| field        | type     | description |
+|--------------|----------|-------------|
+| `feature`    | GeoJSON Feature | The rendered feature taken from the requested geography (`regular`, `cartogram`, or tweened). Includes `feature.properties` and a `centroid` array. |
+enum{} | Resolved via `getFeatureId(feature)` (defaults to `feature.properties.code ?? feature.properties.id`). |
+| `featureId`  | string  | Resolved via `getFeatureId(feature)` (defaults to `feature.properties.code ?? feature.properties.id`). |
+| `data`       | object \| null | When using the built-in lookup this is the morpher key entry: `{ code, population, data }`. The `data` property holds the *enriched* GeoJSON feature returned from `GeoMorpher.prepare()`—handy when you stored additional indicators during enrichment. |
+| `morpher`    | `GeoMorpher` | The instance you passed in, allowing on-demand queries (`getInterpolatedLookup`, etc.). |
+| `geometry`   | string \| function | The geometry source currently in play (`regular`, `cartogram`, or `interpolated`). |
+| `morphFactor`| number  | The morph factor used for the last update (only meaningful when geometry is `interpolated`). |
+
+If you want a different data shape, supply `getGlyphData`:
+
+```js
+const glyphLayer = await createLeafletGlyphLayer({
+  morpher,
+  L,
+  drawGlyph,
+  getGlyphData: ({ featureId }) => externalStatsById[featureId],
+});
+```
+
+The callback receives the same context object (minus the final `data` field) and should return whatever payload your renderer expects. `filterFeature(context)` lets you drop glyphs entirely (return `false`) for a given feature.
+
+#### Alternative chart types and rendering approaches
+
+The glyph system accepts any HTML/SVG content. Here are examples with different visualization types:
+
+**Bar chart:**
+```js
+drawGlyph: ({ data, feature }) => {
+  const values = [data.value1, data.value2, data.value3];
+  const bars = values.map((v, i) => 
+    `<rect x="${i*20}" y="${60-v}" width="15" height="${v}" fill="steelblue"/>`
+  ).join('');
+  
+  return {
+    html: `<svg width="60" height="60">${bars}</svg>`,
+    iconSize: [60, 60],
+    iconAnchor: [30, 30],
+  };
+}
+```
+
+**Using D3.js:**
+```js
+import * as d3 from "d3";
+
+drawGlyph: ({ data }) => {
+  const div = document.createElement('div');
+  div.style.width = '80px';
+  div.style.height = '80px';
+  
+  const svg = d3.select(div).append('svg')
+    .attr('width', 80)
+    .attr('height', 80);
+  
+  // Use D3 to create any visualization
+  svg.selectAll('circle')
+    .data(data.values)
+    .enter().append('circle')
+    .attr('cx', (d, i) => i * 20 + 10)
+    .attr('cy', 40)
+    .attr('r', d => d.radius)
+    .attr('fill', d => d.color);
+  
+  return div; // Return DOM element directly
+}
+```
+
+**Custom icons or images:**
+```js
+drawGlyph: ({ data }) => {
+  return {
+    html: `<img src="/icons/${data.category}.png" width="32" height="32"/>`,
+    iconSize: [32, 32],
+    iconAnchor: [16, 16],
+  };
+}
+```
+
+**Pre-built Leaflet icons:**
+```js
+drawGlyph: ({ data }) => {
+  const icon = L.icon({
+    iconUrl: `/markers/${data.type}.png`,
+    iconSize: [32, 32],
+    iconAnchor: [16, 32],
+    popupAnchor: [0, -32],
+  });
+  
+  return { icon }; // Full control over Leaflet icon
+}
+```
+
+**Sparkline with HTML Canvas:**
+```js
+drawGlyph: ({ data }) => {
+  const canvas = document.createElement('canvas');
+  canvas.width = 80;
+  canvas.height = 40;
+  const ctx = canvas.getContext('2d');
+  
+  // Draw sparkline
+  ctx.strokeStyle = '#4e79a7';
+  ctx.lineWidth = 2;
+  ctx.beginPath();
+  data.timeSeries.forEach((value, i) => {
+    const x = (i / (data.timeSeries.length - 1)) * 80;
+    const y = 40 - (value * 40);
+    i === 0 ? ctx.moveTo(x, y) : ctx.lineTo(x, y);
+  });
+  ctx.stroke();
+  
+  return canvas.toDataURL(); // Return as data URL
+}
+```
+
+#### Zoom-scaling glyphs
+
+By default, glyphs maintain a fixed pixel size regardless of map zoom level (standard Leaflet marker behavior). However, you can enable `scaleWithZoom` to make glyphs resize proportionally with the underlying map features—ideal for waffle charts, heatmap cells, or other visualizations that should fill polygon bounds.
+
+```js
+const glyphLayer = await createLeafletGlyphLayer({
+  morpher,
+  L,
+  map,
+  scaleWithZoom: true, // Enable zoom-responsive sizing
+  drawGlyph: ({ data, feature, featureBounds, zoom }) => {
+    if (!featureBounds) return null;
+    
+    const { width, height } = featureBounds; // Pixel dimensions at current zoom
+    
+    // Create waffle chart that fills the cartogram polygon
+    const gridSize = 10;
+    const cellSize = Math.min(width, height) / gridSize;
+    const fillRatio = data.value / data.max;
+    const filledCells = Math.floor(gridSize * gridSize * fillRatio);
+    
+    const cells = [];
+    for (let i = 0; i < gridSize; i++) {
+      for (let j = 0; j < gridSize; j++) {
+        const index = i * gridSize + j;
+        const filled = index < filledCells;
+        cells.push(
+          `<rect x="${j * cellSize}" y="${i * cellSize}" 
+                 width="${cellSize}" height="${cellSize}" 
+                 fill="${filled ? '#4e79a7' : '#e0e0e0'}"/>`
+        );
+      }
+    }
+    
+    return {
+      html: `<svg width="${width}" height="${height}">${cells.join('')}</svg>`,
+      iconSize: [width, height],
+      iconAnchor: [width / 2, height / 2],
+    };
+  },
+});
+```
+
+When `scaleWithZoom` is enabled:
+- `featureBounds` provides `{ width, height, center, bounds }` in pixels at the current zoom level
+- `zoom` provides the current map zoom level
+- Glyphs automatically update when users zoom in/out
+- Call `glyphLayer.destroy()` to clean up zoom listeners when removing the layer
+
+A complete example is available at `examples/browser/zoom-scaling-glyphs.html`.
+
+### Legacy wrapper
+
+If you previously relied on the `geoMorpher` factory from the Observable notebook, it is still available:
+
+```js
+import { geoMorpher } from "geo-morpher";
+
+const result = await geoMorpher({
+  regularGeoJSON,
+  cartogramGeoJSON,
+  data,
+  aggregations,
+  morphFactor: 0.5,
+});
+
+console.log(result.tweenLookup);
+```
+
+### Native JS example
+
+A runnable script using the bundled Oxford datasets lives in `examples/native.js`:
+
+```bash
+node examples/native.js
+```
+
+It loads `data/oxford_lsoas_regular.json` and `data/oxford_lsoas_cartogram.json`, mirrors their population/household properties into a basic dataset, and prints counts plus a sample tweened feature—all without any bundlers or UI frameworks.
+
+### Native browser examples (Leaflet & MapLibre)
+
+Serve the browser demos to see geo-morpher running on top of either Leaflet or MapLibre without a build step. Dependencies are resolved via import maps to CDN-hosted ES modules.
+
+```bash
+npm run examples:browser
+```
+
+Then open:
+- Leaflet demo: <http://localhost:4173/examples/browser/index.html>
+- MapLibre demo: <http://localhost:4173/examples/browser/maplibre/index.html>
+
+Each demo provides a morph slider and glyph overlays; the MapLibre version showcases GPU-driven rendering, paint-property basemap fading, and DOM marker glyphs running through the new adapter. (An internet connection is required to fetch CDN-hosted modules and map tiles.)
+
+**Additional examples:**
+- `examples/browser/maplibre/index.html` - MapLibre adaptation with basemap paint-property effects and layer toggles
+- `examples/browser/zoom-scaling-glyphs.html` - Demonstrates zoom-responsive waffle charts that resize to fill cartogram polygons as you zoom in/out
+
+## Testing
+
+Run the bundled smoke tests with:
+
+```bash
+npm test
+```
+
+## Build & publish
+
+- `npm run build` compiles ESM and CJS bundles to `dist/` via Rollup.
+- `npm run clean` removes the generated `dist/` folder prior to fresh builds.
+- Publishing runs `npm run build` automatically through the `prepare` hook; verify outputs before executing `npm publish`.
+
+## Roadmap & pending updates
+
+- GPU-batched glyph rendering via MapLibre `CustomLayerInterface` remains on the roadmap for high-volume scenes—follow progress in `docs/maplibre-migration-plan.md`.
+- Adapter-level automated tests (Jest + MapLibre mocks) are planned to complement the current core-only test suite.
+- Post-processing basemap effects (true blur, grayscale for vector tiles) are being explored as custom layers; today, stick to opacity/brightness tweaks via `basemapEffect`.
+- Globe projection support will land after the MapLibre adapter stabilizes on the current release line; expect a follow-up example once the API settles.
+
+## License
+
+MIT

package/data/indonesia/indonesia-grid.csv

@@ -0,0 +1,39 @@
+ID,Provinsi,Initials,row,col
+11,Aceh,ACE,1,1
+51,Bali,BAL,7,7
+36,Banten,BAN,6,3
+17,Bengkulu,BEN,4,1
+34,Daerah Istimewa Yogyakarta,DIY,7,5
+31,Daerah Khusus Ibukota Jakarta,JKT,6,4
+75,Gorontalo,GOR,2,8
+15,Jambi,JAM,3,2
+32,Jawa Barat,JBR,7,4
+33,Jawa Tengah,JTG,6,5
+35,Jawa Timur,JTM,6,6
+61,Kalimantan Barat,KBA,3,4
+63,Kalimantan Selatan,KSL,4,5
+62,Kalimantan Tengah,KTG,4,4
+64,Kalimantan Timur,KTI,3,5
+65,Kalimantan Utara,KUT,2,5
+19,Kepulauan Bangka Belitung,BKB,4,2
+21,Kepulauan Riau,KEP,2,3
+18,Lampung,LAM,5,2
+81,Maluku,MAL,5,10
+82,Maluku Utara,MUT,4,10
+52,Nusa Tenggara Barat,NTB,7,8
+53,Nusa Tenggara Timur,NTT,7,9
+91-A,Papua,PAP,4,13
+92-A,Papua Barat,PAB,4,12
+92-B,Papua Barat Daya,PBD,3,12
+91-B,Papua Pegunungan,PPG,5,13
+91-C,Papua Selatan,PSL,6,13
+91-D,Papua Tengah,PTG,5,12
+14,Riau,RIA,2,2
+76,Sulawesi Barat,SBR,4,7
+73,Sulawesi Selatan,SSL,5,7
+72,Sulawesi Tengah,STN,3,8
+74,Sulawesi Tenggara,STG,4,8
+71,Sulawesi Utara,SUT,2,9
+13,Sumatera Barat,SBP,3,1
+16,Sumatera Selatan,SSE,5,1
+12,Sumatera Utara,SUM,2,1