squirreling 0.9.4 → 0.10.0

package/src/{expression/spatial.geometry.js → spatial/operations.js}

@@ -1,205 +1,11 @@
-/**
- * @import { Relation, SimpleGeometry } from './geometry.js'
- */
-
-export const EPSILON = 1e-10
-export const EPSILON_SQ = EPSILON * EPSILON
-
-/**
- * @typedef {{ minX: number, minY: number, maxX: number, maxY: number }} BBox
- */
-
-/** @type {WeakMap<SimpleGeometry, BBox>} */
-const bboxCache = new WeakMap()
-
-/**
- * Compute the axis-aligned bounding box of a simple geometry.
- * Results are cached per geometry object.
- *
- * @param {SimpleGeometry} geom
- * @returns {BBox}
- */
-export function bbox(geom) {
-  let b = bboxCache.get(geom)
-  if (b) return b
-  if (geom.type === 'Point') {
-    const [x, y] = geom.coordinates
-    b = { minX: x, minY: y, maxX: x, maxY: y }
-  } else {
-    /** @type {number[][]} */
-    const points = geom.type === 'LineString'
-      ? geom.coordinates
-      : geom.coordinates[0] // outer ring
-    let minX = Infinity, minY = Infinity, maxX = -Infinity, maxY = -Infinity
-    for (const p of points) {
-      if (p[0] < minX) minX = p[0]
-      if (p[1] < minY) minY = p[1]
-      if (p[0] > maxX) maxX = p[0]
-      if (p[1] > maxY) maxY = p[1]
-    }
-    b = { minX, minY, maxX, maxY }
-  }
-  bboxCache.set(geom, b)
-  return b
-}
-
-/**
- * Test whether two bounding boxes overlap.
- *
- * @param {BBox} a
- * @param {BBox} b
- * @returns {boolean}
- */
-export function bboxOverlap(a, b) {
-  return a.minX <= b.maxX && a.maxX >= b.minX && a.minY <= b.maxY && a.maxY >= b.minY
-}
-
-/**
- * Compute the squared distance between two 2D points.
- *
- * @param {number[]} a
- * @param {number[]} b
- * @returns {number}
- */
-export function distSq(a, b) {
-  const dx = a[0] - b[0]
-  const dy = a[1] - b[1]
-  return dx * dx + dy * dy
-}
-
-/**
- * Squared minimum distance from point p to line segment [a, b].
- *
- * @param {number[]} p
- * @param {number[]} a
- * @param {number[]} b
- * @returns {number}
- */
-export function pointToSegmentDistSq(p, a, b) {
-  const dx = b[0] - a[0]
-  const dy = b[1] - a[1]
-  const lenSq = dx * dx + dy * dy
-  if (lenSq === 0) return distSq(p, a)
-  let t = ((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / lenSq
-  t = Math.max(0, Math.min(1, t))
-  const ddx = p[0] - a[0] - t * dx
-  const ddy = p[1] - a[1] - t * dy
-  return ddx * ddx + ddy * ddy
-}
-
-/**
- * Test whether two line segments [p1,p2] and [p3,p4] intersect.
- * Returns true if they share any point (including endpoints).
- *
- * @param {number[]} p1
- * @param {number[]} p2
- * @param {number[]} p3
- * @param {number[]} p4
- * @returns {boolean}
- */
-function segmentsIntersect(p1, p2, p3, p4) {
-  const d1 = cross(p3, p4, p1)
-  const d2 = cross(p3, p4, p2)
-  const d3 = cross(p1, p2, p3)
-  const d4 = cross(p1, p2, p4)
-
-  if ((d1 > 0 && d2 < 0 || d1 < 0 && d2 > 0) &&
-      (d3 > 0 && d4 < 0 || d3 < 0 && d4 > 0)) {
-    return true
-  }
-
-  if (Math.abs(d1) < EPSILON && onSegment(p3, p4, p1)) return true
-  if (Math.abs(d2) < EPSILON && onSegment(p3, p4, p2)) return true
-  if (Math.abs(d3) < EPSILON && onSegment(p1, p2, p3)) return true
-  if (Math.abs(d4) < EPSILON && onSegment(p1, p2, p4)) return true
-
-  return false
-}
-
-/**
- * Cross product of vectors (b-a) and (c-a).
- *
- * @param {number[]} a
- * @param {number[]} b
- * @param {number[]} c
- * @returns {number}
- */
-function cross(a, b, c) {
-  return (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0])
-}
-
-/**
- * Check if point c lies on segment [a, b], assuming collinearity.
- *
- * @param {number[]} a
- * @param {number[]} b
- * @param {number[]} c
- * @returns {boolean}
- */
-function onSegment(a, b, c) {
-  return Math.min(a[0], b[0]) - c[0] <= EPSILON && c[0] - Math.max(a[0], b[0]) <= EPSILON &&
-         Math.min(a[1], b[1]) - c[1] <= EPSILON && c[1] - Math.max(a[1], b[1]) <= EPSILON
-}
-
-/**
- * Classify a point relative to a ring: 'OUTSIDE', 'BOUNDARY', or 'INSIDE'.
- * Combines ray casting with boundary distance check in a single pass.
- * ring is an array of [x, y] coords (closed ring, first = last).
- *
- * @param {number[]} point
- * @param {number[][]} ring
- * @returns {Relation}
- */
-function pointInRing(point, ring) {
-  const [px, py] = point
-  let inside = false
-  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
-    if (pointToSegmentDistSq(point, ring[j], ring[i]) < EPSILON_SQ) {
-      return 'BOUNDARY'
-    }
-    const [xi, yi] = ring[i]
-    const [xj, yj] = ring[j]
-    if (yi > py !== yj > py && px < (xj - xi) * (py - yi) / (yj - yi) + xi) {
-      inside = !inside
-    }
-  }
-  return inside ? 'INSIDE' : 'OUTSIDE'
-}
+import { bboxOverlap } from './bbox.js'
+import { pointInPolygon, pointLineRelation, pointOnLine } from './pointRelations.js'
+import { EPSILON_SQ, distSq } from './primitives.js'
+import { segmentIntersectsRing, segmentTouchPoint, segmentsIntersect } from './segments.js'
 
 /**
- * Classify a point relative to a polygon: 'OUTSIDE', 'BOUNDARY', or 'INSIDE'.
- * First ring is exterior, rest are holes.
- *
- * @param {number[]} point
- * @param {number[][][]} rings
- * @returns {Relation}
- */
-export function pointInPolygon(point, rings) {
-  const rel = pointInRing(point, rings[0])
-  if (rel === 'OUTSIDE') return 'OUTSIDE'
-  if (rel === 'BOUNDARY') return 'BOUNDARY'
-  for (let i = 1; i < rings.length; i++) {
-    const holeRel = pointInRing(point, rings[i])
-    if (holeRel === 'INSIDE') return 'OUTSIDE'
-    if (holeRel === 'BOUNDARY') return 'BOUNDARY'
-  }
-  return 'INSIDE'
-}
-
-/**
- * Test if a line segment intersects a ring boundary.
- *
- * @param {number[]} a
- * @param {number[]} b
- * @param {number[][]} ring
- * @returns {boolean}
+ * @import { Relation, SimpleGeometry } from './geometry.js'
  */
-function segmentIntersectsRing(a, b, ring) {
-  for (let i = 0; i < ring.length - 1; i++) {
-    if (segmentsIntersect(a, b, ring[i], ring[i + 1])) return true
-  }
-  return false
-}
 
 /**
  * Test if a linestring intersects a polygon.
@@ -209,11 +15,11 @@ function segmentIntersectsRing(a, b, ring) {
  * @returns {boolean}
  */
 function lineIntersectsPolygon(line, rings) {
-  // Check if any point of the line is inside the polygon
-  for (const pt of line) {
-    if (pointInPolygon(pt, rings) !== 'OUTSIDE') return true
-  }
-  // Check if any segment of the line intersects any ring edge
+  // Fast path for common containment queries: if one point is inside or on
+  // boundary, the line intersects.
+  if (pointInPolygon(line[0], rings) !== 'OUTSIDE') return true
+
+  // Otherwise, detect crossings/touches against polygon boundaries.
   for (let i = 0; i < line.length - 1; i++) {
     for (const ring of rings) {
       if (segmentIntersectsRing(line[i], line[i + 1], ring)) return true
@@ -238,6 +44,15 @@ function linesIntersect(line1, line2) {
   return false
 }
 
+/**
+ * @param {number[]} point
+ * @param {number[][]} line
+ * @returns {boolean}
+ */
+function isLineEndpoint(point, line) {
+  return distSq(point, line[0]) < EPSILON_SQ || distSq(point, line[line.length - 1]) < EPSILON_SQ
+}
+
 /**
  * Classify containment of a linestring within a polygon.
  * Returns 'INSIDE' if entirely in interior, 'BOUNDARY' if inside but
@@ -290,56 +105,6 @@ function polygonContainsPolygon(ringsA, ringsB) {
   return result
 }
 
-/**
- * Test if point is on a linestring.
- *
- * @param {number[]} point
- * @param {number[][]} line
- * @returns {boolean}
- */
-function pointOnLine(point, line) {
-  for (let i = 0; i < line.length - 1; i++) {
-    if (pointToSegmentDistSq(point, line[i], line[i + 1]) < EPSILON_SQ) return true
-  }
-  return false
-}
-
-/**
- * Compute intersection point of two segments (if they intersect at a single point).
- *
- * @param {number[]} p1
- * @param {number[]} p2
- * @param {number[]} p3
- * @param {number[]} p4
- * @returns {number[] | null}
- */
-function segmentIntersectionPoint(p1, p2, p3, p4) {
-  const d1x = p2[0] - p1[0], d1y = p2[1] - p1[1]
-  const d2x = p4[0] - p3[0], d2y = p4[1] - p3[1]
-  const denom = d1x * d2y - d1y * d2x
-  if (Math.abs(denom) < EPSILON) return null // parallel
-  const t = ((p3[0] - p1[0]) * d2y - (p3[1] - p1[1]) * d2x) / denom
-  return [p1[0] + t * d1x, p1[1] + t * d1y]
-}
-
-/**
- * Classify a point relative to a linestring.
- *
- * @param {number[]} point
- * @param {number[][]} line
- * @returns {Relation}
- */
-export function pointLineRelation(point, line) {
-  // Check endpoints first
-  if (distSq(point, line[0]) < EPSILON_SQ) return 'BOUNDARY'
-  if (distSq(point, line[line.length - 1]) < EPSILON_SQ) return 'BOUNDARY'
-  // Check if on any segment
-  for (let i = 0; i < line.length - 1; i++) {
-    if (pointToSegmentDistSq(point, line[i], line[i + 1]) < EPSILON_SQ) return 'INSIDE'
-  }
-  return 'OUTSIDE'
-}
-
 /**
  * Classify the relationship between two linestrings.
  * Returns INSIDE if interiors share a point, BOUNDARY if they only meet
@@ -353,24 +118,10 @@ function lineLineRelation(line1, line2) {
   let boundary = false
   for (let i = 0; i < line1.length - 1; i++) {
     for (let j = 0; j < line2.length - 1; j++) {
-      if (!segmentsIntersect(line1[i], line1[i + 1], line2[j], line2[j + 1])) continue
-      // Segments intersect, check if the intersection is interior to both lines
-      // Check segment midpoints
-      const mid1 = [(line1[i][0] + line1[i + 1][0]) / 2, (line1[i][1] + line1[i + 1][1]) / 2]
-      if (pointLineRelation(mid1, line1) === 'INSIDE' && pointLineRelation(mid1, line2) === 'INSIDE') {
-        return 'INSIDE'
-      }
-      const mid2 = [(line2[j][0] + line2[j + 1][0]) / 2, (line2[j][1] + line2[j + 1][1]) / 2]
-      if (pointLineRelation(mid2, line1) === 'INSIDE' && pointLineRelation(mid2, line2) === 'INSIDE') {
-        return 'INSIDE'
-      }
-      // Check actual intersection point
-      const ip = segmentIntersectionPoint(line1[i], line1[i + 1], line2[j], line2[j + 1])
-      if (ip) {
-        if (pointLineRelation(ip, line1) === 'INSIDE' && pointLineRelation(ip, line2) === 'INSIDE') {
-          return 'INSIDE'
-        }
-      }
+      const touchPoint = segmentTouchPoint(line1[i], line1[i + 1], line2[j], line2[j + 1])
+      if (touchPoint === 'OUTSIDE') continue
+      if (touchPoint === 'INSIDE') return 'INSIDE'
+      if (!isLineEndpoint(touchPoint, line1) && !isLineEndpoint(touchPoint, line2)) return 'INSIDE'
       boundary = true
     }
   }
@@ -475,10 +226,10 @@ function polygonPolygonRelation(rings1, rings2) {
  * @param {SimpleGeometry[]} partsB
  * @returns {boolean}
  */
-export function simpleIntersects(partsA, partsB) {
+export function intersects(partsA, partsB) {
   for (const pa of partsA) {
     for (const pb of partsB) {
-      if (simplePairIntersects(pa, pb)) return true
+      if (pairIntersects(pa, pb)) return true
     }
   }
   return false
@@ -489,8 +240,8 @@ export function simpleIntersects(partsA, partsB) {
  * @param {SimpleGeometry} b
  * @returns {boolean}
  */
-function simplePairIntersects(a, b) {
-  if (!bboxOverlap(bbox(a), bbox(b))) return false
+function pairIntersects(a, b) {
+  if (!bboxOverlap(a, b)) return false
   const ta = a.type
   const tb = b.type
 
@@ -533,8 +284,8 @@ function simplePairIntersects(a, b) {
  * @param {SimpleGeometry} b
  * @returns {Relation}
  */
-export function simplePairRelation(a, b) {
-  if (!bboxOverlap(bbox(a), bbox(b))) return 'OUTSIDE'
+export function pairRelation(a, b) {
+  if (!bboxOverlap(a, b)) return 'OUTSIDE'
   const ta = a.type
   const tb = b.type
 
@@ -589,8 +340,8 @@ export function simplePairRelation(a, b) {
  * @param {SimpleGeometry} b
  * @returns {Relation}
  */
-export function simplePairContainment(a, b) {
-  if (!bboxOverlap(bbox(a), bbox(b))) return 'OUTSIDE'
+export function pairContainment(a, b) {
+  if (!bboxOverlap(a, b)) return 'OUTSIDE'
   const ta = a.type
   const tb = b.type
 

package/src/spatial/pointRelations.js

@@ -0,0 +1,102 @@
+/**
+ * @import { Relation } from './geometry.js'
+ */
+
+import { EPSILON_SQ, distSq } from './primitives.js'
+
+/**
+ * Classify a point relative to a ring: 'OUTSIDE', 'BOUNDARY', or 'INSIDE'.
+ * Combines ray casting with boundary distance check in a single pass.
+ * ring is an array of [x, y] coords (closed ring, first = last).
+ *
+ * @param {number[]} point
+ * @param {number[][]} ring
+ * @returns {Relation}
+ */
+function pointInRing(point, ring) {
+  const [px, py] = point
+  let inside = false
+  for (let i = 0, j = ring.length - 1; i < ring.length; j = i++) {
+    if (pointToSegmentDistSq(point, ring[j], ring[i]) < EPSILON_SQ) {
+      return 'BOUNDARY'
+    }
+    const [xi, yi] = ring[i]
+    const [xj, yj] = ring[j]
+    if (yi > py !== yj > py && px < (xj - xi) * (py - yi) / (yj - yi) + xi) {
+      inside = !inside
+    }
+  }
+  return inside ? 'INSIDE' : 'OUTSIDE'
+}
+
+/**
+ * Classify a point relative to a polygon: 'OUTSIDE', 'BOUNDARY', or 'INSIDE'.
+ * First ring is exterior, rest are holes.
+ *
+ * @param {number[]} point
+ * @param {number[][][]} rings
+ * @returns {Relation}
+ */
+export function pointInPolygon(point, rings) {
+  const rel = pointInRing(point, rings[0])
+  if (rel === 'OUTSIDE') return 'OUTSIDE'
+  if (rel === 'BOUNDARY') return 'BOUNDARY'
+  for (let i = 1; i < rings.length; i++) {
+    const holeRel = pointInRing(point, rings[i])
+    if (holeRel === 'INSIDE') return 'OUTSIDE'
+    if (holeRel === 'BOUNDARY') return 'BOUNDARY'
+  }
+  return 'INSIDE'
+}
+
+/**
+ * Test if point is on a linestring.
+ *
+ * @param {number[]} point
+ * @param {number[][]} line
+ * @returns {boolean}
+ */
+export function pointOnLine(point, line) {
+  for (let i = 0; i < line.length - 1; i++) {
+    if (pointToSegmentDistSq(point, line[i], line[i + 1]) < EPSILON_SQ) return true
+  }
+  return false
+}
+
+/**
+ * Classify a point relative to a linestring.
+ *
+ * @param {number[]} point
+ * @param {number[][]} line
+ * @returns {Relation}
+ */
+export function pointLineRelation(point, line) {
+  // Check endpoints first
+  if (distSq(point, line[0]) < EPSILON_SQ) return 'BOUNDARY'
+  if (distSq(point, line[line.length - 1]) < EPSILON_SQ) return 'BOUNDARY'
+  // Check if on any segment
+  for (let i = 0; i < line.length - 1; i++) {
+    if (pointToSegmentDistSq(point, line[i], line[i + 1]) < EPSILON_SQ) return 'INSIDE'
+  }
+  return 'OUTSIDE'
+}
+
+/**
+ * Squared minimum distance from point p to line segment [a, b].
+ *
+ * @param {number[]} p
+ * @param {number[]} a
+ * @param {number[]} b
+ * @returns {number}
+ */
+export function pointToSegmentDistSq(p, a, b) {
+  const dx = b[0] - a[0]
+  const dy = b[1] - a[1]
+  const lenSq = dx * dx + dy * dy
+  if (lenSq === 0) return distSq(p, a)
+  let t = ((p[0] - a[0]) * dx + (p[1] - a[1]) * dy) / lenSq
+  t = Math.max(0, Math.min(1, t))
+  const ddx = p[0] - a[0] - t * dx
+  const ddy = p[1] - a[1] - t * dy
+  return ddx * ddx + ddy * ddy
+}

package/src/spatial/primitives.js

@@ -0,0 +1,27 @@
+export const EPSILON = 1e-10
+export const EPSILON_SQ = EPSILON * EPSILON
+
+/**
+ * Compute the squared distance between two 2D points.
+ *
+ * @param {number[]} a
+ * @param {number[]} b
+ * @returns {number}
+ */
+export function distSq(a, b) {
+  const dx = a[0] - b[0]
+  const dy = a[1] - b[1]
+  return dx * dx + dy * dy
+}
+
+/**
+ * Cross product of vectors (b-a) and (c-a).
+ *
+ * @param {number[]} a
+ * @param {number[]} b
+ * @param {number[]} c
+ * @returns {number}
+ */
+export function cross(a, b, c) {
+  return (b[0] - a[0]) * (c[1] - a[1]) - (b[1] - a[1]) * (c[0] - a[0])
+}

package/src/spatial/segments.js

@@ -0,0 +1,139 @@
+import { EPSILON, EPSILON_SQ, cross, distSq } from './primitives.js'
+
+/**
+ * Test whether two line segments [p1,p2] and [p3,p4] intersect.
+ * Returns true if they share any point (including endpoints).
+ *
+ * @param {number[]} p1
+ * @param {number[]} p2
+ * @param {number[]} p3
+ * @param {number[]} p4
+ * @returns {boolean}
+ */
+export function segmentsIntersect(p1, p2, p3, p4) {
+  const d1 = cross(p3, p4, p1)
+  const d2 = cross(p3, p4, p2)
+  const d3 = cross(p1, p2, p3)
+  const d4 = cross(p1, p2, p4)
+
+  if ((d1 > 0 && d2 < 0 || d1 < 0 && d2 > 0) &&
+      (d3 > 0 && d4 < 0 || d3 < 0 && d4 > 0)) {
+    return true
+  }
+
+  if (Math.abs(d1) < EPSILON && onSegment(p3, p4, p1)) return true
+  if (Math.abs(d2) < EPSILON && onSegment(p3, p4, p2)) return true
+  if (Math.abs(d3) < EPSILON && onSegment(p1, p2, p3)) return true
+  if (Math.abs(d4) < EPSILON && onSegment(p1, p2, p4)) return true
+
+  return false
+}
+
+/**
+ * Test if a line segment intersects a ring boundary.
+ *
+ * @param {number[]} a
+ * @param {number[]} b
+ * @param {number[][]} ring
+ * @returns {boolean}
+ */
+export function segmentIntersectsRing(a, b, ring) {
+  for (let i = 0; i < ring.length - 1; i++) {
+    if (segmentsIntersect(a, b, ring[i], ring[i + 1])) return true
+  }
+  return false
+}
+
+/**
+ * Compute intersection point of two segments (if they intersect at a single point).
+ *
+ * @param {number[]} p1
+ * @param {number[]} p2
+ * @param {number[]} p3
+ * @param {number[]} p4
+ * @returns {number[] | null}
+ */
+export function segmentIntersectionPoint(p1, p2, p3, p4) {
+  const d1x = p2[0] - p1[0], d1y = p2[1] - p1[1]
+  const d2x = p4[0] - p3[0], d2y = p4[1] - p3[1]
+  const denom = d1x * d2y - d1y * d2x
+  if (Math.abs(denom) < EPSILON) return null // parallel
+  const t = ((p3[0] - p1[0]) * d2y - (p3[1] - p1[1]) * d2x) / denom
+  return [p1[0] + t * d1x, p1[1] + t * d1y]
+}
+
+/**
+ * Check if point p lies on segment [a, b].
+ *
+ * @param {number[]} a
+ * @param {number[]} b
+ * @param {number[]} p
+ * @returns {boolean}
+ */
+export function pointOnSegment(a, b, p) {
+  if (Math.abs(cross(a, b, p)) > EPSILON) return false
+  return p[0] >= Math.min(a[0], b[0]) - EPSILON &&
+    p[0] <= Math.max(a[0], b[0]) + EPSILON &&
+    p[1] >= Math.min(a[1], b[1]) - EPSILON &&
+    p[1] <= Math.max(a[1], b[1]) + EPSILON
+}
+
+/**
+ * Returns the single endpoint touch point for two segments, 'INSIDE' when
+ * they intersect at a non-endpoint/proper crossing or overlap by length,
+ * and 'OUTSIDE' when they do not intersect.
+ *
+ * @param {number[]} a1
+ * @param {number[]} a2
+ * @param {number[]} b1
+ * @param {number[]} b2
+ * @returns {'INSIDE' | 'OUTSIDE' | number[]}
+ */
+export function segmentTouchPoint(a1, a2, b1, b2) {
+  const d1 = cross(b1, b2, a1)
+  const d2 = cross(b1, b2, a2)
+  const d3 = cross(a1, a2, b1)
+  const d4 = cross(a1, a2, b2)
+
+  if ((d1 > 0 && d2 < 0 || d1 < 0 && d2 > 0) &&
+      (d3 > 0 && d4 < 0 || d3 < 0 && d4 > 0)) {
+    return 'INSIDE'
+  }
+
+  /** @type {number[] | undefined} */
+  let point
+  let hasSecondPoint = false
+
+  /**
+   * @param {number[]} candidate
+   */
+  function addPoint(candidate) {
+    if (!point) {
+      point = candidate
+      return
+    }
+    if (distSq(point, candidate) >= EPSILON_SQ) hasSecondPoint = true
+  }
+
+  if (Math.abs(d1) < EPSILON && onSegment(b1, b2, a1)) addPoint(a1)
+  if (Math.abs(d2) < EPSILON && onSegment(b1, b2, a2)) addPoint(a2)
+  if (Math.abs(d3) < EPSILON && onSegment(a1, a2, b1)) addPoint(b1)
+  if (Math.abs(d4) < EPSILON && onSegment(a1, a2, b2)) addPoint(b2)
+
+  if (!point) return 'OUTSIDE'
+
+  return hasSecondPoint ? 'INSIDE' : point
+}
+
+/**
+ * Check if point c lies on segment [a, b], assuming collinearity.
+ *
+ * @param {number[]} a
+ * @param {number[]} b
+ * @param {number[]} c
+ * @returns {boolean}
+ */
+function onSegment(a, b, c) {
+  return Math.min(a[0], b[0]) - c[0] <= EPSILON && c[0] - Math.max(a[0], b[0]) <= EPSILON &&
+         Math.min(a[1], b[1]) - c[1] <= EPSILON && c[1] - Math.max(a[1], b[1]) <= EPSILON
+}