@math.gl/geospatial 5.0.0-alpha.2 → 5.0.0-alpha.20

package/src/projection/experimental/projections/stere.ts

@@ -0,0 +1,59 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {withAngularRenderingProfile} from '../rendering-profile/angular-rendering-profile';
+import {
+  sphericalAzimuthalBounds,
+  ellipsoidalStereographicBounds
+} from '../rendering-profile/azimuthal-rendering-bounds';
+import type {ProjectionPlugin} from '../types';
+import {
+  bindKernel,
+  guardAzimuthalDomain,
+  kernelParameters,
+  ORIGIN_PARAMETERS,
+  SCALE_PARAMETERS
+} from '../kernel';
+import {createState, forward, inverse} from '../kernels/stere';
+
+export const stereographic: ProjectionPlugin = {
+  name: 'stere',
+  aliases: [
+    'Stereographic_South_Pole',
+    'Polar_Stereographic_variant_A',
+    'Polar_Stereographic_variant_B',
+    'Polar_Stereographic'
+  ],
+  parameters: [...ORIGIN_PARAMETERS, ...SCALE_PARAMETERS, 'lat_ts'],
+  create(context) {
+    const base = kernelParameters(context);
+
+    const state = createState(base);
+    const projection = guardAzimuthalDomain(base, bindKernel('stere', state, forward, inverse));
+    return withAngularRenderingProfile(projection, base, (150 * Math.PI) / 180, (region, domain) =>
+      state.sphere
+        ? sphericalAzimuthalBounds(state, region, domain, 'stere')
+        : ellipsoidalStereographicBounds(
+            state,
+            latitude =>
+              2 *
+                Math.atan(
+                  Math.tan(Math.PI / 4 + latitude / 2) *
+                    Math.pow(
+                      (1 - state.e * Math.sin(latitude)) / (1 + state.e * Math.sin(latitude)),
+                      state.e / 2
+                    )
+                ) -
+              Math.PI / 2,
+            state.X0,
+            2 *
+              state.a *
+              state.k0 *
+              (Math.abs(state.coslat0) < 1e-10 ? 1 / state.cons : state.ms1 / state.cosX0),
+            region,
+            domain
+          )
+    );
+  }
+};

package/src/projection/experimental/projections/sterea.ts

@@ -0,0 +1,61 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {withAngularRenderingProfile} from '../rendering-profile/angular-rendering-profile';
+import {ellipsoidalStereographicBounds} from '../rendering-profile/azimuthal-rendering-bounds';
+import type {ProjectionPlugin} from '../types';
+import {
+  bindKernel,
+  guardAzimuthalDomain,
+  kernelParameters,
+  ORIGIN_PARAMETERS,
+  SCALE_PARAMETERS
+} from '../kernel';
+import {createState, forward, inverse} from '../kernels/sterea';
+
+export const obliqueStereographic: ProjectionPlugin = {
+  name: 'sterea',
+  aliases: [
+    'Stereographic_North_Pole',
+    'Oblique_Stereographic',
+    'Oblique Stereographic Alternative',
+    'Double_Stereographic'
+  ],
+  parameters: [...ORIGIN_PARAMETERS, ...SCALE_PARAMETERS],
+  create(context) {
+    const base = kernelParameters(context);
+    if (Math.abs(base.lat0) === Math.PI / 2)
+      throw new Error('sterea requires a non-polar origin; use stere at the poles');
+    const state = createState(base);
+    // Keep the rendering boundary finite without restricting raw conversion.
+    return withAngularRenderingProfile(
+      guardAzimuthalDomain(base, bindKernel('sterea', state, forward, inverse)),
+      base,
+      (Math.PI * 150) / 180,
+      (region, domain) =>
+        ellipsoidalStereographicBounds(
+          base,
+          latitude =>
+            2 *
+              Math.atan(
+                state.K *
+                  Math.pow(Math.tan(Math.PI / 4 + latitude / 2), state.C) *
+                  Math.pow(
+                    (1 - base.e * Math.sin(latitude)) / (1 + base.e * Math.sin(latitude)),
+                    state.ratexp
+                  )
+              ) -
+            Math.PI / 2,
+          state.phic0,
+          base.a * base.k0 * state.R2,
+          region,
+          domain,
+          state.C,
+          Math.abs(Math.log(state.C)) +
+            Math.abs(Math.log(state.K)) +
+            state.C * base.e * Math.atanh(base.e)
+        )
+    );
+  }
+};

package/src/projection/experimental/projections/tpers.ts

@@ -0,0 +1,59 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original plugin adapter for the numerical kernel directly ported from proj4js 2.22.0.
+import {withAngularRenderingProfile} from '../rendering-profile/angular-rendering-profile';
+import {perspectiveBounds} from '../rendering-profile/azimuthal-rendering-bounds';
+import type {ProjectionPlugin} from '../types';
+import {
+  catalogueParameters,
+  catalogueBoundsParameters,
+  bindCatalogueKernel,
+  horizonGuard
+} from '../catalogue-kernel';
+import {createState, forward, inverse} from '../kernels/tpers';
+import {numberParameter} from '../parameters';
+
+export const tiltedPerspective: ProjectionPlugin = {
+  name: 'tpers',
+  aliases: ['Tilted_Perspective'],
+  parameters: ['lon_0', 'x_0', 'y_0', 'lat_0', 'h', 'tilt', 'azi'],
+  create(context) {
+    const base = catalogueParameters(context);
+    const h = numberParameter(context.parameters, 'h', 100000);
+    const tilt = (numberParameter(context.parameters, 'tilt', 0) * Math.PI) / 180;
+    const azi = (numberParameter(context.parameters, 'azi', 0) * Math.PI) / 180;
+    if (Math.abs(tilt) >= Math.PI / 2)
+      throw new Error('Perspective tilt must be between -90 and 90 degrees');
+    const state = createState(base, {h, tilt, azi});
+    const radius = 1 + h / base.a;
+    const horizon = Math.acos(1 / radius);
+    // Tilt can make the image plane singular before the geographic horizon.
+    const angle = Math.abs(tilt);
+    const plane =
+      radius * Math.cos(angle) < 1 ? angle - Math.acos(radius * Math.cos(angle)) : horizon;
+    const distance = Math.min(horizon, plane) * (1 - 1e-10);
+    return withAngularRenderingProfile(
+      bindCatalogueKernel(
+        'tpers',
+        context,
+        state,
+        forward,
+        inverse,
+        horizonGuard(base, 1 / (1 + h / base.a))
+      ),
+      base,
+      distance,
+      (region, domain) =>
+        perspectiveBounds(
+          catalogueBoundsParameters(base, context),
+          radius,
+          tilt,
+          azi,
+          region,
+          domain
+        ),
+      horizon
+    );
+  }
+};

package/src/projection/experimental/projections/transverse-mercator.ts

@@ -0,0 +1,89 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {createFlatProjection} from '../flat-projection';
+import type {ProjectionContext, ProjectionImplementation, ProjectionPlugin} from '../types';
+import {transverseBounds} from '../rendering-profile/rendering-bounds';
+import {createAngularRanges} from '../rendering-profile/geographic-bounds';
+import {withRectangleRenderingProfile} from '../rendering-profile/rectangular-rendering-profile';
+import {
+  bindKernel,
+  flagParameter,
+  kernelParameters,
+  ORIGIN_PARAMETERS,
+  SCALE_PARAMETERS
+} from '../kernel';
+import {
+  createState as createExtended,
+  forward as extendedForward,
+  inverse as extendedInverse
+} from '../kernels/etmerc';
+import {
+  createState as createFast,
+  forward as fastForward,
+  inverse as fastInverse
+} from '../kernels/tmerc';
+
+export function createTransverseMercator(context: ProjectionContext): ProjectionImplementation {
+  const base = kernelParameters(context);
+  // A finite regional strip avoids the transverse singularities at +/-90 degrees.
+  const render = (implementation: ProjectionImplementation) =>
+    withRectangleRenderingProfile(
+      implementation,
+      createAngularRanges(
+        base.long0 - Math.PI / 6,
+        -Math.PI / 2,
+        base.long0 + Math.PI / 6,
+        Math.PI / 2
+      ),
+      ranges => transverseBounds(implementation.forward, ranges, base.long0, base.over),
+      base.primeMeridian,
+      base.over
+    );
+  if (flagParameter(context.parameters, 'approx')) {
+    return render({
+      ...bindKernel(
+        'tmerc +approx',
+        createFast(base),
+        fastForward,
+        fastInverse,
+        createFlatProjection
+      )
+    });
+  }
+  if (base.sphere) throw new Error('Spherical transverse Mercator requires +approx');
+  return render({
+    ...bindKernel(
+      'etmerc',
+      createExtended(base),
+      extendedForward,
+      extendedInverse,
+      createFlatProjection
+    )
+  });
+}
+
+/** Matches proj4js: tmerc uses the extended algorithm unless +approx is supplied. */
+export const transverseMercator: ProjectionPlugin = {
+  name: 'tmerc',
+  aliases: [
+    'Fast_Transverse_Mercator',
+    'Fast Transverse Mercator',
+    'Transverse_Mercator',
+    'Transverse Mercator',
+    'Gauss Kruger',
+    'Gauss_Kruger'
+  ],
+  parameters: [...ORIGIN_PARAMETERS, ...SCALE_PARAMETERS, 'approx'],
+  flags: ['approx'],
+  create: createTransverseMercator
+};
+
+export const extendedTransverseMercator: ProjectionPlugin = {
+  name: 'etmerc',
+  aliases: ['Extended_Transverse_Mercator', 'Extended Transverse Mercator'],
+  parameters: [...ORIGIN_PARAMETERS, ...SCALE_PARAMETERS, 'approx'],
+  flags: ['approx'],
+  create: createTransverseMercator
+};

package/src/projection/experimental/projections/utm.ts

@@ -0,0 +1,50 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ProjectionPlugin} from '../types';
+import {transverseBounds} from '../rendering-profile/rendering-bounds';
+import {createAngularRanges} from '../rendering-profile/geographic-bounds';
+import {withRectangleRenderingProfile} from '../rendering-profile/rectangular-rendering-profile';
+import {numberParameter} from '../parameters';
+import {flagParameter} from '../kernel';
+import {createTransverseMercator} from './transverse-mercator';
+
+export const universalTransverseMercator: ProjectionPlugin = {
+  name: 'utm',
+  aliases: ['Universal Transverse Mercator System'],
+  parameters: ['zone', 'south', 'approx'],
+  flags: ['south', 'approx'],
+  create(context) {
+    const zone = numberParameter(context.parameters, 'zone', NaN);
+    if (!Number.isInteger(zone) || zone < 1 || zone > 60) {
+      throw new Error('UTM requires an integer +zone from 1 to 60');
+    }
+    const south = flagParameter(context.parameters, 'south');
+    const implementation = createTransverseMercator({
+      ...context,
+      parameters: {
+        ...context.parameters,
+        lat_0: '0',
+        lon_0: String(6 * zone - 183),
+        x_0: '500000',
+        y_0: south ? '10000000' : '0',
+        k_0: '0.9996'
+      }
+    });
+    const center = ((6 * zone - 183) * Math.PI) / 180;
+    // Standard six-degree UTM zone coverage, independent of conversion validity.
+    return withRectangleRenderingProfile(
+      implementation,
+      createAngularRanges(
+        center - Math.PI / 60,
+        south ? (-80 * Math.PI) / 180 : 0,
+        center + Math.PI / 60,
+        south ? 0 : (84 * Math.PI) / 180
+      ),
+      ranges => transverseBounds(implementation.forward, ranges, center),
+      context.primeMeridian ?? 0,
+      Object.prototype.hasOwnProperty.call(context.parameters, 'over')
+    );
+  }
+};

package/src/projection/experimental/projections/vandg.ts

@@ -0,0 +1,30 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original plugin adapter for the numerical kernel directly ported from proj4js 2.22.0.
+import {vanDerGrintenBounds} from '../rendering-profile/rendering-bounds';
+import {createAngularRanges} from '../rendering-profile/geographic-bounds';
+import {withRectangleRenderingProfile} from '../rendering-profile/rectangular-rendering-profile';
+import type {ProjectionPlugin} from '../types';
+import {catalogueParameters, bindCatalogueKernel} from '../catalogue-kernel';
+import {createState, forward, inverse} from '../kernels/vandg';
+
+export const vanDerGrinten: ProjectionPlugin = {
+  name: 'vandg',
+  aliases: ['Van_der_Grinten_I', 'VanDerGrinten', 'Van_der_Grinten'],
+  parameters: ['lon_0', 'x_0', 'y_0'],
+  create(context) {
+    const base = catalogueParameters(context);
+
+    const state = createState(base);
+    // The rendering target covers one world; +over still permits conversion beyond it.
+    const projection = bindCatalogueKernel('vandg', context, state, forward, inverse);
+    return withRectangleRenderingProfile(
+      projection,
+      createAngularRanges(base.long0 - Math.PI, -Math.PI / 2, base.long0 + Math.PI, Math.PI / 2),
+      ranges => vanDerGrintenBounds(projection.forward, ranges, base.long0, base.over),
+      base.primeMeridian,
+      base.over
+    );
+  }
+};

package/src/projection/experimental/rendering-profile/angular-rendering-profile.ts

@@ -0,0 +1,117 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {KernelParameters} from '../kernel';
+import type {
+  GeographicBounds,
+  ProjectionImplementation,
+  ProjectionRenderingProfile
+} from '../types';
+import {createAngularRanges, getAngularRanges, normalizeLongitude} from './geographic-bounds';
+import type {AngularRanges} from './geographic-bounds';
+import {createRectangleRenderingProfile} from './rectangular-rendering-profile';
+import {geographicVector, sphericalExtremum} from './spherical-rendering-domain';
+import type {AngularDomain} from './spherical-rendering-domain';
+import {wrapLongitude} from '../parameters';
+import {createAngularNormalization} from './rendering-profile';
+
+export type ResolveAngularBounds = (
+  parameters: AngularRanges,
+  domain?: AngularDomain
+) => ProjectionRenderingProfile['bounds'];
+
+/** A spherical cap with projection-owned analytical bounds and exact coverage intersections. */
+export function createAngularRenderingProfile(
+  base: Pick<KernelParameters, 'long0' | 'lat0' | 'primeMeridian'>,
+  maximumDistance: number,
+  resolveBounds: ResolveAngularBounds,
+  horizon = Math.PI
+): NonNullable<ProjectionImplementation['getRenderingProfile']> {
+  const full: GeographicBounds = [-180, -90, 180, 90];
+  const create = (coverage: GeographicBounds, declared: boolean): ProjectionRenderingProfile => {
+    const parameters = getAngularRanges(coverage, base.primeMeridian, base.long0);
+    const local = createAngularRanges(
+      parameters[0][0] - base.long0,
+      parameters[0][1],
+      parameters[1][0] - base.long0,
+      parameters[1][1]
+    );
+    const axis = [Math.cos(base.lat0), 0, Math.sin(base.lat0)] as const;
+    const minimum = declared ? sphericalExtremum(axis, local, undefined, false).value : -1;
+    const clipped = !declared || minimum <= Math.cos(horizon) + 1e-13;
+    const domain = clipped ? {latitude: base.lat0, distance: maximumDistance} : undefined;
+    const rectangle = createRectangleRenderingProfile(
+      () => resolveBounds(local, domain),
+      coverage,
+      base.long0,
+      base.primeMeridian
+    );
+    const polar = Math.abs(Math.cos(base.lat0)) < 1e-12;
+    const polarLatitude = ((Math.PI / 2 - maximumDistance) * 180) / Math.PI;
+    const normalizeCap =
+      domain &&
+      !polar &&
+      createAngularNormalization(point => {
+        const target = geographicVector(point.x - base.long0, point.y);
+        if (
+          target[0] * Math.cos(base.lat0) + target[2] * Math.sin(base.lat0) >=
+          Math.cos(domain.distance) - 1e-14
+        )
+          return;
+        if (Math.hypot(target[0] + axis[0], target[1], target[2] + axis[2]) < 1e-12) {
+          // All cap bearings are equally close to an exact antipode. Prefer
+          // northward to keep normalization stable, provided coverage allows it.
+          const angle = base.lat0 + domain.distance;
+          const center = (local[0][0] + local[1][0]) / 2;
+          const longitude = center + wrapLongitude((Math.cos(angle) < 0 ? Math.PI : 0) - center);
+          const latitude = Math.atan2(Math.sin(angle), Math.abs(Math.cos(angle)));
+          if (
+            longitude >= local[0][0] &&
+            longitude <= local[1][0] &&
+            latitude >= local[0][1] &&
+            latitude <= local[1][1]
+          ) {
+            point.x = longitude + base.long0;
+            point.y = latitude;
+            return;
+          }
+        }
+        const result = sphericalExtremum(target, local, domain);
+        [point.x, point.y] = [result.point[0] + base.long0, result.point[1]];
+      }, base.primeMeridian);
+    return {
+      get bounds() {
+        return resolveBounds(local, domain);
+      },
+      normalize(point) {
+        rectangle.normalize!(point);
+        if (domain && polar) {
+          // A polar cap is a latitude clamp in degrees; retain its input meridian.
+          point.y =
+            base.lat0 > 0 ? Math.max(polarLatitude, point.y) : Math.min(-polarLatitude, point.y);
+        } else normalizeCap?.(point);
+        // Cap extrema use a continuous coverage interval, which may lie on a
+        // different longitude branch than the rectangle's normalized output.
+        const center = ((base.long0 + base.primeMeridian) * 180) / Math.PI;
+        const offset = point.x - center;
+        if (Math.abs(offset) > 180) point.x = center + normalizeLongitude(offset);
+      }
+    };
+  };
+  return coverage => create(coverage ?? full, Boolean(coverage));
+}
+
+export function withAngularRenderingProfile(
+  implementation: ProjectionImplementation,
+  base: Pick<KernelParameters, 'long0' | 'lat0' | 'primeMeridian'>,
+  distance: number,
+  resolveBounds: ResolveAngularBounds,
+  horizon = Math.PI
+): ProjectionImplementation {
+  return {
+    ...implementation,
+    longitudeOrigin: base.long0,
+    getRenderingProfile: createAngularRenderingProfile(base, distance, resolveBounds, horizon)
+  };
+}