@math.gl/geospatial 5.0.0-alpha.17 → 5.0.0-alpha.19

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

@@ -0,0 +1,61 @@
+// 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 {krovakBounds} from '../rendering-profile/regional-rendering-bounds';
+import {createAngularRanges} from '../rendering-profile/geographic-bounds';
+import {withRectangleRenderingProfile} from '../rendering-profile/rectangular-rendering-profile';
+import type {ProjectionPlugin} from '../types';
+import {
+  catalogueParameters,
+  catalogueBoundsParameters,
+  bindCatalogueKernel
+} from '../catalogue-kernel';
+import {createState, forward, inverse} from '../kernels/krovak';
+import {numberParameter} from '../parameters';
+import {flagParameter, angleParameter} from '../kernel';
+
+export const krovak: ProjectionPlugin = {
+  name: 'krovak',
+  aliases: [
+    'Krovak',
+    'Krovak Modified',
+    'Krovak (North Orientated)',
+    'Krovak Modified (North Orientated)'
+  ],
+  parameters: ['lon_0', 'x_0', 'y_0', 'lat_0', 'k', 'k_0', 'czech', 'alpha', 'lat_ts'],
+  flags: ['czech'],
+  create(context) {
+    // The upstream kernel fixes these angles. Accept the two published azimuth
+    // spellings (legacy PROJ and EPSG), but never silently ignore custom angles.
+    const alpha = numberParameter(context.parameters, 'alpha', 30.28813972222222);
+    const parallel = numberParameter(context.parameters, 'lat_ts', 78.5);
+    if (![30.28813972222222, 30.28813975277778].some(value => Math.abs(alpha - value) <= 1e-10))
+      throw new Error('Krovak requires its fixed cone-axis co-latitude');
+    if (Math.abs(parallel - 78.5) > 1e-10)
+      throw new Error('Krovak requires its fixed 78.5 degree pseudo standard parallel');
+    const base = catalogueParameters(context);
+    base.lat0 = angleParameter(context.parameters, 'lat_0', 49.5);
+    base.long0 = angleParameter(context.parameters, 'lon_0', 24.83333333333333);
+    base.k0 = numberParameter(
+      context.parameters,
+      'k_0',
+      numberParameter(context.parameters, 'k', 0.9999)
+    );
+    const state = createState(base, {czech: flagParameter(context.parameters, 'czech')});
+    // Render the regional conic around its configured origin.
+    const projection = bindCatalogueKernel('krovak', context, state, forward, inverse);
+    return withRectangleRenderingProfile(
+      projection,
+      createAngularRanges(
+        base.long0 - Math.PI / 12,
+        Math.max(-Math.PI / 2 + 1e-8, base.lat0 - Math.PI / 36),
+        base.long0 + Math.PI / 12,
+        Math.min(Math.PI / 2 - 1e-8, base.lat0 + Math.PI / 36)
+      ),
+      ranges => krovakBounds(catalogueBoundsParameters(state, context), ranges),
+      base.primeMeridian,
+      base.over
+    );
+  }
+};

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

@@ -0,0 +1,39 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import qsfnz from '../common/qsfnz';
+import {withAngularRenderingProfile} from '../rendering-profile/angular-rendering-profile';
+import {equalAreaAzimuthalBounds} from '../rendering-profile/azimuthal-rendering-bounds';
+import type {ProjectionPlugin} from '../types';
+import {bindKernel, guardAzimuthalDomain, kernelParameters, ORIGIN_PARAMETERS} from '../kernel';
+import {createState, forward, inverse} from '../kernels/laea';
+
+export const lambertAzimuthalEqualArea: ProjectionPlugin = {
+  name: 'laea',
+  aliases: ['Lambert Azimuthal Equal Area', 'Lambert_Azimuthal_Equal_Area'],
+  parameters: ORIGIN_PARAMETERS,
+  create(context) {
+    const base = kernelParameters(context);
+
+    const state = createState(base);
+    // Keep the rendering boundary finite without restricting raw conversion.
+    return withAngularRenderingProfile(
+      guardAzimuthalDomain(base, bindKernel('laea', state, forward, inverse)),
+      base,
+      (Math.PI * 179) / 180,
+      (region, domain) =>
+        equalAreaAzimuthalBounds(
+          base,
+          base.sphere ? 1 : state.xmf || Math.sqrt(state.qp / 2),
+          base.sphere ? 1 : state.ymf || Math.sqrt(state.qp / 2),
+          region,
+          domain,
+          base.sphere ? base.lat0 : Math.asin(qsfnz(base.e, Math.sin(base.lat0)) / state.qp),
+          base.sphere
+            ? latitude => latitude
+            : latitude => Math.asin(qsfnz(base.e, Math.sin(latitude)) / state.qp)
+        )
+    );
+  }
+};

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

@@ -0,0 +1,67 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import type {ProjectionPlugin} from '../types';
+import {conicBounds} from '../rendering-profile/rendering-bounds';
+import {createAngularRanges} from '../rendering-profile/geographic-bounds';
+import {withRectangleRenderingProfile} from '../rendering-profile/rectangular-rendering-profile';
+import {createFlatProjection as createProjection} from '../flat-projection';
+import {
+  bindKernel,
+  kernelParameters,
+  ORIGIN_PARAMETERS,
+  SCALE_PARAMETERS,
+  validateConic
+} from '../kernel';
+import {createState, forward, inverse} from '../kernels/lcc';
+
+export const lambertConformalConic: ProjectionPlugin = {
+  name: 'lcc',
+  aliases: [
+    'Lambert Tangential Conformal Conic Projection',
+    'Lambert_Conformal_Conic',
+    'Lambert_Conformal_Conic_1SP',
+    'Lambert_Conformal_Conic_2SP',
+    'Lambert Conic Conformal (1SP)',
+    'Lambert Conic Conformal (2SP)'
+  ],
+  parameters: [...ORIGIN_PARAMETERS, ...SCALE_PARAMETERS, 'lat_1', 'lat_2'],
+  create(context) {
+    const base = kernelParameters(context);
+    validateConic(base, context.parameters);
+    const state = createState(base);
+    const implementation = bindKernel('lcc', state, forward, inverse);
+    // The opposite pole diverges for LCC; its rendering target stops at 60 degrees.
+    const projection = {
+      ...createProjection(point => {
+        const latitude = point.y;
+        if (Math.abs(latitude) === Math.PI / 2 && latitude * state.ns < 0) {
+          throw new Error('Lambert conformal conic is undefined at the opposite pole');
+        }
+        implementation.forwardInPlace!(point);
+      }, implementation.inverseInPlace!)
+    };
+    return withRectangleRenderingProfile(
+      projection,
+      createAngularRanges(
+        base.long0 - Math.PI,
+        state.ns > 0 ? -Math.PI / 3 : -Math.PI / 2,
+        base.long0 + Math.PI,
+        state.ns > 0 ? Math.PI / 2 : Math.PI / 3
+      ),
+      ranges =>
+        conicBounds(
+          projection.forward,
+          ranges,
+          base.long0,
+          state.ns,
+          state.x0,
+          state.y0 + state.k0 * state.rh,
+          base.over
+        ),
+      base.primeMeridian,
+      base.over
+    );
+  }
+};

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

@@ -0,0 +1,150 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+// SPDX-FileComment: Original implementation of projection equations; compatibility informed by proj4js 2.22.0.
+
+import {createFlatProjection as createProjection} from '../flat-projection';
+import {DEGREES_TO_RADIANS, latitudeParameter, numberParameter, wrapLongitude} from '../parameters';
+import type {ProjectionPlugin} from '../types';
+import {createAngularRanges, getGeographicBounds} from '../rendering-profile/geographic-bounds';
+import {createRectangleRenderingProfile} from '../rendering-profile/rectangular-rendering-profile';
+import {
+  longitudeRange,
+  envelope,
+  scale as scaleRange,
+  add
+} from '../rendering-profile/rendering-bounds';
+
+/** Spherical and ellipsoidal Mercator, using the PROJ Mercator equations. */
+export const mercator: ProjectionPlugin = {
+  name: 'merc',
+  aliases: [
+    'Mercator',
+    'Popular Visualisation Pseudo Mercator',
+    'Mercator_1SP',
+    'Mercator_Auxiliary_Sphere',
+    'Mercator_Variant_A'
+  ],
+  parameters: ['lon_0', 'lat_ts', 'k', 'k_0', 'x_0', 'y_0'],
+  create({semiMajorAxis: a, eccentricitySquared: es, parameters, primeMeridian = 0}) {
+    const e = Math.sqrt(es);
+    const over = Object.prototype.hasOwnProperty.call(parameters, 'over');
+    const longitudeOrigin = numberParameter(parameters, 'lon_0', 0) * DEGREES_TO_RADIANS;
+    const x0 = numberParameter(parameters, 'x_0', 0);
+    const y0 = numberParameter(parameters, 'y_0', 0);
+    let scale = numberParameter(parameters, 'k_0', numberParameter(parameters, 'k', 1));
+    if (Object.prototype.hasOwnProperty.call(parameters, 'lat_ts')) {
+      const latitude = latitudeParameter(parameters, 'lat_ts');
+      scale = Math.cos(latitude) / Math.sqrt(1 - es * Math.sin(latitude) ** 2);
+    }
+    if (scale <= 0) throw new Error('Mercator scale must be positive');
+    const radius = a * scale;
+    // One finite world is the rendering target, even with unrestricted +over conversion.
+    const maxLatitude = Math.atan(Math.sinh(Math.PI));
+    const width = radius * Math.PI;
+    const height = radius * (Math.PI - e * Math.atanh(e * Math.sin(maxLatitude)));
+    return {
+      longitudeOrigin,
+      getRenderingProfile(coverage) {
+        if (coverage) {
+          // Only the mathematical poles trigger clipping; finite declared
+          // latitudes beyond the default cap remain available as render targets.
+          const clipped = coverage[1] <= -90 || coverage[3] >= 90;
+          const bounds = [
+            coverage[0],
+            clipped
+              ? Math.max(
+                  (-maxLatitude * 180) / Math.PI,
+                  Math.min((maxLatitude * 180) / Math.PI, coverage[1])
+                )
+              : coverage[1],
+            coverage[2],
+            clipped
+              ? Math.max(
+                  (-maxLatitude * 180) / Math.PI,
+                  Math.min((maxLatitude * 180) / Math.PI, coverage[3])
+                )
+              : coverage[3]
+          ] as const;
+          const northing = (latitude: number) =>
+            y0 + radius * (Math.asinh(Math.tan(latitude)) - e * Math.atanh(e * Math.sin(latitude)));
+          return createRectangleRenderingProfile(
+            region =>
+              envelope(
+                add([x0, x0], scaleRange(longitudeRange(region, longitudeOrigin, over), radius)),
+                [northing(region[0][1]), northing(region[1][1])]
+              ),
+            bounds,
+            longitudeOrigin,
+            primeMeridian,
+            over
+          );
+        }
+        const defaultBounds = [
+          [x0 - width, y0 - height, 0],
+          [x0 + width, y0 + height, 0]
+        ] as const;
+        return {
+          bounds: defaultBounds,
+          normalize: createRectangleRenderingProfile(
+            () => defaultBounds,
+            getGeographicBounds(
+              createAngularRanges(
+                longitudeOrigin - Math.PI,
+                -maxLatitude,
+                longitudeOrigin + Math.PI,
+                maxLatitude
+              ),
+              primeMeridian
+            ),
+            longitudeOrigin,
+            primeMeridian,
+            over
+          ).normalize
+        };
+      },
+      ...createProjection(
+        point => {
+          const longitude = point.x,
+            latitude = point.y;
+          if (Math.abs(latitude) >= Math.PI / 2) {
+            throw new Error('Mercator is undefined at the poles');
+          }
+          const isometricLatitude = Math.asinh(Math.tan(latitude));
+          point.x = x0 + radius * wrapLongitude(longitude - longitudeOrigin, over);
+          // Spherical Mercator has no ellipsoidal correction. Normalize signed zero.
+          point.y =
+            y0 +
+            radius *
+              (e === 0
+                ? isometricLatitude + 0
+                : isometricLatitude - e * Math.atanh(e * Math.sin(latitude)));
+        },
+        point => {
+          const x = point.x,
+            y = point.y;
+          const isometricLatitude = (y - y0) / radius;
+          let latitude = Math.atan(Math.sinh(isometricLatitude));
+          // The spherical inverse is already exact; no iteration is needed.
+          if (e === 0) {
+            point.x = wrapLongitude(longitudeOrigin + (x - x0) / radius, over);
+            point.y = latitude + 0;
+            return;
+          }
+          for (let iteration = 0; iteration < 30; iteration++) {
+            const next = Math.atan(
+              Math.sinh(isometricLatitude + e * Math.atanh(e * Math.sin(latitude)))
+            );
+            if (Math.abs(next - latitude) < 1e-13) {
+              point.x = wrapLongitude(longitudeOrigin + (x - x0) / radius, over);
+              point.y = next;
+              return;
+            }
+            latitude = next;
+          }
+          throw new Error('Mercator inverse did not converge');
+        }
+      )
+    };
+  }
+};

package/src/projection/experimental/projections/mill.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 {cylindricalBounds} 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/mill';
+
+export const millerCylindrical: ProjectionPlugin = {
+  name: 'mill',
+  aliases: ['Miller_Cylindrical'],
+  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('mill', context, state, forward, inverse);
+    return withRectangleRenderingProfile(
+      projection,
+      createAngularRanges(base.long0 - Math.PI, -Math.PI / 2, base.long0 + Math.PI, Math.PI / 2),
+      ranges => cylindricalBounds(projection.forward, ranges, base.long0, base.over),
+      base.primeMeridian,
+      base.over
+    );
+  }
+};

package/src/projection/experimental/projections/moll.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 {cylindricalBounds} 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/moll';
+
+export const mollweide: ProjectionPlugin = {
+  name: 'moll',
+  aliases: ['Mollweide'],
+  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('moll', context, state, forward, inverse);
+    return withRectangleRenderingProfile(
+      projection,
+      createAngularRanges(base.long0 - Math.PI, -Math.PI / 2, base.long0 + Math.PI, Math.PI / 2),
+      ranges => cylindricalBounds(projection.forward, ranges, base.long0, base.over),
+      base.primeMeridian,
+      base.over
+    );
+  }
+};

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

@@ -0,0 +1,47 @@
+// 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 {nzmgBounds} from '../rendering-profile/regional-rendering-bounds';
+import {createAngularRanges} from '../rendering-profile/geographic-bounds';
+import {withRectangleRenderingProfile} from '../rendering-profile/rectangular-rendering-profile';
+import type {ProjectionPlugin} from '../types';
+import {
+  catalogueParameters,
+  catalogueBoundsParameters,
+  bindCatalogueKernel
+} from '../catalogue-kernel';
+import {createState, forward, inverse} from '../kernels/nzmg';
+import {numberParameter} from '../parameters';
+
+export const newZealandMapGrid: ProjectionPlugin = {
+  name: 'nzmg',
+  aliases: ['New_Zealand_Map_Grid'],
+  parameters: ['lon_0', 'x_0', 'y_0', 'lat_0', 'iterations'],
+  create(context) {
+    const base = catalogueParameters(context);
+    const iterations = numberParameter(context.parameters, 'iterations', 1);
+    if (!Number.isInteger(iterations) || iterations < 0 || iterations > 10)
+      throw new Error('NZMG iterations must be an integer from 0 to 10');
+    if (
+      !Object.prototype.hasOwnProperty.call(context.parameters, 'lat_0') ||
+      !Object.prototype.hasOwnProperty.call(context.parameters, 'lon_0')
+    )
+      throw new Error('NZMG requires lat_0 and lon_0');
+    const state = createState(base, {iterations});
+    // The New Zealand polynomial is regional: render eight degrees around its origin.
+    const projection = bindCatalogueKernel('nzmg', context, state, forward, inverse);
+    return withRectangleRenderingProfile(
+      projection,
+      createAngularRanges(
+        base.long0 - Math.PI / 22.5,
+        Math.max(-Math.PI / 2, base.lat0 - Math.PI / 22.5),
+        base.long0 + Math.PI / 22.5,
+        Math.min(Math.PI / 2, base.lat0 + Math.PI / 22.5)
+      ),
+      ranges => nzmgBounds(catalogueBoundsParameters(state, context), ranges),
+      base.primeMeridian,
+      base.over
+    );
+  }
+};