astraeus 0.2.0 → 0.3.0
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/CHANGELOG.md +28 -0
- package/README.md +41 -5
- package/package.json +2 -1
- package/src/api/AstraeusScene.js +1 -1
- package/src/api/AstraeusScene.node.js +37 -0
- package/src/api/group.d.ts +7 -1
- package/src/api/index.d.ts +1 -0
- package/src/api/index.js +1 -0
- package/src/api/index.node.js +8 -0
- package/src/api/mount.js +3 -1
- package/src/api/mount.node.js +36 -0
- package/src/api/scene.d.ts +32 -6
- package/src/api/scene.js +123 -26
- package/src/api/story.d.ts +8 -2
- package/src/api/story.js +11 -0
- package/src/api/sunOrbit.d.ts +6 -0
- package/src/api/sunOrbit.js +24 -0
- package/src/app/App.d.ts +6 -2
- package/src/app/App.js +8 -4
- package/src/app/App.node.js +401 -0
- package/src/app/PanelLoadBoundary.d.ts +2 -1
- package/src/app/PanelLoadBoundary.js +2 -2
- package/src/app/SkyView.d.ts +3 -3
- package/src/app/SkyView.js +19 -10
- package/src/app/experienceDefinition.d.ts +8 -0
- package/src/app/sceneContentsHooks.js +2 -2
- package/src/app/sceneFrame.js +4 -3
- package/src/app/sceneFraming.d.ts +13 -0
- package/src/app/sceneFraming.js +22 -0
- package/src/app/skyModel.js +1 -1
- package/src/assets/pictures.d.ts +1 -1
- package/src/assets/sky.d.ts +4 -4
- package/src/assets/sky.js +12 -13
- package/src/core/bodies/io.js +1 -1
- package/src/core/bodies/jupiterData.js +2 -2
- package/src/core/bodies/jupiterMoons.js +8 -12
- package/src/core/bodies/moon.d.ts +8 -0
- package/src/core/bodies/moon.js +28 -5
- package/src/core/bodies/outerPlanetData.js +7 -7
- package/src/core/bodies/planetMoons.js +18 -27
- package/src/core/bodies/swiftTuttle.js +2 -0
- package/src/core/elementsBody.d.ts +2 -0
- package/src/core/elementsBody.js +3 -0
- package/src/core/moonTrajectory.js +3 -5
- package/src/core/planetModels.js +1 -1
- package/src/core/provenance.d.ts +6 -2
- package/src/core/provenance.js +3 -1
- package/src/shell/AstraeusShell.js +5 -3
- package/src/shell/AstraeusShell.node.js +225 -0
- package/src/shell/DisplaySwitches.js +1 -1
- package/src/shell/StoryPanelView.js +3 -1
- package/src/shell/TimelineBar.node.js +75 -0
- package/src/shell/TopBar.node.js +14 -0
- package/src/shell/experience.d.ts +2 -0
- package/src/shell/infoModel.js +3 -1
- package/src/shell/phone.css +1 -1
- package/src/shell/useDrawers.js +1 -1
- package/src/shell/useZoomThrough.d.ts +7 -0
- package/src/shell/useZoomThrough.js +51 -0
package/src/api/scene.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { createProvenance } from "../core/provenance.js";
|
|
2
2
|
import { SampledTrajectory } from "../core/sampledTrajectory.js";
|
|
3
3
|
import { readableScale, trueScale } from "../core/scalePolicy.js";
|
|
4
|
+
import { createStateResolver } from "../core/stateResolver.js";
|
|
5
|
+
import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
|
|
4
6
|
import { loadPlanetSeries, planetSeriesLoaded } from "../core/planetSeries.js";
|
|
5
7
|
import { catalogue as builtInCatalogue, extendCatalogue, rootBodyId } from "../assets/catalogue.js";
|
|
6
8
|
import { buildElementsBody, ElementsBodyError, parseElementsBodyRecord } from "../core/elementsBody.js";
|
|
@@ -10,7 +12,7 @@ import { bodyMetrics } from "../app/bodyMetrics.js";
|
|
|
10
12
|
import { needsPlanetSeries } from "../app/planetNeeds.js";
|
|
11
13
|
import { catalogueItem } from "../app/catalogueItem.js";
|
|
12
14
|
import { createReadoutMetrics } from "../app/trackedMetrics.js";
|
|
13
|
-
import { circlesTheSun, sunOrbitIdOf, sunOrbitLayer } from "./sunOrbit.js";
|
|
15
|
+
import { circlesTheSun, farthestSunDistanceKm, sunOrbitIdOf, sunOrbitLayer } from "./sunOrbit.js";
|
|
14
16
|
import { readyMade } from "./bodies.js";
|
|
15
17
|
import { installData } from "./data.js";
|
|
16
18
|
import { planActivity, rateMetricOf } from "./activity.js";
|
|
@@ -18,7 +20,7 @@ import { buildGroupLayer, planGroup } from "./group.js";
|
|
|
18
20
|
import { SceneError } from "./errors.js";
|
|
19
21
|
import { toUtcMs } from "./time.js";
|
|
20
22
|
import { switchesOf } from "./switches.js";
|
|
21
|
-
import { eventsOf, panelsOf, timelineOf } from "./story.js";
|
|
23
|
+
import { eventProvenanceOf, eventsOf, panelsOf, timelineOf } from "./story.js";
|
|
22
24
|
export { toUtcMs } from "./time.js";
|
|
23
25
|
/** The orbits the engine can draw: the parent the line is measured from, and the span one lap covers. */
|
|
24
26
|
const ORBITS = {
|
|
@@ -35,9 +37,12 @@ export class SceneCamera {
|
|
|
35
37
|
#following = false;
|
|
36
38
|
#view = {};
|
|
37
39
|
#reach;
|
|
40
|
+
#fit;
|
|
38
41
|
#has;
|
|
39
|
-
|
|
42
|
+
#circlesSun;
|
|
43
|
+
constructor(has, circlesSun) {
|
|
40
44
|
this.#has = has;
|
|
45
|
+
this.#circlesSun = circlesSun;
|
|
41
46
|
}
|
|
42
47
|
/** Opens framed on a body or trajectory already added to the scene and already following it (the viewer's Follow button shows as pressed). */
|
|
43
48
|
follow(id, view = {}) {
|
|
@@ -59,14 +64,38 @@ export class SceneCamera {
|
|
|
59
64
|
}
|
|
60
65
|
/**
|
|
61
66
|
* Sets how far the viewer can zoom out from what they look at, in Earth radii (the scene's scaled unit); a finite number above 0, else `bad-camera`.
|
|
67
|
+
* Also sets the camera's far plane (where drawing stops) to 2.5 times `distance`, so what lies out to the reach is still drawn.
|
|
62
68
|
* Labels reach as far: a body's label stays shown at any distance the camera can take. Without this call the camera frames the scene as before.
|
|
69
|
+
* `setReach` and `fitOrbit` set the same limit, so the later call wins and replaces the earlier one.
|
|
63
70
|
*/
|
|
64
71
|
setReach(distance) {
|
|
65
72
|
if (!(typeof distance === "number" && Number.isFinite(distance) && distance > 0))
|
|
66
73
|
throw new SceneError("bad-camera", `camera.setReach: distance must be a finite number above 0, got ${String(distance)}`);
|
|
67
74
|
this.#reach = distance;
|
|
75
|
+
this.#fit = undefined;
|
|
68
76
|
return this;
|
|
69
77
|
}
|
|
78
|
+
/**
|
|
79
|
+
* Sets the farthest zoom-out so the whole orbit of a body circling the Sun (a planet, a built-in comet or one from `addBodyFromElements`, already added to the scene) fits the canvas
|
|
80
|
+
* from any view direction: the orbit's farthest Sun distance divided by the sine of the narrower half field of view of the canvas (vertical 45 degrees, or horizontal from the
|
|
81
|
+
* canvas's width over height), with 10 percent to spare. The viewer fits again whenever the canvas changes shape, such as a phone turning or a window resizing; the far plane follows
|
|
82
|
+
* as for `setReach`. The opening view does not move. Any other body throws `bad-camera` naming it; an id not in the scene throws `unknown-body`. `setReach` and `fitOrbit` set the
|
|
83
|
+
* same limit, so the later call wins and replaces the earlier one.
|
|
84
|
+
* @example
|
|
85
|
+
* scene.camera.fitOrbit("c-2025-a1");
|
|
86
|
+
*/
|
|
87
|
+
fitOrbit(body) {
|
|
88
|
+
const id = typeof body === "string" ? body : body.id;
|
|
89
|
+
if (!this.#has(id))
|
|
90
|
+
throw new SceneError("unknown-body", `camera.fitOrbit("${id}"): no body or trajectory with that id has been added to the scene`);
|
|
91
|
+
if (!this.#circlesSun(id))
|
|
92
|
+
throw new SceneError("bad-camera", `camera.fitOrbit("${id}"): "${id}" is not a body that circles the Sun (a planet, a comet or one added with addBodyFromElements)`);
|
|
93
|
+
this.#fit = id;
|
|
94
|
+
this.#reach = undefined;
|
|
95
|
+
return this;
|
|
96
|
+
}
|
|
97
|
+
/** The body `fitOrbit` fits the zoom-out to, if any. */
|
|
98
|
+
get fitted() { return this.#fit; }
|
|
70
99
|
/** The farthest zoom-out set with `setReach`, if any. */
|
|
71
100
|
get reach() { return this.#reach; }
|
|
72
101
|
get target() { return this.#target; }
|
|
@@ -96,16 +125,18 @@ export class Scene {
|
|
|
96
125
|
#catalogue = builtInCatalogue;
|
|
97
126
|
#notes = new Map();
|
|
98
127
|
#looks = new Map();
|
|
128
|
+
#sources = new Map();
|
|
99
129
|
#timeUtcMs;
|
|
100
130
|
#scale = trueScale;
|
|
101
131
|
#scaleOnly = false;
|
|
102
132
|
#events = [];
|
|
103
133
|
#eventProvenance;
|
|
134
|
+
#eventOwnProvenance = new Map();
|
|
104
135
|
#panels;
|
|
105
136
|
#timeline;
|
|
106
137
|
#switches;
|
|
107
138
|
constructor() {
|
|
108
|
-
this.camera = new SceneCamera((id) => this.#taken(id));
|
|
139
|
+
this.camera = new SceneCamera((id) => this.#taken(id), (id) => this.#bodies.has(id) && circlesTheSun(this.#catalogue, id));
|
|
109
140
|
}
|
|
110
141
|
/** Adds a catalogued body: a ready-made one (`earth`, `moon`, ...) or its id. The first body added is the scene's centre. `{ orbit: true }` also draws its orbit line. */
|
|
111
142
|
addBody(body, options = {}) {
|
|
@@ -179,7 +210,7 @@ export class Scene {
|
|
|
179
210
|
}
|
|
180
211
|
/**
|
|
181
212
|
* Adds a group of listed orbits drawn as one set of dots (one colour and dot size, one menu item and info card), with an optional clump near a body.
|
|
182
|
-
* The orbits circle the scene's centre unless `center` names another body. A repeated id throws `duplicate-id`; an empty list, a bad orbit, colour
|
|
213
|
+
* The orbits circle the scene's centre unless `center` names another body. A repeated id throws `duplicate-id`; an empty list, a bad orbit, colour or clump throws `bad-group`. A `center` that is not a catalogued body throws `unknown-body`; a catalogued one the finished scene does not hold throws `bad-group` from `toDefinition`.
|
|
183
214
|
* @example
|
|
184
215
|
* scene.addGroup({ id: "ring", orbits: [{ id: "a", semiMajorAxisKm: 90_000, eccentricity: 0.1, inclinationDeg: 5, raanDeg: 40, argumentOfPeriapsisDeg: 70 }], color: "#9de3a8" });
|
|
185
216
|
*/
|
|
@@ -216,19 +247,27 @@ export class Scene {
|
|
|
216
247
|
this.#scaleOnly = options.only === true;
|
|
217
248
|
return this;
|
|
218
249
|
}
|
|
219
|
-
/** Adds timed events to the timeline, each with an id, a label and a moment; `provenance` says where the times come from and is shown with every event. May be called more than once. */
|
|
250
|
+
/** Adds timed events to the timeline, each with an id, a label and a moment; `provenance` says where the times come from and is shown with every event that has none of its own (`EventInput.provenance`). May be called more than once. Malformed provenance throws "bad-event". */
|
|
220
251
|
addEvents(events, options = {}) {
|
|
221
|
-
|
|
222
|
-
|
|
223
|
-
|
|
252
|
+
const merged = eventsOf(events, this.#events);
|
|
253
|
+
const own = events.flatMap((event) => event.provenance === undefined ? [] : [[event.id, eventProvenanceOf(event.provenance, event.id)]]);
|
|
254
|
+
const batch = options.provenance === undefined ? undefined : eventProvenanceOf(options.provenance);
|
|
255
|
+
this.#events = merged;
|
|
256
|
+
for (const [id, provenance] of own)
|
|
257
|
+
this.#eventOwnProvenance.set(id, provenance);
|
|
258
|
+
if (batch !== undefined)
|
|
259
|
+
this.#eventProvenance = batch;
|
|
224
260
|
return this;
|
|
225
261
|
}
|
|
226
|
-
/**
|
|
262
|
+
/**
|
|
263
|
+
* Adds story panels that open as playback reaches them. A panel opens only when forward playback crosses its time, so one at the opening instant never opens by itself
|
|
264
|
+
* (a panel with an `object` still has its marker on that object). `at.utc` may be any instant inside the timeline, in any year. Their times may name events (`addEvents`) and path anchors, and `object` a body or path; these are checked when the scene is built (`mount`), and a mistake throws `bad-panels` naming the panel and field.
|
|
265
|
+
*/
|
|
227
266
|
addStoryPanels(panels) {
|
|
228
267
|
this.#panels = panels;
|
|
229
268
|
return this;
|
|
230
269
|
}
|
|
231
|
-
/** Sets the timeline: its span (`start`, `end`), the speeds offered (`rates`), the speed it opens at (`rate`) and whether playback wraps from the end to the start (`loop`), or `{ none: true }` for no timeline bar, with time frozen at `at` or running at `rate`. Without this call the span follows the paths and the speeds are 1 minute, 1 hour and 1 day per second. */
|
|
270
|
+
/** Sets the timeline: its span (`start`, `end`), the speeds offered (`rates`), the speed it opens at (`rate`) and whether playback wraps from the end to the start (`loop`; ignored with `{ none: true }`, which has no span to wrap, and when `setTimeline` is not called), or `{ none: true }` for no timeline bar, with time frozen at `at` or running at `rate`. Without this call the span follows the paths and the speeds are 1 minute, 1 hour and 1 day per second. */
|
|
232
271
|
setTimeline(timeline) {
|
|
233
272
|
this.#timeline = timelineOf(timeline);
|
|
234
273
|
return this;
|
|
@@ -245,16 +284,55 @@ export class Scene {
|
|
|
245
284
|
this.#switches = switchesOf(switches, this.#switches);
|
|
246
285
|
return this;
|
|
247
286
|
}
|
|
248
|
-
/**
|
|
287
|
+
/**
|
|
288
|
+
* The state of a body in the scene at a moment (position in km always; velocity in km/s only where the body's source provides it), the same State the viewer draws: for a path added with `addTrajectory`, about its centre body;
|
|
289
|
+
* for a ready-made body or one from `addBodyFromElements`, about its parent (a planet about the Sun, a moon about its planet). Figures a story quotes, such as a distance from the Sun, come from here. `velocityKmS` is set only for a path whose
|
|
290
|
+
* samples or provider carry velocities and for a moon from fitted data (Io); planets, Earth, the Sun, the built-in comet and elements bodies give position only, so check it before use. An id the scene does not hold throws `unknown-body`. Ready-made and elements bodies answer at any date (they have no data cut-off); only a moment outside an
|
|
291
|
+
* `addTrajectory` path throws `bad-time`. A planet before the planet series have loaded (they load at mount) throws `missing-data`.
|
|
292
|
+
* @example
|
|
293
|
+
* const sunDistanceKm = Math.hypot(...scene.stateOf("earth", "2026-08-12T00:00:00Z").positionKm);
|
|
294
|
+
*/
|
|
249
295
|
stateOf(id, time) {
|
|
250
296
|
const entry = this.#tracked.get(id);
|
|
251
|
-
if (entry === undefined)
|
|
252
|
-
throw new SceneError("unknown-body", `stateOf("${id}"): no trajectory with that id has been added to the scene`);
|
|
297
|
+
if (entry === undefined && !this.#bodies.has(id))
|
|
298
|
+
throw new SceneError("unknown-body", `stateOf("${id}"): no body or trajectory with that id has been added to the scene`);
|
|
253
299
|
const timeUtcMs = toUtcMs(time, `stateOf("${id}") time`);
|
|
254
|
-
const
|
|
255
|
-
|
|
256
|
-
|
|
257
|
-
|
|
300
|
+
const trajectory = entry?.body.trajectory ?? this.#catalogueSource(id);
|
|
301
|
+
const bounds = trajectory?.bounds;
|
|
302
|
+
if (bounds !== undefined && (timeUtcMs < bounds.startUtcMs || timeUtcMs > bounds.endUtcMs))
|
|
303
|
+
throw new SceneError("bad-time", `stateOf("${id}"): ${new Date(timeUtcMs).toISOString()} is outside the ${entry === undefined ? "body's data" : "path"} (${new Date(bounds.startUtcMs).toISOString()} to ${new Date(bounds.endUtcMs).toISOString()})`);
|
|
304
|
+
if (trajectory === undefined)
|
|
305
|
+
return this.#sunState(id, timeUtcMs);
|
|
306
|
+
try {
|
|
307
|
+
return trajectory.stateAt(timeUtcMs, entry?.center ?? this.#catalogue.get(id).definition.parentId);
|
|
308
|
+
}
|
|
309
|
+
catch (error) {
|
|
310
|
+
if (entry === undefined && error instanceof Error && error.message.startsWith("the planet series are not loaded"))
|
|
311
|
+
throw new SceneError("missing-data", `stateOf("${id}"): ${error.message}`);
|
|
312
|
+
throw error;
|
|
313
|
+
}
|
|
314
|
+
}
|
|
315
|
+
/** The Provenance of a body's position, as its info card shows it: for a ready-made or elements body the catalogue's position record, for a path the one passed to `addTrajectory`. Carries `accuracyClass` and `maxErrorFraction` where a comparison with an independent ephemeris exists. An id the scene does not hold throws `unknown-body`. */
|
|
316
|
+
provenanceOf(id) {
|
|
317
|
+
const entry = this.#tracked.get(id);
|
|
318
|
+
if (entry !== undefined)
|
|
319
|
+
return entry.body.provenance; // addTrajectory always sets one
|
|
320
|
+
if (!this.#bodies.has(id))
|
|
321
|
+
throw new SceneError("unknown-body", `provenanceOf("${id}"): no body or trajectory with that id has been added to the scene`);
|
|
322
|
+
return this.#catalogue.get(id).definition.accuracy.position;
|
|
323
|
+
}
|
|
324
|
+
/** A catalogued body's state source, the one the viewer draws from, made once per scene; none for the root (the Sun). */
|
|
325
|
+
#catalogueSource(id) {
|
|
326
|
+
const binding = this.#catalogue.sources().find((source) => source.body === id);
|
|
327
|
+
if (binding === undefined)
|
|
328
|
+
return undefined;
|
|
329
|
+
const made = this.#sources.get(id) ?? binding.create(createOrbAstronomyAdapter());
|
|
330
|
+
this.#sources.set(id, made);
|
|
331
|
+
return made;
|
|
332
|
+
}
|
|
333
|
+
/** The root body is at the origin of itself and at rest. */
|
|
334
|
+
#sunState(id, timeUtcMs) {
|
|
335
|
+
return createStateResolver(this.#catalogue.definitions(), this.#catalogue.sources(), createOrbAstronomyAdapter()).stateOf(id, timeUtcMs, id);
|
|
258
336
|
}
|
|
259
337
|
/** The story panels, resolved against this scene's events, anchors, objects and timeline span. */
|
|
260
338
|
#storyPanels(window) {
|
|
@@ -336,11 +414,18 @@ export class Scene {
|
|
|
336
414
|
throw new SceneError("bad-trajectory", `addTrajectory("${[...this.#tracked.keys()][0]}"): a scene centred on the Sun cannot hold a tracked path yet; centre the scene on Earth or another body`);
|
|
337
415
|
return sunCentred;
|
|
338
416
|
}
|
|
339
|
-
/** The shell item of a body: from the catalogue, with the scene's own words, look and label setting. A Sun-centred scene sets no label
|
|
417
|
+
/** The shell item of a body: from the catalogue, with the scene's own words, look and label setting. A Sun-centred scene, or one that fits the zoom-out to an orbit (`fitOrbit`, whose limit changes with the canvas), sets no label limit, so labels stay shown at any distance. */
|
|
340
418
|
#bodyObject(body, ids, sunCentred) {
|
|
341
|
-
const own = { labelPriority: 100 - ids.indexOf(body.id), ...(sunCentred ? {} : { labelMaxDistance: Math.max(500, this.camera.reach ?? 0) }), ...(this.#shape.get(body.id)?.showLabel === undefined ? {} : { showLabel: this.#shape.get(body.id).showLabel }), ...(this.#notes.has(body.id) ? { description: this.#notes.get(body.id) } : {}), ...this.#looks.get(body.id) };
|
|
419
|
+
const own = { labelPriority: 100 - ids.indexOf(body.id), ...(sunCentred || this.camera.fitted !== undefined ? {} : { labelMaxDistance: Math.max(500, this.camera.reach ?? 0) }), ...(this.#shape.get(body.id)?.showLabel === undefined ? {} : { showLabel: this.#shape.get(body.id).showLabel }), ...(this.#notes.has(body.id) ? { description: this.#notes.get(body.id) } : {}), ...this.#looks.get(body.id) };
|
|
342
420
|
return { ...catalogueItem(body.id, own, this.#catalogue), label: body.label };
|
|
343
421
|
}
|
|
422
|
+
/** The event provenance entries of the experience: the batch's, and each event's own. */
|
|
423
|
+
#eventProvenanceEntries() {
|
|
424
|
+
return {
|
|
425
|
+
...(this.#eventProvenance === undefined ? {} : { eventProvenance: this.#eventProvenance }),
|
|
426
|
+
...(this.#eventOwnProvenance.size === 0 ? {} : { eventProvenanceById: Object.fromEntries(this.#eventOwnProvenance) }),
|
|
427
|
+
};
|
|
428
|
+
}
|
|
344
429
|
/** The bodies that asked for a Sun-orbit line, checked: the Sun must be in the scene and the line's id free. */
|
|
345
430
|
#sunOrbitIds(ids) {
|
|
346
431
|
return [...this.#orbits].filter((id) => ORBITS[id] === undefined).map((id) => {
|
|
@@ -351,6 +436,14 @@ export class Scene {
|
|
|
351
436
|
return id;
|
|
352
437
|
});
|
|
353
438
|
}
|
|
439
|
+
/** The fitted body's farthest Sun distance, read once when the viewer first needs it (a planet's reads the planet series, loaded by then); undefined when no orbit is fitted. */
|
|
440
|
+
#fitFarthestKm(openUtcMs) {
|
|
441
|
+
const id = this.camera.fitted;
|
|
442
|
+
if (id === undefined)
|
|
443
|
+
return undefined;
|
|
444
|
+
let km;
|
|
445
|
+
return () => (km ??= farthestSunDistanceKm(this.#catalogue, id, openUtcMs, this.#own.get(id)));
|
|
446
|
+
}
|
|
354
447
|
/** One Sun-orbit line: one full turn from the opening time (an own body from its periapsis). Reads planet positions, so the planet series must be loaded. */
|
|
355
448
|
#sunPath(id, openUtcMs) {
|
|
356
449
|
const layer = sunOrbitLayer(this.#catalogue, id, openUtcMs, this.#looks.get(id)?.color ?? "", this.#own.get(id));
|
|
@@ -398,6 +491,7 @@ export class Scene {
|
|
|
398
491
|
const late = (plan) => !seriesIn && plan.input.clump !== undefined;
|
|
399
492
|
const layers = [...this.#groupLayers(ids, window, startUtcMs, (plan) => !late(plan))];
|
|
400
493
|
const labelled = [...this.#bodies.values(), ...tracked, ...[...this.#groups.values()]].map(({ id, label }) => ({ id, label }));
|
|
494
|
+
const catalogue = this.#catalogue;
|
|
401
495
|
const definition = {
|
|
402
496
|
experience: {
|
|
403
497
|
objects: [
|
|
@@ -407,7 +501,7 @@ export class Scene {
|
|
|
407
501
|
cameraPresets: cameraPresetsOf(labelled),
|
|
408
502
|
...(target === undefined ? {} : { startCameraPresetId: `${this.camera.following ? "follow" : "focus"}-${target}` }),
|
|
409
503
|
events: this.#events,
|
|
410
|
-
...
|
|
504
|
+
...this.#eventProvenanceEntries(),
|
|
411
505
|
...(storyPanels === undefined ? {} : { storyPanels }),
|
|
412
506
|
...(timeline?.none === true ? { hideTimeline: true } : {}),
|
|
413
507
|
window,
|
|
@@ -422,11 +516,11 @@ export class Scene {
|
|
|
422
516
|
composition: createComposition(this.#catalogue, { id: "scene", bodies: ids, defaultCenter: ids[0], ...(paths.length === 0 ? {} : { paths }) }),
|
|
423
517
|
scaleChoices: scaleChoicesOf(this.#scale, this.#scaleOnly, this.#enlargedInSun(sunCentred)),
|
|
424
518
|
...(this.#switches === undefined ? {} : { displaySwitches: this.#switches }),
|
|
425
|
-
...viewEntries(timeline, this.camera),
|
|
519
|
+
...viewEntries(timeline, this.camera, this.#fitFarthestKm(startUtcMs)),
|
|
426
520
|
...(target === undefined ? {} : { startView: { focus: target, azimuthDeg: view.azimuthDeg ?? 0, elevationDeg: view.elevationDeg ?? 30, distance: view.distance ?? 40 } }),
|
|
427
521
|
trackedBodies: tracked,
|
|
428
522
|
createMetrics: ({ resolver }) => {
|
|
429
|
-
const catalogued = bodyMetrics(resolver, ids, ["distance"]);
|
|
523
|
+
const catalogued = bodyMetrics(resolver, ids, ["distance"], catalogue);
|
|
430
524
|
const readouts = createReadoutMetrics([...this.#tracked.values()].map(({ body, readouts: specs }) => ({ body, readouts: specs })), resolver);
|
|
431
525
|
return (objectId, timeUtcMs) => (this.#groups.has(objectId) ? this.#groupMetrics(objectId, timeUtcMs) : this.#tracked.has(objectId) ? readouts(objectId, timeUtcMs) : catalogued(objectId, timeUtcMs));
|
|
432
526
|
},
|
|
@@ -444,11 +538,12 @@ export class Scene {
|
|
|
444
538
|
}
|
|
445
539
|
}
|
|
446
540
|
/** The playback and camera settings the scene asked for: looping, the farthest zoom-out and the ecliptic up. */
|
|
447
|
-
function viewEntries(timeline, camera) {
|
|
541
|
+
function viewEntries(timeline, camera, farthestKm) {
|
|
448
542
|
const { reach, view, target } = camera;
|
|
449
543
|
return {
|
|
450
544
|
...(timeline?.loop === true ? { loop: true } : {}),
|
|
451
545
|
...(reach === undefined ? {} : { camera: { maxFocusDistance: reach, far: reach * 2.5 } }),
|
|
546
|
+
...(farthestKm === undefined ? {} : { camera: { fitOrbit: { farthestKm } } }),
|
|
452
547
|
...(view.up === undefined || target === undefined ? {} : { viewUp: view.up }),
|
|
453
548
|
};
|
|
454
549
|
}
|
|
@@ -489,11 +584,13 @@ function cameraPresetsOf(objects) {
|
|
|
489
584
|
/** The timeline span and the moment the clock opens at; a moment outside a span the caller set is a `bad-timeline`. */
|
|
490
585
|
function spanOf(timeline, timeUtcMs, tracked) {
|
|
491
586
|
const setTime = (timeline?.none === true ? timeline.atUtcMs : undefined) ?? timeUtcMs;
|
|
492
|
-
|
|
587
|
+
// With nothing setting a span or a moment, the month window is centred on now and the clock opens at now (not at the window's start).
|
|
588
|
+
const now = setTime === undefined && timeline?.window === undefined && tracked.length === 0 ? Date.now() : undefined;
|
|
589
|
+
const window = timeline?.window ?? windowOf(tracked, setTime ?? now);
|
|
493
590
|
if (timeline?.window !== undefined && setTime !== undefined && (setTime < window.startUtcMs || setTime > window.endUtcMs)) {
|
|
494
591
|
throw new SceneError("bad-timeline", `setTime ${new Date(setTime).toISOString()} is outside the timeline (${new Date(window.startUtcMs).toISOString()} to ${new Date(window.endUtcMs).toISOString()})`);
|
|
495
592
|
}
|
|
496
|
-
return { window, startUtcMs: setTime ?? window.startUtcMs };
|
|
593
|
+
return { window, startUtcMs: setTime ?? now ?? window.startUtcMs };
|
|
497
594
|
}
|
|
498
595
|
/** The clock's opening: 60 times real time unless set; with no timeline and no rate, frozen. */
|
|
499
596
|
function clockOf(timeline, startUtcMs) {
|
package/src/api/story.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
import { type TimelineEvent } from "../core/events.js";
|
|
2
|
-
import type
|
|
2
|
+
import { type Provenance } from "../core/provenance.js";
|
|
3
3
|
import type { TimeBounds } from "../core/trajectory.js";
|
|
4
4
|
import { type PanelLookup, type StoryPanelSet } from "../shell/storyPanels.js";
|
|
5
5
|
import { type TimeInput } from "./time.js";
|
|
@@ -10,6 +10,8 @@ export interface EventInput {
|
|
|
10
10
|
readonly time: TimeInput;
|
|
11
11
|
/** A free word the timeline may group by, such as "launch". */
|
|
12
12
|
readonly type?: string;
|
|
13
|
+
/** Where this event's time comes from. Shown with the event; an event without one shows the `provenance` of `addEvents`. Malformed: `addEvents` throws "bad-event" naming the event. */
|
|
14
|
+
readonly provenance?: Provenance;
|
|
13
15
|
}
|
|
14
16
|
/** Options of `addEvents`. */
|
|
15
17
|
export interface AddEventsOptions {
|
|
@@ -25,7 +27,7 @@ export type TimelineInput = {
|
|
|
25
27
|
readonly start: TimeInput;
|
|
26
28
|
readonly end: TimeInput;
|
|
27
29
|
readonly rates?: readonly number[];
|
|
28
|
-
readonly rate?: number; /** True: while playing, reaching the end wraps to the start and plays on. The viewer can still seek and pause. Default false. */
|
|
30
|
+
readonly rate?: number; /** True: while playing, reaching the end wraps to the start and plays on. The viewer can still seek and pause. Default false. Not available with `none: true`, where it is ignored. */
|
|
29
31
|
readonly loop?: boolean;
|
|
30
32
|
readonly none?: undefined;
|
|
31
33
|
} | {
|
|
@@ -51,10 +53,14 @@ export interface TimelineSetting {
|
|
|
51
53
|
* body or path of the scene; these are checked when the scene is turned into a definition (mount), and a mistake throws `bad-panels` naming the panel and field.
|
|
52
54
|
*/
|
|
53
55
|
export interface StoryPanelsInput {
|
|
56
|
+
/** Seconds playback holds when a panel opens by itself (0 to 20, default 6; 0 never pauses). Playback then restarts, unless the visitor pressed Play during the hold, which ends it at once. */
|
|
54
57
|
readonly pauseSeconds?: number;
|
|
58
|
+
/** Whether panels open by themselves as forward playback crosses them (default true). */
|
|
55
59
|
readonly autoOpen?: boolean;
|
|
56
60
|
readonly panels: readonly unknown[];
|
|
57
61
|
}
|
|
62
|
+
/** Checks a provenance given to `addEvents` (for the whole batch, or for the event `eventId`) and returns it frozen; throws "bad-event" when malformed. */
|
|
63
|
+
export declare function eventProvenanceOf(value: unknown, eventId?: string): Provenance;
|
|
58
64
|
/** The events merged with `inputs`, sorted by time; each needs a distinct non-empty id and label and a valid moment. */
|
|
59
65
|
export declare function eventsOf(inputs: readonly EventInput[], known: readonly TimelineEvent[]): readonly TimelineEvent[];
|
|
60
66
|
/** Checks a `setTimeline` argument and converts its moments. */
|
package/src/api/story.js
CHANGED
|
@@ -1,7 +1,18 @@
|
|
|
1
1
|
import { createEvents } from "../core/events.js";
|
|
2
|
+
import { createProvenance } from "../core/provenance.js";
|
|
2
3
|
import { parseStoryPanels, StoryPanelError } from "../shell/storyPanels.js";
|
|
3
4
|
import { SceneError } from "./errors.js";
|
|
4
5
|
import { toUtcMs } from "./time.js";
|
|
6
|
+
/** Checks a provenance given to `addEvents` (for the whole batch, or for the event `eventId`) and returns it frozen; throws "bad-event" when malformed. */
|
|
7
|
+
export function eventProvenanceOf(value, eventId) {
|
|
8
|
+
const where = eventId === undefined ? "addEvents: provenance" : `addEvents: event "${eventId}" provenance`;
|
|
9
|
+
try {
|
|
10
|
+
return createProvenance(value);
|
|
11
|
+
}
|
|
12
|
+
catch (error) {
|
|
13
|
+
throw new SceneError("bad-event", `${where} is malformed (${error instanceof Error ? error.message : String(error)})`);
|
|
14
|
+
}
|
|
15
|
+
}
|
|
5
16
|
/** The events merged with `inputs`, sorted by time; each needs a distinct non-empty id and label and a valid moment. */
|
|
6
17
|
export function eventsOf(inputs, known) {
|
|
7
18
|
if (!Array.isArray(inputs))
|
package/src/api/sunOrbit.d.ts
CHANGED
|
@@ -12,3 +12,9 @@ export declare function circlesTheSun(catalogue: BodyCatalogue, id: BodyId): boo
|
|
|
12
12
|
* the body completes no turn within the search (a comet's century-long orbit given without elements).
|
|
13
13
|
*/
|
|
14
14
|
export declare function sunOrbitLayer(catalogue: BodyCatalogue, id: BodyId, startUtcMs: number, color: string, given?: EccentricSampling): PathLayer | undefined;
|
|
15
|
+
/**
|
|
16
|
+
* The farthest a body that circles the Sun gets from it, in km: a(1+e) when the period and eccentricity are known (published elements or the
|
|
17
|
+
* catalogue's comet sampling; a from Kepler's third law about the Sun), else the largest Sun distance over one full turn of its own state source.
|
|
18
|
+
* A planet's source reads the planet series, so those must be loaded. Throws `no-orbit` for a body that completes no turn in the search.
|
|
19
|
+
*/
|
|
20
|
+
export declare function farthestSunDistanceKm(catalogue: BodyCatalogue, id: BodyId, startUtcMs: number, given?: EccentricSampling): number;
|
package/src/api/sunOrbit.js
CHANGED
|
@@ -2,6 +2,7 @@ import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
|
|
|
2
2
|
import { BUILT_IN_SAMPLING, EARTH_EPHEMERIS } from "../core/bodies/index.js";
|
|
3
3
|
import { createEarthSunTrajectory, fullTurnSpanMs } from "../core/sunCentredSources.js";
|
|
4
4
|
import { rootBodyId } from "../assets/catalogue.js";
|
|
5
|
+
import { SceneError } from "./errors.js";
|
|
5
6
|
const DAY_MS = 86_400_000;
|
|
6
7
|
/** The turn search walks in two-day steps; the longest orbit among the planets is a dozen years. */
|
|
7
8
|
const TURN_STEP_MS = 2 * DAY_MS;
|
|
@@ -59,3 +60,26 @@ function turnSpan(source, startUtcMs) {
|
|
|
59
60
|
throw error;
|
|
60
61
|
}
|
|
61
62
|
}
|
|
63
|
+
/**
|
|
64
|
+
* The farthest a body that circles the Sun gets from it, in km: a(1+e) when the period and eccentricity are known (published elements or the
|
|
65
|
+
* catalogue's comet sampling; a from Kepler's third law about the Sun), else the largest Sun distance over one full turn of its own state source.
|
|
66
|
+
* A planet's source reads the planet series, so those must be loaded. Throws `no-orbit` for a body that completes no turn in the search.
|
|
67
|
+
*/
|
|
68
|
+
export function farthestSunDistanceKm(catalogue, id, startUtcMs, given) {
|
|
69
|
+
const sampling = given ?? BUILT_IN_SAMPLING[id];
|
|
70
|
+
if (sampling !== undefined) {
|
|
71
|
+
const gm = catalogue.get(rootBodyId(catalogue)).definition.gmKm3S2;
|
|
72
|
+
const semiMajorKm = Math.cbrt(gm * (sampling.periodMs / 1000 / (2 * Math.PI)) ** 2);
|
|
73
|
+
return semiMajorKm * (1 + sampling.eccentricity);
|
|
74
|
+
}
|
|
75
|
+
const source = trajectoryOf(catalogue, id);
|
|
76
|
+
const span = turnSpan(source, startUtcMs);
|
|
77
|
+
if (span === undefined)
|
|
78
|
+
throw new SceneError("no-orbit", `camera.fitOrbit("${id}"): "${id}" completes no turn within a dozen years and the catalogue does not know its period; add it with addBodyFromElements`);
|
|
79
|
+
let farthest = 0;
|
|
80
|
+
for (let k = 0; k < TURN_SAMPLES; k += 1) {
|
|
81
|
+
const [x, y, z] = source.stateAt(Math.round(span.startUtcMs + ((span.endUtcMs - span.startUtcMs) * k) / (TURN_SAMPLES - 1)), rootBodyId(catalogue)).positionKm;
|
|
82
|
+
farthest = Math.max(farthest, Math.hypot(x, y, z));
|
|
83
|
+
}
|
|
84
|
+
return farthest;
|
|
85
|
+
}
|
package/src/app/App.d.ts
CHANGED
|
@@ -6,8 +6,12 @@ export declare function hiddenLabelsFrom(search: string, objects: readonly {
|
|
|
6
6
|
}[]): Set<string>;
|
|
7
7
|
/** `?loop=on` or `?loop=off` overrides the experience's own looping setting. */
|
|
8
8
|
export declare function loopFromSearch(search: string, fallback: boolean): boolean;
|
|
9
|
-
/**
|
|
10
|
-
|
|
9
|
+
/**
|
|
10
|
+
* `onOpenAddress`: the entry's way to open a switch's address in place; without it a switch navigates the page.
|
|
11
|
+
* `writeTitle`: whether the page heading is set to the experience's name (default true); `mount` and `AstraeusScene` pass false so a host page keeps its own title.
|
|
12
|
+
*/
|
|
13
|
+
export declare function App({ definition, onOpenAddress, writeTitle }: {
|
|
11
14
|
readonly definition: ExperienceDefinition;
|
|
12
15
|
readonly onOpenAddress?: (address: string) => void;
|
|
16
|
+
readonly writeTitle?: boolean;
|
|
13
17
|
}): import("react").JSX.Element;
|
package/src/app/App.js
CHANGED
|
@@ -142,12 +142,16 @@ function initialSceneControls(definition, runtime, experience, startScale, glowB
|
|
|
142
142
|
...(startView === undefined ? {} : { startView }),
|
|
143
143
|
};
|
|
144
144
|
}
|
|
145
|
-
/**
|
|
146
|
-
|
|
145
|
+
/**
|
|
146
|
+
* `onOpenAddress`: the entry's way to open a switch's address in place; without it a switch navigates the page.
|
|
147
|
+
* `writeTitle`: whether the page heading is set to the experience's name (default true); `mount` and `AstraeusScene` pass false so a host page keeps its own title.
|
|
148
|
+
*/
|
|
149
|
+
export function App({ definition, onOpenAddress, writeTitle = true }) {
|
|
147
150
|
// The page heading names the experience once it is open; app.html says only "Astraeus" until then.
|
|
148
151
|
useEffect(() => {
|
|
149
|
-
|
|
150
|
-
|
|
152
|
+
if (writeTitle)
|
|
153
|
+
document.title = pageTitleOf(definition);
|
|
154
|
+
}, [definition, writeTitle]);
|
|
151
155
|
const runtime = useMemo(() => buildRuntime(definition), [definition]);
|
|
152
156
|
const experienceRuntime = useMemo(() => ({ clock: runtime.clock, resolver: runtime.resolver, catalogue: runtime.catalogue }), [runtime]);
|
|
153
157
|
// The choices offered, in the experience's order; the solar-system policy enlarges only the bodies the experience names.
|