@math.gl/earth 5.0.0-beta.1 → 5.0.0-beta.11

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (41) hide show
  1. package/README.md +157 -0
  2. package/THIRD-PARTY-NOTICES.md +7 -7
  3. package/{geoid/data → data/geoid}/README.md +0 -3
  4. package/{timezone/data → data/timezone}/README.md +2 -18
  5. package/dist/index.cjs +6 -4
  6. package/dist/index.cjs.map +3 -3
  7. package/dist/sun/cloud-lighting.d.ts.map +1 -1
  8. package/dist/sun/cloud-lighting.js +2 -2
  9. package/dist/sun/cloud-lighting.js.map +1 -1
  10. package/dist/sun/index.cjs +6 -4
  11. package/dist/sun/index.cjs.map +3 -3
  12. package/dist/sun/moon.js +1 -1
  13. package/dist/sun/moon.js.map +1 -1
  14. package/dist/sun/planet-visibility.d.ts.map +1 -1
  15. package/dist/sun/planet-visibility.js +2 -2
  16. package/dist/sun/planet-visibility.js.map +1 -1
  17. package/dist/sun/sky-lighting.js +1 -1
  18. package/dist/sun/sky-lighting.js.map +1 -1
  19. package/dist/sun/sunlight.js +1 -1
  20. package/dist/sun/sunlight.js.map +1 -1
  21. package/package.json +15 -17
  22. package/src/sun/cloud-lighting.ts +2 -2
  23. package/src/sun/data/bright-stars.ts +1 -1
  24. package/src/sun/moon.ts +1 -1
  25. package/src/sun/planet-visibility.ts +2 -2
  26. package/src/sun/sky-lighting.ts +1 -1
  27. package/src/sun/sunlight.ts +1 -1
  28. package/src/timezone/vendor/temporal/README.md +0 -23
  29. package/src/timezone/vendor/tz-lookup/README.md +0 -22
  30. /package/{sun/LICENSE-BRIGHT-STARS → LICENSE-BRIGHT-STARS} +0 -0
  31. /package/{sun/LICENSE-HOSEK-WILKIE → LICENSE-HOSEK-WILKIE} +0 -0
  32. /package/{sun/LICENSE-SUNCALC → LICENSE-SUNCALC} +0 -0
  33. /package/{geoid/data → data/geoid}/geoid-egm96-hi.pgm +0 -0
  34. /package/{geoid/data → data/geoid}/geoid-egm96-low.pgm +0 -0
  35. /package/{geoid/data → data/geoid}/geoid-manifest.json +0 -0
  36. /package/{timezone/data → data/timezone}/LICENSE-ODbL.txt +0 -0
  37. /package/{timezone/data → data/timezone}/manifest.json +0 -0
  38. /package/{timezone/data → data/timezone}/timezone-geometry-hi.json +0 -0
  39. /package/{timezone/data → data/timezone}/timezone-geometry-hi.parquet +0 -0
  40. /package/{timezone/data → data/timezone}/timezone-geometry-low.json +0 -0
  41. /package/{timezone/data → data/timezone}/timezone-geometry-low.parquet +0 -0
package/README.md CHANGED
@@ -18,3 +18,160 @@ Existing `@math.gl/earth`, `@math.gl/earth/sun`, and `@math.gl/earth/timezone` i
18
18
 
19
19
  See [the packaged source and license index](./THIRD-PARTY-NOTICES.md) and
20
20
  [math.gl references and credits](https://math.gl/docs/references-and-credits).
21
+
22
+ ## Geoid
23
+
24
+ This module contains support for non-ellipsoidal surface using earth gravity models.
25
+
26
+ Use `createGeoidFromGrid({width, height, values, offset, scale, cubic})` to create
27
+ a geoid from a complete decoded `Uint16Array` grid, including Parquet's
28
+ `raw_value` column. The array must retain GeographicLib row/column order.
29
+ Decode files in the application; this API requires no Arrow or Parquet dependency.
30
+ See the [grid factory documentation](https://github.com/visgl/math.gl/blob/master/docs/modules/earth/geoid/api-reference/create-geoid-from-grid.md).
31
+
32
+ ### Optional EGM96 grids
33
+
34
+ Import `@math.gl/earth/geoid/geoid-egm96-low.pgm` (1° preview, 130 KB) or
35
+ `@math.gl/earth/geoid/geoid-egm96-hi.pgm` (15′ original, 2.08 MB) as an asset URL, fetch
36
+ the bytes, and pass them to `parsePGM(bytes, {cubic: true})`. In Node, resolve the
37
+ asset with `import.meta.resolve` and read it using `node:fs/promises`.
38
+
39
+ `getHeight(latitude, longitude)` returns geoid height N above WGS84 in meters:
40
+ h = H + N. Use the original grid for height conversion; the preview is downsampled
41
+ for visualization. See [data provenance and licensing](./data/geoid/README.md).
42
+
43
+ ## Sun
44
+
45
+ This module contains math to calculate sun positions.
46
+
47
+ Sunlight color and intensity use derived Hošek–Wilkie 1.4a model data under BSD-3-Clause.
48
+ The complete copyright and license notice is included in `LICENSE-HOSEK-WILKIE`.
49
+ Original math.gl code is MIT-licensed; generated data carries its own SPDX notice.
50
+
51
+ Lunar ephemeris and illumination calculations are adapted from SunCalc 1.9.0 under BSD-2-Clause. The full notice is included in `LICENSE-SUNCALC`. Original moonlight and star-field rotation code is MIT-licensed; source files carry SPDX ownership and provenance comments.
52
+
53
+ The `@math.gl/earth/sun` entry point uses the declared
54
+ MIT-licensed `astronomy-engine` dependency for planetary and Galilean moon ephemerides.
55
+ Its original TypeScript adapter records API and physical-data references in SPDX comments.
56
+
57
+ ## Timezone
58
+
59
+ `@math.gl/earth/timezone` is an intentional complement to JavaScript's `Intl`: it supplies geographic timezone lookup and numeric local-calendar computations for maps, charts, daily aggregation, and scheduling. `Intl` remains the interface for localized presentation and supplies the runtime's timezone rules. math.gl turns those rules into application-facing coordinates, fields, offsets, day boundaries, and transition records.
60
+
61
+ ### Design
62
+
63
+ The API centers on computational results: IANA identifiers, numeric fields, and epoch milliseconds. Use `Intl.DateTimeFormat` directly for general date and time formatting; the module's date-aware timezone label helper is a small convenience for timezone selectors and legends.
64
+
65
+ Capabilities have separate dependency boundaries:
66
+
67
+ - `@math.gl/earth/timezone`: offsets, local calendar fields, timezone labels, runtime identifier support, and lazy geographic lookup. These utilities use native `Intl`.
68
+ - `@math.gl/earth/timezone`: synchronous approximate geographic lookup with the compact boundary table.
69
+ - `@math.gl/earth/timezone`: local-day boundaries, local-time conversion, and offset transitions. This entry point uses a vendored copy of `@js-temporal/polyfill` 0.5.1 (including JSBI) for Temporal algorithms across supported browsers and Node versions. It does not modify globals. Its vendored compatibility implementation is isolated from root and lookup consumers; it still uses runtime timezone rules.
70
+
71
+ The package does not ship an `Intl` polyfill or a separate date-specific timezone-rule database.
72
+
73
+ ### Installation
74
+
75
+ ```bash
76
+ npm install @math.gl/earth
77
+ ```
78
+
79
+ ### Usage
80
+
81
+ ```typescript
82
+ import {getTimezoneOffset, getLocalDateTime, lookupTimezoneAsync} from '@math.gl/earth/timezone';
83
+
84
+ const timezone = await lookupTimezoneAsync([-74.006, 40.7128]);
85
+ const instant = new Date('2024-07-15T12:00:00Z');
86
+ const offset = getTimezoneOffset(timezone, instant); // -240
87
+ const local = getLocalDateTime(timezone, instant); // year/month/day and clock fields
88
+ const label = new Intl.DateTimeFormat('en', {timeZone: timezone, dateStyle: 'full'}).format(instant);
89
+ ```
90
+
91
+ The root offset utility uses native `Intl.DateTimeFormat`, without importing the geographic table. The asynchronous lookup loads that table on first use and reuses the loaded module. Bundlers with dynamic-import code splitting can put lookup data in a separate chunk; downloading it is deferred, not eliminated. Importing only the offset utility allows tree shaking to remove lookup entirely.
92
+
93
+ For synchronous lookup, import the dedicated entry point:
94
+
95
+ ```typescript
96
+ import {lookupTimezone} from '@math.gl/earth/timezone';
97
+
98
+ const timezone = lookupTimezone([-74.006, 40.7128]); // America/New_York
99
+ ```
100
+
101
+ Coordinates are `[longitude, latitude]` in degrees. Geographic lookup uses the compact [@photostructure/tz-lookup](https://github.com/photostructure/tz-lookup) implementation, vendored at version 11.7.0. Its compressed boundaries are approximate and can produce incorrect results, including near borders. It returns one identifier and does not resolve ambiguous political timezone usage. Updating the vendored upstream snapshot refreshes geographic data; date-specific offsets depend separately on the runtime's timezone database.
102
+
103
+ ### Local calendar computations
104
+
105
+ ```typescript
106
+ import {
107
+ getStartOfDay,
108
+ getTimezoneTransitions,
109
+ localDateTimeToInstant
110
+ } from '@math.gl/earth/timezone';
111
+
112
+ const dayStart = getStartOfDay('America/New_York', new Date('2024-03-10T12:00:00Z'));
113
+ // Epoch milliseconds for 2024-03-10T05:00:00Z. This local day has 23 hours.
114
+
115
+ const instant = localDateTimeToInstant(
116
+ 'America/New_York',
117
+ {year: 2024, month: 11, day: 3, hour: 1, minute: 30},
118
+ {disambiguation: 'later'}
119
+ ); // Epoch milliseconds for 2024-11-03T06:30:00Z.
120
+
121
+ const changes = getTimezoneTransitions(
122
+ 'America/New_York',
123
+ Date.parse('2024-01-01T00:00:00Z'),
124
+ Date.parse('2025-01-01T00:00:00Z')
125
+ ); // Two records containing instant, offsetBefore, and offsetAfter.
126
+ ```
127
+
128
+ Local clock fields alone do not uniquely identify an instant. Offset changes can repeat clock times or skip them entirely. Conversion rejects ambiguous or nonexistent times by default; callers can choose `earlier`, `later`, or Temporal's `compatible` behavior. Day boundaries use the first valid instant of the local calendar date, which can be later than midnight. Transition records describe any offset change, including political changes; they do not classify changes as daylight saving.
129
+
130
+ ### Optional geometry datasets
131
+
132
+ Approximate timezone polygons, including oceans, are available as separate assets:
133
+
134
+ - `@math.gl/earth/timezone/timezone-geometry-low.json`
135
+ - `@math.gl/earth/timezone/timezone-geometry-hi.json`
136
+ - `@math.gl/earth/timezone/timezone-geometry-low.parquet`
137
+ - `@math.gl/earth/timezone/timezone-geometry-hi.parquet`
138
+
139
+ JSON assets are standard GeoJSON FeatureCollections; each feature contains a
140
+ MultiPolygon and `properties.tzid`. Low uses a 20 km simplification interval
141
+ (~142 KB gzip), high uses 1 km (~1.33 MB gzip). Both retain 444 identifiers from
142
+ Timezone Boundary Builder 2026d's comprehensive with-oceans dataset.
143
+
144
+ ```js
145
+ import geometry from '@math.gl/earth/timezone/timezone-geometry-low.json' with {type: 'json'};
146
+ import {getTimezoneOffset} from '@math.gl/earth/timezone';
147
+
148
+ const instant = Date.parse('2026-07-15T12:00:00Z');
149
+ const offsetMinutes = getTimezoneOffset(geometry.features[0].properties.tzid, instant);
150
+ ```
151
+
152
+ For Vite, load assets by URL instead of including geometry in JavaScript:
153
+
154
+ ```js
155
+ import geometryUrl from '@math.gl/earth/timezone/timezone-geometry-low.json?url';
156
+ import parquetUrl from '@math.gl/earth/timezone/timezone-geometry-hi.parquet?url';
157
+
158
+ const geometry = await fetch(geometryUrl).then(response => response.json());
159
+ // Pass parquetUrl to a GeoParquet-capable loader, or fetch its binary contents.
160
+ ```
161
+
162
+ Parquet subpaths resolve to binary assets, not JavaScript modules; a plain import
163
+ is not automatically a URL. Use your bundler's asset mechanism or, in Node.js,
164
+ `import.meta.resolve('@math.gl/earth/timezone/timezone-geometry-hi.parquet')` to obtain
165
+ its file URL. GeoParquet 1.1 contains `tzid` strings and WKB `geometry` with
166
+ OGC:CRS84 coordinates. Geometry contains no date-specific rules or offsets.
167
+ These assets are never imported by the root, lookup, or temporal entry points.
168
+
169
+ See the [deck.gl 9.4 globe example](https://github.com/visgl/math.gl/blob/master/examples/earth/timezone-globe/README.md)
170
+ for a date slider, offset colors, and local-time hover details. Boundaries are
171
+ approximate; IANA does not define geographic polygons. Individual identifiers
172
+ may require a newer runtime timezone database.
173
+
174
+ The geometry data is **ODbL 1.0**, separately from the package's MIT code.
175
+ Attribute OpenStreetMap contributors and Timezone Boundary Builder and preserve
176
+ applicable ODbL obligations. See `data/timezone/README.md`, `data/timezone/LICENSE-ODbL.txt`, and
177
+ `data/timezone/manifest.json` in the package for provenance details.
@@ -9,14 +9,14 @@ latest available upstream releases.
9
9
  | Source / author | Use and retained notice |
10
10
  | --- | --- |
11
11
  | Charles Karney / GeographicLib 1.50.1 | Adapted geoid interpolation and PGM parsing; MIT, [LICENSE](./LICENSE). |
12
- | Vladimir Agafonkin / SunCalc | Adapted lunar calculations; BSD-2-Clause, [SunCalc notice](./sun/LICENSE-SUNCALC). Sun-position code also cites the astronomical equations of Louis Strous. |
13
- | Lukas Hošek and Alexander Wilkie | Derived 1.4a sunlight/sky model data; BSD-3-Clause, [model notice](./sun/LICENSE-HOSEK-WILKIE). |
14
- | Bretton Wade / YaleBrightStarCatalog | Derived bright-star data; [catalogue notice](./sun/LICENSE-BRIGHT-STARS); the source records the pinned upstream commit. |
15
- | ECMA International / Temporal contributors | Vendored `@js-temporal/polyfill` 0.5.1; ISC, [provenance](./src/timezone/vendor/temporal/README.md), [license](./src/timezone/vendor/temporal/LICENSE.txt). |
12
+ | Vladimir Agafonkin / SunCalc | Adapted lunar calculations; BSD-2-Clause, [SunCalc notice](./LICENSE-SUNCALC). Sun-position code also cites the astronomical equations of Louis Strous. |
13
+ | Lukas Hošek and Alexander Wilkie | Derived 1.4a sunlight/sky model data; BSD-3-Clause, [model notice](./LICENSE-HOSEK-WILKIE). |
14
+ | Bretton Wade / YaleBrightStarCatalog | Derived bright-star data; [catalogue notice](./LICENSE-BRIGHT-STARS); the source records the pinned upstream commit. |
15
+ | ECMA International / Temporal contributors | Vendored `@js-temporal/polyfill` 0.5.1; ISC, [provenance](https://github.com/visgl/math.gl/blob/master/modules/earth/src/timezone/vendor/temporal/README.md), [license](./src/timezone/vendor/temporal/LICENSE.txt). |
16
16
  | V8 authors / JSBI | JSBI 4.3.2 bundled with Temporal; Apache-2.0, [license](./src/timezone/vendor/temporal/JSBI-LICENSE.txt). |
17
- | PhotoStructure and tz-lookup contributors | Vendored `@photostructure/tz-lookup` 11.7.0 algorithm/table; CC0-1.0, [provenance](./src/timezone/vendor/tz-lookup/README.md), [dedication](./src/timezone/vendor/tz-lookup/LICENSE.txt). |
18
- | NGA / GeographicLib EGM96 distribution | Optional geoid grids; public-domain model data, [provenance, resolution and checksum manifest](./geoid/data/README.md). |
19
- | OpenStreetMap and Timezone Boundary Builder contributors | Optional simplified timezone boundaries, ODbL-1.0; [source and modifications](./timezone/data/README.md), [full license](./timezone/data/LICENSE-ODbL.txt). The MIT code license does not relicense this database. |
17
+ | PhotoStructure and tz-lookup contributors | Vendored `@photostructure/tz-lookup` 11.7.0 algorithm/table; CC0-1.0, [provenance](https://github.com/visgl/math.gl/blob/master/modules/earth/src/timezone/vendor/tz-lookup/README.md), [dedication](./src/timezone/vendor/tz-lookup/LICENSE.txt). |
18
+ | NGA / GeographicLib EGM96 distribution | Optional geoid grids; public-domain model data, [provenance, resolution and checksum manifest](./data/geoid/README.md). |
19
+ | OpenStreetMap and Timezone Boundary Builder contributors | Optional simplified timezone boundaries, ODbL-1.0; [source and modifications](./data/timezone/README.md), [full license](./data/timezone/LICENSE-ODbL.txt). The MIT code license does not relicense this database. |
20
20
 
21
21
  The `astronomy-engine` runtime dependency supplies planetary ephemerides under its own
22
22
  MIT license. Source comments cite the physical data and photometric papers used
@@ -23,6 +23,3 @@ The NGA EGM96 model data are public domain, distributed in PGM format by
23
23
  [PROJ's NGA data attribution](https://github.com/OSGeo/PROJ-data/blob/master/us_nga/us_nga_README.txt)
24
24
  documents the public-domain license. The package's MIT license covers its code.
25
25
  `geoid-manifest.json` records the source archive and SHA-256 checksums.
26
-
27
- Regenerate with `python3 modules/earth/geoid/scripts/generate-data.py /path/to/egm96-15.tar.bz2`.
28
- The generator checks the pinned archive checksum before reading it.
@@ -30,21 +30,5 @@ longitude/latitude degrees and exactly one property, `tzid`. GeoParquet 1.1 uses
30
30
  compression, and standard `geo` metadata. Omitted CRS means OGC:CRS84.
31
31
  No offset or DST fields are stored; join `tzid` with date-specific timezone APIs.
32
32
 
33
- ## Regeneration
34
-
35
- Use Python 3.10+ and Node.js, installing build tools outside the package:
36
-
37
- ```sh
38
- python3 -m venv /tmp/timezone-tools
39
- /tmp/timezone-tools/bin/pip install -r modules/earth/timezone/scripts/geometry-requirements.txt
40
- npm install --prefix /tmp/timezone-node mapshaper@0.6.113
41
- /tmp/timezone-tools/bin/python modules/earth/timezone/scripts/generate-geometry.py \
42
- --mapshaper /tmp/timezone-node/node_modules/.bin/mapshaper
43
- /tmp/timezone-tools/bin/python modules/earth/timezone/scripts/check-geometry.py
44
- ```
45
-
46
- The generator checks the pinned upstream ZIP checksum before extracting data.
47
- Use `--archive /path/to/timezones-with-oceans.geojson.zip` for offline generation.
48
- The manifest records provenance, simplification settings, sizes, repairs, and asset
49
- checksums. Build tools are not runtime dependencies. Update the pinned release and
50
- checksum deliberately when refreshing the data; review the regenerated geometry.
33
+ The [manifest](./manifest.json) records provenance, simplification settings, sizes,
34
+ repairs, and asset checksums.
package/dist/index.cjs CHANGED
@@ -2481,6 +2481,9 @@ function skyRotationToGlobe(rotation, observer) {
2481
2481
  return [0, 3, 6].flatMap((offset) => skyDirectionToGlobe(rotation.slice(offset, offset + 3), observer));
2482
2482
  }
2483
2483
 
2484
+ // dist/sun/cloud-lighting.js
2485
+ var import_core3 = require("@math.gl/core");
2486
+
2484
2487
  // dist/sun/cloud-spectral.js
2485
2488
  var samples = Array.from({ length: 41 }, (_2, i2) => {
2486
2489
  const nm = 380 + 10 * i2;
@@ -2601,8 +2604,7 @@ function normalize2(rgb2) {
2601
2604
  };
2602
2605
  }
2603
2606
  function smoothstep(lower, upper, value) {
2604
- const t2 = Math.max(0, Math.min(1, (value - lower) / (upper - lower)));
2605
- return t2 * t2 * (3 - 2 * t2);
2607
+ return (0, import_core3.smoothstep)(value, lower, upper);
2606
2608
  }
2607
2609
 
2608
2610
  // dist/sun/terminator.js
@@ -2689,6 +2691,7 @@ function getSunTerminator(timestamp, { altitude = 0, resolution = 360 } = {}) {
2689
2691
  var import_astronomy_engine2 = require("astronomy-engine");
2690
2692
 
2691
2693
  // dist/sun/planet-visibility.js
2694
+ var import_core4 = require("@math.gl/core");
2692
2695
  function getPlanetVisibility(magnitude, altitude, sunAltitude, sunSeparation, options = {}) {
2693
2696
  const { darkSkyLimitingMagnitude = 6, extinction = 0.2, minimumAltitude = 5 * Math.PI / 180, minimumSunSeparation = 10 * Math.PI / 180 } = options;
2694
2697
  validateRange("Magnitude", magnitude, -30, 30);
@@ -2735,8 +2738,7 @@ function getPlanetVisibility(magnitude, altitude, sunAltitude, sunSeparation, op
2735
2738
  };
2736
2739
  }
2737
2740
  function smoothstep2(minimum, maximum, value) {
2738
- const t2 = Math.max(0, Math.min(1, (value - minimum) / (maximum - minimum)));
2739
- return t2 * t2 * (3 - 2 * t2);
2741
+ return (0, import_core4.smoothstep)(value, minimum, maximum);
2740
2742
  }
2741
2743
 
2742
2744
  // dist/sun/sky-time.js