@math.gl/earth 5.0.0-beta.3 → 5.0.0-beta.5
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.
- package/README.md +157 -0
- package/THIRD-PARTY-NOTICES.md +7 -7
- package/{geoid/data → data/geoid}/README.md +0 -3
- package/{timezone/data → data/timezone}/README.md +2 -18
- package/dist/index.cjs +6 -4
- package/dist/index.cjs.map +3 -3
- package/dist/sun/cloud-lighting.d.ts.map +1 -1
- package/dist/sun/cloud-lighting.js +2 -2
- package/dist/sun/cloud-lighting.js.map +1 -1
- package/dist/sun/index.cjs +6 -4
- package/dist/sun/index.cjs.map +3 -3
- package/dist/sun/moon.js +1 -1
- package/dist/sun/moon.js.map +1 -1
- package/dist/sun/planet-visibility.d.ts.map +1 -1
- package/dist/sun/planet-visibility.js +2 -2
- package/dist/sun/planet-visibility.js.map +1 -1
- package/dist/sun/sky-lighting.js +1 -1
- package/dist/sun/sky-lighting.js.map +1 -1
- package/dist/sun/sunlight.js +1 -1
- package/dist/sun/sunlight.js.map +1 -1
- package/package.json +15 -17
- package/src/sun/cloud-lighting.ts +2 -2
- package/src/sun/data/bright-stars.ts +1 -1
- package/src/sun/moon.ts +1 -1
- package/src/sun/planet-visibility.ts +2 -2
- package/src/sun/sky-lighting.ts +1 -1
- package/src/sun/sunlight.ts +1 -1
- package/src/timezone/vendor/temporal/README.md +0 -23
- package/src/timezone/vendor/tz-lookup/README.md +0 -22
- /package/{sun/LICENSE-BRIGHT-STARS → LICENSE-BRIGHT-STARS} +0 -0
- /package/{sun/LICENSE-HOSEK-WILKIE → LICENSE-HOSEK-WILKIE} +0 -0
- /package/{sun/LICENSE-SUNCALC → LICENSE-SUNCALC} +0 -0
- /package/{geoid/data → data/geoid}/geoid-egm96-hi.pgm +0 -0
- /package/{geoid/data → data/geoid}/geoid-egm96-low.pgm +0 -0
- /package/{geoid/data → data/geoid}/geoid-manifest.json +0 -0
- /package/{timezone/data → data/timezone}/LICENSE-ODbL.txt +0 -0
- /package/{timezone/data → data/timezone}/manifest.json +0 -0
- /package/{timezone/data → data/timezone}/timezone-geometry-hi.json +0 -0
- /package/{timezone/data → data/timezone}/timezone-geometry-hi.parquet +0 -0
- /package/{timezone/data → data/timezone}/timezone-geometry-low.json +0 -0
- /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.
|
package/THIRD-PARTY-NOTICES.md
CHANGED
|
@@ -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](./
|
|
13
|
-
| Lukas Hošek and Alexander Wilkie | Derived 1.4a sunlight/sky model data; BSD-3-Clause, [model notice](./
|
|
14
|
-
| Bretton Wade / YaleBrightStarCatalog | Derived bright-star data; [catalogue notice](./
|
|
15
|
-
| ECMA International / Temporal contributors | Vendored `@js-temporal/polyfill` 0.5.1; ISC, [provenance](
|
|
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](
|
|
18
|
-
| NGA / GeographicLib EGM96 distribution | Optional geoid grids; public-domain model data, [provenance, resolution and checksum manifest](./geoid/
|
|
19
|
-
| OpenStreetMap and Timezone Boundary Builder contributors | Optional simplified timezone boundaries, ODbL-1.0; [source and modifications](./timezone/
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|