geo-morpher 0.1.1 → 0.1.2

package/README.md

@@ -7,10 +7,16 @@ GeoJSON morphing utilities for animating between regular geography and cartogram
 
 ![](demo.gif)
 
+To quickly create a grid cartogram, checkout my other library: ![gridmapper](https://danylaksono.is-a.dev/gridmapper/demo/).
 
-## Status
 
-This library is currently in early-stage development (v0.1.0) and has recently completed a migration to a MapLibre-first adapter. The core morphing engine is stable, but the MapLibre adapter is new and under active development. Leaflet compatibility is maintained. Community feedback and contributions are welcome.
+## 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
@@ -19,30 +25,16 @@ This library is currently in early-stage development (v0.1.0) and has recently c
 npm install geo-morpher
 ```
 
-Bring your own MapLibre or Leaflet instance (both listed as peer dependencies). MapLibre is the default adapter; Leaflet remains supported for backward compatibility.
+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 browser demos (MapLibre & Leaflet)
-test/              # node:test coverage for core behaviours
-```
-
 ### 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 relying on the adapter in production.
 
 #### MapLibre basemap effects
 
@@ -103,39 +95,27 @@ 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.
+
+- **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.
 
 ```js
-import { GeoMorpher, WGS84Projection, isLikelyWGS84 } from "geo-morpher";
+import { GeoMorpher, WGS84Projection, createProj4Projection } from "geo-morpher";
+import proj4 from "proj4";
 
-// Auto-detect coordinate system
-const detectedProjection = isLikelyWGS84(regularGeoJSON);
-console.log("Detected:", detectedProjection); // 'WGS84', 'OSGB', or 'UNKNOWN'
+// 1. Auto-detected (usually works for WGS84 or OSGB)
+const morpher = new GeoMorpher({ regularGeoJSON, cartogramGeoJSON });
 
-// For data already in WGS84 (lat/lng)
-const morpher = new GeoMorpher({
-  regularGeoJSON,
-  cartogramGeoJSON,
-  projection: WGS84Projection, // No transformation needed
-});
+// 2. Explicit WGS84 (Identity)
+const morpher = new GeoMorpher({ ..., projection: WGS84Projection });
 
-// 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];
-  }
-};
+// 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/maplibre/projections/index.html` for a browser-based custom projection demo.
@@ -241,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:
@@ -487,6 +485,10 @@ Run the bundled smoke tests with:
 npm test
 ```
 
+## Author
+
+Dany Laksono
+
 ## License
 
 MIT