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

package/src/constants.ts

@@ -5,7 +5,7 @@
 // SPDX-FileComment: Derived from Cesium. See the repository LICENSE for upstream attribution and Apache-2.0 terms.
 
 // This file is derived from the Cesium math library under Apache 2 license
-// See LICENSE.md and https://github.com/AnalyticalGraphicsInc/cesium/blob/master/LICENSE.md
+// See ../LICENSE for the retained Cesium notice and Apache-2.0 terms.
 
 export const WGS84_RADIUS_X = 6378137.0;
 export const WGS84_RADIUS_Y = 6378137.0;

package/src/discontinuous/AIR-OCEAN-LICENSE.txt

@@ -0,0 +1,26 @@
+Copyright 2017-2024 Mike Bostock
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.
+
+Philippe Rivière’s implementation of the Gray-Fuller raw projection (grayfuller.js)
+belongs to the public domain.
+
+> Buckminster Fuller’s spherical triangle transformation procedure
+>
+> Based on Robert W. Gray’s formulae published in “Exact Transformation Equations
+> For Fuller's World Map,” _Cartographica_, 32(3): 17-25 (1995).
+>
+> Implemented for D3.js by Philippe Rivière, 2018 (https://visionscarto.net/)
+>
+> To the extent possible under law, Philippe Rivière has waived all copyright
+> and related or neighboring rights to this implementation. (Public Domain.)

package/src/discontinuous/D3-LICENSE.txt

@@ -0,0 +1,37 @@
+Copyright 2013-2021 Mike Bostock
+
+Permission to use, copy, modify, and/or distribute this software for any purpose
+with or without fee is hereby granted, provided that the above copyright notice
+and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES WITH
+REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
+FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY SPECIAL, DIRECT,
+INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS
+OF USE, DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE OR OTHER
+TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF
+THIS SOFTWARE.
+
+MIT License for https://github.com/scijs/integrate-adaptive-simpson
+
+The MIT License (MIT)
+
+Copyright 2015 Ricky Reusser
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/src/discontinuous/PETROFF-LICENSE.txt

@@ -0,0 +1,55 @@
+# Supplement to _A Square Equal-area Map Projection with Low Angular Distortion, Minimal Cusps, and Closed-form Solutions_
+
+This work serves as a supplement to the paper titled
+_A Square Equal-area Map Projection with Low Angular Distortion, Minimal Cusps, and Closed-form Solutions_.
+
+This archive contains the map projection implementations used in the analysis,
+the notebook used to perform the analysis, and the source files for the figures
+in the paper. It aims to be compatible with [Binder](https://mybinder.org/) for
+reproducibility.
+
+
+## Map Analysis
+
+The `map-projection-analysis.ipynb` notebook was used to perform the map
+projection analysis for the paper, using map projection implementations defined
+in the `collignon_quincuncial.py`, `gringorten.py`, and `new_projection.py`
+source files. The outputs of this notebook are in the `output` directory. The
+`input` directory contains the equirectangular-format source panorama used for
+one of the figures; the reproduced Haslam map data need to be downloaded from
+[LAMBDA](https://lambda.gsfc.nasa.gov/product/foreground/fg_2014_haslam_408_get.cfm)
+and placed in this directory.
+
+
+## Figure Sources
+
+The `figure-sources` directory contains the source files for the triangle
+drawings in the paper, which were constructed using
+[Asymptote](https://asymptote.sourceforge.io/). It also contains the source
+files for the world maps, which were drawn using [D3.js](https://d3js.org/);
+the SVG files were extracted using
+[SVG Crowbar 2](https://nytimes.github.io/svg-crowbar/). The components of the
+outline figure were constructed using Asymptote but then edited and assembled
+using Inkscape.
+
+
+## License
+
+This work is placed into the public domain via the
+[CC0 1.0 public domain dedication](https://creativecommons.org/publicdomain/zero/1.0/)
+except for the `gringorten.py`, `surfacepaths.asy`, `peabody-library-stacks-pano.jpg`, and
+`new-projection-pano.png` files. The `gringorten.py` file is based on the
+Gringorten projection implementation in `d3-geo-projection`, which is licensed
+under a [3-Clause BSD License](https://github.com/d3/d3-geo-projection/blob/6b86866e19ba9959bb0ac115689ffac5ccf6d3db/LICENSE).
+The `surfacepaths.asy` file is from a [Stack Exchange post](https://tex.stackexchange.com/a/135438)
+by Charles Staats, which is licensed under a
+[CC BY-SA 3.0 license](https://creativecommons.org/licenses/by-sa/3.0/).
+The `peabody-library-stacks-pano.jpg` and `new-projection-pano.png` images are
+copyright Matthew Petroff and are licensed under a
+[CC BY 4.0 license](https://creativecommons.org/licenses/by/4.0/).
+
+
+## Credits
+
+This work was produced by Matthew A. Petroff
+([ORCID:0000-0002-4436-4215](https://orcid.org/0000-0002-4436-4215)).

package/src/discontinuous/PROJ-LICENSE.txt

@@ -0,0 +1,34 @@
+
+All source, data files and other contents of the PROJ package are 
+available under the following terms.  Note that the PROJ 4.3 and earlier
+was "public domain" as is common with US government work, but apparently
+this is not a well defined legal term in many countries. Frank Warmerdam placed
+everything under the following MIT style license because he believed it is
+effectively the same as public domain, allowing anyone to use the code as
+they wish, including making proprietary derivatives.
+
+Initial PROJ 4.3 public domain code was put as Frank Warmerdam as copyright
+holder, but he didn't mean to imply he did the work. Essentially all work was
+done by Gerald Evenden.
+
+Copyright information can be found in source files.
+
+ --------------
+
+ Permission is hereby granted, free of charge, to any person obtaining a
+ copy of this software and associated documentation files (the "Software"),
+ to deal in the Software without restriction, including without limitation
+ the rights to use, copy, modify, merge, publish, distribute, sublicense,
+ and/or sell copies of the Software, and to permit persons to whom the
+ Software is furnished to do so, subject to the following conditions:
+
+ The above copyright notice and this permission notice shall be included
+ in all copies or substantial portions of the Software.
+
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+ OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+ THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+ FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+ DEALINGS IN THE SOFTWARE.

package/src/discontinuous/air-ocean-mesh.ts

@@ -0,0 +1,86 @@
+// math.gl
+// SPDX-License-Identifier: ISC
+// SPDX-FileCopyrightText: Copyright 2017-2024 Mike Bostock
+// AirOcean topology/rotation adapted from d3-geo-polygon, ISC license.
+// Copyright 2017-2024 Mike Bostock. See AIR-OCEAN-LICENSE.txt.
+// Arrangement implementation credited upstream to Jason Davies, Enrico Spinielli,
+// and Philippe Riviere. Hinge geometry and rendering are independent of Nico's code.
+
+import {Matrix4} from '@math.gl/core';
+import {add, cross, dot, scale, type Vector as Vec3} from './math';
+const subtract = (a: Vec3, b: Vec3) => add(a, scale(b, -1));
+const center = (points: Vec3[]) => scale(points.reduce(add, [0, 0, 0]), 1 / points.length);
+type Polyhedron = {vertices: Vec3[]; faces: number[][]};
+
+/** The 24-piece AirOcean net: 20 icosahedron faces, with three faces split.
+ * Added vertices stay in the original planar facets, preserving a true flat net.
+ * This supplies the cut arrangement, not the Gray-Fuller geographic projection.
+ */
+export function airOceanMesh(): {mesh: Polyhedron; joins: number[][]} {
+  const latitude = Math.atan(0.5);
+  const vertices: Vec3[] = [
+    [0, 0, 1],
+    [0, 0, -1]
+  ];
+  for (let i = 0; i < 10; i++) {
+    const lon = (i * Math.PI) / 5,
+      lat = i % 2 ? latitude : -latitude;
+    vertices.push([Math.cos(lat) * Math.cos(lon), Math.cos(lat) * Math.sin(lon), Math.sin(lat)]);
+  }
+  const faces = [
+    [0, 3, 11],
+    [0, 5, 3],
+    [0, 7, 5],
+    [0, 9, 7],
+    [0, 11, 9],
+    [2, 11, 3],
+    [3, 4, 2],
+    [4, 3, 5],
+    [5, 6, 4],
+    [6, 5, 7],
+    [7, 8, 6],
+    [8, 7, 9],
+    [9, 10, 8],
+    [10, 9, 11],
+    [11, 2, 10],
+    [1, 2, 4],
+    [1, 4, 6],
+    [1, 6, 8],
+    [1, 8, 10],
+    [1, 10, 2]
+  ];
+  vertices.push(center(faces[15].map(i => vertices[i]))); // 12: facet centroid
+  vertices.push(center([vertices[2], vertices[10]])); // 13: shared edge midpoint
+  faces[15] = [12, 2, 4];
+  faces.push([1, 12, 4], [1, 2, 12]); // 20,21
+  faces[14] = [11, 13, 10];
+  faces.push([11, 2, 13]); // 22
+  faces[19] = [1, 13, 2];
+  faces.push([13, 1, 10]); // 23
+  // Invert the geographic-to-polyhedron Euler rotation from the AirOcean preset.
+  const radians = Math.PI / 180;
+  const rotation = new Matrix4()
+    .rotateZ(83.65929 * radians)
+    .rotateY(25.44458 * radians)
+    .rotateX(87.45184 * radians);
+  const geographicVertices = vertices.map(v => Array.from(rotation.transformAsPoint(v)) as Vec3);
+  for (const f of faces) {
+    if (
+      dot(
+        cross(
+          subtract(geographicVertices[f[1]], geographicVertices[f[0]]),
+          subtract(geographicVertices[f[2]], geographicVertices[f[0]])
+        ),
+        geographicVertices[f[0]]
+      ) < 0
+    )
+      f.reverse();
+  }
+  const parents = [
+    -1, 0, 1, 11, 13, 6, 7, 1, 7, 8, 9, 10, 11, 12, 13, 6, 8, 10, 17, 21, 16, 15, 19, 19
+  ];
+  return {
+    mesh: {vertices: geographicVertices, faces},
+    joins: parents.flatMap((parent, face) => (parent < 0 ? [] : [[parent, face]]))
+  };
+}

package/src/discontinuous/albers-usa.ts

@@ -0,0 +1,181 @@
+// math.gl
+// SPDX-License-Identifier: MIT
+// SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
+
+import {DiscontinuousMap, type MapRegion} from './map-layout';
+import {RAD, type Position} from './math';
+
+/** Independent spherical Albers USA composite with Alaska and Hawaii insets.
+ * Geographic masks have great-circle edges, not political or D3 clip boundaries.
+ */
+export function createAlbersUsaMap(
+  options: {radius?: number; includeTerritories?: boolean} = {}
+): DiscontinuousMap {
+  const radius = options.radius ?? 1;
+  if (!Number.isFinite(radius) || radius <= 0)
+    throw new Error('Radius must be finite and positive');
+  const region = (
+    id: string,
+    bounds: [number, number, number, number],
+    center: Position,
+    parallels: Position,
+    size: number,
+    offset: Position,
+    insetBounds?: [number, number, number, number]
+  ): MapRegion => {
+    const [west, south, east, north] = bounds;
+    const n = (Math.sin(parallels[0] * RAD) + Math.sin(parallels[1] * RAD)) / 2;
+    const c = Math.cos(parallels[0] * RAD) ** 2 + 2 * n * Math.sin(parallels[0] * RAD);
+    const rho = (latitude: number) => Math.sqrt(c - 2 * n * Math.sin(latitude)) / n;
+    const origin = rho(center[1] * RAD);
+    const definition: MapRegion = {
+      id,
+      layout: {
+        label:
+          {
+            lower48: 'Contiguous U.S.',
+            alaska: 'Alaska',
+            hawaii: 'Hawaii',
+            puertoRico: 'Puerto Rico',
+            virginIslands: 'U.S. Virgin Islands',
+            guam: 'Guam',
+            northernMariana: 'Northern Mariana Islands',
+            americanSamoa: 'American Samoa'
+          }[id] ?? id,
+        kind: insetBounds ? 'inset' : 'main',
+        ...(insetBounds
+          ? {
+              parentId: 'lower48',
+              frame: insetBounds.map(v => v * radius) as [number, number, number, number]
+            }
+          : {}),
+        relativeScale: size,
+        drawOrder: insetBounds ? 1 : 0
+      },
+      boundary: [
+        [west, south],
+        [east, south],
+        [east, north],
+        [west, north]
+      ],
+      interior: center,
+      placement: [radius * size, 0, 0, radius * size, radius * offset[0], radius * offset[1]],
+      project: ([longitude, latitude]) => {
+        const delta = ((((longitude - center[0] + 180) % 360) + 360) % 360) - 180;
+        const angle = n * delta * RAD,
+          r = rho(latitude * RAD);
+        return [r * Math.sin(angle), origin - r * Math.cos(angle)];
+      },
+      unproject: ([x, y]) => {
+        const dy = origin - y;
+        const sine = (c - n * n * (x * x + dy * dy)) / (2 * n);
+        if (Math.abs(sine) > 1 + 1e-12) return null;
+        return [
+          center[0] + Math.atan2(x * Math.sign(n), dy * Math.sign(n)) / n / RAD,
+          Math.asin(Math.max(-1, Math.min(1, sine))) / RAD
+        ];
+      }
+    };
+    if (insetBounds) {
+      const [left, bottom, right, top] = insetBounds;
+      definition.boundary = [
+        [left, bottom],
+        [right, bottom],
+        [right, top],
+        [left, top]
+      ].map(([x, y]) => definition.unproject([(x - offset[0]) / size, (y - offset[1]) / size])!);
+      definition.interior = definition.unproject([
+        ((left + right) / 2 - offset[0]) / size,
+        ((bottom + top) / 2 - offset[1]) / size
+      ])!;
+    }
+    return definition;
+  };
+  const regions = [
+    region('lower48', [-127, 20, -65, 51], [-96, 38], [29.5, 45.5], 1, [0, 0]),
+    region(
+      'alaska',
+      [-190, 40, -130, 78],
+      [-154, 60],
+      [55, 65],
+      0.35,
+      [-0.307, -0.201],
+      [-0.425, -0.234, -0.22, -0.12]
+    ),
+    region(
+      'hawaii',
+      [-179, 17, -153, 30],
+      [-157, 21],
+      [8, 18],
+      1,
+      [-0.15, -0.2],
+      [-0.215, -0.245, -0.1, -0.155]
+    )
+  ];
+  if (options.includeTerritories) {
+    const territory = (
+      id: string,
+      bounds: [number, number, number, number],
+      center: Position,
+      parallels: Position,
+      scale: number,
+      frame: [number, number, number, number]
+    ) => {
+      const result = region(id, bounds, center, parallels, scale, [
+        (frame[0] + frame[2]) / 2,
+        (frame[1] + frame[3]) / 2
+      ]);
+      result.layout = {
+        ...result.layout,
+        kind: 'inset',
+        parentId: 'lower48',
+        frame: frame.map(value => value * radius) as [number, number, number, number],
+        drawOrder: 1
+      };
+      return result;
+    };
+    regions.push(
+      territory(
+        'puertoRico',
+        [-68.4, 17.4, -64.2, 19.2],
+        [-66.4, 18.2],
+        [15, 21],
+        2.6,
+        [-0.205, -0.34, -0.125, -0.26]
+      ),
+      territory(
+        'virginIslands',
+        [-65.2, 17.6, -64.3, 18.8],
+        [-64.8, 18.3],
+        [15, 21],
+        7,
+        [-0.12, -0.34, -0.04, -0.26]
+      ),
+      territory(
+        'guam',
+        [144.4, 13.1, 145.1, 13.9],
+        [144.8, 13.5],
+        [10, 17],
+        7,
+        [-0.035, -0.34, 0.045, -0.26]
+      ),
+      territory(
+        'northernMariana',
+        [144.7, 13.8, 146.4, 20.6],
+        [145.6, 17],
+        [12, 20],
+        2.5,
+        [0.05, -0.34, 0.13, -0.26]
+      ),
+      territory(
+        'americanSamoa',
+        [-171.5, -14.5, -168, -10.8],
+        [-170.6, -12.8],
+        [-17, -11],
+        5,
+        [0.135, -0.34, 0.215, -0.26]
+      )
+    );
+  }
+  return new DiscontinuousMap(regions);
+}