@math.gl/geospatial 5.0.0-alpha.9 → 5.0.0-beta.2

package/src/terrain/profile-measure.ts

@@ -0,0 +1,146 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {TerrainProfile} from './profile';
+import {TerrainSampleStatus as Status} from './types';
+
+export type TerrainProfileMeasurements = {
+  length: number;
+  coveredLength: number;
+  missingLength: number;
+  coveredSegmentCount: number;
+  missingSegmentCount: number;
+  validSampleCount: number;
+  minimumHeight: number | undefined;
+  maximumHeight: number | undefined;
+  ascent: number;
+  descent: number;
+  surfaceLength: number;
+  /** Trapezoidal integral over covered station intervals, in height * distance units. */
+  heightIntegral: number;
+  meanHeight: number | undefined;
+  /** Every sample was VALID, including isolated samples and single-point profiles. */
+  complete: boolean;
+};
+
+/** Measure the sampled piecewise-linear profile. Only adjacent VALID samples contribute intervals.
+ * Distances are the authoritative horizontal stationing. No gaps are bridged or terrain resampled.
+ */
+export function measureTerrainProfile(
+  profile: TerrainProfile,
+  options: {maxSamples?: number} = {}
+): TerrainProfileMeasurements {
+  const limit = options.maxSamples ?? 1_000_000;
+  if (
+    !Number.isSafeInteger(limit) ||
+    limit < 0 ||
+    !(profile.distances instanceof Float64Array) ||
+    profile.distances.length < 1 ||
+    profile.distances.length > limit
+  )
+    throw new Error('Invalid terrain profile sample capacity');
+  const count = profile.distances.length;
+  if (
+    !(profile.positions instanceof Float64Array) ||
+    profile.positions.length !== 2 * count ||
+    !profile.positions.every(Number.isFinite) ||
+    !(profile.heights instanceof Float64Array) ||
+    profile.heights.length !== count ||
+    !(profile.statuses instanceof Uint8Array) ||
+    profile.statuses.length !== count
+  )
+    throw new Error('Invalid terrain profile buffers');
+  if (
+    !Number.isFinite(profile.length) ||
+    profile.length < 0 ||
+    profile.distances[0] !== 0 ||
+    profile.distances[count - 1] !== profile.length
+  )
+    throw new Error('Invalid terrain profile stationing');
+  let validSampleCount = 0,
+    minimum = Infinity,
+    maximum = -Infinity,
+    coveredSegmentCount = 0,
+    missingSegmentCount = 0;
+  // Compensated accumulation for lengths, elevation changes and the height integral.
+  let meanHeight = 0;
+  const sums = new Float64Array(6),
+    corrections = new Float64Array(6);
+  const add = (index: number, value: number): void => {
+    const y = value - corrections[index],
+      next = sums[index] + y;
+    if (!Number.isFinite(value) || !Number.isFinite(next))
+      throw new Error('Terrain profile measurement arithmetic overflow');
+    corrections[index] = next - sums[index] - y;
+    sums[index] = next;
+  };
+  for (let i = 0; i < count; i++) {
+    const distance = profile.distances[i],
+      status = profile.statuses[i],
+      height = profile.heights[i];
+    if (!Number.isFinite(distance) || (i > 0 && distance <= profile.distances[i - 1]))
+      throw new Error('Invalid terrain profile stationing');
+    if (status > Status.NOT_RESIDENT) throw new Error('Invalid terrain profile status');
+    if (status === Status.VALID) {
+      if (!Number.isFinite(height)) throw new Error('Invalid terrain profile height');
+      validSampleCount++;
+      minimum = Math.min(minimum, height);
+      maximum = Math.max(maximum, height);
+    }
+    if (i === 0) continue;
+    const ds = distance - profile.distances[i - 1];
+    if (status !== Status.VALID || profile.statuses[i - 1] !== Status.VALID) {
+      missingSegmentCount++;
+      add(1, ds);
+      continue;
+    }
+    coveredSegmentCount++;
+    const previousCovered = sums[0];
+    add(0, ds);
+    const previous = profile.heights[i - 1],
+      dh = height - previous;
+    add(dh >= 0 ? 2 : 3, Math.abs(dh));
+    add(4, Math.hypot(ds, dh));
+    const average = previous + dh / 2;
+    add(5, average * ds);
+    if (previousCovered === 0) meanHeight = average;
+    else {
+      const newWeight = ds / sums[0];
+      const delta = average - meanHeight;
+      meanHeight = Number.isFinite(delta)
+        ? newWeight <= 0.5
+          ? meanHeight + weighted(delta, ds, sums[0])
+          : average - weighted(delta, previousCovered, sums[0])
+        : weighted(meanHeight, previousCovered, sums[0]) + weighted(average, ds, sums[0]);
+      if (!Number.isFinite(meanHeight))
+        throw new Error('Terrain profile measurement arithmetic overflow');
+    }
+  }
+  return {
+    length: profile.length,
+    coveredLength: sums[0],
+    missingLength: sums[1],
+    coveredSegmentCount,
+    missingSegmentCount,
+    validSampleCount,
+    minimumHeight: validSampleCount ? minimum : undefined,
+    maximumHeight: validSampleCount ? maximum : undefined,
+    ascent: sums[2],
+    descent: sums[3],
+    surfaceLength: sums[4],
+    heightIntegral: sums[5],
+    meanHeight: sums[0] ? meanHeight : undefined,
+    complete: validSampleCount === count
+  };
+}
+
+/** Apply tiny weights before division so a representable contribution is not rounded away. */
+function weighted(value: number, part: number, total: number): number {
+  const ratio = part / total;
+  if (ratio < Number.MIN_VALUE / Number.EPSILON) {
+    const product = value * part;
+    if (Number.isFinite(product) && product !== 0) return product / total;
+  }
+  return value * ratio;
+}

package/src/terrain/profile.ts

@@ -0,0 +1,111 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {TerrainSampleStatus as Status, type TerrainSampleStatus} from './types';
+
+/** Bind source choice, interpolation and residency policy in the callback. */
+export type TerrainProfileSampler = (
+  x: number,
+  y: number
+) => {status: TerrainSampleStatus; height: number};
+export type TerrainProfile = {
+  positions: Float64Array;
+  distances: Float64Array;
+  heights: Float64Array;
+  statuses: Uint8Array;
+  /** Horizontal Cartesian path length, not surface length or geodesic distance. */
+  length: number;
+};
+
+/** Preserve every nonrepeated path vertex; subdivide each segment evenly to at most spacing.
+ * Missing samples remain explicit. No interpolation across gaps or clearance guarantee is implied.
+ */
+export function sampleTerrainProfile(
+  sample: TerrainProfileSampler,
+  path: ArrayLike<number>,
+  options: {spacing: number; maxSamples?: number}
+): TerrainProfile {
+  const limit = options.maxSamples ?? 1_000_000;
+  if (
+    !Number.isFinite(options.spacing) ||
+    options.spacing <= 0 ||
+    !Number.isSafeInteger(limit) ||
+    limit < 1
+  )
+    throw new Error('Invalid terrain profile spacing or capacity');
+  if (
+    !Number.isSafeInteger(path.length) ||
+    path.length < 2 ||
+    path.length % 2 ||
+    path.length / 2 > limit
+  )
+    throw new Error('Invalid terrain profile path or vertex capacity');
+  for (let i = 0; i < path.length; i++)
+    if (!Number.isFinite(path[i])) throw new Error('Terrain profile coordinates must be finite');
+  const points = Float64Array.from(path),
+    lengths = new Float64Array(points.length / 2 - 1),
+    divisions = new Float64Array(lengths.length);
+  let count = 1,
+    length = 0;
+  for (let i = 0; i < lengths.length; i++) {
+    const distance = Math.hypot(
+      points[2 * i + 2] - points[2 * i],
+      points[2 * i + 3] - points[2 * i + 1]
+    );
+    const nextLength = length + distance;
+    if (!Number.isFinite(nextLength) || (distance > 0 && nextLength <= length))
+      throw new Error('Terrain profile distance overflow or loss of precision');
+    const steps = distance === 0 ? 0 : Math.max(1, Math.ceil(distance / options.spacing));
+    if (!Number.isSafeInteger(steps) || count + steps > limit)
+      throw new Error('Terrain profile sample capacity exceeded');
+    lengths[i] = distance;
+    divisions[i] = steps;
+    count += steps;
+    length = nextLength;
+  }
+  const positions = new Float64Array(count * 2),
+    distances = new Float64Array(count),
+    heights = new Float64Array(count),
+    statuses = new Uint8Array(count);
+  let index = 0;
+  const emit = (x: number, y: number, distance: number): void => {
+    if (
+      index > 0 &&
+      (distance <= distances[index - 1] ||
+        (x === positions[2 * index - 2] && y === positions[2 * index - 1]))
+    )
+      throw new Error('Terrain profile samples lose coordinate or distance precision');
+    positions[2 * index] = x;
+    positions[2 * index + 1] = y;
+    distances[index] = distance;
+    const value = sample(x, y);
+    if (!Number.isInteger(value.status) || value.status < 0 || value.status > Status.NOT_RESIDENT)
+      throw new Error('Invalid terrain profile sample status');
+    statuses[index] = value.status;
+    if (value.status === Status.VALID) {
+      if (Number.isFinite(value.height)) heights[index] = value.height;
+      else statuses[index] = Status.NUMERIC_ERROR;
+    }
+    index++;
+  };
+  emit(points[0], points[1], 0);
+  let start = 0;
+  for (let i = 0; i < lengths.length; i++) {
+    const steps = divisions[i];
+    for (let j = 1; j <= steps; j++) {
+      const fraction = j / steps;
+      emit(
+        j === steps
+          ? points[2 * i + 2]
+          : points[2 * i] + (points[2 * i + 2] - points[2 * i]) * fraction,
+        j === steps
+          ? points[2 * i + 3]
+          : points[2 * i + 1] + (points[2 * i + 3] - points[2 * i + 1]) * fraction,
+        start + lengths[i] * fraction
+      );
+    }
+    start += lengths[i];
+  }
+  return {positions, distances, heights, statuses, length};
+}

package/src/terrain/slope-aspect.ts

@@ -0,0 +1,74 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {TerrainGradientGrid} from './derivatives';
+import {TerrainSampleStatus as Status} from './types';
+
+/** Radians: slope from horizontal; downhill aspect clockwise from world +Y.
+ * Aspect is undefined on an exactly flat surface. This does not infer geographic north.
+ */
+export function getTerrainSlopeAspect(
+  gradientX: number,
+  gradientY: number
+): {slope: number; aspect: number | undefined} {
+  if (!Number.isFinite(gradientX) || !Number.isFinite(gradientY))
+    throw new Error('Terrain gradient must be finite');
+  const slope = Math.atan(Math.hypot(gradientX, gradientY));
+  const angle = Math.atan2(-gradientX, -gradientY);
+  return {
+    slope,
+    aspect:
+      gradientX === 0 && gradientY === 0
+        ? undefined
+        : (angle < 0 ? angle + 2 * Math.PI : angle || 0) % (2 * Math.PI)
+  };
+}
+
+export type TerrainSlopeAspectGrid = {
+  width: number;
+  height: number;
+  slopes: Float64Array;
+  aspects: Float64Array;
+  statuses: Uint8Array;
+  aspectStatuses: Uint8Array;
+};
+
+/** Convert an explicit gradient grid without importing stencil calculation or terrain classes. */
+export function createTerrainSlopeAspectGrid(
+  grid: Pick<TerrainGradientGrid, 'width' | 'height' | 'gradients' | 'statuses'>,
+  options: {maxSamples?: number} = {}
+): TerrainSlopeAspectGrid {
+  const count = grid.width * grid.height,
+    limit = options.maxSamples ?? 1_100_000;
+  if (
+    !Number.isSafeInteger(grid.width) ||
+    grid.width < 2 ||
+    !Number.isSafeInteger(grid.height) ||
+    grid.height < 2 ||
+    !Number.isSafeInteger(limit) ||
+    limit < 0 ||
+    count > limit
+  )
+    throw new Error('Invalid terrain slope grid dimensions or capacity');
+  if (
+    !(grid.gradients instanceof Float64Array) ||
+    grid.gradients.length !== 2 * count ||
+    !(grid.statuses instanceof Uint8Array) ||
+    grid.statuses.length !== count
+  )
+    throw new Error('Invalid terrain slope grid buffers');
+  const slopes = new Float64Array(count),
+    aspects = new Float64Array(count);
+  const statuses = grid.statuses.slice(),
+    aspectStatuses = grid.statuses.slice();
+  for (let i = 0; i < count; i++) {
+    if (statuses[i] > Status.NOT_RESIDENT) throw new Error('Invalid terrain gradient status');
+    if (statuses[i] !== Status.VALID) continue;
+    const value = getTerrainSlopeAspect(grid.gradients[2 * i], grid.gradients[2 * i + 1]);
+    slopes[i] = value.slope;
+    if (value.aspect === undefined) aspectStatuses[i] = Status.NO_DATA;
+    else aspects[i] = value.aspect;
+  }
+  return {width: grid.width, height: grid.height, slopes, aspects, statuses, aspectStatuses};
+}