geo-morpher 0.1.0 → 0.1.2

package/README.md

@@ -1,9 +1,23 @@
 # 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.
+[![npm version](https://badge.fury.io/js/geo-morpher.svg)](https://badge.fury.io/js/geo-morpher)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+GeoJSON morphing utilities for animating between regular geography and cartograms, packaged as a native JavaScript library with a MapLibre-first adapter and Leaflet compatibility helpers.
 
 ![](demo.gif)
 
+To quickly create a grid cartogram, checkout my other library: ![gridmapper](https://danylaksono.is-a.dev/gridmapper/demo/).
+
+
+## Features
+
+- **MapLibre & Leaflet Adapters**: High-performance MapLibre-first implementation with Leaflet compatibility helpers.
+- **Generic Morphing Engine**: Smoothly interpolates between any two aligned GeoJSON geometries using `flubber`.
+- **Multivariate Glyphs**: Highly customizable DOM/SVG/Canvas overlays (charts, icons, sparklines) that stay synced with morphing geometry.
+- **Basemap Effects**: Synchronized fading, blurring, or grayscale effects for basemap layers during transitions.
+- **Projection Agnostic**: Auto-detects WGS84 (lat/lng) data; defaults to OSGB (British National Grid) for UK data but supports any CRS via `proj4`.
+
 
 ## Installation
 
@@ -11,44 +25,16 @@ Imperative GeoJSON morphing utilities for animating between regular geography an
 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.
+Leaflet is provided as a peer dependency—bring your own Leaflet instance when using the compatibility helpers. MapLibre remains the default adapter and is bundled as a dependency for out-of-the-box usage; if your build already supplies `maplibre-gl`, mark it as external to avoid duplicating the library.
 
 ## 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
+### MapLibre adapter (default)
 
 - `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
 
@@ -109,44 +95,32 @@ const cartogram = morpher.getCartogramFeatureCollection();
 const tween = morpher.getInterpolatedFeatureCollection(0.5);
 ```
 
-#### Using custom projections
+#### Projections & Coordinate Systems
 
-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:
+While `geo-morpher` was born out of UK-centric cartography, it is fully generic. It internally projects all data to WGS84 (latitude/longitude) for mapping compatibility.
 
-```js
-import { GeoMorpher, WGS84Projection, isLikelyWGS84 } from "geo-morpher";
+- **Auto-detection**: If no projection is provided, `GeoMorpher` inspects your coordinates. If they look like WGS84, it uses them as-is.
+- **OSGB Default**: If coordinates fall outside the geographic range, it assumes OSGB (EPSG:27700) and transforms them to WGS84.
+- **Manual Override**: Pass a helper like `WebMercatorProjection` or a custom `proj4` wrapper for other systems.
 
-// Auto-detect coordinate system
-const detectedProjection = isLikelyWGS84(regularGeoJSON);
-console.log("Detected:", detectedProjection); // 'WGS84', 'OSGB', or 'UNKNOWN'
+```js
+import { GeoMorpher, WGS84Projection, createProj4Projection } from "geo-morpher";
+import proj4 from "proj4";
 
-// For data already in WGS84 (lat/lng)
-const morpher = new GeoMorpher({
-  regularGeoJSON,
-  cartogramGeoJSON,
-  projection: WGS84Projection, // No transformation needed
-});
+// 1. Auto-detected (usually works for WGS84 or OSGB)
+const morpher = new GeoMorpher({ regularGeoJSON, cartogramGeoJSON });
 
-// For Web Mercator data
-import { WebMercatorProjection } from "geo-morpher";
-const morpher = new GeoMorpher({
-  regularGeoJSON,
-  cartogramGeoJSON,
-  projection: WebMercatorProjection,
-});
+// 2. Explicit WGS84 (Identity)
+const morpher = new GeoMorpher({ ..., projection: WGS84Projection });
 
-// Custom projection (e.g., using proj4)
-const customProjection = {
-  toGeo: ([x, y]) => {
-    // Transform [x, y] to [lng, lat]
-    return [lng, lat];
-  }
-};
+// 3. Custom Projection (e.g., UTM Zone 33N)
+const projection = createProj4Projection("+proj=utm +zone=33 +datum=WGS84", proj4);
+const morpher = new GeoMorpher({ ..., projection });
 ```
 
-See `examples/custom-projection.js` for detailed examples.
+See `examples/maplibre/projections/index.html` for a browser-based custom projection demo.
 
-### 2. Drop the morph straight into Leaflet
+### 2. Drop the morph straight into Leaflet (compat)
 
 ```js
 import L from "leaflet";
@@ -195,6 +169,8 @@ Provide either `basemapLayer` (any Leaflet layer with a container) or `basemapEf
 
 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.
 
+See the full glyphs guide: `docs/glyphs.md`
+
 **Example with pie charts:**
 
 ```js
@@ -245,6 +221,24 @@ slider.addEventListener("input", (event) => {
   updateMorphFactor(value);
   glyphLayer.updateGlyphs({ morphFactor: value });
 });
+
+// You can also decouple glyphs from the GeoMorpher by providing a
+// `featureCollection` or a live `featureProvider({ geometry, morphFactor })`:
+//
+// const glyph = await createLeafletGlyphLayer({
+//   drawGlyph,
+//   L,
+//   featureCollection: morpher.getRegularFeatureCollection(), // static set
+// });
+//
+// const glyphProvider = await createLeafletGlyphLayer({
+//   drawGlyph,
+//   L,
+//   featureProvider: ({ geometry, morphFactor }) => morpher.getInterpolatedFeatureCollection(morphFactor),
+// });
+//
+// The adapters also export small helper functions to convert normalized glyph values
+// into platform-specific objects: `createLeafletIcon` and `createMapLibreMarkerData`.
 ```
 
 `drawGlyph` receives `{ feature, featureId, data, morpher, geometry, morphFactor }` and can return:
@@ -276,7 +270,6 @@ By default `createLeafletGlyphLayer` will surface whatever the core `GeoMorpher`
 | 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.). |
@@ -439,7 +432,7 @@ When `scaleWithZoom` is enabled:
 - 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`.
+A complete example is available at `examples/leaflet/zoom-scaling-glyphs.html`.
 
 ### Legacy wrapper
 
@@ -459,17 +452,11 @@ const result = await geoMorpher({
 console.log(result.tweenLookup);
 ```
 
-### Native JS example
+### Node script (removed)
 
-A runnable script using the bundled Oxford datasets lives in `examples/native.js`:
+The previous Node-only example has been removed in favor of browser-based demos under `examples/maplibre` and `examples/leaflet`.
 
-```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)
+### Native browser examples (MapLibre & Leaflet)
 
 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.
 
@@ -478,14 +465,17 @@ 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>
+- MapLibre demo: <http://localhost:4173/examples/maplibre/index.html>
+- Indonesia (MapLibre): <http://localhost:4173/examples/maplibre/indonesia/index.html>
+- MapLibre (Projections): <http://localhost:4173/examples/maplibre/projections/index.html>
+- Leaflet demo: <http://localhost:4173/examples/leaflet/index.html>
+- Leaflet zoom-scaling: <http://localhost:4173/examples/leaflet/zoom-scaling-glyphs.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
+- `examples/maplibre/index.html` - MapLibre adaptation with basemap paint-property effects and layer toggles
+- `examples/leaflet/zoom-scaling-glyphs.html` - Demonstrates zoom-responsive waffle charts that resize to fill cartogram polygons as you zoom in/out
 
 ## Testing
 
@@ -495,19 +485,15 @@ Run the bundled smoke tests with:
 npm test
 ```
 
-## Build & publish
+## Author
 
-- `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.
+Dany Laksono
 
 ## License
 
 MIT
+
+## Documentation
+
+- API Reference: `docs/api.md`
+- Glyphs Guide: `docs/glyphs.md`