@math.gl/geometry 5.0.0-alpha.19 → 5.0.0-alpha.20

package/src/polygon/subdivide-polyline.ts

@@ -2,7 +2,15 @@
 // SPDX-License-Identifier: MIT
 // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
 
-/** Configuration for sampling straight source edges through a nonlinear transform. */
+/** A constant-speed source edge, sampled at fractions of its declared length.
+ * Endpoints must match the factory inputs exactly. Samples are copied before use.
+ */
+export type PolylineEdgeSampler = {
+  readonly length: number;
+  sample: (fraction: number) => ArrayLike<number>;
+};
+
+/** Configuration for sampling source edges through a nonlinear transform. */
 export type SubdividePolylineOptions = {
   /** Maps a source position to target coordinates; null or nonfinite output rejects the geometry.
    * Must be deterministic. A fresh array is passed on every invocation.
@@ -10,11 +18,21 @@ export type SubdividePolylineOptions = {
   transform: (position: readonly number[]) => ArrayLike<number> | null;
   /** Positive error tolerance in target-coordinate units, measured across all output components. */
   tolerance: number;
+  /** Optional factory, called once per original edge with independent endpoint copies.
+   * Without it, source coordinates interpolate linearly. Must be deterministic.
+   */
+  createEdgeSampler?: (
+    start: readonly number[],
+    end: readonly number[],
+    segmentIndex: number
+  ) => PolylineEdgeSampler;
   /** Number of source components per vertex. Default 2. */
   size?: 2 | 3;
   /** Number of target components per vertex. Defaults to size. */
   targetSize?: 2 | 3;
-  /** Optional positive maximum Euclidean edge length in source-coordinate units. */
+  /** Positive maximum leaf length: Euclidean source distance by default, or the
+   * custom sampler's declared length multiplied by its fraction interval.
+   */
   maxSegmentLength?: number;
   /** Maximum bisection depth per input edge. Default 16; maximum 30. */
   maxDepth?: number;
@@ -41,7 +59,8 @@ type Sample = {source: number[]; target: number[]; fraction: number};
 /** Adaptively subdivides a flat polyline by sampling a supplied coordinate transform.
  * Each leaf edge checks its quarter, midpoint and three-quarter positions against linear
  * interpolation of its target endpoints. This is a sampled criterion, not a guaranteed
- * bound for arbitrary transforms. Source edges and extra source components interpolate linearly.
+ * bound for arbitrary transforms. Source components interpolate linearly unless a custom
+ * constant-speed source-edge sampler is supplied.
  * Explicitly closed rings stay closed. Split seams and clip invalid domains before calling.
  * @throws RangeError For invalid options/coordinates, rejected transform samples, or exhausted limits.
  * Exceptions thrown by the transform itself propagate unchanged.
@@ -53,6 +72,7 @@ export function subdividePolyline(
   const {
     transform,
     tolerance,
+    createEdgeSampler,
     size = 2,
     targetSize = size,
     maxSegmentLength = Infinity,
@@ -61,6 +81,7 @@ export function subdividePolyline(
   } = options;
   if (
     typeof transform !== 'function' ||
+    (createEdgeSampler !== undefined && typeof createEdgeSampler !== 'function') ||
     !Number.isFinite(tolerance) ||
     tolerance <= 0 ||
     (size !== 2 && size !== 3) ||
@@ -113,24 +134,48 @@ export function subdividePolyline(
     segmentFractions.push(point.fraction);
   }
 
-  function interpolate(a: Sample, b: Sample, fraction: number): Sample {
-    // Weighted sum avoids overflow from subtracting opposite large finite values.
-    const source = a.source.map((value, i) => value * (1 - fraction) + b.source[i] * fraction);
-    return sample(source, a.fraction * (1 - fraction) + b.fraction * fraction);
+  function sampledSource(sampler: PolylineEdgeSampler, fraction: number): number[] {
+    const value = sampler.sample(fraction);
+    if (!value || value.length !== size) throw new RangeError('Invalid source-edge sample size');
+    const source = Array.from(value);
+    if (!source.every(Number.isFinite)) throw new RangeError('Nonfinite source-edge sample');
+    return source;
+  }
+
+  function interpolate(
+    a: Sample,
+    b: Sample,
+    fraction: number,
+    sampler?: PolylineEdgeSampler
+  ): Sample {
+    const originalFraction = a.fraction * (1 - fraction) + b.fraction * fraction;
+    // Always sample the original edge, never a new curve fitted to recursive endpoints.
+    const source = sampler
+      ? sampledSource(sampler, originalFraction)
+      : a.source.map((value, i) => value * (1 - fraction) + b.source[i] * fraction);
+    return sample(source, originalFraction);
   }
 
-  function subdivide(a: Sample, b: Sample, segment: number, depth: number): void {
+  function subdivide(
+    a: Sample,
+    b: Sample,
+    segment: number,
+    depth: number,
+    sampler?: PolylineEdgeSampler
+  ): void {
     let error = 0;
     let midpoint: Sample;
     for (const fraction of [0.25, 0.5, 0.75]) {
-      const point = interpolate(a, b, fraction);
+      const point = interpolate(a, b, fraction, sampler);
       if (fraction === 0.5) midpoint = point;
       const delta = point.target.map(
         (value, i) => value - (a.target[i] * (1 - fraction) + b.target[i] * fraction)
       );
       error = Math.max(error, Math.hypot(...delta));
     }
-    const sourceLength = Math.hypot(...a.source.map((value, i) => value - b.source[i]));
+    const sourceLength = sampler
+      ? sampler.length * (b.fraction - a.fraction)
+      : Math.hypot(...a.source.map((value, i) => value - b.source[i]));
     if (error <= tolerance && sourceLength <= maxSegmentLength) {
       append(b, segment);
       return;
@@ -138,8 +183,8 @@ export function subdividePolyline(
     if (depth >= maxDepth) {
       throw new RangeError(`Polyline subdivision exceeded maxDepth on input edge ${segment}`);
     }
-    subdivide(a, midpoint!, segment, depth + 1);
-    subdivide(midpoint!, b, segment, depth + 1);
+    subdivide(a, midpoint!, segment, depth + 1, sampler);
+    subdivide(midpoint!, b, segment, depth + 1, sampler);
   }
 
   if (vertexCount) {
@@ -147,7 +192,25 @@ export function subdividePolyline(
     append(previous, 0);
     for (let i = 1; i < vertexCount; i++) {
       const next = sample(sources.slice(i * size, (i + 1) * size), 1);
-      subdivide({...previous, fraction: 0}, next, i - 1, 0);
+      const start = {...previous, fraction: 0};
+      const sampler = createEdgeSampler?.(start.source.slice(), next.source.slice(), i - 1);
+      if (createEdgeSampler) {
+        if (
+          !sampler ||
+          typeof sampler.sample !== 'function' ||
+          !Number.isFinite(sampler.length) ||
+          sampler.length < 0
+        ) {
+          throw new RangeError('Invalid source-edge sampler');
+        }
+        for (const endpoint of [start, next]) {
+          const sampled = sampledSource(sampler, endpoint.fraction);
+          if (sampled.some((value, component) => value !== endpoint.source[component])) {
+            throw new RangeError('Source-edge sampler endpoints must match input');
+          }
+        }
+      }
+      subdivide(start, next, i - 1, 0, sampler);
       previous = next;
     }
   }