@math.gl/projection 0.0.0-stage → 5.0.0-alpha.12

package/src/lib/projection.ts

@@ -0,0 +1,167 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original compatibility wrapper around the math.gl projection engine. Projection kernels retain their proj4js/PROJ port notices and licenses in ../experimental/.
+import {ProjectionEngine} from '../experimental/typescript-projection';
+import {
+  mercator,
+  equidistantCylindrical,
+  lambertConformalConic,
+  albersEqualArea,
+  equidistantConic,
+  lambertAzimuthalEqualArea,
+  stereographic,
+  obliqueStereographic,
+  azimuthalEquidistant,
+  transverseMercator,
+  extendedTransverseMercator,
+  universalTransverseMercator,
+  geocentric,
+  bonne,
+  cassiniSoldner,
+  cylindricalEqualArea,
+  eckertVI,
+  equalEarth,
+  equirectangular,
+  geostationary,
+  gnomonic,
+  gaussSchreiberTransverseMercator,
+  krovak,
+  millerCylindrical,
+  mollweide,
+  newZealandMapGrid,
+  obliqueMercator,
+  orthographic,
+  polyconic,
+  quadrilateralizedSphericalCube,
+  robinson,
+  sinusoidal,
+  swissObliqueMercator,
+  tiltedPerspective,
+  vanDerGrinten,
+  obliqueTransformation,
+  parseNTv2Grid,
+  wktCRSParser,
+  projJSONCRSParser
+} from '../experimental/index';
+import {CORE_PARAMETERS} from '../experimental/crs/normalize';
+import type {ProjectionPlugin} from '../experimental/types';
+import type {DatumGrid, VerticalGridCollection} from '../experimental/grids/types';
+import type {ReadonlyCRSDefinition} from '@math.gl/crs';
+
+export type DatumGridOptions = {includeErrorFields?: boolean};
+
+/** Compatibility options with explicit, per-instance vertical grids. */
+export type ProjectionOptions = {
+  from?: ReadonlyCRSDefinition;
+  to?: ReadonlyCRSDefinition;
+  enforceAxis?: boolean;
+  verticalGrids?: VerticalGridCollection;
+};
+
+const aliases: Record<string, ReadonlyCRSDefinition> = Object.create(null);
+const grids: Record<string, DatumGrid> = Object.create(null);
+let preset: readonly ProjectionPlugin[] | undefined;
+function defaultProjections(): readonly ProjectionPlugin[] {
+  if (preset) return preset;
+  const projections: ProjectionPlugin[] = [
+    mercator,
+    equidistantCylindrical,
+    lambertConformalConic,
+    albersEqualArea,
+    equidistantConic,
+    lambertAzimuthalEqualArea,
+    stereographic,
+    obliqueStereographic,
+    azimuthalEquidistant,
+    transverseMercator,
+    extendedTransverseMercator,
+    universalTransverseMercator,
+    geocentric,
+    bonne,
+    cassiniSoldner,
+    cylindricalEqualArea,
+    eckertVI,
+    equalEarth,
+    equirectangular,
+    geostationary,
+    gnomonic,
+    gaussSchreiberTransverseMercator,
+    krovak,
+    millerCylindrical,
+    mollweide,
+    newZealandMapGrid,
+    obliqueMercator,
+    orthographic,
+    polyconic,
+    quadrilateralizedSphericalCube,
+    robinson,
+    sinusoidal,
+    swissObliqueMercator,
+    tiltedPerspective,
+    vanDerGrinten
+  ];
+  const key = (name: string): string => name.toLowerCase().replace(/[\s_-]/g, '');
+  const geographic = obliqueTransformation('longlat');
+  // The convenience wrapper supplies the catalogue; the configurable engine still
+  // requires an explicit child plugin for obliqueTransformation.
+  const oblique: ProjectionPlugin = {
+    name: geographic.name,
+    aliases: geographic.aliases,
+    parameters: [...new Set([...geographic.parameters, ...projections.flatMap(p => p.parameters)])],
+    flags: [...new Set(projections.flatMap(p => p.flags || []))],
+    create(context) {
+      const requested = context.parameters['o_proj'];
+      if (!requested) throw new Error('Oblique transformation requires +o_proj');
+      const child = ['longlat', 'latlong', 'latlon', 'lonlat', 'identity'].includes(key(requested))
+        ? 'longlat'
+        : projections.find(p =>
+            [p.name, ...(p.aliases || [])].some(name => key(name) === key(requested))
+          );
+      if (!child) throw new Error('Unknown oblique transformation projection: ' + requested);
+      const plugin = obliqueTransformation(child);
+      const allowed = new Set([...CORE_PARAMETERS, ...plugin.parameters]);
+      for (const parameter of Object.keys(context.parameters))
+        if (!allowed.has(parameter)) throw new Error('Unsupported PROJ parameter: +' + parameter);
+      return plugin.create(context);
+    }
+  };
+
+  preset = [...projections, oblique];
+  return preset;
+}
+
+/** Classic wrapper API, executed by the math.gl projection engine with all built-in plugins and readers. */
+export class Projection extends ProjectionEngine {
+  /** Register aliases for subsequently constructed projections. */
+  static defineProjectionAliases(definitions: {[name: string]: ReadonlyCRSDefinition}): void {
+    for (const name of Object.keys(definitions)) {
+      const definition = definitions[name];
+      aliases[name] =
+        typeof definition === 'string' ? definition : JSON.parse(JSON.stringify(definition));
+    }
+  }
+
+  /** Register an owned NTv2 grid snapshot for subsequent projections. */
+  static registerDatumGrid(name: string, grid: ArrayBuffer, options?: DatumGridOptions): void {
+    grids[name] = parseNTv2Grid(grid, options);
+  }
+
+  constructor({
+    from = 'WGS84',
+    to = 'WGS84',
+    enforceAxis = false,
+    verticalGrids
+  }: ProjectionOptions) {
+    super({
+      from,
+      to,
+      enforceAxis,
+      verticalGrids,
+      projections: defaultProjections(),
+      parsers: [wktCRSParser, projJSONCRSParser],
+      aliases,
+      datumGrids: grids
+    });
+  }
+}

package/src/operations.ts

@@ -0,0 +1,358 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original application-supplied coordinate operation selection; no database or model data.
+
+/** Geographic bounds in degrees: west, south, east, north. West > east crosses the antimeridian. */
+export type OperationArea = readonly [west: number, south: number, east: number, north: number];
+/** Inclusive decimal-year interval, separate from coordinate M values. */
+export type OperationEpochRange = readonly [start: number, end: number];
+
+/** Identity of application-prepared grid data. Both strings must match at selection time. */
+export type OperationGrid = {readonly id: string; readonly revision: string};
+/** Application-reviewed source and pinned revision of the operation metadata. */
+export type OperationProvenance = {
+  readonly authority: string;
+  readonly version: string;
+  readonly reference: string;
+};
+
+/** A directed, application-reviewed operation; the payload is never called or copied. */
+export type CoordinateOperation<T> = {
+  readonly id: string;
+  readonly sourceCRS: string;
+  readonly targetCRS: string;
+  readonly area: OperationArea;
+  /** null explicitly declares that this operation has no epoch restriction. */
+  readonly epochRange: OperationEpochRange | null;
+  /** Declared accuracy in metres; null means unknown, not zero. */
+  readonly accuracyMeters: number | null;
+  readonly ballpark?: boolean;
+  readonly grids?: readonly OperationGrid[];
+  readonly provenance: OperationProvenance;
+  readonly operation: T;
+};
+
+export type OperationSelectionRequest = {
+  readonly sourceCRS: string;
+  readonly targetCRS: string;
+  readonly area: OperationArea;
+  /** A coordinate epoch or the inclusive range of a batch's epochs. */
+  readonly epoch?: number | OperationEpochRange;
+  readonly availableGrids?: readonly OperationGrid[];
+  readonly maxAccuracyMeters?: number;
+  readonly allowUnknownAccuracy?: boolean;
+  readonly allowBallpark?: boolean;
+};
+
+export type OperationRejectionReason =
+  | 'source-crs'
+  | 'target-crs'
+  | 'area'
+  | 'epoch-required'
+  | 'epoch'
+  | 'grid'
+  | 'accuracy-unknown'
+  | 'accuracy'
+  | 'ballpark';
+
+export type OperationRejection<T> = {
+  readonly candidate: CoordinateOperation<T>;
+  readonly reasons: readonly OperationRejectionReason[];
+  readonly missingGrids: readonly OperationGrid[];
+};
+export type OperationSelection<T> = {
+  readonly selected: CoordinateOperation<T> | undefined;
+  /** Eligible operations in rank order. */
+  readonly candidates: readonly CoordinateOperation<T>[];
+  readonly rejected: readonly OperationRejection<T>[];
+};
+
+type Request = {
+  sourceCRS: string;
+  targetCRS: string;
+  area: OperationArea;
+  epoch: OperationEpochRange | undefined;
+  grids: Map<string, Set<string>>;
+  maxAccuracyMeters: number | undefined;
+  allowUnknownAccuracy: boolean;
+  allowBallpark: boolean;
+};
+const REASONS: readonly OperationRejectionReason[] = [
+  'source-crs',
+  'target-crs',
+  'area',
+  'epoch-required',
+  'epoch',
+  'grid',
+  'accuracy-unknown',
+  'accuracy',
+  'ballpark'
+];
+
+/**
+ * Optional metadata-only catalogue. Rank by non-ballpark, known accuracy, lower
+ * accuracy in metres, then code-unit identifier order. No downloads, CRS inference,
+ * inverse synthesis or execution; select once before processing a coordinate batch.
+ */
+export class OperationCatalog<T> {
+  readonly operations: readonly CoordinateOperation<T>[];
+
+  constructor(operations: readonly CoordinateOperation<T>[]) {
+    if (!Array.isArray(operations)) throw new Error('Operations must be an array');
+    const ids = new Set<string>();
+    const snapshots: CoordinateOperation<T>[] = [];
+    for (const candidate of operations) {
+      const snapshot = snapshotOperation<T>(candidate);
+      if (ids.has(snapshot.id)) throw new Error(`Duplicate operation id: ${snapshot.id}`);
+      ids.add(snapshot.id);
+      snapshots.push(snapshot);
+    }
+    this.operations = Object.freeze(snapshots.sort(compareOperations));
+    // Prevent replacement of reviewed metadata at runtime, too. Payload ownership stays with the caller.
+    Object.freeze(this);
+  }
+
+  /** Best eligible operation, or undefined. Malformed metadata/request values throw. */
+  select(request: OperationSelectionRequest): CoordinateOperation<T> | undefined {
+    const normalized = normalizeRequest(request);
+    for (const candidate of this.operations) {
+      if (rejectionMask(candidate, normalized) === 0) return candidate;
+    }
+    return undefined;
+  }
+
+  /** Explain eligibility without constructing, preloading or executing any payload. */
+  inspect(request: OperationSelectionRequest): OperationSelection<T> {
+    const normalized = normalizeRequest(request);
+    const candidates: CoordinateOperation<T>[] = [];
+    const rejected: OperationRejection<T>[] = [];
+    for (const candidate of this.operations) {
+      const mask = rejectionMask(candidate, normalized);
+      if (mask === 0) {
+        candidates.push(candidate);
+      } else {
+        const reasons = REASONS.filter((_, index) => Boolean(mask & (1 << index)));
+        const missingGrids = (candidate.grids || []).filter(grid => !hasGrid(normalized, grid));
+        rejected.push(
+          Object.freeze({
+            candidate,
+            reasons: Object.freeze(reasons),
+            missingGrids: Object.freeze(missingGrids)
+          })
+        );
+      }
+    }
+    return Object.freeze({
+      selected: candidates[0],
+      candidates: Object.freeze(candidates),
+      rejected: Object.freeze(rejected)
+    });
+  }
+}
+
+function rejectionMask<T>(candidate: CoordinateOperation<T>, request: Request): number {
+  let mask = 0;
+  if (candidate.sourceCRS !== request.sourceCRS) mask |= 1 << 0;
+  if (candidate.targetCRS !== request.targetCRS) mask |= 1 << 1;
+  if (!containsArea(candidate.area, request.area)) mask |= 1 << 2;
+  if (candidate.epochRange) {
+    if (!request.epoch) mask |= 1 << 3;
+    else if (
+      request.epoch[0] < candidate.epochRange[0] ||
+      request.epoch[1] > candidate.epochRange[1]
+    )
+      mask |= 1 << 4;
+  }
+  for (const grid of candidate.grids || []) {
+    if (!hasGrid(request, grid)) {
+      mask |= 1 << 5;
+      break;
+    }
+  }
+  if (candidate.accuracyMeters === null) {
+    // An unknown accuracy can never satisfy a numerical accuracy ceiling.
+    if (!request.allowUnknownAccuracy || request.maxAccuracyMeters !== undefined) mask |= 1 << 6;
+  } else if (
+    request.maxAccuracyMeters !== undefined &&
+    candidate.accuracyMeters > request.maxAccuracyMeters
+  )
+    mask |= 1 << 7;
+  if (candidate.ballpark && !request.allowBallpark) mask |= 1 << 8;
+  return mask;
+}
+
+function hasGrid(request: Request, grid: OperationGrid): boolean {
+  return Boolean(request.grids.get(grid.id)?.has(grid.revision));
+}
+
+function containsArea(outer: OperationArea, inner: OperationArea): boolean {
+  if (inner[1] < outer[1] || inner[3] > outer[3]) return false;
+  if (outer[0] === -180 && outer[2] === 180) return true;
+  const innerPoint = inner[0] === inner[2] || (inner[0] === 180 && inner[2] === -180);
+  if (innerPoint) return containsLongitude(outer, inner[0]);
+  if (outer[0] === outer[2] || (outer[0] === 180 && outer[2] === -180)) return false;
+  // Canonical seam endpoints for nonzero arcs. Compare intervals directly: adding
+  // 360 to tiny differences could round an out-of-area point onto the boundary.
+  const west = outer[0] === 180 ? -180 : outer[0];
+  const east = outer[2] === -180 ? 180 : outer[2];
+  const innerWest = inner[0] === 180 ? -180 : inner[0];
+  const innerEast = inner[2] === -180 ? 180 : inner[2];
+  if (west <= east) return innerWest <= innerEast && innerWest >= west && innerEast <= east;
+  return innerWest > innerEast
+    ? innerWest >= west && innerEast <= east
+    : innerWest >= west || innerEast <= east;
+}
+
+function containsLongitude(area: OperationArea, longitude: number): boolean {
+  // Both seam spellings identify the same point, including degenerate seam arcs.
+  if (longitude === -180 || longitude === 180) {
+    return area[0] === -180 || area[2] === 180 || area[0] > area[2];
+  }
+  return area[0] <= area[2]
+    ? longitude >= area[0] && longitude <= area[2]
+    : longitude >= area[0] || longitude <= area[2];
+}
+
+function compareOperations<T>(a: CoordinateOperation<T>, b: CoordinateOperation<T>): number {
+  const ballpark = Number(Boolean(a.ballpark)) - Number(Boolean(b.ballpark));
+  if (ballpark) return ballpark;
+  if (a.accuracyMeters !== b.accuracyMeters) {
+    if (a.accuracyMeters === null) return 1;
+    if (b.accuracyMeters === null) return -1;
+    return a.accuracyMeters - b.accuracyMeters;
+  }
+  return a.id < b.id ? -1 : a.id > b.id ? 1 : 0;
+}
+
+function snapshotOperation<T>(candidate: CoordinateOperation<T>): CoordinateOperation<T> {
+  if (!candidate || typeof candidate !== 'object')
+    throw new Error('Operation metadata must be an object');
+  const id = text(candidate.id, 'operation id');
+  const sourceCRS = text(candidate.sourceCRS, 'sourceCRS');
+  const targetCRS = text(candidate.targetCRS, 'targetCRS');
+  const area = snapshotArea(candidate.area);
+  const epochRange = candidate.epochRange === null ? null : snapshotEpoch(candidate.epochRange);
+  const accuracyMeters = candidate.accuracyMeters;
+  if (accuracyMeters !== null) nonnegative(accuracyMeters, 'accuracyMeters');
+  const ballpark = optionalBoolean(candidate.ballpark, 'ballpark');
+  const grids = snapshotGrids(candidate.grids);
+  const provenance = Object.freeze({
+    authority: text(candidate.provenance.authority, 'provenance authority'),
+    version: text(candidate.provenance.version, 'provenance version'),
+    reference: text(candidate.provenance.reference, 'provenance reference')
+  });
+  return Object.freeze({
+    id,
+    sourceCRS,
+    targetCRS,
+    area,
+    epochRange,
+    accuracyMeters,
+    ballpark,
+    grids,
+    provenance,
+    operation: candidate.operation
+  });
+}
+
+function normalizeRequest(request: OperationSelectionRequest): Request {
+  const sourceCRS = text(request.sourceCRS, 'sourceCRS');
+  const targetCRS = text(request.targetCRS, 'targetCRS');
+  const area = snapshotArea(request.area);
+  const epoch =
+    request.epoch === undefined
+      ? undefined
+      : typeof request.epoch === 'number'
+        ? snapshotEpoch([request.epoch, request.epoch])
+        : snapshotEpoch(request.epoch);
+  const maxAccuracyMeters = request.maxAccuracyMeters;
+  if (maxAccuracyMeters !== undefined) nonnegative(maxAccuracyMeters, 'maxAccuracyMeters');
+  const allowUnknownAccuracy = optionalBoolean(
+    request.allowUnknownAccuracy,
+    'allowUnknownAccuracy'
+  );
+  const allowBallpark = optionalBoolean(request.allowBallpark, 'allowBallpark');
+  const grids = new Map<string, Set<string>>();
+  for (const grid of snapshotGrids(request.availableGrids)) {
+    let revisions = grids.get(grid.id);
+    if (!revisions) {
+      revisions = new Set();
+      grids.set(grid.id, revisions);
+    }
+    revisions.add(grid.revision);
+  }
+  return {
+    sourceCRS,
+    targetCRS,
+    area,
+    epoch,
+    grids,
+    maxAccuracyMeters,
+    allowUnknownAccuracy,
+    allowBallpark
+  };
+}
+
+function snapshotArea(area: OperationArea): OperationArea {
+  if (
+    !Array.isArray(area) ||
+    area.length !== 4 ||
+    !Number.isFinite(area[0]) ||
+    !Number.isFinite(area[1]) ||
+    !Number.isFinite(area[2]) ||
+    !Number.isFinite(area[3]) ||
+    area[0] < -180 ||
+    area[0] > 180 ||
+    area[2] < -180 ||
+    area[2] > 180 ||
+    area[1] < -90 ||
+    area[3] > 90 ||
+    area[1] > area[3]
+  ) {
+    throw new Error('Operation area must be [west, south, east, north] in geographic degrees');
+  }
+  return Object.freeze([area[0], area[1], area[2], area[3]]);
+}
+
+function snapshotEpoch(epoch: OperationEpochRange): OperationEpochRange {
+  if (
+    !Array.isArray(epoch) ||
+    epoch.length !== 2 ||
+    !Number.isFinite(epoch[0]) ||
+    !Number.isFinite(epoch[1]) ||
+    epoch[0] > epoch[1]
+  ) {
+    throw new Error('Operation epoch range must contain two finite, ordered decimal years');
+  }
+  return Object.freeze([epoch[0], epoch[1]]);
+}
+
+function snapshotGrids(grids: readonly OperationGrid[] = []): readonly OperationGrid[] {
+  if (!Array.isArray(grids)) throw new Error('Operation grids must be an array');
+  const snapshots: OperationGrid[] = [];
+  for (const grid of grids) {
+    if (!grid || typeof grid !== 'object') throw new Error('Operation grid must be an object');
+    snapshots.push(
+      Object.freeze({id: text(grid.id, 'grid id'), revision: text(grid.revision, 'grid revision')})
+    );
+  }
+  return Object.freeze(snapshots);
+}
+
+function text(value: string, label: string): string {
+  if (typeof value !== 'string' || !value.trim())
+    throw new Error(`Operation ${label} must be a nonempty string`);
+  return value;
+}
+
+function nonnegative(value: number, label: string): void {
+  if (!Number.isFinite(value) || value < 0)
+    throw new Error(`Operation ${label} must be finite and nonnegative`);
+}
+
+function optionalBoolean(value: boolean | undefined, label: string): boolean {
+  if (value !== undefined && typeof value !== 'boolean')
+    throw new Error(`Operation ${label} must be boolean`);
+  return value === true;
+}

package/src/pipeline.ts

@@ -0,0 +1,4 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+export * from './experimental/projection-pipeline';