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

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 (269) hide show
  1. package/README.md +14 -2
  2. package/dist/geoid/create-geoid-from-grid.d.ts +15 -0
  3. package/dist/geoid/create-geoid-from-grid.d.ts.map +1 -0
  4. package/dist/geoid/create-geoid-from-grid.js +38 -0
  5. package/dist/geoid/create-geoid-from-grid.js.map +1 -0
  6. package/dist/geoid/geoid.d.ts +60 -0
  7. package/dist/geoid/geoid.d.ts.map +1 -0
  8. package/dist/geoid/geoid.js +261 -0
  9. package/dist/geoid/geoid.js.map +1 -0
  10. package/dist/geoid/index.cjs +727 -0
  11. package/dist/geoid/index.cjs.map +6 -0
  12. package/dist/geoid/index.d.ts +5 -0
  13. package/dist/geoid/index.d.ts.map +1 -0
  14. package/dist/geoid/index.js +7 -0
  15. package/dist/geoid/index.js.map +1 -0
  16. package/dist/geoid/parse-pgm.d.ts +12 -0
  17. package/dist/geoid/parse-pgm.d.ts.map +1 -0
  18. package/dist/geoid/parse-pgm.js +183 -0
  19. package/dist/geoid/parse-pgm.js.map +1 -0
  20. package/dist/index.cjs +2646 -0
  21. package/dist/index.cjs.map +6 -0
  22. package/dist/index.d.ts +4 -0
  23. package/dist/index.d.ts.map +1 -0
  24. package/dist/index.js +7 -0
  25. package/dist/index.js.map +1 -0
  26. package/dist/sun/astronomy.cjs +1729 -0
  27. package/dist/sun/astronomy.cjs.map +6 -0
  28. package/dist/sun/astronomy.d.ts +359 -0
  29. package/dist/sun/astronomy.d.ts.map +1 -0
  30. package/dist/sun/astronomy.js +181 -0
  31. package/dist/sun/astronomy.js.map +1 -0
  32. package/dist/sun/celestial.d.ts +4 -0
  33. package/dist/sun/celestial.d.ts.map +1 -0
  34. package/dist/sun/celestial.js +18 -0
  35. package/dist/sun/celestial.js.map +1 -0
  36. package/dist/sun/cloud-lighting.d.ts +49 -0
  37. package/dist/sun/cloud-lighting.d.ts.map +1 -0
  38. package/dist/sun/cloud-lighting.js +121 -0
  39. package/dist/sun/cloud-lighting.js.map +1 -0
  40. package/dist/sun/cloud-spectral.d.ts +3 -0
  41. package/dist/sun/cloud-spectral.d.ts.map +1 -0
  42. package/dist/sun/cloud-spectral.js +45 -0
  43. package/dist/sun/cloud-spectral.js.map +1 -0
  44. package/dist/sun/data/bright-stars.d.ts +3 -0
  45. package/dist/sun/data/bright-stars.d.ts.map +1 -0
  46. package/dist/sun/data/bright-stars.js +7015 -0
  47. package/dist/sun/data/bright-stars.js.map +1 -0
  48. package/dist/sun/data/sunlight.d.ts +2 -0
  49. package/dist/sun/data/sunlight.d.ts.map +1 -0
  50. package/dist/sun/data/sunlight.js +970 -0
  51. package/dist/sun/data/sunlight.js.map +1 -0
  52. package/dist/sun/index.cjs +1744 -0
  53. package/dist/sun/index.cjs.map +6 -0
  54. package/dist/sun/index.d.ts +23 -0
  55. package/dist/sun/index.d.ts.map +1 -0
  56. package/dist/sun/index.js +17 -0
  57. package/dist/sun/index.js.map +1 -0
  58. package/dist/sun/moon-appearance.d.ts +25 -0
  59. package/dist/sun/moon-appearance.d.ts.map +1 -0
  60. package/dist/sun/moon-appearance.js +50 -0
  61. package/dist/sun/moon-appearance.js.map +1 -0
  62. package/dist/sun/moon-sky-brightness.d.ts +7 -0
  63. package/dist/sun/moon-sky-brightness.d.ts.map +1 -0
  64. package/dist/sun/moon-sky-brightness.js +50 -0
  65. package/dist/sun/moon-sky-brightness.js.map +1 -0
  66. package/dist/sun/moon.d.ts +26 -0
  67. package/dist/sun/moon.d.ts.map +1 -0
  68. package/dist/sun/moon.js +74 -0
  69. package/dist/sun/moon.js.map +1 -0
  70. package/dist/sun/moonlight.d.ts +23 -0
  71. package/dist/sun/moonlight.d.ts.map +1 -0
  72. package/dist/sun/moonlight.js +48 -0
  73. package/dist/sun/moonlight.js.map +1 -0
  74. package/dist/sun/planet-position.d.ts +63 -0
  75. package/dist/sun/planet-position.d.ts.map +1 -0
  76. package/dist/sun/planet-position.js +189 -0
  77. package/dist/sun/planet-position.js.map +1 -0
  78. package/dist/sun/planet-times.d.ts +41 -0
  79. package/dist/sun/planet-times.d.ts.map +1 -0
  80. package/dist/sun/planet-times.js +86 -0
  81. package/dist/sun/planet-times.js.map +1 -0
  82. package/dist/sun/planet-visibility.d.ts +39 -0
  83. package/dist/sun/planet-visibility.d.ts.map +1 -0
  84. package/dist/sun/planet-visibility.js +82 -0
  85. package/dist/sun/planet-visibility.js.map +1 -0
  86. package/dist/sun/planets.cjs +411 -0
  87. package/dist/sun/planets.cjs.map +6 -0
  88. package/dist/sun/planets.d.ts +7 -0
  89. package/dist/sun/planets.d.ts.map +1 -0
  90. package/dist/sun/planets.js +7 -0
  91. package/dist/sun/planets.js.map +1 -0
  92. package/dist/sun/sky-brightness.d.ts +32 -0
  93. package/dist/sun/sky-brightness.d.ts.map +1 -0
  94. package/dist/sun/sky-brightness.js +108 -0
  95. package/dist/sun/sky-brightness.js.map +1 -0
  96. package/dist/sun/sky-events.d.ts +16 -0
  97. package/dist/sun/sky-events.d.ts.map +1 -0
  98. package/dist/sun/sky-events.js +60 -0
  99. package/dist/sun/sky-events.js.map +1 -0
  100. package/dist/sun/sky-globe.d.ts +15 -0
  101. package/dist/sun/sky-globe.d.ts.map +1 -0
  102. package/dist/sun/sky-globe.js +51 -0
  103. package/dist/sun/sky-globe.js.map +1 -0
  104. package/dist/sun/sky-lighting.d.ts +27 -0
  105. package/dist/sun/sky-lighting.d.ts.map +1 -0
  106. package/dist/sun/sky-lighting.js +88 -0
  107. package/dist/sun/sky-lighting.js.map +1 -0
  108. package/dist/sun/sky-observer.d.ts +22 -0
  109. package/dist/sun/sky-observer.d.ts.map +1 -0
  110. package/dist/sun/sky-observer.js +57 -0
  111. package/dist/sun/sky-observer.js.map +1 -0
  112. package/dist/sun/sky-time.d.ts +9 -0
  113. package/dist/sun/sky-time.d.ts.map +1 -0
  114. package/dist/sun/sky-time.js +38 -0
  115. package/dist/sun/sky-time.js.map +1 -0
  116. package/dist/sun/star-galactic.d.ts +15 -0
  117. package/dist/sun/star-galactic.d.ts.map +1 -0
  118. package/dist/sun/star-galactic.js +98 -0
  119. package/dist/sun/star-galactic.js.map +1 -0
  120. package/dist/sun/star-milky-way.d.ts +14 -0
  121. package/dist/sun/star-milky-way.d.ts.map +1 -0
  122. package/dist/sun/star-milky-way.js +32 -0
  123. package/dist/sun/star-milky-way.js.map +1 -0
  124. package/dist/sun/star-render.d.ts +38 -0
  125. package/dist/sun/star-render.d.ts.map +1 -0
  126. package/dist/sun/star-render.js +98 -0
  127. package/dist/sun/star-render.js.map +1 -0
  128. package/dist/sun/star-types.d.ts +60 -0
  129. package/dist/sun/star-types.d.ts.map +1 -0
  130. package/dist/sun/star-types.js +5 -0
  131. package/dist/sun/star-types.js.map +1 -0
  132. package/dist/sun/starfield.d.ts +13 -0
  133. package/dist/sun/starfield.d.ts.map +1 -0
  134. package/dist/sun/starfield.js +86 -0
  135. package/dist/sun/starfield.js.map +1 -0
  136. package/dist/sun/stars.cjs +7519 -0
  137. package/dist/sun/stars.cjs.map +6 -0
  138. package/dist/sun/stars.d.ts +26 -0
  139. package/dist/sun/stars.d.ts.map +1 -0
  140. package/dist/sun/stars.js +188 -0
  141. package/dist/sun/stars.js.map +1 -0
  142. package/dist/sun/suncalc.d.ts +26 -0
  143. package/dist/sun/suncalc.d.ts.map +1 -0
  144. package/dist/sun/suncalc.js +94 -0
  145. package/dist/sun/suncalc.js.map +1 -0
  146. package/dist/sun/sunlight.d.ts +25 -0
  147. package/dist/sun/sunlight.d.ts.map +1 -0
  148. package/dist/sun/sunlight.js +76 -0
  149. package/dist/sun/sunlight.js.map +1 -0
  150. package/dist/timezone/index.cjs +205 -0
  151. package/dist/timezone/index.cjs.map +6 -0
  152. package/dist/timezone/index.d.ts +6 -0
  153. package/dist/timezone/index.d.ts.map +1 -0
  154. package/dist/timezone/index.js +8 -0
  155. package/dist/timezone/index.js.map +1 -0
  156. package/dist/timezone/instant.d.ts +4 -0
  157. package/dist/timezone/instant.d.ts.map +1 -0
  158. package/dist/timezone/instant.js +20 -0
  159. package/dist/timezone/instant.js.map +1 -0
  160. package/dist/timezone/local-date-time.d.ts +4 -0
  161. package/dist/timezone/local-date-time.d.ts.map +1 -0
  162. package/dist/timezone/local-date-time.js +34 -0
  163. package/dist/timezone/local-date-time.js.map +1 -0
  164. package/dist/timezone/lookup-async.d.ts +3 -0
  165. package/dist/timezone/lookup-async.d.ts.map +1 -0
  166. package/dist/timezone/lookup-async.js +14 -0
  167. package/dist/timezone/lookup-async.js.map +1 -0
  168. package/dist/timezone/lookup.cjs +83 -0
  169. package/dist/timezone/lookup.cjs.map +6 -0
  170. package/dist/timezone/lookup.d.ts +3 -0
  171. package/dist/timezone/lookup.d.ts.map +1 -0
  172. package/dist/timezone/lookup.js +18 -0
  173. package/dist/timezone/lookup.js.map +1 -0
  174. package/dist/timezone/temporal.cjs +5696 -0
  175. package/dist/timezone/temporal.cjs.map +6 -0
  176. package/dist/timezone/temporal.d.ts +9 -0
  177. package/dist/timezone/temporal.d.ts.map +1 -0
  178. package/dist/timezone/temporal.js +60 -0
  179. package/dist/timezone/temporal.js.map +1 -0
  180. package/dist/timezone/timezone-label.d.ts +5 -0
  181. package/dist/timezone/timezone-label.d.ts.map +1 -0
  182. package/dist/timezone/timezone-label.js +27 -0
  183. package/dist/timezone/timezone-label.js.map +1 -0
  184. package/dist/timezone/timezone-offset.d.ts +3 -0
  185. package/dist/timezone/timezone-offset.d.ts.map +1 -0
  186. package/dist/timezone/timezone-offset.js +22 -0
  187. package/dist/timezone/timezone-offset.js.map +1 -0
  188. package/dist/timezone/types.d.ts +23 -0
  189. package/dist/timezone/types.d.ts.map +1 -0
  190. package/dist/timezone/types.js +5 -0
  191. package/dist/timezone/types.js.map +1 -0
  192. package/dist/timezone/vendor/temporal/runtime.d.ts +3 -0
  193. package/dist/timezone/vendor/temporal/runtime.d.ts.map +1 -0
  194. package/dist/timezone/vendor/temporal/runtime.js +5649 -0
  195. package/dist/timezone/vendor/temporal/runtime.js.map +1 -0
  196. package/dist/timezone/vendor/temporal/types.d.ts +939 -0
  197. package/dist/timezone/vendor/temporal/types.d.ts.map +1 -0
  198. package/dist/timezone/vendor/temporal/types.js +4 -0
  199. package/dist/timezone/vendor/temporal/types.js.map +1 -0
  200. package/dist/timezone/vendor/tz-lookup/runtime.d.ts +3 -0
  201. package/dist/timezone/vendor/tz-lookup/runtime.d.ts.map +1 -0
  202. package/dist/timezone/vendor/tz-lookup/runtime.js +53 -0
  203. package/dist/timezone/vendor/tz-lookup/runtime.js.map +1 -0
  204. package/geoid/data/README.md +28 -0
  205. package/geoid/data/geoid-egm96-hi.pgm +0 -0
  206. package/geoid/data/geoid-egm96-low.pgm +0 -0
  207. package/geoid/data/geoid-manifest.json +22 -0
  208. package/package.json +91 -4
  209. package/src/geoid/create-geoid-from-grid.ts +51 -0
  210. package/src/geoid/geoid.ts +297 -0
  211. package/src/geoid/index.ts +8 -0
  212. package/src/geoid/parse-pgm.ts +189 -0
  213. package/src/index.ts +7 -0
  214. package/src/sun/astronomy.ts +272 -0
  215. package/src/sun/celestial.ts +22 -0
  216. package/src/sun/cloud-lighting.ts +198 -0
  217. package/src/sun/cloud-spectral.ts +54 -0
  218. package/src/sun/data/bright-stars.ts +7024 -0
  219. package/src/sun/data/sunlight.ts +969 -0
  220. package/src/sun/index.ts +43 -0
  221. package/src/sun/moon-appearance.ts +81 -0
  222. package/src/sun/moon-sky-brightness.ts +64 -0
  223. package/src/sun/moon.ts +122 -0
  224. package/src/sun/moonlight.ts +88 -0
  225. package/src/sun/planet-position.ts +305 -0
  226. package/src/sun/planet-times.ts +142 -0
  227. package/src/sun/planet-visibility.ts +143 -0
  228. package/src/sun/planets.ts +18 -0
  229. package/src/sun/sky-brightness.ts +148 -0
  230. package/src/sun/sky-events.ts +66 -0
  231. package/src/sun/sky-globe.ts +72 -0
  232. package/src/sun/sky-lighting.ts +118 -0
  233. package/src/sun/sky-observer.ts +66 -0
  234. package/src/sun/sky-time.ts +42 -0
  235. package/src/sun/star-galactic.ts +111 -0
  236. package/src/sun/star-milky-way.ts +61 -0
  237. package/src/sun/star-render.ts +149 -0
  238. package/src/sun/star-types.ts +66 -0
  239. package/src/sun/starfield.ts +100 -0
  240. package/src/sun/stars.ts +260 -0
  241. package/src/sun/suncalc.ts +141 -0
  242. package/src/sun/sunlight.ts +112 -0
  243. package/src/timezone/index.ts +9 -0
  244. package/src/timezone/instant.ts +21 -0
  245. package/src/timezone/local-date-time.ts +40 -0
  246. package/src/timezone/lookup-async.ts +15 -0
  247. package/src/timezone/lookup.ts +21 -0
  248. package/src/timezone/temporal.ts +81 -0
  249. package/src/timezone/timezone-label.ts +30 -0
  250. package/src/timezone/timezone-offset.ts +21 -0
  251. package/src/timezone/types.ts +30 -0
  252. package/src/timezone/vendor/temporal/JSBI-LICENSE.txt +179 -0
  253. package/src/timezone/vendor/temporal/LICENSE.txt +16 -0
  254. package/src/timezone/vendor/temporal/README.md +23 -0
  255. package/src/timezone/vendor/temporal/runtime.ts +5070 -0
  256. package/src/timezone/vendor/temporal/types.ts +1146 -0
  257. package/src/timezone/vendor/tz-lookup/LICENSE.txt +119 -0
  258. package/src/timezone/vendor/tz-lookup/README.md +22 -0
  259. package/src/timezone/vendor/tz-lookup/runtime.ts +53 -0
  260. package/sun/LICENSE-BRIGHT-STARS +21 -0
  261. package/sun/LICENSE-HOSEK-WILKIE +30 -0
  262. package/sun/LICENSE-SUNCALC +24 -0
  263. package/timezone/data/LICENSE-ODbL.txt +538 -0
  264. package/timezone/data/README.md +50 -0
  265. package/timezone/data/manifest.json +37 -0
  266. package/timezone/data/timezone-geometry-hi.json +1 -0
  267. package/timezone/data/timezone-geometry-hi.parquet +0 -0
  268. package/timezone/data/timezone-geometry-low.json +1 -0
  269. package/timezone/data/timezone-geometry-low.parquet +0 -0
@@ -0,0 +1,272 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+ // SPDX-FileComment: Original adapter to the MIT Astronomy Engine JavaScript API.
5
+ // https://github.com/cosinekitty/astronomy/tree/v2.1.19/source/js
6
+ // Ring dimensions: https://nssdc.gsfc.nasa.gov/planetary/factsheet/satringfact.html
7
+ import {
8
+ Body,
9
+ Equator,
10
+ Observer,
11
+ Rotation_EQJ_HOR,
12
+ RotateVector,
13
+ RotationAxis,
14
+ Libration,
15
+ Vector,
16
+ Illumination
17
+ } from 'astronomy-engine';
18
+ import {createSkyObserver, reverseSkyDirection, getSkyHorizonAltitude} from './sky-observer';
19
+ import type {SkyObserver, SkyHorizonProfile} from './sky-observer';
20
+ import {validateObserver} from './celestial';
21
+ import {getPlanetSkyInfo} from './planet-position';
22
+ import {getMoonAppearance} from './moon-appearance';
23
+ import type {SkyAtmosphereOptions} from './sky-brightness';
24
+ import {skyDirectionToGlobe, skyRotationToGlobe, getSkyGlobePosition} from './sky-globe';
25
+ import {createSkyTime} from './sky-time';
26
+ import type {SkyTimeScales} from './sky-time';
27
+ import {getSkyLighting} from './sky-lighting';
28
+ import {getScatteredMoonLuminance} from './moon-sky-brightness';
29
+ import {getPlanetVisibility} from './planet-visibility';
30
+ export type {SkyTimeScales} from './sky-time';
31
+
32
+ export type SkySnapshotOptions = {
33
+ galileanMoons?: boolean;
34
+ atmosphere?: SkyAtmosphereOptions;
35
+ timeScales?: SkyTimeScales;
36
+ horizonProfile?: SkyHorizonProfile;
37
+ /** Distance of render shell from observer, meters. Default 10000000. */
38
+ renderingDistance?: number;
39
+ };
40
+ /** Consistent geometric, topocentric snapshot; all local vectors use outward ENU. */
41
+ export function getSkySnapshot(
42
+ timestamp: number | Date,
43
+ observerOptions: SkyObserver,
44
+ options: SkySnapshotOptions = {}
45
+ ) {
46
+ const observer = createSkyObserver(observerOptions);
47
+ validateObserver(timestamp, observer.latitude, observer.longitude);
48
+ const date = new Date(timestamp);
49
+ const time = createSkyTime(timestamp, options.timeScales);
50
+ const location = new Observer(observer.latitude, observer.longitude, observer.elevation);
51
+ const rotation = Rotation_EQJ_HOR(time, location);
52
+ const localVector = (v: Vector): [number, number, number] => {
53
+ const local = RotateVector(rotation, v);
54
+ return [-local.y, local.x, local.z];
55
+ };
56
+ const geometry = (direction: [number, number, number]) => ({
57
+ globeDirection: skyDirectionToGlobe(direction, observer),
58
+ globePosition: getSkyGlobePosition(direction, observer, options.renderingDistance ?? 10000000)
59
+ });
60
+ const bodyInfo = (body: Body.Sun | Body.Moon) => {
61
+ const position = Equator(body, time, location, false, false);
62
+ const local = RotateVector(rotation, position.vec);
63
+ const length = position.vec.Length();
64
+ const direction: [number, number, number] = [
65
+ -local.y / length,
66
+ local.x / length,
67
+ local.z / length
68
+ ];
69
+ return {
70
+ direction,
71
+ incomingDirection: reverseSkyDirection(direction),
72
+ altitude: Math.atan2(direction[2], Math.hypot(direction[0], direction[1])),
73
+ azimuth: Math.atan2(-direction[0], -direction[1]),
74
+ distance: position.dist * 149597870.7,
75
+ angularDiameter:
76
+ 2 * Math.asin((body === Body.Sun ? 695700 : 1737.4) / (position.dist * 149597870.7)),
77
+ ...geometry(direction)
78
+ };
79
+ };
80
+ const sun = bodyInfo(Body.Sun);
81
+ const moon = bodyInfo(Body.Moon);
82
+ const lunarPhotometry = Illumination(Body.Moon, time);
83
+ const lightVector = localVector(
84
+ new Vector(-lunarPhotometry.hc.x, -lunarPhotometry.hc.y, -lunarPhotometry.hc.z, time)
85
+ );
86
+ const sunDirection = lightVector.map(value => value / Math.hypot(...lightVector)) as [
87
+ number,
88
+ number,
89
+ number
90
+ ];
91
+ const phaseAngle = Math.acos(
92
+ Math.max(
93
+ -1,
94
+ Math.min(1, -sunDirection.reduce((sum, value, i) => sum + value * moon.direction[i], 0))
95
+ )
96
+ );
97
+ const sunSeparation = Math.acos(
98
+ Math.max(
99
+ -1,
100
+ Math.min(
101
+ 1,
102
+ sun.direction.reduce((sum, value, i) => sum + value * moon.direction[i], 0)
103
+ )
104
+ )
105
+ );
106
+ const appearance = getMoonAppearance(moon.altitude, sun.altitude, {
107
+ ...options.atmosphere,
108
+ distance: moon.distance,
109
+ phaseAngle,
110
+ sunSeparation,
111
+ horizonAltitude: getSkyHorizonAltitude(moon.azimuth, options.horizonProfile)
112
+ });
113
+ const orientation = (body: Body, distance: number) => {
114
+ const axis = RotationAxis(body, time.AddDays(-distance / 299792.458 / 86400));
115
+ const ra = (axis.ra * Math.PI) / 12;
116
+ const dec = (axis.dec * Math.PI) / 180;
117
+ const w = (axis.spin * Math.PI) / 180;
118
+ const x = [-Math.sin(ra), Math.cos(ra), 0];
119
+ const y = [-Math.sin(dec) * Math.cos(ra), -Math.sin(dec) * Math.sin(ra), Math.cos(dec)];
120
+ const matrix = [
121
+ localVector(
122
+ new Vector(
123
+ ...(x.map((value, i) => value * Math.cos(w) + y[i] * Math.sin(w)) as [
124
+ number,
125
+ number,
126
+ number
127
+ ]),
128
+ axis.north.t
129
+ )
130
+ ),
131
+ localVector(
132
+ new Vector(
133
+ ...(x.map((value, i) => -value * Math.sin(w) + y[i] * Math.cos(w)) as [
134
+ number,
135
+ number,
136
+ number
137
+ ]),
138
+ axis.north.t
139
+ )
140
+ ),
141
+ localVector(axis.north)
142
+ ].flat();
143
+ return {rotation: matrix, globeRotation: skyRotationToGlobe(matrix, observer)};
144
+ };
145
+ const starfieldRotation = rotation.rot.flatMap(column => [-column[1], column[0], column[2]]);
146
+ const libration = Libration(time);
147
+ const lighting = getSkyLighting(sun.altitude, moon.altitude, {
148
+ ...options.atmosphere,
149
+ moonPhaseAngle: phaseAngle,
150
+ moonDistance: moon.distance,
151
+ moonSunSeparation: sunSeparation
152
+ });
153
+ lighting.moon.illuminance = appearance.illuminance;
154
+ lighting.moon.horizontalIlluminance = appearance.horizontalIlluminance;
155
+ return {
156
+ timestamp: date.getTime(),
157
+ observer,
158
+ frame: 'topocentric-ENU' as const,
159
+ equatorialFrame: 'J2000' as const,
160
+ angleUnits: 'radians' as const,
161
+ distanceUnits: 'kilometers' as const,
162
+ starfieldRotation,
163
+ globeStarfieldRotation: skyRotationToGlobe(starfieldRotation, observer),
164
+ sun,
165
+ lighting,
166
+ moon: {
167
+ ...moon,
168
+ phaseAngle,
169
+ illuminatedFraction: (1 + Math.cos(phaseAngle)) / 2,
170
+ sunDirection,
171
+ globeSunDirection: skyDirectionToGlobe(sunDirection, observer),
172
+ appearance,
173
+ ...orientation(Body.Moon, moon.distance),
174
+ libration: {
175
+ longitude: (libration.elon * Math.PI) / 180,
176
+ latitude: (libration.elat * Math.PI) / 180
177
+ }
178
+ },
179
+ planets: getPlanetSkyInfo(date, observer.latitude, observer.longitude, {
180
+ elevation: observer.elevation,
181
+ galileanMoons: options.galileanMoons,
182
+ timeScales: options.timeScales,
183
+ horizon: azimuth => getSkyHorizonAltitude(azimuth, options.horizonProfile),
184
+ visibility: {model: 'contrast', atmosphere: options.atmosphere}
185
+ }).map(planet => {
186
+ const angle = (direction: number[]) =>
187
+ Math.acos(
188
+ Math.max(
189
+ -1,
190
+ Math.min(
191
+ 1,
192
+ direction.reduce((sum, value, i) => sum + value * planet.direction[i], 0)
193
+ )
194
+ )
195
+ );
196
+ if (!planet.parent)
197
+ planet.visibility = getPlanetVisibility(
198
+ planet.magnitude!,
199
+ planet.altitude,
200
+ sun.altitude,
201
+ angle(sun.direction),
202
+ {
203
+ model: 'contrast',
204
+ atmosphere: options.atmosphere,
205
+ minimumAltitude: Math.max(
206
+ (5 * Math.PI) / 180,
207
+ getSkyHorizonAltitude(planet.azimuth, options.horizonProfile)
208
+ ),
209
+ additionalSkyLuminance: getScatteredMoonLuminance(
210
+ phaseAngle,
211
+ moon.altitude,
212
+ planet.altitude,
213
+ angle(moon.direction),
214
+ {...options.atmosphere, distance: moon.distance}
215
+ )
216
+ }
217
+ );
218
+ const axes = planet.parent ? null : orientation(planet.name as Body, planet.distance);
219
+ const normal = axes?.rotation.slice(6, 9) as [number, number, number] | undefined;
220
+ return {
221
+ ...planet,
222
+ ...geometry(planet.direction),
223
+ globeSunDirection: skyDirectionToGlobe(planet.sunDirection, observer),
224
+ orientation: axes,
225
+ rings:
226
+ planet.name === 'Saturn' && normal
227
+ ? {
228
+ normal,
229
+ globeNormal: skyDirectionToGlobe(normal, observer),
230
+ innerRadius: 74658,
231
+ outerRadius: 136780
232
+ }
233
+ : null
234
+ };
235
+ })
236
+ };
237
+ }
238
+
239
+ /** Reusable observer and bounded snapshot cache. Returned values are independent copies. */
240
+ export function createSkyContext(
241
+ observerOptions: SkyObserver,
242
+ options: SkySnapshotOptions & {cacheSize?: number} = {}
243
+ ) {
244
+ const observer = createSkyObserver(observerOptions);
245
+ const configuration = structuredClone(options);
246
+ const capacity = options.cacheSize ?? 32;
247
+ if (!Number.isInteger(capacity) || capacity < 0 || capacity > 10000)
248
+ throw new RangeError('Cache size must be an integer from 0 to 10000');
249
+ const cache = new Map<number, ReturnType<typeof getSkySnapshot>>();
250
+ let calculations = 0;
251
+ const getSnapshot = (timestamp: number | Date) => {
252
+ const key = new Date(timestamp).getTime();
253
+ let snapshot = cache.get(key);
254
+ if (snapshot) cache.delete(key);
255
+ else {
256
+ snapshot = getSkySnapshot(timestamp, observer, configuration);
257
+ calculations++;
258
+ }
259
+ if (capacity > 0) {
260
+ cache.set(key, snapshot);
261
+ if (cache.size > capacity) cache.delete(cache.keys().next().value!);
262
+ }
263
+ return structuredClone(snapshot);
264
+ };
265
+ return {
266
+ observer,
267
+ getSnapshot,
268
+ getSnapshots: (timestamps: readonly (number | Date)[]) => timestamps.map(getSnapshot),
269
+ clearCache: () => cache.clear(),
270
+ getStatistics: () => ({calculations, cachedSnapshots: cache.size})
271
+ };
272
+ }
@@ -0,0 +1,22 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+ /** Validate new celestial APIs without changing existing sun API behavior. */
5
+ export function validateObserver(
6
+ timestamp: number | Date,
7
+ latitude: number,
8
+ longitude: number
9
+ ): void {
10
+ const milliseconds = typeof timestamp === 'number' ? timestamp : timestamp.getTime();
11
+ if (!Number.isFinite(milliseconds) || !Number.isFinite(new Date(milliseconds).getTime())) {
12
+ throw new RangeError('Timestamp must be a valid Date or milliseconds since Unix epoch');
13
+ }
14
+ validateRange('Latitude', latitude, -90, 90);
15
+ validateRange('Longitude', longitude, -Number.MAX_VALUE, Number.MAX_VALUE);
16
+ }
17
+
18
+ export function validateRange(name: string, value: number, minimum: number, maximum: number): void {
19
+ if (!Number.isFinite(value) || value < minimum || value > maximum) {
20
+ throw new RangeError(`${name} must be finite and between ${minimum} and ${maximum}`);
21
+ }
22
+ }
@@ -0,0 +1,198 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+ // SPDX-FileComment: Original equations-based implementation; no reference code copied.
5
+ // Spherical exponential atmosphere and Beer-Lambert extinction: Bruneton & Neyret (2008),
6
+ // https://ebruneton.github.io/precomputed_atmospheric_scattering/
7
+ // Spectral Rayleigh/Angstrom approximation: Preetham et al. (1999),
8
+ // https://doi.org/10.1145/311535.311545
9
+ // Henyey-Greenstein phase function: https://www.pbr-book.org/3ed-2018/Volume_Scattering/Phase_Functions
10
+ import {getCloudSunSpectrum} from './cloud-spectral';
11
+ import {validateRange} from './celestial';
12
+ import {createSkyAtmosphere, getSkyLuminance} from './sky-brightness';
13
+ import {getSunLight} from './sunlight';
14
+ import type {SkyAtmosphereOptions} from './sky-brightness';
15
+ import type {LightColor} from './sunlight';
16
+
17
+ export type CloudLightingOptions = SkyAtmosphereOptions & {
18
+ /** Cloud sample altitude above mean sea level, meters, [0, 50000]. Default 2000. */
19
+ cloudAltitude?: number;
20
+ /** Aerosol wavelength exponent, [0, 4]. Default 1.3. */
21
+ angstromExponent?: number;
22
+ /** Optical depth of the cloud segment being rendered. Default 10, inherited from atmosphere. */
23
+ cloudOpticalDepth?: number;
24
+ /** Other clouds/material between this sample and the Sun, along the actual ray. Default 0. */
25
+ sunOpticalDepth?: number;
26
+ /** Cloud material between this sample and the viewer, along the actual ray. Default 0. */
27
+ viewOpticalDepth?: number;
28
+ /** Angle between Sun and cloud sightlines, radians [0, PI]. Default PI/2. */
29
+ sunSeparation?: number;
30
+ /** Henyey-Greenstein asymmetry, [-0.95, 0.95]. Default 0.7 (forward scattering). */
31
+ asymmetry?: number;
32
+ /** Fraction of cloud extinction due to scattering, [0, 1]. Default 0.999. */
33
+ singleScatteringAlbedo?: number;
34
+ /** Even Simpson quadrature steps, [32, 2048]. Default 512. */
35
+ integrationSteps?: number;
36
+ };
37
+
38
+ export type CloudLighting = {
39
+ /** Relative incident beam irradiance: unattenuated 5778 K solar peak is one. */
40
+ direct: LightColor;
41
+ /** Approximate incident hemispherical sky irradiance on the same relative scale. */
42
+ diffuse: LightColor;
43
+ /** Approximate single-scattered radiance, relative irradiance per steradian; not lux. */
44
+ scattered: LightColor;
45
+ /** Fraction of the geometric solar disk above the cloud's depressed Earth horizon. */
46
+ sunVisibleFraction: number;
47
+ /** Earth horizon below the cloud's local horizontal plane, radians. */
48
+ horizonAltitude: number;
49
+ /** Exponential density columns divided by their sea-level vertical scale heights. */
50
+ rayleighAirMass: number;
51
+ aerosolAirMass: number;
52
+ /** Henyey-Greenstein value in inverse steradians. Can exceed one. */
53
+ phaseFunction: number;
54
+ /** Extinction opacity of the rendered cloud segment; distinct from coverage. */
55
+ opacity: number;
56
+ };
57
+ const EARTH_RADIUS = 6371000;
58
+ const ATMOSPHERE_TOP = 100000;
59
+ const RAYLEIGH_HEIGHT = 8000;
60
+ const AEROSOL_HEIGHT = 1200;
61
+ const SUN_RADIUS = (0.266 * Math.PI) / 180;
62
+ // Approximate clear zenith solar illuminance used only to scale ambient photometry.
63
+ const REFERENCE_ILLUMINANCE = 110000;
64
+
65
+ /**
66
+ * Cloud-sample lighting from geometric Sun altitude relative to its local horizontal.
67
+ * Cloud height is MSL, not height above the viewer. Refraction and ozone are omitted.
68
+ * Direct extinction uses a spherical spectral atmosphere; ambient and cloud scattering
69
+ * are rendering approximations, not a volumetric multiple-scattering solution.
70
+ */
71
+ export function getCloudLighting(
72
+ sunAltitude: number,
73
+ options: CloudLightingOptions = {}
74
+ ): CloudLighting {
75
+ validateRange('Sun altitude', sunAltitude, -Math.PI / 2, Math.PI / 2);
76
+ const atmosphere = createSkyAtmosphere(options);
77
+ const {
78
+ cloudAltitude = 2000,
79
+ angstromExponent = 1.3,
80
+ sunOpticalDepth = 0,
81
+ viewOpticalDepth = 0,
82
+ sunSeparation = Math.PI / 2,
83
+ asymmetry = 0.7,
84
+ singleScatteringAlbedo = 0.999,
85
+ integrationSteps = 512
86
+ } = options;
87
+ validateRange('Cloud altitude', cloudAltitude, 0, 50000);
88
+ validateRange('Angstrom exponent', angstromExponent, 0, 4);
89
+ validateRange('Sun optical depth', sunOpticalDepth, 0, 1000);
90
+ validateRange('View optical depth', viewOpticalDepth, 0, 1000);
91
+ validateRange('Sun separation', sunSeparation, 0, Math.PI);
92
+ validateRange('Asymmetry', asymmetry, -0.95, 0.95);
93
+ validateRange('Single-scattering albedo', singleScatteringAlbedo, 0, 1);
94
+ validateRange('Integration steps', integrationSteps, 32, 2048);
95
+ if (!Number.isInteger(integrationSteps) || integrationSteps % 2)
96
+ throw new RangeError('Integration steps must be an even integer');
97
+ const radius = EARTH_RADIUS + cloudAltitude;
98
+ const horizonAltitude = -Math.acos(EARTH_RADIUS / radius);
99
+ const diskHeight =
100
+ sunAltitude <= horizonAltitude - SUN_RADIUS
101
+ ? -1
102
+ : sunAltitude >= horizonAltitude + SUN_RADIUS
103
+ ? 1
104
+ : (sunAltitude - horizonAltitude) / SUN_RADIUS;
105
+ const theta = Math.acos(-diskHeight);
106
+ // Stable circular-segment area near the first sliver, where subtraction loses precision.
107
+ const segmentArea =
108
+ theta < 0.01
109
+ ? theta ** 3 * (2 / 3 - (2 * theta ** 2) / 15 + (4 * theta ** 4) / 315)
110
+ : theta - Math.sin(theta) * Math.cos(theta);
111
+ const sunVisibleFraction = Math.max(0, Math.min(1, segmentArea / Math.PI));
112
+ // A visible segment's vertical centroid supplies one representative atmospheric ray.
113
+ const centroid = segmentArea > 0 ? ((2 / 3) * Math.sin(theta) ** 3) / segmentArea : 0;
114
+ const rayAltitude = Math.max(horizonAltitude, sunAltitude + centroid * SUN_RADIUS);
115
+ let rayleighAirMass = 0,
116
+ aerosolAirMass = 0;
117
+ const directRGB: [number, number, number] = [0, 0, 0];
118
+ if (sunVisibleFraction > 0) {
119
+ const mu = Math.sin(rayAltitude);
120
+ const top = EARTH_RADIUS + ATMOSPHERE_TOP;
121
+ const rayLength = -radius * mu + Math.sqrt((radius * mu) ** 2 + top * top - radius * radius);
122
+ const step = rayLength / integrationSteps;
123
+ for (let i = 0; i <= integrationSteps; i++) {
124
+ const s = i * step;
125
+ const radialSquared = radius * radius + 2 * radius * mu * s + s * s;
126
+ const height = Math.max(
127
+ 0,
128
+ (radialSquared - EARTH_RADIUS ** 2) / (Math.sqrt(radialSquared) + EARTH_RADIUS)
129
+ );
130
+ const weight = i === 0 || i === integrationSteps ? 1 : i % 2 ? 4 : 2;
131
+ rayleighAirMass += weight * Math.exp(-height / RAYLEIGH_HEIGHT);
132
+ aerosolAirMass += weight * Math.exp(-height / AEROSOL_HEIGHT);
133
+ }
134
+ rayleighAirMass *= step / (3 * RAYLEIGH_HEIGHT);
135
+ aerosolAirMass *= step / (3 * AEROSOL_HEIGHT);
136
+ const spectrum = getCloudSunSpectrum(
137
+ rayleighAirMass,
138
+ aerosolAirMass,
139
+ atmosphere.pressure,
140
+ atmosphere.aerosolOpticalDepth,
141
+ angstromExponent
142
+ );
143
+ const transmission = sunVisibleFraction * Math.exp(-sunOpticalDepth);
144
+ for (let channel = 0; channel < 3; channel++)
145
+ directRGB[channel] = spectrum[channel] * transmission;
146
+ }
147
+ // Empirical ground-column sky brightness reused at the cloud's location. Height
148
+ // correction for ambient multiple scattering is deliberately not inferred here.
149
+ const skyLuminance = getSkyLuminance(
150
+ sunAltitude,
151
+ Math.PI / 2,
152
+ Math.PI / 2 - sunAltitude,
153
+ atmosphere
154
+ );
155
+ const skyIrradiance = (Math.PI * skyLuminance) / REFERENCE_ILLUMINANCE;
156
+ const sky = getSunLight(Math.max(0, sunAltitude), {
157
+ turbidity: Math.min(10, 1 + 20 * atmosphere.aerosolOpticalDepth)
158
+ }).diffuse.color;
159
+ const daylight = smoothstep((-5 * Math.PI) / 180, 0, sunAltitude);
160
+ const diffuseRGB = [0.45, 0.65, 1].map((twilight, i) => {
161
+ const tint =
162
+ (twilight * (1 - daylight) + sky[i] * daylight) * (1 - atmosphere.cloudCover) +
163
+ atmosphere.cloudCover;
164
+ return skyIrradiance * tint;
165
+ }) as [number, number, number];
166
+ const phaseFunction =
167
+ (1 - asymmetry * asymmetry) /
168
+ (4 * Math.PI * (1 + asymmetry * asymmetry - 2 * asymmetry * Math.cos(sunSeparation)) ** 1.5);
169
+ const opacity = -Math.expm1(-atmosphere.cloudOpticalDepth);
170
+ const throughput = singleScatteringAlbedo * opacity * Math.exp(-viewOpticalDepth);
171
+ // Ambient hemisphere replaced by an isotropic incident field, not HG integration.
172
+ const scatteredRGB = directRGB.map(
173
+ (value, i) => throughput * (value * phaseFunction + diffuseRGB[i] / (2 * Math.PI))
174
+ ) as [number, number, number];
175
+ return {
176
+ direct: normalize(directRGB),
177
+ diffuse: normalize(diffuseRGB),
178
+ scattered: normalize(scatteredRGB),
179
+ sunVisibleFraction,
180
+ horizonAltitude,
181
+ rayleighAirMass,
182
+ aerosolAirMass,
183
+ phaseFunction,
184
+ opacity
185
+ };
186
+ }
187
+ function normalize(rgb: [number, number, number]): LightColor {
188
+ const intensity = Math.max(...rgb);
189
+ return {
190
+ color:
191
+ intensity > 0 ? (rgb.map(value => value / intensity) as [number, number, number]) : [0, 0, 0],
192
+ intensity
193
+ };
194
+ }
195
+ function smoothstep(lower: number, upper: number, value: number): number {
196
+ const t = Math.max(0, Math.min(1, (value - lower) / (upper - lower)));
197
+ return t * t * (3 - 2 * t);
198
+ }
@@ -0,0 +1,54 @@
1
+ // math.gl
2
+ // SPDX-License-Identifier: MIT
3
+ // SPDX-FileCopyrightText: Copyright (c) vis.gl contributors
4
+ // SPDX-FileComment: Independently implemented published equations; no reference code copied.
5
+ // Planck spectrum; Preetham et al. (1999) Rayleigh/Angstrom optical depths:
6
+ // https://doi.org/10.1145/311535.311545
7
+ // Wyman, Sloan & Shirley (2013), equation 4 / table 1 CIE matching-function fits:
8
+ // https://jcgt.org/published/0002/02/01/
9
+
10
+ const samples = Array.from({length: 41}, (_, i) => {
11
+ const nm = 380 + 10 * i;
12
+ const wavelength = nm * 1e-9;
13
+ const power = 1 / (wavelength ** 5 * Math.expm1(0.01438776877 / (5778 * wavelength)));
14
+ const weight = i === 0 || i === 40 ? 0.5 : 1;
15
+ const lobe = (center: number, left: number, right: number): number =>
16
+ Math.exp(-0.5 * ((nm - center) * (nm < center ? left : right)) ** 2);
17
+ const matching = [
18
+ 0.362 * lobe(442, 0.0624, 0.0374) +
19
+ 1.056 * lobe(599.8, 0.0264, 0.0323) -
20
+ 0.065 * lobe(501.1, 0.049, 0.0382),
21
+ 0.821 * lobe(568.8, 0.0213, 0.0247) + 0.286 * lobe(530.9, 0.0613, 0.0322),
22
+ 1.217 * lobe(437, 0.0845, 0.0278) + 0.681 * lobe(459, 0.0385, 0.0725)
23
+ ];
24
+ return {wavelength: nm / 1000, xyz: matching.map(value => value * power * weight)};
25
+ });
26
+ const referenceXYZ = [0, 1, 2].map(axis =>
27
+ samples.reduce((sum, sample) => sum + sample.xyz[axis], 0)
28
+ );
29
+ const reference = Math.max(...rgb(referenceXYZ));
30
+
31
+ /** Visible-band quadrature; normalized to peak unattenuated 5778 K solar linear sRGB. */
32
+ export function getCloudSunSpectrum(
33
+ molecularColumn: number,
34
+ aerosolColumn: number,
35
+ pressure: number,
36
+ aerosolOpticalDepth: number,
37
+ angstromExponent: number
38
+ ): [number, number, number] {
39
+ const xyz = [0, 0, 0];
40
+ for (const sample of samples) {
41
+ const rayleigh = (0.008735 * sample.wavelength ** -4.08 * pressure) / 1013.25;
42
+ const aerosol = aerosolOpticalDepth * (sample.wavelength / 0.55) ** -angstromExponent;
43
+ const transmission = Math.exp(-rayleigh * molecularColumn - aerosol * aerosolColumn);
44
+ for (let axis = 0; axis < 3; axis++) xyz[axis] += transmission * sample.xyz[axis];
45
+ }
46
+ return rgb(xyz).map(value => Math.max(0, value / reference)) as [number, number, number];
47
+ }
48
+ function rgb([x, y, z]: number[]): number[] {
49
+ return [
50
+ 3.2406 * x - 1.5372 * y - 0.4986 * z,
51
+ -0.9689 * x + 1.8758 * y + 0.0415 * z,
52
+ 0.0557 * x - 0.204 * y + 1.057 * z
53
+ ];
54
+ }