@math.gl/earth 0.0.0-stage → 5.0.0-alpha.20

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 (271) hide show
  1. package/LICENSE +1015 -0
  2. package/README.md +19 -2
  3. package/THIRD-PARTY-NOTICES.md +25 -0
  4. package/dist/geoid/create-geoid-from-grid.d.ts +15 -0
  5. package/dist/geoid/create-geoid-from-grid.d.ts.map +1 -0
  6. package/dist/geoid/create-geoid-from-grid.js +38 -0
  7. package/dist/geoid/create-geoid-from-grid.js.map +1 -0
  8. package/dist/geoid/geoid.d.ts +60 -0
  9. package/dist/geoid/geoid.d.ts.map +1 -0
  10. package/dist/geoid/geoid.js +261 -0
  11. package/dist/geoid/geoid.js.map +1 -0
  12. package/dist/geoid/index.cjs +727 -0
  13. package/dist/geoid/index.cjs.map +6 -0
  14. package/dist/geoid/index.d.ts +5 -0
  15. package/dist/geoid/index.d.ts.map +1 -0
  16. package/dist/geoid/index.js +7 -0
  17. package/dist/geoid/index.js.map +1 -0
  18. package/dist/geoid/parse-pgm.d.ts +12 -0
  19. package/dist/geoid/parse-pgm.d.ts.map +1 -0
  20. package/dist/geoid/parse-pgm.js +183 -0
  21. package/dist/geoid/parse-pgm.js.map +1 -0
  22. package/dist/index.cjs +2646 -0
  23. package/dist/index.cjs.map +6 -0
  24. package/dist/index.d.ts +4 -0
  25. package/dist/index.d.ts.map +1 -0
  26. package/dist/index.js +7 -0
  27. package/dist/index.js.map +1 -0
  28. package/dist/sun/astronomy.cjs +1729 -0
  29. package/dist/sun/astronomy.cjs.map +6 -0
  30. package/dist/sun/astronomy.d.ts +359 -0
  31. package/dist/sun/astronomy.d.ts.map +1 -0
  32. package/dist/sun/astronomy.js +181 -0
  33. package/dist/sun/astronomy.js.map +1 -0
  34. package/dist/sun/celestial.d.ts +4 -0
  35. package/dist/sun/celestial.d.ts.map +1 -0
  36. package/dist/sun/celestial.js +18 -0
  37. package/dist/sun/celestial.js.map +1 -0
  38. package/dist/sun/cloud-lighting.d.ts +49 -0
  39. package/dist/sun/cloud-lighting.d.ts.map +1 -0
  40. package/dist/sun/cloud-lighting.js +121 -0
  41. package/dist/sun/cloud-lighting.js.map +1 -0
  42. package/dist/sun/cloud-spectral.d.ts +3 -0
  43. package/dist/sun/cloud-spectral.d.ts.map +1 -0
  44. package/dist/sun/cloud-spectral.js +45 -0
  45. package/dist/sun/cloud-spectral.js.map +1 -0
  46. package/dist/sun/data/bright-stars.d.ts +3 -0
  47. package/dist/sun/data/bright-stars.d.ts.map +1 -0
  48. package/dist/sun/data/bright-stars.js +7015 -0
  49. package/dist/sun/data/bright-stars.js.map +1 -0
  50. package/dist/sun/data/sunlight.d.ts +2 -0
  51. package/dist/sun/data/sunlight.d.ts.map +1 -0
  52. package/dist/sun/data/sunlight.js +970 -0
  53. package/dist/sun/data/sunlight.js.map +1 -0
  54. package/dist/sun/index.cjs +1744 -0
  55. package/dist/sun/index.cjs.map +6 -0
  56. package/dist/sun/index.d.ts +23 -0
  57. package/dist/sun/index.d.ts.map +1 -0
  58. package/dist/sun/index.js +17 -0
  59. package/dist/sun/index.js.map +1 -0
  60. package/dist/sun/moon-appearance.d.ts +25 -0
  61. package/dist/sun/moon-appearance.d.ts.map +1 -0
  62. package/dist/sun/moon-appearance.js +50 -0
  63. package/dist/sun/moon-appearance.js.map +1 -0
  64. package/dist/sun/moon-sky-brightness.d.ts +7 -0
  65. package/dist/sun/moon-sky-brightness.d.ts.map +1 -0
  66. package/dist/sun/moon-sky-brightness.js +50 -0
  67. package/dist/sun/moon-sky-brightness.js.map +1 -0
  68. package/dist/sun/moon.d.ts +26 -0
  69. package/dist/sun/moon.d.ts.map +1 -0
  70. package/dist/sun/moon.js +74 -0
  71. package/dist/sun/moon.js.map +1 -0
  72. package/dist/sun/moonlight.d.ts +23 -0
  73. package/dist/sun/moonlight.d.ts.map +1 -0
  74. package/dist/sun/moonlight.js +48 -0
  75. package/dist/sun/moonlight.js.map +1 -0
  76. package/dist/sun/planet-position.d.ts +63 -0
  77. package/dist/sun/planet-position.d.ts.map +1 -0
  78. package/dist/sun/planet-position.js +189 -0
  79. package/dist/sun/planet-position.js.map +1 -0
  80. package/dist/sun/planet-times.d.ts +41 -0
  81. package/dist/sun/planet-times.d.ts.map +1 -0
  82. package/dist/sun/planet-times.js +86 -0
  83. package/dist/sun/planet-times.js.map +1 -0
  84. package/dist/sun/planet-visibility.d.ts +39 -0
  85. package/dist/sun/planet-visibility.d.ts.map +1 -0
  86. package/dist/sun/planet-visibility.js +82 -0
  87. package/dist/sun/planet-visibility.js.map +1 -0
  88. package/dist/sun/planets.cjs +411 -0
  89. package/dist/sun/planets.cjs.map +6 -0
  90. package/dist/sun/planets.d.ts +7 -0
  91. package/dist/sun/planets.d.ts.map +1 -0
  92. package/dist/sun/planets.js +7 -0
  93. package/dist/sun/planets.js.map +1 -0
  94. package/dist/sun/sky-brightness.d.ts +32 -0
  95. package/dist/sun/sky-brightness.d.ts.map +1 -0
  96. package/dist/sun/sky-brightness.js +108 -0
  97. package/dist/sun/sky-brightness.js.map +1 -0
  98. package/dist/sun/sky-events.d.ts +16 -0
  99. package/dist/sun/sky-events.d.ts.map +1 -0
  100. package/dist/sun/sky-events.js +60 -0
  101. package/dist/sun/sky-events.js.map +1 -0
  102. package/dist/sun/sky-globe.d.ts +15 -0
  103. package/dist/sun/sky-globe.d.ts.map +1 -0
  104. package/dist/sun/sky-globe.js +51 -0
  105. package/dist/sun/sky-globe.js.map +1 -0
  106. package/dist/sun/sky-lighting.d.ts +27 -0
  107. package/dist/sun/sky-lighting.d.ts.map +1 -0
  108. package/dist/sun/sky-lighting.js +88 -0
  109. package/dist/sun/sky-lighting.js.map +1 -0
  110. package/dist/sun/sky-observer.d.ts +22 -0
  111. package/dist/sun/sky-observer.d.ts.map +1 -0
  112. package/dist/sun/sky-observer.js +57 -0
  113. package/dist/sun/sky-observer.js.map +1 -0
  114. package/dist/sun/sky-time.d.ts +9 -0
  115. package/dist/sun/sky-time.d.ts.map +1 -0
  116. package/dist/sun/sky-time.js +38 -0
  117. package/dist/sun/sky-time.js.map +1 -0
  118. package/dist/sun/star-galactic.d.ts +15 -0
  119. package/dist/sun/star-galactic.d.ts.map +1 -0
  120. package/dist/sun/star-galactic.js +98 -0
  121. package/dist/sun/star-galactic.js.map +1 -0
  122. package/dist/sun/star-milky-way.d.ts +14 -0
  123. package/dist/sun/star-milky-way.d.ts.map +1 -0
  124. package/dist/sun/star-milky-way.js +32 -0
  125. package/dist/sun/star-milky-way.js.map +1 -0
  126. package/dist/sun/star-render.d.ts +38 -0
  127. package/dist/sun/star-render.d.ts.map +1 -0
  128. package/dist/sun/star-render.js +98 -0
  129. package/dist/sun/star-render.js.map +1 -0
  130. package/dist/sun/star-types.d.ts +60 -0
  131. package/dist/sun/star-types.d.ts.map +1 -0
  132. package/dist/sun/star-types.js +5 -0
  133. package/dist/sun/star-types.js.map +1 -0
  134. package/dist/sun/starfield.d.ts +13 -0
  135. package/dist/sun/starfield.d.ts.map +1 -0
  136. package/dist/sun/starfield.js +86 -0
  137. package/dist/sun/starfield.js.map +1 -0
  138. package/dist/sun/stars.cjs +7519 -0
  139. package/dist/sun/stars.cjs.map +6 -0
  140. package/dist/sun/stars.d.ts +26 -0
  141. package/dist/sun/stars.d.ts.map +1 -0
  142. package/dist/sun/stars.js +188 -0
  143. package/dist/sun/stars.js.map +1 -0
  144. package/dist/sun/suncalc.d.ts +26 -0
  145. package/dist/sun/suncalc.d.ts.map +1 -0
  146. package/dist/sun/suncalc.js +94 -0
  147. package/dist/sun/suncalc.js.map +1 -0
  148. package/dist/sun/sunlight.d.ts +25 -0
  149. package/dist/sun/sunlight.d.ts.map +1 -0
  150. package/dist/sun/sunlight.js +76 -0
  151. package/dist/sun/sunlight.js.map +1 -0
  152. package/dist/timezone/index.cjs +205 -0
  153. package/dist/timezone/index.cjs.map +6 -0
  154. package/dist/timezone/index.d.ts +6 -0
  155. package/dist/timezone/index.d.ts.map +1 -0
  156. package/dist/timezone/index.js +8 -0
  157. package/dist/timezone/index.js.map +1 -0
  158. package/dist/timezone/instant.d.ts +4 -0
  159. package/dist/timezone/instant.d.ts.map +1 -0
  160. package/dist/timezone/instant.js +20 -0
  161. package/dist/timezone/instant.js.map +1 -0
  162. package/dist/timezone/local-date-time.d.ts +4 -0
  163. package/dist/timezone/local-date-time.d.ts.map +1 -0
  164. package/dist/timezone/local-date-time.js +34 -0
  165. package/dist/timezone/local-date-time.js.map +1 -0
  166. package/dist/timezone/lookup-async.d.ts +3 -0
  167. package/dist/timezone/lookup-async.d.ts.map +1 -0
  168. package/dist/timezone/lookup-async.js +14 -0
  169. package/dist/timezone/lookup-async.js.map +1 -0
  170. package/dist/timezone/lookup.cjs +83 -0
  171. package/dist/timezone/lookup.cjs.map +6 -0
  172. package/dist/timezone/lookup.d.ts +3 -0
  173. package/dist/timezone/lookup.d.ts.map +1 -0
  174. package/dist/timezone/lookup.js +18 -0
  175. package/dist/timezone/lookup.js.map +1 -0
  176. package/dist/timezone/temporal.cjs +5696 -0
  177. package/dist/timezone/temporal.cjs.map +6 -0
  178. package/dist/timezone/temporal.d.ts +9 -0
  179. package/dist/timezone/temporal.d.ts.map +1 -0
  180. package/dist/timezone/temporal.js +60 -0
  181. package/dist/timezone/temporal.js.map +1 -0
  182. package/dist/timezone/timezone-label.d.ts +5 -0
  183. package/dist/timezone/timezone-label.d.ts.map +1 -0
  184. package/dist/timezone/timezone-label.js +27 -0
  185. package/dist/timezone/timezone-label.js.map +1 -0
  186. package/dist/timezone/timezone-offset.d.ts +3 -0
  187. package/dist/timezone/timezone-offset.d.ts.map +1 -0
  188. package/dist/timezone/timezone-offset.js +22 -0
  189. package/dist/timezone/timezone-offset.js.map +1 -0
  190. package/dist/timezone/types.d.ts +23 -0
  191. package/dist/timezone/types.d.ts.map +1 -0
  192. package/dist/timezone/types.js +5 -0
  193. package/dist/timezone/types.js.map +1 -0
  194. package/dist/timezone/vendor/temporal/runtime.d.ts +3 -0
  195. package/dist/timezone/vendor/temporal/runtime.d.ts.map +1 -0
  196. package/dist/timezone/vendor/temporal/runtime.js +5649 -0
  197. package/dist/timezone/vendor/temporal/runtime.js.map +1 -0
  198. package/dist/timezone/vendor/temporal/types.d.ts +939 -0
  199. package/dist/timezone/vendor/temporal/types.d.ts.map +1 -0
  200. package/dist/timezone/vendor/temporal/types.js +4 -0
  201. package/dist/timezone/vendor/temporal/types.js.map +1 -0
  202. package/dist/timezone/vendor/tz-lookup/runtime.d.ts +3 -0
  203. package/dist/timezone/vendor/tz-lookup/runtime.d.ts.map +1 -0
  204. package/dist/timezone/vendor/tz-lookup/runtime.js +53 -0
  205. package/dist/timezone/vendor/tz-lookup/runtime.js.map +1 -0
  206. package/geoid/data/README.md +28 -0
  207. package/geoid/data/geoid-egm96-hi.pgm +0 -0
  208. package/geoid/data/geoid-egm96-low.pgm +0 -0
  209. package/geoid/data/geoid-manifest.json +22 -0
  210. package/package.json +102 -4
  211. package/src/geoid/create-geoid-from-grid.ts +51 -0
  212. package/src/geoid/geoid.ts +297 -0
  213. package/src/geoid/index.ts +8 -0
  214. package/src/geoid/parse-pgm.ts +189 -0
  215. package/src/index.ts +7 -0
  216. package/src/sun/astronomy.ts +272 -0
  217. package/src/sun/celestial.ts +22 -0
  218. package/src/sun/cloud-lighting.ts +198 -0
  219. package/src/sun/cloud-spectral.ts +54 -0
  220. package/src/sun/data/bright-stars.ts +7024 -0
  221. package/src/sun/data/sunlight.ts +969 -0
  222. package/src/sun/index.ts +43 -0
  223. package/src/sun/moon-appearance.ts +81 -0
  224. package/src/sun/moon-sky-brightness.ts +64 -0
  225. package/src/sun/moon.ts +122 -0
  226. package/src/sun/moonlight.ts +88 -0
  227. package/src/sun/planet-position.ts +305 -0
  228. package/src/sun/planet-times.ts +142 -0
  229. package/src/sun/planet-visibility.ts +143 -0
  230. package/src/sun/planets.ts +18 -0
  231. package/src/sun/sky-brightness.ts +148 -0
  232. package/src/sun/sky-events.ts +66 -0
  233. package/src/sun/sky-globe.ts +72 -0
  234. package/src/sun/sky-lighting.ts +118 -0
  235. package/src/sun/sky-observer.ts +66 -0
  236. package/src/sun/sky-time.ts +42 -0
  237. package/src/sun/star-galactic.ts +111 -0
  238. package/src/sun/star-milky-way.ts +61 -0
  239. package/src/sun/star-render.ts +149 -0
  240. package/src/sun/star-types.ts +66 -0
  241. package/src/sun/starfield.ts +100 -0
  242. package/src/sun/stars.ts +260 -0
  243. package/src/sun/suncalc.ts +141 -0
  244. package/src/sun/sunlight.ts +112 -0
  245. package/src/timezone/index.ts +9 -0
  246. package/src/timezone/instant.ts +21 -0
  247. package/src/timezone/local-date-time.ts +40 -0
  248. package/src/timezone/lookup-async.ts +15 -0
  249. package/src/timezone/lookup.ts +21 -0
  250. package/src/timezone/temporal.ts +81 -0
  251. package/src/timezone/timezone-label.ts +30 -0
  252. package/src/timezone/timezone-offset.ts +21 -0
  253. package/src/timezone/types.ts +30 -0
  254. package/src/timezone/vendor/temporal/JSBI-LICENSE.txt +179 -0
  255. package/src/timezone/vendor/temporal/LICENSE.txt +16 -0
  256. package/src/timezone/vendor/temporal/README.md +23 -0
  257. package/src/timezone/vendor/temporal/runtime.ts +5070 -0
  258. package/src/timezone/vendor/temporal/types.ts +1146 -0
  259. package/src/timezone/vendor/tz-lookup/LICENSE.txt +119 -0
  260. package/src/timezone/vendor/tz-lookup/README.md +22 -0
  261. package/src/timezone/vendor/tz-lookup/runtime.ts +53 -0
  262. package/sun/LICENSE-BRIGHT-STARS +21 -0
  263. package/sun/LICENSE-HOSEK-WILKIE +30 -0
  264. package/sun/LICENSE-SUNCALC +24 -0
  265. package/timezone/data/LICENSE-ODbL.txt +538 -0
  266. package/timezone/data/README.md +50 -0
  267. package/timezone/data/manifest.json +37 -0
  268. package/timezone/data/timezone-geometry-hi.json +1 -0
  269. package/timezone/data/timezone-geometry-hi.parquet +0 -0
  270. package/timezone/data/timezone-geometry-low.json +1 -0
  271. package/timezone/data/timezone-geometry-low.parquet +0 -0
@@ -0,0 +1,141 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+ // SPDX-FileComment: Inspired by SunCalc; equations follow https://www.aa.quae.nl/en/reken/zonpositie.html.
5
+ const DEGREES_TO_RADIANS = Math.PI / 180;
6
+
7
+ const DAY_IN_MS = 1000 * 60 * 60 * 24;
8
+ const JD1970 = 2440588; // Julian Day year 1970
9
+ const JD2000 = 2451545; // Julian Day year 2000
10
+
11
+ // This angle ε [epsilon] is called the obliquity of the ecliptic and its value at the beginning of 2000 was 23.4397°
12
+ const e = DEGREES_TO_RADIANS * 23.4397; // obliquity of the Earth
13
+
14
+ // Refer https://www.aa.quae.nl/en/reken/zonpositie.html
15
+ // "The Mean Anomaly" section for explanation
16
+ const M0 = 357.5291; // Earth mean anomaly on start day
17
+ const M1 = 0.98560028; // Earth angle traverses on average per day seen from the sun
18
+
19
+ const THETA0 = 280.147; // The sidereal time (in degrees) at longitude 0° at the instant defined by JD2000
20
+ const THETA1 = 360.9856235; // The rate of change of the sidereal time, in degrees per day.
21
+
22
+ /**
23
+ * A position in the sky defined by two angles
24
+ * The altitude is 0° at the horizon, +90° in the zenith (straight over your head), and −90° in the nadir (straight down).
25
+ * The azimuth is the direction along the horizon, which we measure from south to west.
26
+ * South has azimuth 0°, west +90°, north +180°, and east +270° (or −90°, that's the same thing).
27
+ */
28
+ export type CelestialPosition = {
29
+ azimuth: number;
30
+ altitude: number;
31
+ };
32
+
33
+ /**
34
+ * Calculate sun position
35
+ * based on https://www.aa.quae.nl/en/reken/zonpositie.html
36
+ * inspired by https://github.com/mourner/suncalc/blob/master/suncalc.js
37
+ */
38
+ export function getSunPosition(
39
+ timestamp: number | Date,
40
+ latitude: number,
41
+ longitude: number
42
+ ): CelestialPosition {
43
+ const longitudeWestInRadians = DEGREES_TO_RADIANS * -longitude;
44
+ const phi = DEGREES_TO_RADIANS * latitude;
45
+ const d = toDays(timestamp);
46
+
47
+ const c = getSunCoords(d);
48
+ // hour angle
49
+ const H = getSiderealTime(d, longitudeWestInRadians) - c.rightAscension;
50
+
51
+ return {
52
+ azimuth: getAzimuth(H, phi, c.declination),
53
+ altitude: getAltitude(H, phi, c.declination)
54
+ };
55
+ }
56
+
57
+ export function getSunDirection(
58
+ timestamp: number | Date,
59
+ latitude: number,
60
+ longitude: number
61
+ ): number[] {
62
+ const {azimuth, altitude} = getSunPosition(timestamp, latitude, longitude);
63
+
64
+ // solar position to light direction
65
+ return [
66
+ Math.sin(azimuth) * Math.cos(altitude),
67
+ Math.cos(azimuth) * Math.cos(altitude),
68
+ -Math.sin(altitude)
69
+ ];
70
+ }
71
+
72
+ function toJulianDay(timestamp: number | Date): number {
73
+ const ts = typeof timestamp === 'number' ? timestamp : timestamp.getTime();
74
+ return ts / DAY_IN_MS - 0.5 + JD1970;
75
+ }
76
+
77
+ export function toDays(timestamp: number | Date): number {
78
+ return toJulianDay(timestamp) - JD2000;
79
+ }
80
+
81
+ export function getRightAscension(eclipticLongitude: number, b: number): number {
82
+ const lambda = eclipticLongitude;
83
+ return Math.atan2(Math.sin(lambda) * Math.cos(e) - Math.tan(b) * Math.sin(e), Math.cos(lambda));
84
+ }
85
+
86
+ export function getDeclination(eclipticLongitude: number, b: number): number {
87
+ const lambda = eclipticLongitude;
88
+ return Math.asin(Math.sin(b) * Math.cos(e) + Math.cos(b) * Math.sin(e) * Math.sin(lambda));
89
+ }
90
+
91
+ export function getAzimuth(
92
+ hourAngle: number,
93
+ latitudeInRadians: number,
94
+ declination: number
95
+ ): number {
96
+ const H = hourAngle;
97
+ const phi = latitudeInRadians;
98
+ const delta = declination;
99
+ return Math.atan2(Math.sin(H), Math.cos(H) * Math.sin(phi) - Math.tan(delta) * Math.cos(phi));
100
+ }
101
+
102
+ function getAltitude(hourAngle: number, latitudeInRadians: number, declination: number): number {
103
+ const H = hourAngle;
104
+ const phi = latitudeInRadians;
105
+ const delta = declination;
106
+ return Math.asin(Math.sin(phi) * Math.sin(delta) + Math.cos(phi) * Math.cos(delta) * Math.cos(H));
107
+ }
108
+
109
+ // https://www.aa.quae.nl/en/reken/zonpositie.html
110
+ // "The Observer section"
111
+ function getSiderealTime(dates: number, longitudeWestInRadians: number): number {
112
+ return DEGREES_TO_RADIANS * (THETA0 + THETA1 * dates) - longitudeWestInRadians;
113
+ }
114
+
115
+ function getSolarMeanAnomaly(days: number): number {
116
+ return DEGREES_TO_RADIANS * (M0 + M1 * days);
117
+ }
118
+
119
+ function getEclipticLongitude(meanAnomaly: number): number {
120
+ const M = meanAnomaly;
121
+ // equation of center
122
+ const C =
123
+ DEGREES_TO_RADIANS * (1.9148 * Math.sin(M) + 0.02 * Math.sin(2 * M) + 0.0003 * Math.sin(3 * M));
124
+ // perihelion of the Earth
125
+ const P = DEGREES_TO_RADIANS * 102.9372;
126
+
127
+ return M + C + P + Math.PI;
128
+ }
129
+
130
+ export function getSunCoords(dates: number): {
131
+ declination: number;
132
+ rightAscension: number;
133
+ } {
134
+ const M = getSolarMeanAnomaly(dates);
135
+ const L = getEclipticLongitude(M);
136
+
137
+ return {
138
+ declination: getDeclination(L, 0),
139
+ rightAscension: getRightAscension(L, 0)
140
+ };
141
+ }
@@ -0,0 +1,112 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+ // SPDX-FileComment: Original wrapper of derived Hošek-Wilkie data; reference: https://cgg.mff.cuni.cz/projects/SkylightModelling/
5
+ // Derived BSD-3-Clause data and notices: ./data/sunlight.ts and ../../sun/LICENSE-HOSEK-WILKIE.
6
+ import {SUNLIGHT_DATA} from './data/sunlight';
7
+
8
+ export type SunLightOptions = {
9
+ /** Atmospheric turbidity, from 1 (clear) to 10 (hazy). Default 3. */
10
+ turbidity?: number;
11
+ /** Fractional cloud coverage in [0, 1]. Default 0. Represents averaged conditions. */
12
+ cloudCover?: number;
13
+ /** Vertical cloud optical depth, nonnegative. Default 10. */
14
+ cloudOpticalDepth?: number;
15
+ };
16
+
17
+ export type LightColor = {
18
+ /** Normalized linear sRGB, with maximum component 1 when illuminated. */
19
+ color: [number, number, number];
20
+ /** Relative peak-channel irradiance. Multiply by color to recover RGB irradiance. */
21
+ intensity: number;
22
+ };
23
+
24
+ export type SunLight = LightColor & {
25
+ /** Hemispherical diffuse irradiance on a horizontal surface, on the same relative scale. */
26
+ diffuse: LightColor;
27
+ };
28
+
29
+ const SUN_RADIUS = (0.255 * Math.PI) / 180;
30
+ // Fixed reference: brightest channel of clear (turbidity 1), zenith direct sunlight.
31
+ const REFERENCE_IRRADIANCE = Math.max(...SUNLIGHT_DATA[0][90].slice(0, 3));
32
+
33
+ /**
34
+ * Estimate direct sunlight and hemispherical diffuse skylight from altitude in radians.
35
+ * Uses spectrally integrated Hošek-Wilkie 1.4a lookup data at sea level with black ground.
36
+ * Clouds use a separate neutral, energy-bounded approximation, not the Hošek-Wilkie model.
37
+ */
38
+ export function getSunLight(altitude: number, options: SunLightOptions = {}): SunLight {
39
+ const {turbidity = 3, cloudCover = 0, cloudOpticalDepth = 10} = options;
40
+ validateRange('Sun altitude', altitude, -Math.PI / 2, Math.PI / 2);
41
+ validateRange('Turbidity', turbidity, 1, 10);
42
+ validateRange('Cloud cover', cloudCover, 0, 1);
43
+ validateRange('Cloud optical depth', cloudOpticalDepth, 0, Number.MAX_VALUE);
44
+ if (altitude <= -SUN_RADIUS) {
45
+ return {color: [0, 0, 0], intensity: 0, diffuse: {color: [0, 0, 0], intensity: 0}};
46
+ }
47
+
48
+ const elevation = Math.max(0, altitude);
49
+ const degrees = (elevation * 180) / Math.PI;
50
+ const altitudeIndex = Math.min(89, Math.floor(degrees));
51
+ const altitudeFraction = degrees - altitudeIndex;
52
+ const turbidityIndex = Math.min(8, Math.floor(turbidity) - 1);
53
+ const turbidityFraction = turbidity - turbidityIndex - 1;
54
+ const sample = (channel: number): number => {
55
+ const lower = SUNLIGHT_DATA[turbidityIndex];
56
+ const upper = SUNLIGHT_DATA[turbidityIndex + 1];
57
+ const low = interpolate(
58
+ lower[altitudeIndex][channel],
59
+ lower[altitudeIndex + 1][channel],
60
+ altitudeFraction
61
+ );
62
+ const high = interpolate(
63
+ upper[altitudeIndex][channel],
64
+ upper[altitudeIndex + 1][channel],
65
+ altitudeFraction
66
+ );
67
+ return interpolate(low, high, turbidityFraction) / REFERENCE_IRRADIANCE;
68
+ };
69
+
70
+ // Uniform-disk horizon clipping. Limb darkening is included in the full-disk lookup,
71
+ // but this partial-disk fade omits its spatial variation and atmospheric refraction.
72
+ const diskHeight = Math.min(1, altitude / SUN_RADIUS);
73
+ const visibility =
74
+ (Math.acos(-diskHeight) + diskHeight * Math.sqrt(1 - diskHeight * diskHeight)) / Math.PI;
75
+ const mu = Math.sin(elevation);
76
+ // Beer-Lambert transmission of the covered fraction. The path is bounded near the
77
+ // horizon because this simple plane-parallel cloud layer cannot model curved geometry.
78
+ const cloudTransmission = Math.exp(-cloudOpticalDepth / Math.max(0.05, mu));
79
+ const directTransmission = 1 - cloudCover + cloudCover * cloudTransmission;
80
+ // Heuristic transmission of redistributed light through the cloud layer, including
81
+ // loss upward. This is not a fitted weather model. It never creates incident energy.
82
+ const diffuseTransmission = 1 / (1 + 0.12 * cloudOpticalDepth);
83
+ const direct: [number, number, number] = [0, 0, 0];
84
+ const diffuse: [number, number, number] = [0, 0, 0];
85
+ for (let channel = 0; channel < 3; channel++) {
86
+ const beam = sample(channel) * visibility;
87
+ const sky = sample(channel + 3) * visibility;
88
+ direct[channel] = beam * directTransmission;
89
+ diffuse[channel] =
90
+ (1 - cloudCover) * sky +
91
+ cloudCover * diffuseTransmission * (sky + beam * mu * (1 - cloudTransmission));
92
+ }
93
+ return {...normalize(direct), diffuse: normalize(diffuse)};
94
+ }
95
+
96
+ function interpolate(a: number, b: number, fraction: number): number {
97
+ return a + (b - a) * fraction;
98
+ }
99
+
100
+ function normalize(rgb: [number, number, number]): LightColor {
101
+ const intensity = Math.max(...rgb);
102
+ return {
103
+ color: intensity > 0 ? [rgb[0] / intensity, rgb[1] / intensity, rgb[2] / intensity] : [0, 0, 0],
104
+ intensity
105
+ };
106
+ }
107
+
108
+ function validateRange(name: string, value: number, minimum: number, maximum: number): void {
109
+ if (!Number.isFinite(value) || value < minimum || value > maximum) {
110
+ throw new RangeError(`${name} must be finite and between ${minimum} and ${maximum}`);
111
+ }
112
+ }
@@ -0,0 +1,9 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ export {getTimezoneOffset} from './timezone-offset';
6
+ export {lookupTimezoneAsync} from './lookup-async';
7
+ export {getLocalDateTime} from './local-date-time';
8
+ export {getTimezoneLabel, isTimezoneSupported} from './timezone-label';
9
+ export type {LocalDateTime} from './types';
@@ -0,0 +1,21 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ /** Normalize an instant without consulting the host timezone or parsing local strings. */
6
+ export function getInstant(date: Date | number): Date {
7
+ if (!(date instanceof Date) && typeof date !== 'number') {
8
+ throw new RangeError('Date must be a Date or epoch milliseconds');
9
+ }
10
+ const instant = new Date(date instanceof Date ? date.getTime() : date);
11
+ if (!Number.isFinite(instant.getTime())) {
12
+ throw new RangeError('Date must represent a valid instant');
13
+ }
14
+ return instant;
15
+ }
16
+
17
+ export function assertTimezone(timezone: string): void {
18
+ if (typeof timezone !== 'string' || !timezone) {
19
+ throw new RangeError('Timezone must be a valid timezone identifier');
20
+ }
21
+ }
@@ -0,0 +1,40 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import {assertTimezone, getInstant} from './instant';
6
+ import type {LocalDateTime} from './types';
7
+
8
+ /** Returns Gregorian local calendar fields for an instant, independent of the host timezone. */
9
+ export function getLocalDateTime(
10
+ timezone: string,
11
+ date: Date | number = Date.now()
12
+ ): LocalDateTime {
13
+ const instant = getInstant(date);
14
+ assertTimezone(timezone);
15
+ const parts = new Intl.DateTimeFormat('en-US', {
16
+ timeZone: timezone,
17
+ calendar: 'gregory',
18
+ numberingSystem: 'latn',
19
+ hourCycle: 'h23',
20
+ era: 'short',
21
+ year: 'numeric',
22
+ month: 'numeric',
23
+ day: 'numeric',
24
+ hour: 'numeric',
25
+ minute: 'numeric',
26
+ second: 'numeric'
27
+ }).formatToParts(instant);
28
+ const value = (type: Intl.DateTimeFormatPartTypes): string =>
29
+ parts.find(part => part.type === type)!.value;
30
+ const year = Number(value('year'));
31
+ return {
32
+ year: value('era') === 'BC' ? 1 - year : year,
33
+ month: Number(value('month')),
34
+ day: Number(value('day')),
35
+ hour: Number(value('hour')),
36
+ minute: Number(value('minute')),
37
+ second: Number(value('second')),
38
+ millisecond: instant.getUTCMilliseconds()
39
+ };
40
+ }
@@ -0,0 +1,15 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ let lookupModule: Promise<typeof import('./lookup')> | undefined;
6
+
7
+ /** Looks up an approximate IANA timezone, loading the geographic table on first use. */
8
+ export async function lookupTimezoneAsync(coordinates: readonly [number, number]): Promise<string> {
9
+ lookupModule ||= import('./lookup').catch(error => {
10
+ lookupModule = undefined;
11
+ throw error;
12
+ });
13
+ const {lookupTimezone} = await lookupModule;
14
+ return lookupTimezone(coordinates);
15
+ }
@@ -0,0 +1,21 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import tzLookup from './vendor/tz-lookup/runtime';
6
+
7
+ /** Returns an approximate IANA timezone for [longitude, latitude] in degrees. */
8
+ export function lookupTimezone(coordinates: readonly [number, number]): string {
9
+ const [longitude, latitude] = coordinates;
10
+ if (
11
+ !Number.isFinite(longitude) ||
12
+ !Number.isFinite(latitude) ||
13
+ longitude < -180 ||
14
+ longitude > 180 ||
15
+ latitude < -90 ||
16
+ latitude > 90
17
+ ) {
18
+ throw new RangeError('Coordinates must be finite longitude [-180, 180] and latitude [-90, 90]');
19
+ }
20
+ return tzLookup(latitude, longitude);
21
+ }
@@ -0,0 +1,81 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import temporalRuntime from './vendor/temporal/runtime';
6
+ import type {Temporal as TemporalTypes} from './vendor/temporal/types';
7
+
8
+ import {assertTimezone, getInstant} from './instant';
9
+ import type {LocalDateTimeInput, LocalDateTimeOptions, TimezoneTransition} from './types';
10
+
11
+ export type {LocalDateTimeInput, LocalDateTimeOptions, TimezoneTransition} from './types';
12
+
13
+ const Temporal: typeof TemporalTypes = temporalRuntime;
14
+
15
+ function getZonedDateTime(timezone: string, date: Date | number): TemporalTypes.ZonedDateTime {
16
+ assertTimezone(timezone);
17
+ return Temporal.Instant.fromEpochMilliseconds(getInstant(date).getTime()).toZonedDateTimeISO(
18
+ timezone
19
+ );
20
+ }
21
+
22
+ /** Epoch milliseconds of the first valid instant of the instant's local calendar day. */
23
+ export function getStartOfDay(timezone: string, date: Date | number = Date.now()): number {
24
+ return getZonedDateTime(timezone, date).startOfDay().epochMilliseconds;
25
+ }
26
+
27
+ /** Convert Gregorian wall-clock fields to epoch milliseconds with explicit DST disambiguation. */
28
+ export function localDateTimeToInstant(
29
+ timezone: string,
30
+ fields: LocalDateTimeInput,
31
+ options: LocalDateTimeOptions = {}
32
+ ): number {
33
+ assertTimezone(timezone);
34
+ const values = {
35
+ year: fields.year,
36
+ month: fields.month,
37
+ day: fields.day,
38
+ hour: fields.hour ?? 0,
39
+ minute: fields.minute ?? 0,
40
+ second: fields.second ?? 0,
41
+ millisecond: fields.millisecond ?? 0
42
+ };
43
+ if (!Object.values(values).every(Number.isInteger)) {
44
+ throw new RangeError('Local date and time fields must be finite integers');
45
+ }
46
+ if (values.second < 0 || values.second > 59) {
47
+ throw new RangeError('Seconds must be between 0 and 59; leap seconds are not supported');
48
+ }
49
+ return Temporal.ZonedDateTime.from(
50
+ {...values, timeZone: timezone, calendar: 'iso8601'},
51
+ {overflow: 'reject', disambiguation: options.disambiguation ?? 'reject'}
52
+ ).epochMilliseconds;
53
+ }
54
+
55
+ /** Return offset changes in [start, end), including political changes as well as DST. */
56
+ export function getTimezoneTransitions(
57
+ timezone: string,
58
+ start: Date | number,
59
+ end: Date | number
60
+ ): TimezoneTransition[] {
61
+ const startDate = getInstant(start);
62
+ const endDate = getInstant(end);
63
+ if (endDate.getTime() < startDate.getTime()) {
64
+ throw new RangeError('End must not precede start');
65
+ }
66
+ let cursor = getZonedDateTime(timezone, startDate);
67
+ // Start one nanosecond earlier so a transition exactly at start is included.
68
+ if (startDate.getTime() > -8640000000000000) cursor = cursor.subtract({nanoseconds: 1});
69
+ const transitions: TimezoneTransition[] = [];
70
+ while (true) {
71
+ const next = cursor.getTimeZoneTransition('next');
72
+ if (!next || next.epochMilliseconds >= endDate.getTime()) break;
73
+ transitions.push({
74
+ instant: next.epochMilliseconds,
75
+ offsetBefore: next.subtract({nanoseconds: 1}).offsetNanoseconds / 60000000000,
76
+ offsetAfter: next.offsetNanoseconds / 60000000000
77
+ });
78
+ cursor = next;
79
+ }
80
+ return transitions;
81
+ }
@@ -0,0 +1,30 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import {assertTimezone, getInstant} from './instant';
6
+
7
+ /** A localized, date-aware display label; never use it as an identifier or offset. */
8
+ export function getTimezoneLabel(
9
+ timezone: string,
10
+ date: Date | number = Date.now(),
11
+ locale: string | string[] = 'en'
12
+ ): string {
13
+ const instant = getInstant(date);
14
+ assertTimezone(timezone);
15
+ return new Intl.DateTimeFormat(locale, {timeZone: timezone, timeZoneName: 'long'})
16
+ .formatToParts(instant)
17
+ .find(part => part.type === 'timeZoneName')!.value;
18
+ }
19
+
20
+ /** Whether the current runtime accepts a timezone identifier, including supported aliases. */
21
+ export function isTimezoneSupported(timezone: string): boolean {
22
+ if (typeof timezone !== 'string' || !timezone) return false;
23
+ try {
24
+ new Intl.DateTimeFormat('en', {timeZone: timezone});
25
+ return true;
26
+ } catch (error) {
27
+ if (error instanceof RangeError) return false;
28
+ throw error;
29
+ }
30
+ }
@@ -0,0 +1,21 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ import {assertTimezone, getInstant} from './instant';
6
+
7
+ /** Returns minutes east of UTC at an instant (epoch milliseconds or Date; defaults to now). */
8
+ export function getTimezoneOffset(timezone: string, date: Date | number = Date.now()): number {
9
+ const instant = getInstant(date);
10
+ assertTimezone(timezone);
11
+ const formatter = new Intl.DateTimeFormat('en-US', {
12
+ timeZone: timezone,
13
+ timeZoneName: 'longOffset'
14
+ });
15
+ const offset = formatter.formatToParts(instant).find(part => part.type === 'timeZoneName')?.value;
16
+ if (offset === 'GMT') return 0;
17
+ const match = /^GMT([+-])(\d{2}):(\d{2})(?::(\d{2}))?$/.exec(offset || '');
18
+ if (!match) throw new Error(`Unable to calculate offset for timezone: ${timezone}`);
19
+ const minutes = Number(match[2]) * 60 + Number(match[3]) + Number(match[4] || 0) / 60;
20
+ return match[1] === '-' ? -minutes : minutes;
21
+ }
@@ -0,0 +1,30 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+
5
+ /** Gregorian local calendar and clock fields; this is not an instant. */
6
+ export type LocalDateTime = {
7
+ year: number;
8
+ month: number;
9
+ day: number;
10
+ hour: number;
11
+ minute: number;
12
+ second: number;
13
+ millisecond: number;
14
+ };
15
+
16
+ /** Local date with optional clock fields, which default to zero. */
17
+ export type LocalDateTimeInput = Pick<LocalDateTime, 'year' | 'month' | 'day'> &
18
+ Partial<Pick<LocalDateTime, 'hour' | 'minute' | 'second' | 'millisecond'>>;
19
+
20
+ /** How to resolve a repeated or nonexistent local clock time. Defaults to reject. */
21
+ export type LocalDateTimeOptions = {
22
+ disambiguation?: 'reject' | 'earlier' | 'later' | 'compatible';
23
+ };
24
+
25
+ /** An offset change at epoch milliseconds; offsets are minutes east of UTC. */
26
+ export type TimezoneTransition = {
27
+ instant: number;
28
+ offsetBefore: number;
29
+ offsetAfter: number;
30
+ };