geogrid 1.1.1 → 1.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geogrid",
-  "version": "1.1.1",
+  "version": "1.2.0",
   "description": "Regular and irregular geoJSON grids ",
   "main": "src/index.js",
   "module": "src/index.js",
@@ -41,20 +41,26 @@
     "@turf/boolean-intersects": "^7.2.0",
     "@turf/boolean-point-in-polygon": "^7.1.0",
     "@turf/boolean-within": "^7.2.0",
+    "@turf/centroid": "^7.2.0",
     "@turf/helpers": "^7.1.0",
     "@turf/intersect": "^7.1.0",
     "@turf/length": "^7.2.0",
     "@turf/line-split": "^7.2.0",
+    "@turf/rewind": "^7.2.0",
     "d3-array": "^3.2.4",
     "d3-delaunay": "^6.0.4",
     "d3-geo": "^3.1.1",
     "d3-geo-projection": "^4.0.0",
+    "d3-geo-voronoi": "^2.1.0",
     "docs": "^0.3.2-canary.0",
     "documentation": "^14.0.3",
     "geojson2h3": "^1.2.0",
     "h3-js": "^4.1.0",
+    "martinez-polygon-clipping": "^0.7.4",
     "rbush": "^4.0.1",
-    "rollup": "^4.10.0"
+    "rollup": "^4.10.0",
+    "s2-geometry": "^1.2.10",
+    "s2js": "^1.43.6"
   },
   "devDependencies": {
     "@jood/jsdoc-theme": "^0.1.14",

package/src/grid/square_sph.js

@@ -0,0 +1,98 @@
+import { createSteppedArray } from "../helpers/createSteppedArray.js";
+import booleanIntersects from "@turf/boolean-intersects";
+
+/**
+ * @function square_sph
+ * @summary Compute a square grid in WGS84 degrees.
+ * @description Builds a square grid in latitude/longitude degrees,
+ * avoids coordinates exactly at ±180 or ±90 to prevent rewind issues.
+ * @param {object} options
+ * @param {number[]} [options.start=[-180, -90]] - Starting coordinates [lon, lat].
+ * @param {number} [options.width=360] - Width of the grid in degrees (longitude span).
+ * @param {number} [options.height=180] - Height of the grid in degrees (latitude span).
+ * @param {number} [options.step=1] - Step size in degrees.
+ * @param {GeoJSON.Feature|GeoJSON.FeatureCollection|GeoJSON.Geometry} [options.domain] -
+ *   Optional GeoJSON object. Only cells that intersect this domain are kept.
+ * @returns {GeoJSON.FeatureCollection} A GeoJSON FeatureCollection of polygons.
+ */
+export function square_sph({
+  start = [-180, -90],
+  width = 360,
+  height = 180,
+  step = 1,
+  domain = null,
+} = {}) {
+  const LON_MIN = -180;
+  const LON_MAX = 180;
+  const LAT_MIN = -90;
+  const LAT_MAX = 90;
+  const EPS = 1e-2; // petit décalage pour éviter ±180 et ±90 exacts
+
+  const lonStart = Math.max(LON_MIN, start[0]);
+  const latStart = Math.max(LAT_MIN, start[1]);
+  const lonEnd = Math.min(LON_MAX, start[0] + width);
+  const latEnd = Math.min(LAT_MAX, start[1] + height);
+
+  let x = createSteppedArray(lonStart + step / 2, lonEnd - step / 2, step);
+  let y = createSteppedArray(
+    latStart + step / 2,
+    latEnd - step / 2,
+    step,
+    true
+  );
+
+  const features = [];
+  let i = 0;
+
+  for (const lon of x) {
+    for (const lat of y) {
+      // coins initiaux
+      let lonWest = lon - step / 2;
+      let lonEast = lon + step / 2;
+      let latSouth = lat - step / 2;
+      let latNorth = lat + step / 2;
+
+      // remplacer ±180 et ±90 par des valeurs légèrement inférieures/supérieures
+      if (lonWest <= LON_MIN) lonWest = LON_MIN + EPS;
+      if (lonEast >= LON_MAX) lonEast = LON_MAX - EPS;
+      if (latSouth <= LAT_MIN) latSouth = LAT_MIN + EPS;
+      if (latNorth >= LAT_MAX) latNorth = LAT_MAX - EPS;
+
+      features.push({
+        type: "Feature",
+        geometry: {
+          type: "Polygon",
+          coordinates: [
+            [
+              [lonWest, latNorth],
+              [lonEast, latNorth],
+              [lonEast, latSouth],
+              [lonWest, latSouth],
+              [lonWest, latNorth],
+            ],
+          ],
+        },
+        properties: { index: i++ },
+      });
+    }
+  }
+
+  // Domain
+  let filtered = features;
+  if (domain) {
+    filtered = features.filter((f) => {
+      try {
+        return booleanIntersects(f, domain);
+      } catch {
+        return false;
+      }
+    });
+  }
+
+  return {
+    type: "FeatureCollection",
+    grid: "square_sph",
+    geo: true,
+    features: filtered,
+  };
+}

package/src/helpers/sphere.js

@@ -0,0 +1,41 @@
+import { polygon, featureCollection } from "@turf/helpers";
+
+/**
+ * Crée un polygone approximatif de la sphère projetée dans le plan SVG
+ * et le retourne dans une FeatureCollection
+ * @param {d3.GeoProjection} projection - La projection D3 utilisée pour le SVG
+ * @param {number} [stepDeg=5] - Pas en degrés pour approximer la sphère
+ * @returns {GeoJSON.FeatureCollection} - FeatureCollection contenant le polygone Turf de la sphère projetée
+ */
+export function sphere(projection, stepDeg = 5) {
+  const coords = [];
+
+  // contour supérieur (latitude 90°)
+  for (let lon = -180; lon <= 180; lon += stepDeg) {
+    const pt = projection([lon, 90]);
+    if (pt) coords.push(pt);
+  }
+
+  // contour droit (longitude 180°)
+  for (let lat = 90; lat >= -90; lat -= stepDeg) {
+    const pt = projection([180, lat]);
+    if (pt) coords.push(pt);
+  }
+
+  // contour inférieur (latitude -90°)
+  for (let lon = 180; lon >= -180; lon -= stepDeg) {
+    const pt = projection([lon, -90]);
+    if (pt) coords.push(pt);
+  }
+
+  // contour gauche (longitude -180°)
+  for (let lat = -90; lat <= 90; lat += stepDeg) {
+    const pt = projection([-180, lat]);
+    if (pt) coords.push(pt);
+  }
+
+  const poly = polygon([coords]);
+
+  // Retourner une FeatureCollection pour être compatible avec Turf intersect
+  return featureCollection([poly]);
+}

package/src/helpers/stitchmerge.js

@@ -0,0 +1,144 @@
+/**
+ * Takes a GeoJSON and processes each MultiPolygon feature that
+ * crosses the antimeridian, converting it into a continuous Polygon feature.
+ */
+export function stitchmerge(geojson) {
+  // Helper: adjust longitude relative to previous one to handle wrapping around ±180°
+  function adjustLonToPrev(lon, prevLon) {
+    if (prevLon === null || prevLon === undefined) return lon;
+    // Normalize angular difference to be within [-180, 180]
+    while (lon - prevLon > 180) lon -= 360;
+    while (prevLon - lon > 180) lon += 360;
+    return lon;
+  }
+
+  // Helper: remove consecutive duplicate points (with a small tolerance)
+  function dedupeConsecutive(points) {
+    const out = [];
+    for (let i = 0; i < points.length; i++) {
+      const p = points[i];
+      const prev = out.length ? out[out.length - 1] : null;
+      if (
+        !prev ||
+        Math.abs(prev[0] - p[0]) > 1e-12 ||
+        Math.abs(prev[1] - p[1]) > 1e-12
+      ) {
+        out.push(p);
+      }
+    }
+    return out;
+  }
+
+  // Helper: ensure the ring is closed (first == last point)
+  function closeRing(ring) {
+    if (!ring.length) return ring;
+    const first = ring[0];
+    const last = ring[ring.length - 1];
+    if (
+      Math.abs(first[0] - last[0]) > 1e-12 ||
+      Math.abs(first[1] - last[1]) > 1e-12
+    ) {
+      ring.push([first[0], first[1]]);
+    }
+    return ring;
+  }
+
+  // Process one MultiPolygon geometry -> returns a merged Polygon geometry
+  function processMultiPolygonGeometry(multiCoords) {
+    // multiCoords: Array of polygons; each polygon is an array of rings.
+    // We treat the outer ring (index 0) of each polygon as a possible fragment
+    // of a single continuous outer ring that needs to be reconnected.
+    // Additional rings (holes) are collected and preserved as holes.
+    const exteriorRings = [];
+    const interiorRings = [];
+
+    for (let p = 0; p < multiCoords.length; p++) {
+      const polygon = multiCoords[p];
+      if (!polygon || !polygon.length) continue;
+      // polygon[0] is the exterior ring
+      exteriorRings.push(polygon[0].slice());
+      // if polygon has holes, collect them
+      for (let r = 1; r < polygon.length; r++) {
+        interiorRings.push(polygon[r].slice());
+      }
+    }
+
+    // Unwrap all exterior rings so that longitudes are continuous
+    const unwrappedExteriors = [];
+    let prevLon = null;
+    for (let i = 0; i < exteriorRings.length; i++) {
+      const ring = exteriorRings[i];
+      const newRing = [];
+      for (let j = 0; j < ring.length; j++) {
+        let [lon, lat] = ring[j];
+        lon = adjustLonToPrev(lon, prevLon);
+        newRing.push([lon, lat]);
+        prevLon = lon;
+      }
+      const trimmed = dedupeConsecutive(newRing);
+      unwrappedExteriors.push(trimmed);
+    }
+
+    // Merge all unwrapped exterior rings into a single continuous ring
+    // We remove internal closures and only close at the end
+    let mergedExterior = [];
+    for (let i = 0; i < unwrappedExteriors.length; i++) {
+      const ring = unwrappedExteriors[i].slice();
+      // remove last point if it's equal to the first (closed ring)
+      if (ring.length > 1) {
+        const f = ring[0];
+        const l = ring[ring.length - 1];
+        if (Math.abs(f[0] - l[0]) < 1e-12 && Math.abs(f[1] - l[1]) < 1e-12) {
+          ring.pop();
+        }
+      }
+      mergedExterior = mergedExterior.concat(ring);
+    }
+
+    // Deduplicate consecutive identical points
+    mergedExterior = dedupeConsecutive(mergedExterior);
+    // Close the final merged ring
+    mergedExterior = closeRing(mergedExterior);
+
+    // Unwrap interior rings (holes) so they match the unwrapped longitude system
+    const unwrappedInteriors = interiorRings.map((ring) => {
+      const out = [];
+      for (let i = 0; i < ring.length; i++) {
+        const anchorLon = mergedExterior.length ? mergedExterior[0][0] : null;
+        let lon = ring[i][0];
+        if (anchorLon !== null) {
+          while (lon - anchorLon > 180) lon -= 360;
+          while (anchorLon - lon > 180) lon += 360;
+        }
+        out.push([lon, ring[i][1]]);
+      }
+      return closeRing(dedupeConsecutive(out));
+    });
+
+    // Return a single Polygon geometry: outer + holes
+    const coords = [mergedExterior].concat(unwrappedInteriors);
+    return { type: "Polygon", coordinates: coords };
+  }
+
+  // MAIN: process all features
+  const out = {
+    ...geojson,
+    features: (geojson.features || []).map((feature) => {
+      if (!feature || !feature.geometry) return feature;
+      const geom = feature.geometry;
+      if (geom.type === "MultiPolygon") {
+        try {
+          const newGeom = processMultiPolygonGeometry(geom.coordinates);
+          return { ...feature, geometry: newGeom };
+        } catch (e) {
+          console.warn("Error stitching a MultiPolygon:", e);
+          return feature; // fallback to original geometry
+        }
+      }
+      // Leave other geometries unchanged
+      return feature;
+    }),
+  };
+
+  return out;
+}

package/src/helpers/unstitch.js

@@ -0,0 +1,31 @@
+import { geoProject } from "d3-geo-projection";
+import { rewind } from "geotoolbox";
+import { geoEquirectangular } from "d3-geo";
+
+/**
+ * @function unstitch
+ * @description After Matthieu Viry: https://observablehq.com/@mthh/unstitch
+ */
+
+export function unstitch(a) {
+  a = JSON.parse(JSON.stringify(a));
+  a = geoProject(
+    a,
+    geoEquirectangular()
+      .scale(180 / Math.PI)
+      .translate([0, 0])
+  );
+
+  for (const f of a.features) {
+    if (f.geometry.type === "Polygon")
+      f.geometry.coordinates.forEach((ring) =>
+        ring.forEach((point) => (point[1] *= -1))
+      );
+    else if (f.geometry.type === "MultiPolygon")
+      f.geometry.coordinates.forEach((poly) =>
+        poly.forEach((ring) => ring.forEach((point) => (point[1] *= -1)))
+      );
+  }
+
+  return rewind(a, { simple: true });
+}

package/src/index.js

@@ -1,11 +1,21 @@
+// Planar grids
 export { square } from "./grid/square.js";
 export { triangle } from "./grid/triangle.js";
 export { dot } from "./grid/dot.js";
 export { random } from "./grid/random.js";
 export { diamond } from "./grid/diamond.js";
 export { hexbin } from "./grid/hexbin.js";
+
+// Spherical grids
+export { square_sph } from "./grid/square_sph.js";
 export { h3 } from "./grid/h3.js";
+
+// Operators
 export { pointstogrid } from "./operator/pointstogrid.js";
 export { polygonstogrid } from "./operator/polygonstogrid.js";
 export { linestogrid } from "./operator/linestogrid.js";
+
+// Helpers
 export { project } from "./helpers/project.js";
+export { unstitch } from "./helpers/unstitch.js";
+export { sphere } from "./helpers/sphere.js";

package/src/operator/linestogrid.js

@@ -1,6 +1,8 @@
 import { bbox } from "@turf/bbox";
 import { lineSplit } from "@turf/line-split";
 import { length } from "@turf/length";
+import { stitchmerge } from "../helpers/stitchmerge.js";
+import { unstitch } from "../helpers/unstitch.js";
 import RBush from "rbush";
 
 /**
@@ -18,16 +20,21 @@ import RBush from "rbush";
  * @property {boolean} [values=false] - Include array of raw lines properties
  */
 export function linestogrid(opts = {}) {
-  const {
+  let {
     grid,
     lines,
-    grid_id = "index",
     var: varField,
     values: includeValues = false,
+    spherical = false,
   } = opts;
 
   const t0 = performance.now();
 
+  // Unstitch grids if needed
+  if (spherical) {
+    grid = unstitch(grid);
+  }
+
   // --- Normalize varField to array ---
   const varFields = varField
     ? Array.isArray(varField)
@@ -104,5 +111,5 @@ export function linestogrid(opts = {}) {
     ).toFixed(2)} ms`
   );
 
-  return filteredGrid;
+  return spherical ? stitchmerge(filteredGrid) : filteredGrid;
 }

package/src/operator/pointstogrid.js

@@ -1,6 +1,8 @@
 import RBush from "rbush";
 import { bbox } from "@turf/bbox";
 import booleanPointInPolygon from "@turf/boolean-point-in-polygon";
+import { stitchmerge } from "../helpers/stitchmerge.js";
+import { unstitch } from "../helpers/unstitch.js";
 
 /**
  * @function pointstogrid
@@ -11,12 +13,23 @@ import booleanPointInPolygon from "@turf/boolean-point-in-polygon";
  * @property {object} [grid] - GeoJSON grid (polygons)
  * @property {string|Array} [var] - Field(s) for summing values
  * @property {boolean} [values=false] - Include array of raw point properties
+ * @property {boolean} [spherical=false] - Use true if you use a spherical coordinate system
  */
 export function pointstogrid(opts = {}) {
-  const { points, grid, var: varField, values: includeValues = false } = opts;
+  let {
+    points,
+    grid,
+    var: varField,
+    values: includeValues = false,
+    spherical = false,
+  } = opts;
 
   const t0 = performance.now();
 
+  if (spherical) {
+    grid = unstitch(grid);
+  }
+
   const gridFeatures = grid.features;
   const pointFeatures = points.features;
 
@@ -105,5 +118,5 @@ export function pointstogrid(opts = {}) {
   const t1 = performance.now();
   console.log(`Execution time: ${(t1 - t0).toFixed(2)} ms`);
 
-  return result;
+  return spherical ? stitchmerge(result) : result;
 }

package/src/operator/polygonstogrid.js

@@ -1,34 +1,43 @@
 import { bbox } from "@turf/bbox";
 import { intersect } from "@turf/intersect";
+import { area } from "@turf/area";
 import { geoPath } from "d3-geo";
+import { stitchmerge } from "../helpers/stitchmerge.js";
+import { unstitch } from "../helpers/unstitch.js";
 import RBush from "rbush";
 
 /**
  * @function polygonstogrid
  * @description Assign polygons to a grid and compute weighted sums per cell.
- *              Uses a spatial index to speed up calculations
- *              Optimized and removes cells with count = 0
- *              Supports multiple variables in varField (string or array of strings)
- *              Treats undefined or NaN as zero when summing
- *              If `values` is true, stores an array of intersected polygon properties
+ *              Supports planar (path.area) or spherical (Turf area) surface calculation.
+ *              Optimized and removes cells with count = 0.
+ *              Supports multiple variables in varField (string or array of strings).
+ *              Treats undefined or NaN as zero when summing.
+ *              If `values` is true, stores an array of intersected polygon properties.
  * @param {object} opts
- * @property {object} [polygons] - GeoJSON polygons or multi polygons to assign
+ * @property {object} [polygons] - GeoJSON polygons or multipolygons to assign
  * @property {object} [grid] - GeoJSON grid
- * @property {string|Array} [var] - Field(s) ton compute weighted sums (optional)
- * @property {boolean} [values=false] - Include array of raw polygons properties
+ * @property {string|Array} [var] - Field(s) to compute weighted sums (optional)
+ * @property {boolean} [values=false] - Include array of raw polygon properties
+ * @property {boolean} [spherical=false] - Compute areas on the sphere (Turf) instead of planar (D3)
  */
 export function polygonstogrid(opts = {}) {
-  const {
+  let {
     grid,
     polygons,
-    grid_id = "index",
     var: varField,
     values: includeValues = false,
+    spherical = false,
   } = opts;
 
   const t0 = performance.now();
   const path = geoPath();
 
+  // Unstitch grids if needed
+  if (spherical) {
+    grid = unstitch(grid);
+  }
+
   // --- Normalize varField to array ---
   const varFields = varField
     ? Array.isArray(varField)
@@ -36,18 +45,18 @@ export function polygonstogrid(opts = {}) {
       : [varField]
     : [];
 
-  // --- 1. Compute planar areas for polygons and grid cells ---
+  // --- 1. Compute areas for polygons and grid cells ---
   for (const poly of polygons.features) {
-    poly.properties.area_plan = path.area(poly);
+    if (spherical) poly.properties.area_spherical = area(poly);
+    else poly.properties.area_plan = path.area(poly);
   }
+
   for (const cell of grid.features) {
-    cell.properties.area_plan = path.area(cell);
+    if (spherical) cell.properties.area_spherical = area(cell);
+    else cell.properties.area_plan = path.area(cell);
 
-    // initialize statistics
     cell.properties.count = 0;
-    for (const v of varFields) {
-      cell.properties[v] = 0;
-    }
+    for (const v of varFields) cell.properties[v] = 0;
     if (includeValues) cell.properties.values = [];
   }
 
@@ -67,27 +76,31 @@ export function polygonstogrid(opts = {}) {
     for (const cand of candidates) {
       const cell = cand.cell;
 
+      // vérifier que les deux features existent
+      if (!poly || !cell) continue;
+
+      // Turf v7: intersect via FeatureCollection contenant exactement deux géométries
       const inter = intersect({
         type: "FeatureCollection",
         features: [poly, cell],
       });
       if (!inter) continue;
 
-      const areaPlan = path.area(inter);
-      const pctAreaPlan = areaPlan / poly.properties.area_plan;
+      const areaVal = spherical ? area(inter) : path.area(inter);
+      const pctArea =
+        areaVal /
+        (spherical
+          ? poly.properties.area_spherical
+          : poly.properties.area_plan);
 
       // update cell statistics
       cell.properties.count += 1;
-
       for (const v of varFields) {
         const value = parseFloat(poly.properties[v]);
-        cell.properties[v] += !isNaN(value) ? value * pctAreaPlan : 0;
+        cell.properties[v] += !isNaN(value) ? value * pctArea : 0;
       }
 
-      // add properties of intersected polygons
-      if (includeValues) {
-        cell.properties.values.push({ ...poly.properties });
-      }
+      if (includeValues) cell.properties.values.push({ ...poly.properties });
     }
   }
 
@@ -104,5 +117,5 @@ export function polygonstogrid(opts = {}) {
     ).toFixed(2)} ms`
   );
 
-  return filteredGrid;
+  return spherical ? stitchmerge(filteredGrid) : filteredGrid;
 }