geogrid 1.1.1 → 1.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "geogrid",
-  "version": "1.1.1",
+  "version": "1.2.2",
   "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,95 @@
+import booleanIntersects from "@turf/boolean-intersects";
+
+/**
+ * @function square_sph
+ * @summary Build a global square grid in lon/lat.
+ * @description
+ * Generates a grid of square polygons covering the whole globe in WGS84 coordinates.
+ * - Longitudes: start at -180, add `step` until reaching +180 (last cell may be smaller)
+ * - Latitudes: start at +90, subtract `step` until reaching -90 (last cell may be smaller)
+ * - Cells never overlap; borders align exactly
+ * - EPS is used to avoid coordinates exactly at ±180 and ±90 to prevent rewind/topology issues
+ *
+ * @param {object} options
+ * @param {number} [options.step=1] - Grid cell size in degrees
+ * @param {GeoJSON} [options.domain=null] - Optional GeoJSON mask; only intersecting cells are kept
+ * @returns {GeoJSON.FeatureCollection} A FeatureCollection of square polygons
+ */
+export function square_sph({ step = 1, domain = null } = {}) {
+  const LON_MIN = -180;
+  const LON_MAX = 180;
+  const LAT_MIN = -90;
+  const LAT_MAX = 90;
+  const EPS = 1e-2; // small offset to avoid exact ±180/±90 coordinates
+
+  if (step <= 0) throw new Error("step must be > 0");
+
+  const features = [];
+  let index = 0;
+
+  // --- Longitudes: from -180 (west) to +180 (east), incrementing by step ---
+  let lonWest = LON_MIN;
+  while (lonWest < LON_MAX - 1e-12) {
+    let lonEast = lonWest + step;
+    if (lonEast > LON_MAX) lonEast = LON_MAX;
+
+    // Apply EPS to avoid exact ±180
+    const lonW = Math.max(lonWest, LON_MIN + EPS);
+    const lonE = Math.min(lonEast, LON_MAX - EPS);
+
+    // --- Latitudes: from +90 (north) to -90 (south), decrementing by step ---
+    let latNorth = LAT_MAX;
+    while (latNorth > LAT_MIN + 1e-12) {
+      let latSouth = latNorth - step;
+      if (latSouth < LAT_MIN) latSouth = LAT_MIN;
+
+      // Apply EPS to avoid exact ±90
+      const latN = Math.min(latNorth, LAT_MAX - EPS);
+      const latS = Math.max(latSouth, LAT_MIN + EPS);
+
+      // Skip degenerate cells (can happen with EPS near poles)
+      if (lonE - lonW > 1e-12 && latN - latS > 1e-12) {
+        features.push({
+          type: "Feature",
+          geometry: {
+            type: "Polygon",
+            coordinates: [
+              [
+                [lonW, latN],
+                [lonE, latN],
+                [lonE, latS],
+                [lonW, latS],
+                [lonW, latN],
+              ],
+            ],
+          },
+          properties: { index: index++ },
+        });
+      }
+
+      // Move to the next row (southward)
+      latNorth = latSouth;
+    }
+
+    // Move to the next column (eastward)
+    lonWest = lonEast;
+  }
+
+  // --- Optional filtering by domain ---
+  const filtered = domain
+    ? features.filter((f) => {
+        try {
+          return booleanIntersects(f, domain);
+        } catch {
+          return false;
+        }
+      })
+    : features;
+
+  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,54 +1,67 @@
 import { bbox } from "@turf/bbox";
 import { lineSplit } from "@turf/line-split";
 import { length } from "@turf/length";
+import { booleanWithin } from "@turf/boolean-within";
+import { stitchmerge } from "../helpers/stitchmerge.js";
+import { unstitch } from "../helpers/unstitch.js";
 import RBush from "rbush";
 
 /**
  * @function linestogrid
- * @description Assign lines 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 line properties
- * @param {object} opts
- * @property {object} [lines] - GeoJSON lines to assign
- * @property {object} [grid] - GeoJSON grid
- * @property {string|Array} [var] - Field(s) to compute weighted sums (optional)
- * @property {boolean} [values=false] - Include array of raw lines properties
+ * @description Assign lines (LineString or MultiLineString) to a grid and compute weighted sums per cell.
+ *              MultiLineStrings are treated as a single feature for count and proportional distribution.
  */
+
 export function linestogrid(opts = {}) {
-  const {
+  let {
     grid,
     lines,
-    grid_id = "index",
     var: varField,
     values: includeValues = false,
+    spherical = false,
+    debug = false,
   } = opts;
 
   const t0 = performance.now();
 
-  // --- Normalize varField to array ---
+  if (spherical) grid = unstitch(grid);
+
   const varFields = varField
     ? Array.isArray(varField)
       ? varField
       : [varField]
     : [];
 
-  // --- 1. Compute total lengths for lines and initialize grid cells ---
-  for (const line of lines.features) {
-    line.properties.length_total = length(line, { units: "meters" });
+  // --- Add stable ID to grid cells ---
+  grid.features.forEach((cell, i) => (cell._id = i));
+
+  // --- Compute total length per line feature ---
+  for (const f of lines.features) {
+    if (f.geometry.type === "LineString") {
+      f.properties.length_total = length(f, { units: "meters" });
+    } else if (f.geometry.type === "MultiLineString") {
+      let total = 0;
+      for (const coords of f.geometry.coordinates) {
+        const part = {
+          type: "Feature",
+          geometry: { type: "LineString", coordinates: coords },
+        };
+        total += length(part, { units: "meters" });
+      }
+      f.properties.length_total = total;
+    } else {
+      f.properties.length_total = 0;
+    }
   }
 
+  // --- Initialize grid cells ---
   for (const cell of grid.features) {
     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 = [];
   }
 
-  // --- 2. Build spatial index (RBush) on the grid ---
+  // --- Build spatial index ---
   const tree = new RBush();
   const items = grid.features.map((cell) => {
     const [minX, minY, maxX, maxY] = bbox(cell);
@@ -56,53 +69,100 @@ export function linestogrid(opts = {}) {
   });
   tree.load(items);
 
-  // --- 3. Loop over lines ---
-  for (const line of lines.features) {
-    const [minX, minY, maxX, maxY] = bbox(line);
+  // --- Track counted features for debug ---
+  const countedLines = new Set();
+
+  // --- Process each line feature ---
+  for (const f of lines.features) {
+    const totalLength = f.properties.length_total || 0;
+    if (totalLength === 0) continue;
+
+    const [minX, minY, maxX, maxY] = bbox(f);
     const candidates = tree.search({ minX, minY, maxX, maxY });
+    const touched = new Set();
+    let totalSegLen = 0;
 
     for (const cand of candidates) {
       const cell = cand.cell;
+      let segLen = 0;
+
+      if (f.geometry.type === "LineString") {
+        segLen = safeSegLength(f, cell);
+      } else if (f.geometry.type === "MultiLineString") {
+        for (const coords of f.geometry.coordinates) {
+          const part = {
+            type: "Feature",
+            geometry: { type: "LineString", coordinates: coords },
+          };
+          segLen += safeSegLength(part, cell);
+        }
+      }
 
-      // split line by cell polygon
-      const splitLines = lineSplit(line, cell);
-      if (!splitLines.features.length) continue;
+      if (segLen === 0) continue;
+      totalSegLen += segLen;
 
-      // compute total length of segments inside the cell
-      let totalSegLength = 0;
-      for (const seg of splitLines.features) {
-        totalSegLength += length(seg, { units: "meters" });
+      if (!touched.has(cell._id)) {
+        cell.properties.count += 1;
+        touched.add(cell._id);
       }
-      if (totalSegLength === 0) continue;
-
-      // --- update cell statistics ---
-      cell.properties.count += 1; // one line per cell
 
       for (const v of varFields) {
-        const value = parseFloat(line.properties[v]);
+        const value = parseFloat(f.properties[v]);
         cell.properties[v] += !isNaN(value)
-          ? value * (totalSegLength / line.properties.length_total)
+          ? value * (segLen / totalLength)
           : 0;
       }
 
-      if (includeValues) {
-        cell.properties.values.push({ ...line.properties });
-      }
+      if (includeValues) cell.properties.values.push({ ...f.properties });
     }
+
+    if (totalSegLen > 0) countedLines.add(f.properties.id || f.id || f);
   }
 
-  // --- 4. Filter out cells with count == 0 ---
+  // --- Filter empty cells ---
   const filteredGrid = {
     ...grid,
-    features: grid.features.filter((cell) => cell.properties.count > 0),
+    features: grid.features.filter((c) => c.properties.count > 0),
   };
 
   const t1 = performance.now();
   console.log(
-    `Line intersection completed for ${filteredGrid.features.length} cells — ${(
+    `Line aggregation completed for ${filteredGrid.features.length} cells — ${(
       t1 - t0
     ).toFixed(2)} ms`
   );
 
-  return filteredGrid;
+  // --- Debug report ---
+  if (debug) {
+    const totalLines = lines.features.length;
+    const missing = totalLines - countedLines.size;
+    console.log(
+      `Counted ${countedLines.size}/${totalLines} line features (${missing} missing)`
+    );
+  }
+
+  return spherical ? stitchmerge(filteredGrid) : filteredGrid;
+}
+
+/**
+ * @function safeSegLength
+ * @description Returns total segment length of intersection between a line and polygon cell,
+ *              including case where line is entirely contained in the cell.
+ */
+function safeSegLength(line, cell) {
+  try {
+    if (booleanWithin(line, cell)) {
+      return length(line, { units: "meters" });
+    }
+
+    const split = lineSplit(line, cell);
+    let sum = 0;
+    for (const s of split.features) {
+      const l = length(s, { units: "meters" });
+      if (l > 0.001) sum += l; // ignore sub-mm artifacts
+    }
+    return sum;
+  } catch (e) {
+    return 0;
+  }
 }

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;
 }