astraeus 0.7.0 → 0.8.1
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 +189 -0
- package/README.md +202 -38
- package/data/ephemerides/planets/planets.json +1 -1
- package/package.json +5 -4
- package/src/api/AstraeusScene.d.ts +21 -5
- package/src/api/AstraeusScene.js +34 -10
- package/src/api/AstraeusScene.node.js +34 -10
- package/src/api/assembleScene.d.ts +36 -0
- package/src/api/assembleScene.js +175 -0
- package/src/api/bodySetChecks.d.ts +10 -0
- package/src/api/bodySetChecks.js +117 -0
- package/src/api/bodySetInput.d.ts +81 -0
- package/src/api/bodySetInput.js +1 -0
- package/src/api/containingBlock.d.ts +6 -0
- package/src/api/containingBlock.js +16 -0
- package/src/api/data.d.ts +17 -5
- package/src/api/data.js +28 -10
- package/src/api/definitionOf.d.ts +16 -0
- package/src/api/definitionOf.js +20 -0
- package/src/api/errors.d.ts +63 -1
- package/src/api/frozenCopy.d.ts +6 -0
- package/src/api/frozenCopy.js +26 -0
- package/src/api/group.d.ts +8 -2
- package/src/api/group.js +24 -5
- package/src/api/index.d.ts +18 -7
- package/src/api/index.js +2 -2
- package/src/api/index.node.js +2 -2
- package/src/api/listeners.d.ts +5 -0
- package/src/api/listeners.js +25 -0
- package/src/api/look.d.ts +47 -0
- package/src/api/look.js +1 -0
- package/src/api/lookInput.d.ts +3 -0
- package/src/api/lookInput.js +41 -0
- package/src/api/moonPanelInput.d.ts +60 -0
- package/src/api/moonPanelInput.js +1 -0
- package/src/api/mount.d.ts +9 -19
- package/src/api/mount.js +27 -13
- package/src/api/mount.node.js +27 -13
- package/src/api/pathProvenance.js +1 -1
- package/src/api/pickerInput.d.ts +25 -0
- package/src/api/pickerInput.js +1 -0
- package/src/api/planBodies.d.ts +72 -0
- package/src/api/planBodies.js +300 -0
- package/src/api/planBodySets.d.ts +68 -0
- package/src/api/planBodySets.js +234 -0
- package/src/api/planCamera.d.ts +83 -0
- package/src/api/planCamera.js +184 -0
- package/src/api/planGroups.d.ts +36 -0
- package/src/api/planGroups.js +103 -0
- package/src/api/planMoonPanel.d.ts +19 -0
- package/src/api/planMoonPanel.js +104 -0
- package/src/api/planPaths.d.ts +40 -0
- package/src/api/planPaths.js +212 -0
- package/src/api/planPicker.d.ts +12 -0
- package/src/api/planPicker.js +40 -0
- package/src/api/planPlaces.d.ts +16 -0
- package/src/api/planPlaces.js +99 -0
- package/src/api/planStory.d.ts +26 -0
- package/src/api/planStory.js +66 -0
- package/src/api/planTimeline.d.ts +27 -0
- package/src/api/planTimeline.js +68 -0
- package/src/api/planViews.d.ts +25 -0
- package/src/api/planViews.js +35 -0
- package/src/api/prepared.js +4 -1
- package/src/api/renamedInputs.d.ts +15 -0
- package/src/api/renamedInputs.js +39 -0
- package/src/api/scene.d.ts +162 -68
- package/src/api/scene.js +247 -793
- package/src/api/sceneFreeze.d.ts +4 -0
- package/src/api/sceneFreeze.js +10 -0
- package/src/api/sceneReads.d.ts +171 -0
- package/src/api/sceneReads.js +6 -0
- package/src/api/story.d.ts +49 -19
- package/src/api/story.js +54 -22
- package/src/api/sunOrbit.js +9 -11
- package/src/api/time.d.ts +2 -1
- package/src/api/time.js +2 -1
- package/src/api/viewerCamera.d.ts +22 -0
- package/src/api/viewerCamera.js +84 -0
- package/src/api/viewerClock.d.ts +30 -0
- package/src/api/viewerClock.js +85 -0
- package/src/api/viewerFirstDraw.d.ts +14 -0
- package/src/api/viewerFirstDraw.js +26 -0
- package/src/api/viewerHandle.d.ts +85 -0
- package/src/api/viewerHandle.js +32 -0
- package/src/api/viewerLink.d.ts +88 -15
- package/src/api/viewerLink.js +117 -75
- package/src/api/viewerLooks.d.ts +19 -0
- package/src/api/viewerLooks.js +37 -0
- package/src/api/viewerPicker.d.ts +22 -0
- package/src/api/viewerPicker.js +49 -0
- package/src/api/viewerSelection.d.ts +30 -0
- package/src/api/viewerSelection.js +46 -0
- package/src/api/viewerViews.d.ts +10 -0
- package/src/api/viewerViews.js +18 -0
- package/src/api/viewerZones.d.ts +20 -0
- package/src/api/viewerZones.js +47 -0
- package/src/api/views.d.ts +7 -6
- package/src/api/views.js +12 -6
- package/src/app/App.d.ts +5 -3
- package/src/app/App.js +211 -82
- package/src/app/App.node.js +211 -82
- package/src/app/AstraeusScene.d.ts +18 -2
- package/src/app/AstraeusScene.js +4 -4
- package/src/app/BodyView.d.ts +4 -1
- package/src/app/BodyView.js +2 -2
- package/src/app/CameraController.d.ts +6 -0
- package/src/app/DeveloperSettings.d.ts +1 -4
- package/src/app/DeveloperSettings.js +6 -10
- package/src/app/FeatureMarkers.d.ts +4 -3
- package/src/app/FeatureMarkers.js +8 -13
- package/src/app/FrameRateSection.js +2 -1
- package/src/app/OrbitSetView.js +1 -1
- package/src/app/SettingControls.d.ts +11 -3
- package/src/app/SettingControls.js +10 -2
- package/src/app/SkyView.d.ts +3 -10
- package/src/app/SkyView.js +6 -28
- package/src/app/address.d.ts +16 -0
- package/src/app/address.js +31 -0
- package/src/app/bodyDraw.d.ts +10 -7
- package/src/app/bodyDraw.js +12 -32
- package/src/app/bodyMetrics.js +2 -2
- package/src/app/bodySet.d.ts +4 -20
- package/src/app/bodySet.js +5 -16
- package/src/app/debugReadout.js +1 -1
- package/src/app/displaySwitches.d.ts +4 -0
- package/src/app/displaySwitches.js +6 -0
- package/src/app/experienceDefinition.d.ts +11 -23
- package/src/app/listSwitch.d.ts +8 -14
- package/src/app/listSwitch.js +3 -10
- package/src/app/liveLook.d.ts +39 -0
- package/src/app/liveLook.js +66 -0
- package/src/app/look.d.ts +36 -0
- package/src/app/look.js +61 -0
- package/src/app/mission.d.ts +1 -1
- package/src/app/mission.js +1 -1
- package/src/app/openClock.d.ts +3 -2
- package/src/app/openClock.js +3 -3
- package/src/app/sceneCamera.d.ts +2 -0
- package/src/app/sceneCamera.js +11 -1
- package/src/app/sceneFrame.d.ts +4 -4
- package/src/app/sceneFrame.js +13 -8
- package/src/app/sceneHooks.js +3 -2
- package/src/app/style.css +114 -139
- package/src/app/trackedMetrics.d.ts +10 -3
- package/src/app/trackedMetrics.js +22 -11
- package/src/app/viewLink.d.ts +10 -32
- package/src/app/viewLink.js +10 -49
- package/src/app/viewerPort.d.ts +52 -0
- package/src/app/views.d.ts +3 -0
- package/src/assets/bodies/galileanMoons.js +1 -2
- package/src/assets/bodies/io.js +2 -2
- package/src/assets/bodies/listedMoons.d.ts +1 -1
- package/src/assets/bodies/listedMoons.js +2 -3
- package/src/assets/bodies/planetSystemMaps.js +2 -3
- package/src/assets/bodies/venus.js +2 -6
- package/src/assets/catalogue.js +1 -2
- package/src/assets/licence.d.ts +3 -3
- package/src/assets/licence.js +3 -3
- package/src/assets/pictures.d.ts +15 -12
- package/src/assets/pictures.js +24 -20
- package/src/assets/sky.d.ts +6 -5
- package/src/assets/sky.js +6 -9
- package/src/assets/visual.d.ts +4 -0
- package/src/core/astronomyAdapter.d.ts +1 -1
- package/src/core/astronomyAdapter.js +3 -3
- package/src/core/bodies/index.d.ts +0 -4
- package/src/core/bodies/index.js +14 -18
- package/src/core/bodies/jupiter.js +1 -1
- package/src/core/bodies/jupiterData.d.ts +0 -1
- package/src/core/bodies/jupiterData.js +2 -5
- package/src/core/bodies/mars.js +1 -1
- package/src/core/bodies/mercury.js +1 -1
- package/src/core/bodies/moonSystem.d.ts +1 -1
- package/src/core/bodies/moonSystem.js +102 -55
- package/src/core/bodies/outerPlanetRingData.js +2 -2
- package/src/core/bodies/outerPlanets.d.ts +2 -3
- package/src/core/bodies/outerPlanets.js +4 -13
- package/src/core/bodies/planetMoons.d.ts +0 -2
- package/src/core/bodies/planetMoons.js +1 -18
- package/src/core/bodies/planetRecords.d.ts +8 -2
- package/src/core/bodies/planetRecords.js +13 -5
- package/src/core/bodies/planetTrajectory.d.ts +21 -4
- package/src/core/bodies/planetTrajectory.js +29 -5
- package/src/core/bodies/venus.js +1 -1
- package/src/core/bodySetFamilies.d.ts +20 -0
- package/src/core/bodySetFamilies.js +14 -0
- package/src/core/chebyshevEphemeris.js +1 -1
- package/src/core/elementsBody.d.ts +8 -4
- package/src/core/elementsBody.js +32 -11
- package/src/core/elementsGroup.d.ts +27 -0
- package/src/core/elementsGroup.js +85 -0
- package/src/core/events.d.ts +2 -0
- package/src/core/events.js +2 -0
- package/src/core/illumination.js +1 -1
- package/src/core/listedOrbitGroup.d.ts +2 -0
- package/src/core/listedOrbitGroup.js +11 -7
- package/src/core/moonListText.d.ts +6 -0
- package/src/core/moonListText.js +19 -0
- package/src/core/moonTrajectory.js +1 -1
- package/src/core/pacing.d.ts +38 -3
- package/src/core/pacing.js +55 -4
- package/src/core/planetModels.d.ts +1 -1
- package/src/core/planetModels.js +3 -3
- package/src/core/planetSeries.d.ts +10 -2
- package/src/core/planetSeries.js +17 -3
- package/src/core/pointGroup.js +1 -1
- package/src/core/provenance.d.ts +2 -1
- package/src/core/provenance.js +2 -2
- package/src/core/referenceCenters.js +5 -5
- package/src/core/sampledTrajectory.js +1 -1
- package/src/core/scalePolicy.d.ts +1 -0
- package/src/core/startView.d.ts +19 -0
- package/src/core/startView.js +28 -0
- package/src/core/state.d.ts +6 -2
- package/src/core/state.js +3 -3
- package/src/core/storyPanels.d.ts +63 -0
- package/src/core/storyPanels.js +111 -0
- package/src/core/sunCentredSources.d.ts +4 -0
- package/src/core/sunCentredSources.js +9 -2
- package/src/core/timeInput.d.ts +4 -0
- package/src/core/timeInput.js +4 -0
- package/src/shell/AstraeusShell.d.ts +18 -2
- package/src/shell/AstraeusShell.js +53 -14
- package/src/shell/AstraeusShell.node.js +53 -14
- package/src/shell/Collapsible.d.ts +4 -3
- package/src/shell/Collapsible.js +5 -5
- package/src/shell/ControlsDrawer.d.ts +1 -1
- package/src/shell/ControlsDrawer.js +3 -1
- package/src/shell/DisplaySwitches.js +2 -1
- package/src/shell/InfoPanel.d.ts +3 -1
- package/src/shell/InfoPanel.js +5 -4
- package/src/shell/MoonFamilyPanel.js +1 -1
- package/src/shell/ObjectControls.d.ts +3 -1
- package/src/shell/ObjectControls.js +2 -2
- package/src/shell/Sources.d.ts +5 -3
- package/src/shell/Sources.js +5 -5
- package/src/shell/StoryPanelView.d.ts +4 -3
- package/src/shell/StoryPanelView.js +8 -6
- package/src/shell/SwitchControl.d.ts +5 -11
- package/src/shell/SwitchControl.js +2 -20
- package/src/shell/TimelineBar.css +81 -81
- package/src/shell/TimelineBar.d.ts +5 -2
- package/src/shell/TimelineBar.js +9 -8
- package/src/shell/TimelineBar.node.js +9 -8
- package/src/shell/TopBar.css +22 -22
- package/src/shell/TopBar.d.ts +5 -1
- package/src/shell/TopBar.js +2 -2
- package/src/shell/TopBar.node.js +2 -2
- package/src/shell/bootLoader.d.ts +4 -10
- package/src/shell/bootLoader.js +6 -52
- package/src/shell/embedded.css +18 -18
- package/src/shell/experience.d.ts +1 -1
- package/src/shell/moonFamilies.d.ts +2 -6
- package/src/shell/moonFamilies.js +2 -18
- package/src/shell/phone.css +58 -58
- package/src/shell/storyPanels.d.ts +2 -53
- package/src/shell/storyPanels.js +1 -106
- package/src/shell/style.css +153 -134
- package/src/shell/useDrawers.d.ts +3 -2
- package/src/shell/useDrawers.js +4 -3
- package/src/shell/viewerKeys.d.ts +8 -0
- package/src/shell/viewerKeys.js +16 -0
- package/src/synthetic/syntheticDefinition.js +20 -24
- package/src/synthetic/syntheticJourneyScene.js +3 -3
- package/src/synthetic/syntheticProbeDefinition.js +2 -1
- package/src/synthetic/syntheticViewsDefinition.d.ts +0 -3
- package/src/synthetic/syntheticViewsDefinition.js +10 -16
- package/data/moons/jupiter.json +0 -3333
- package/data/moons/neptune.json +0 -555
- package/data/moons/pluto.json +0 -205
- package/data/moons/saturn.json +0 -8267
- package/data/moons/uranus.json +0 -887
- package/src/app/addressNavigation.d.ts +0 -17
- package/src/app/addressNavigation.js +0 -16
- package/src/assets/bodies/jupiterMoonCatalogue.d.ts +0 -3
- package/src/assets/bodies/jupiterMoonCatalogue.js +0 -4
- package/src/assets/bodies/outerPlanetCatalogues.d.ts +0 -7
- package/src/assets/bodies/outerPlanetCatalogues.js +0 -8
- package/src/assets/bodies/swiftTuttle.d.ts +0 -12
- package/src/assets/bodies/swiftTuttle.js +0 -13
- package/src/assets/moonCatalogue.d.ts +0 -49
- package/src/assets/moonCatalogue.js +0 -80
- package/src/core/bodies/outerPlanetData.d.ts +0 -4
- package/src/core/bodies/outerPlanetData.js +0 -13
- package/src/core/bodies/swiftTuttle.d.ts +0 -46
- package/src/core/bodies/swiftTuttle.js +0 -106
package/src/api/scene.js
CHANGED
|
@@ -1,126 +1,34 @@
|
|
|
1
|
-
import { createProvenance } from "../core/provenance.js";
|
|
2
|
-
import { planLineStretches, planPathProvenance } from "./pathProvenance.js";
|
|
3
|
-
import { influenceStretches, sphereOfInfluenceKm } from "./sphereOfInfluence.js";
|
|
4
|
-
import { SampledTrajectory } from "../core/sampledTrajectory.js";
|
|
5
1
|
import { readableScale, solarSystemScale, trueScale } from "../core/scalePolicy.js";
|
|
6
|
-
import { createState } from "../core/state.js";
|
|
7
|
-
import { createOrbTwoBodyAdapter } from "../core/twoBodyAdapter.js";
|
|
8
2
|
import { createStateResolver } from "../core/stateResolver.js";
|
|
9
3
|
import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
|
|
10
|
-
import {
|
|
11
|
-
import {
|
|
12
|
-
import {
|
|
13
|
-
import { createComposition } from "../assets/compositions.js";
|
|
14
|
-
import { bodyMetrics } from "../app/bodyMetrics.js";
|
|
15
|
-
import { needsPlanetSeries } from "../app/planetNeeds.js";
|
|
16
|
-
import { lineBodies } from "../app/mission.js";
|
|
17
|
-
import { catalogueItem } from "../app/catalogueItem.js";
|
|
18
|
-
import { createReadoutMetrics } from "../app/trackedMetrics.js";
|
|
19
|
-
import { circlesTheSun, farthestSunDistanceKm, sunOrbitIdOf, sunOrbitLayer } from "./sunOrbit.js";
|
|
20
|
-
import { listedMoonBodyOf } from "../core/bodies/listedMoonBodies.js";
|
|
21
|
-
import { FALLBACK_SCENE_CENTRE, readyMade } from "./bodies.js";
|
|
22
|
-
import { installData } from "./data.js";
|
|
23
|
-
import { planActivity, rateMetricOf } from "./activity.js";
|
|
24
|
-
import { buildGroupLayer, planGroup } from "./group.js";
|
|
4
|
+
import { catalogue as builtInCatalogue } from "../assets/catalogue.js";
|
|
5
|
+
import { circlesTheSun } from "./sunOrbit.js";
|
|
6
|
+
import { FALLBACK_SCENE_CENTRE } from "./bodies.js";
|
|
25
7
|
import { SceneError } from "./errors.js";
|
|
8
|
+
import { frozenCopy } from "./frozenCopy.js";
|
|
9
|
+
import { NotLoadedError } from "../core/planetSeries.js";
|
|
10
|
+
import { BodyPlan } from "./planBodies.js";
|
|
11
|
+
import { GroupPlan } from "./planGroups.js";
|
|
12
|
+
import { BodySetPlan } from "./planBodySets.js";
|
|
13
|
+
import { MoonPanelPlan } from "./planMoonPanel.js";
|
|
14
|
+
import { PickerPlan } from "./planPicker.js";
|
|
15
|
+
import { PlacesPlan } from "./planPlaces.js";
|
|
16
|
+
import { assembleScene } from "./assembleScene.js";
|
|
17
|
+
import { SceneCamera } from "./planCamera.js";
|
|
18
|
+
import { definitionOf, registerDefinition, registerMissingData } from "./definitionOf.js";
|
|
19
|
+
import { isMounted } from "./sceneFreeze.js";
|
|
20
|
+
import { StoryPlan } from "./planStory.js";
|
|
21
|
+
import { buildTracked, pathReads } from "./planPaths.js";
|
|
26
22
|
import { toUtcMs } from "./time.js";
|
|
27
|
-
import {
|
|
28
|
-
import {
|
|
29
|
-
import {
|
|
30
|
-
import { checkEventObjects, eventProvenanceOf, eventsOf, pacingFor, panelsOf, timelineOf } from "./story.js";
|
|
23
|
+
import { TimelinePlan } from "./planTimeline.js";
|
|
24
|
+
import { ViewPlan } from "./planViews.js";
|
|
25
|
+
import { checkedLook } from "./lookInput.js";
|
|
31
26
|
export { toUtcMs } from "./time.js";
|
|
32
|
-
|
|
33
|
-
|
|
34
|
-
* elements), drawn about its parent. Undefined where the definition gives no period. A moon closes its loop (Io's look) unless its definition says its line fades (the Moon's, as before).
|
|
35
|
-
*/
|
|
36
|
-
function moonOrbitPath(catalogue, id) {
|
|
37
|
-
if (!catalogue.has(id))
|
|
38
|
-
return undefined;
|
|
39
|
-
const { orbitPeriodDays, orbitLineFades, parentId } = catalogue.get(id).definition;
|
|
40
|
-
if (orbitPeriodDays === undefined || parentId === undefined)
|
|
41
|
-
return undefined;
|
|
42
|
-
return { spanMs: orbitPeriodDays * 86_400_000, ...(orbitLineFades === true ? {} : { look: { endFadeOn: false } }) };
|
|
43
|
-
}
|
|
44
|
-
const DEFAULT_COLOR = "#ffd27a";
|
|
45
|
-
const DAY_MS = 86_400_000;
|
|
46
|
-
const PROVIDER_PATH_SAMPLES = 128;
|
|
27
|
+
const DEFAULT_BODY_READOUTS = Object.freeze(["distance"]);
|
|
28
|
+
const BODY_READOUT_KINDS = ["distance", "phase", "coordinates"];
|
|
47
29
|
const SCALES = [trueScale, readableScale, solarSystemScale];
|
|
48
|
-
/** Samples along a path when its farthest distance is read for the default zoom-out. */
|
|
49
|
-
const PATH_COVER_SAMPLES = 400;
|
|
50
|
-
/** The scene's camera: what it opens on. */
|
|
51
|
-
export class SceneCamera {
|
|
52
|
-
#target;
|
|
53
|
-
#following = false;
|
|
54
|
-
#view = {};
|
|
55
|
-
#reach;
|
|
56
|
-
#fit;
|
|
57
|
-
#has;
|
|
58
|
-
#circlesSun;
|
|
59
|
-
constructor(has, circlesSun) {
|
|
60
|
-
this.#has = has;
|
|
61
|
-
this.#circlesSun = circlesSun;
|
|
62
|
-
}
|
|
63
|
-
/** Opens framed on a body or trajectory already added to the scene and already following it (the viewer's Follow button shows as pressed). */
|
|
64
|
-
follow(id, view = {}) {
|
|
65
|
-
return this.#open("follow", id, view, true);
|
|
66
|
-
}
|
|
67
|
-
/** Opens framed on a body or trajectory already added to the scene, looking at it but not following it (the viewer's Focus button shows as pressed). The last of `follow` and `lookAt` wins. */
|
|
68
|
-
lookAt(id, view = {}) {
|
|
69
|
-
return this.#open("lookAt", id, view, false);
|
|
70
|
-
}
|
|
71
|
-
#open(call, id, view, following) {
|
|
72
|
-
if (!this.#has(id))
|
|
73
|
-
throw new SceneError("unknown-body", `camera.${call}("${id}"): no body or trajectory with that id has been added to the scene`);
|
|
74
|
-
if (view.up !== undefined && view.up !== "equatorial" && view.up !== "ecliptic")
|
|
75
|
-
throw new SceneError("bad-camera", `camera.${call}("${id}"): up "${String(view.up)}" must be "equatorial" or "ecliptic"`);
|
|
76
|
-
this.#target = id;
|
|
77
|
-
this.#following = following;
|
|
78
|
-
this.#view = view;
|
|
79
|
-
return this;
|
|
80
|
-
}
|
|
81
|
-
/**
|
|
82
|
-
* 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`.
|
|
83
|
-
* 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.
|
|
84
|
-
* 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.
|
|
85
|
-
* `setReach` and `fitOrbit` set the same limit, so the later call wins and replaces the earlier one.
|
|
86
|
-
*/
|
|
87
|
-
setReach(distance) {
|
|
88
|
-
if (!(typeof distance === "number" && Number.isFinite(distance) && distance > 0))
|
|
89
|
-
throw new SceneError("bad-camera", `camera.setReach: distance must be a finite number above 0, got ${String(distance)}`);
|
|
90
|
-
this.#reach = distance;
|
|
91
|
-
this.#fit = undefined;
|
|
92
|
-
return this;
|
|
93
|
-
}
|
|
94
|
-
/**
|
|
95
|
-
* 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
|
|
96
|
-
* 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
|
|
97
|
-
* 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
|
|
98
|
-
* 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
|
|
99
|
-
* same limit, so the later call wins and replaces the earlier one.
|
|
100
|
-
* @example
|
|
101
|
-
* scene.camera.fitOrbit("c-2025-a1");
|
|
102
|
-
*/
|
|
103
|
-
fitOrbit(body) {
|
|
104
|
-
const id = typeof body === "string" ? body : body.id;
|
|
105
|
-
if (!this.#has(id))
|
|
106
|
-
throw new SceneError("unknown-body", `camera.fitOrbit("${id}"): no body or trajectory with that id has been added to the scene`);
|
|
107
|
-
if (!this.#circlesSun(id))
|
|
108
|
-
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)`);
|
|
109
|
-
this.#fit = id;
|
|
110
|
-
this.#reach = undefined;
|
|
111
|
-
return this;
|
|
112
|
-
}
|
|
113
|
-
/** The body `fitOrbit` fits the zoom-out to, if any. */
|
|
114
|
-
get fitted() { return this.#fit; }
|
|
115
|
-
/** The farthest zoom-out set with `setReach`, if any. */
|
|
116
|
-
get reach() { return this.#reach; }
|
|
117
|
-
get target() { return this.#target; }
|
|
118
|
-
/** Whether the opening view follows its target (`follow`) rather than only looking at it (`lookAt`). */
|
|
119
|
-
get following() { return this.#following; }
|
|
120
|
-
get view() { return this.#view; }
|
|
121
|
-
}
|
|
122
30
|
/**
|
|
123
|
-
* A scene built with imperative calls. `mount(element, scene)` draws it
|
|
31
|
+
* A scene built with imperative calls. `mount(element, scene)` draws it. Every method returns the scene, so calls chain.
|
|
124
32
|
* @example
|
|
125
33
|
* const scene = new Scene()
|
|
126
34
|
* .addBody(earth)
|
|
@@ -131,55 +39,78 @@ export class SceneCamera {
|
|
|
131
39
|
export class Scene {
|
|
132
40
|
/** The camera: `scene.camera.follow(id)` opens framed on a body or trajectory. */
|
|
133
41
|
camera;
|
|
134
|
-
#
|
|
42
|
+
#plan = new BodyPlan((id) => this.#taken(id), (id) => { for (const input of this.#defaulted.values())
|
|
43
|
+
this.#track(input, id); });
|
|
135
44
|
#tracked = new Map();
|
|
136
45
|
/** Paths added without a `center`: they follow the scene's first body, so one added before any body is rebuilt when the first body arrives. */
|
|
137
46
|
#defaulted = new Map();
|
|
138
|
-
#
|
|
139
|
-
#
|
|
140
|
-
#
|
|
141
|
-
#
|
|
142
|
-
#
|
|
143
|
-
#
|
|
144
|
-
#
|
|
145
|
-
#
|
|
146
|
-
#looks = new Map();
|
|
47
|
+
#groupPlan = new GroupPlan(() => this.#plan.catalogue, (id) => this.#taken(id));
|
|
48
|
+
#bodySets = new BodySetPlan(() => this.#plan.catalogue, (id) => this.#taken(id));
|
|
49
|
+
#moonPanel = new MoonPanelPlan();
|
|
50
|
+
#places = new PlacesPlan();
|
|
51
|
+
#picker = new PickerPlan();
|
|
52
|
+
#story = new StoryPlan();
|
|
53
|
+
#timeline = new TimelinePlan();
|
|
54
|
+
#viewPlan = new ViewPlan();
|
|
147
55
|
#sources = new Map();
|
|
148
|
-
#timeUtcMs;
|
|
149
56
|
#scale = trueScale;
|
|
150
57
|
#scaleOnly = false;
|
|
151
|
-
#
|
|
152
|
-
#
|
|
153
|
-
#eventOwnProvenance = new Map();
|
|
154
|
-
#panels;
|
|
155
|
-
#timeline;
|
|
156
|
-
#switches;
|
|
157
|
-
#views;
|
|
58
|
+
#look;
|
|
59
|
+
#bodyReadouts = DEFAULT_BODY_READOUTS;
|
|
158
60
|
constructor() {
|
|
159
|
-
this.camera = new SceneCamera((id) => this.#taken(id), (id) => this.#bodies.has(id) && circlesTheSun(this.#catalogue, id));
|
|
160
|
-
|
|
61
|
+
this.camera = new SceneCamera((id) => this.#taken(id), (id) => this.#plan.bodies.has(id) && circlesTheSun(this.#plan.catalogue, id), () => this.#editable());
|
|
62
|
+
registerDefinition(this, (data) => this.#definition(data));
|
|
63
|
+
registerMissingData(this, (data) => [...new Set([...this.#plan.missingData(data), ...this.#bodySets.missingData(data)])]);
|
|
64
|
+
}
|
|
65
|
+
/** Refuses an edit once a viewer has taken the scene. */
|
|
66
|
+
#editable() {
|
|
67
|
+
if (isMounted(this))
|
|
68
|
+
throw new SceneError("scene-mounted", "this scene was edited after a viewer took it; build a new scene instead");
|
|
69
|
+
}
|
|
70
|
+
/** The bodies the scene holds, in the order added (the first is the scene's centre): id, label, the body it circles, whether its orbit line is on, and how much it is enlarged. A fresh frozen list on every read; it answers on a scene a viewer has taken. */
|
|
71
|
+
get bodies() { return this.#plan.reads(); }
|
|
72
|
+
/** The paths the scene holds (`addTrajectory`), in the order added: id, label, centre body and provenance. A fresh frozen list on every read. */
|
|
73
|
+
get paths() { return pathReads(this.#tracked.values()); }
|
|
74
|
+
/** The groups the scene holds (`addGroup`), in the order added: id, label, orbit count, centre body, plane and the provenance the group's card shows. A fresh frozen list on every read. */
|
|
75
|
+
get groups() { return this.#groupPlan.reads(this.#sceneFirst()); }
|
|
76
|
+
/** The body sets the scene holds (`addBodySet`), in the order added: id, centre body, member count and family ids. A fresh frozen list on every read. */
|
|
77
|
+
get bodySets() { return this.#bodySets.reads(this.#sceneFirst()); }
|
|
78
|
+
/** The picker (`setPicker`), as set; undefined when none was set. */
|
|
79
|
+
get picker() { return this.#picker.input; }
|
|
80
|
+
/** The moon panel (`setMoonPanel`): how many moons it lists and the line that states them with their source and date; undefined when none was set. */
|
|
81
|
+
get moonPanel() { return this.#moonPanel.read(); }
|
|
82
|
+
/** The bodies that hold tagged places (`addPlaces`), in the order added, with how many each holds. A fresh frozen list on every read. */
|
|
83
|
+
get places() { return this.#places.reads(); }
|
|
84
|
+
/** The events the scene holds (`addEvents`), sorted by time: id, label, `timeUtcMs`, type, object and provenance (the event's own, else the batch's). A fresh frozen list on every read. */
|
|
85
|
+
get events() { return this.#story.eventReads(); }
|
|
86
|
+
/** The story panels (`addStoryPanels`), sorted by time with their times resolved against the events, path anchors and timeline as `mount` resolves them; empty when none were added. A bad panel throws `bad-panels`, as `mount` would. A fresh frozen list on every read. */
|
|
87
|
+
get panels() {
|
|
88
|
+
const { window } = this.#timelineSpan();
|
|
89
|
+
return this.#story.panelReads(window, this.#tracked.values(), [...this.#plan.bodies.keys(), ...this.#tracked.keys(), ...this.#groupPlan.groups.keys(), ...this.#bodySets.memberIds()]);
|
|
90
|
+
}
|
|
91
|
+
/** The views the scene names (`setViews`): the id of the opening view (`startId`), where the choice shows and each view's id, label and the `objects`, `events` and `panels` it shows (ids, as the viewer resolves them: what the view names plus whatever no view names); undefined when none were named. Checks the ids as `mount` does, so a bad one throws `bad-view`. A fresh frozen object on every read. */
|
|
92
|
+
get views() {
|
|
93
|
+
return this.#viewPlan.read(() => ({ objects: [...this.#tracked.keys(), ...this.#plan.bodies.keys(), ...this.#groupPlan.groups.keys()], events: this.events.map(({ id }) => id), panels: this.panels.map(({ id }) => id) }));
|
|
94
|
+
}
|
|
95
|
+
/** The scale choices the viewer will offer, in order, as ids ("true-scale", "readable-scale", "solar-system"); the first is the opening scale and `setScale(.., { only: true })` leaves just that one. */
|
|
96
|
+
get scales() { return Object.freeze(this.#plan.scaleChoices(this.#scale, this.#scaleOnly)); }
|
|
97
|
+
/** The activities added with `addActivity`, in the order added: each one's `id`, `label`, `unit`, span, peak and curve in UTC milliseconds, and where its stretches come from. Fresh, frozen and a copy of what was given, so editing the list or the input afterwards changes nothing. */
|
|
98
|
+
get activities() { return this.#groupPlan.activityReads(); }
|
|
99
|
+
/** The timeline the scene opens with: its span and opening moment in UTC milliseconds (`windowStartUtcMs`, `windowEndUtcMs`, `openUtcMs`), the speeds offered (`rates`), the opening `rate` and whether playback wraps (`loop`). With no span or moment set and no path or activity, the span is a month about the moment of the read. A moment outside a span set with `setTimeline` throws `bad-timeline`, as `mount` would. */
|
|
100
|
+
get timeline() { return this.#timeline.read(this.#spans()); }
|
|
101
|
+
/** The spans of the paths and activities, which the timeline follows when nothing sets it. */
|
|
102
|
+
#spans() {
|
|
103
|
+
return [...[...this.#tracked.values()].map(({ body }) => body.trajectory.bounds), ...[...this.#groupPlan.activities.values()].map((activity) => activity.window)];
|
|
104
|
+
}
|
|
105
|
+
#timelineSpan() { return this.#timeline.span(this.#spans()); }
|
|
106
|
+
/** The scene's first body, the centre of a group that names none. */
|
|
107
|
+
#sceneFirst() { return this.#plan.bodies.keys().next().value ?? FALLBACK_SCENE_CENTRE; }
|
|
161
108
|
/** 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. */
|
|
162
109
|
addBody(body, options = {}) {
|
|
163
|
-
|
|
164
|
-
|
|
165
|
-
this.#addListedMoon(id);
|
|
166
|
-
try {
|
|
167
|
-
this.#register("addBody", id, typeof body === "string" ? readyMade(id) ?? { id, label: this.#catalogue.has(id) ? this.#catalogue.get(id).definition.label : id } : body, options);
|
|
168
|
-
}
|
|
169
|
-
catch (error) {
|
|
170
|
-
this.#catalogue = before;
|
|
171
|
-
throw error;
|
|
172
|
-
}
|
|
110
|
+
this.#editable();
|
|
111
|
+
this.#plan.addBody(body, options);
|
|
173
112
|
return this;
|
|
174
113
|
}
|
|
175
|
-
/** A moon in the listed-moon table that the built-in catalogue does not define by hand is defined now, by the one rule, and joins this scene's catalogue only (an unused moon costs nothing). */
|
|
176
|
-
#addListedMoon(id) {
|
|
177
|
-
if (this.#catalogue.has(id))
|
|
178
|
-
return;
|
|
179
|
-
const moon = listedMoonBodyOf(id);
|
|
180
|
-
if (moon !== undefined && this.#catalogue.has(moon.definition.parentId))
|
|
181
|
-
this.#catalogue = extendCatalogueWithMoons(this.#catalogue, [moon]);
|
|
182
|
-
}
|
|
183
114
|
/**
|
|
184
115
|
* Adds your own body that circles the Sun, from its published orbit elements and where they came from: a record with the id, label, elements at an epoch, the source
|
|
185
116
|
* (name, URL, solution, access date), a stated accuracy and optionally a radius and marker. Drawn as a marker on unperturbed two-body motion about the Sun; the provenance
|
|
@@ -189,153 +120,175 @@ export class Scene {
|
|
|
189
120
|
* scene.addBody(sun).addBodyFromElements(record, { orbit: true, showLabel: false });
|
|
190
121
|
*/
|
|
191
122
|
addBodyFromElements(record, options = {}) {
|
|
192
|
-
|
|
193
|
-
|
|
194
|
-
const parsed = parseRecord(record);
|
|
195
|
-
if (this.#taken(parsed.id) || this.#catalogue.has(parsed.id))
|
|
196
|
-
throw new SceneError("duplicate-id", `addBodyFromElements("${parsed.id}"): that id is already in the scene or the catalogue`);
|
|
197
|
-
const root = builtInCatalogue.get(rootBodyId()).definition;
|
|
198
|
-
const before = this.#catalogue;
|
|
199
|
-
this.#catalogue = extendCatalogue(before, [parsed]);
|
|
200
|
-
try {
|
|
201
|
-
this.#register("addBodyFromElements", parsed.id, { id: parsed.id, label: parsed.label }, options);
|
|
202
|
-
}
|
|
203
|
-
catch (error) {
|
|
204
|
-
this.#catalogue = before;
|
|
205
|
-
throw error;
|
|
206
|
-
}
|
|
207
|
-
this.#own.set(parsed.id, buildElementsBody(parsed, { id: root.id, gmKm3S2: root.gmKm3S2 }).sampling);
|
|
123
|
+
this.#editable();
|
|
124
|
+
this.#plan.addFromElements(record, options);
|
|
208
125
|
return this;
|
|
209
126
|
}
|
|
210
|
-
#register(call, id, ref, options) {
|
|
211
|
-
if (options.orbit === true && moonOrbitPath(this.#catalogue, id) === undefined && !(circlesTheSun(this.#catalogue, id)))
|
|
212
|
-
throw new SceneError("no-orbit", `${call}("${id}", { orbit: true }): the engine draws the orbit line of any catalogued moon whose data give a period about its planet and of any body that circles the Sun (every planet: its own source over a full turn where the source covers one, else the two-body ellipse osculating at the opening time)`);
|
|
213
|
-
if (!this.#catalogue.has(id))
|
|
214
|
-
throw new SceneError("unknown-body", `${call}("${id}"): not a catalogued body (known: ${builtInCatalogue.ids().join(", ")}; any moon in the moon lists is added by its id, and \`listedMoons(planet)\` names them with the data package each needs)`);
|
|
215
|
-
if (this.#taken(id))
|
|
216
|
-
throw new SceneError("duplicate-id", `${call}("${id}"): already in the scene`);
|
|
217
|
-
checkBodyLook(id, options);
|
|
218
|
-
if (options.labelReach !== undefined)
|
|
219
|
-
this.#labelReaches.set(id, options.labelReach);
|
|
220
|
-
if (options.orbit === true)
|
|
221
|
-
this.#orbits.add(id);
|
|
222
|
-
if (options.color !== undefined || options.knownLimitations !== undefined)
|
|
223
|
-
this.#looks.set(id, { ...(options.color === undefined ? {} : { color: options.color }), ...(options.knownLimitations === undefined ? {} : { knownLimitations: options.knownLimitations }) });
|
|
224
|
-
if (options.enlarge !== undefined || options.showLabel !== undefined)
|
|
225
|
-
this.#shape.set(id, { ...(options.enlarge === undefined ? {} : { enlarge: options.enlarge }), ...(options.showLabel === undefined ? {} : { showLabel: options.showLabel }) });
|
|
226
|
-
if (options.description !== undefined)
|
|
227
|
-
this.#notes.set(id, options.description);
|
|
228
|
-
this.#bodies.set(id, ref);
|
|
229
|
-
if (this.#bodies.size === 1 && builtInCatalogue.has(id))
|
|
230
|
-
for (const input of this.#defaulted.values())
|
|
231
|
-
this.#buildTracked(input, id);
|
|
232
|
-
}
|
|
233
127
|
/** Adds a path to follow and draw, from sampled states or a provider with `stateAt(time)`. */
|
|
234
128
|
addTrajectory(input) {
|
|
235
|
-
|
|
129
|
+
this.#editable();
|
|
130
|
+
const own = frozenCopy(input);
|
|
131
|
+
const id = own.id;
|
|
236
132
|
if (typeof id !== "string" || id === "")
|
|
237
133
|
throw new SceneError("bad-trajectory", "addTrajectory: the trajectory needs a non-empty id");
|
|
238
134
|
if (this.#taken(id))
|
|
239
135
|
throw new SceneError("duplicate-id", `addTrajectory("${id}"): that id is already in the scene`);
|
|
240
|
-
this.#
|
|
241
|
-
if (
|
|
242
|
-
this.#defaulted.set(id,
|
|
136
|
+
this.#track(own, own.center ?? this.#sceneCentre());
|
|
137
|
+
if (own.center === undefined)
|
|
138
|
+
this.#defaulted.set(id, own);
|
|
243
139
|
return this;
|
|
244
140
|
}
|
|
245
|
-
/** The scene's centre: its first body when that is a built-in one, else Earth (the default of a path added before any body;
|
|
141
|
+
/** The scene's centre: its first body when that is a built-in one, else Earth (the default of a path added before any body; the body plan re-reads it when the first body arrives). */
|
|
246
142
|
#sceneCentre() {
|
|
247
|
-
const first = this.#bodies.keys().next();
|
|
143
|
+
const first = this.#plan.bodies.keys().next();
|
|
248
144
|
return first.done === true || !builtInCatalogue.has(first.value) ? FALLBACK_SCENE_CENTRE : first.value;
|
|
249
145
|
}
|
|
250
|
-
/** Validates and stores one path about `center
|
|
251
|
-
#
|
|
252
|
-
|
|
253
|
-
if (!builtInCatalogue.has(center))
|
|
254
|
-
throw new SceneError("unknown-body", `addTrajectory("${id}"): centre "${center}" is not a catalogued body`);
|
|
255
|
-
const provenance = input.provenance ?? createProvenance({ sourceType: "illustrative", sources: ["Supplied by the caller"], accuracy: "As supplied; the engine makes no claim.", notes: "Positions were passed to addTrajectory." });
|
|
256
|
-
const common = { id, label: input.label ?? id, color: input.color ?? DEFAULT_COLOR, anchorTimesUtcMs: [], provenance };
|
|
257
|
-
const readouts = readoutsOf(id, input.readouts);
|
|
258
|
-
if (input.labelReach !== undefined) {
|
|
259
|
-
checkLabelReach(input.labelReach, new SceneError("bad-trajectory", `addTrajectory("${id}"): labelReach ${String(input.labelReach)} must be a positive finite number`));
|
|
260
|
-
this.#labelReaches.set(id, input.labelReach);
|
|
261
|
-
}
|
|
262
|
-
if (input.plane !== undefined && input.plane !== "EQJ" && input.plane !== "ecliptic-j2000")
|
|
263
|
-
throw new SceneError("bad-trajectory", `addTrajectory("${id}"): plane "${String(input.plane)}" must be "EQJ" or "ecliptic-j2000"`);
|
|
264
|
-
const toEqj = input.plane === "ecliptic-j2000" ? createOrbTwoBodyAdapter().eclipticJ2000ToEqjMatrix() : null;
|
|
265
|
-
const body = "samples" in input ? sampledBody(common, input, center, toEqj) : providerBody(common, input, toEqj);
|
|
266
|
-
const span = { startUtcMs: body.trajectory.bounds.startUtcMs, endUtcMs: body.trajectory.bounds.endUtcMs };
|
|
267
|
-
const provenanceSpans = input.provenanceSpans === undefined ? undefined : planPathProvenance(id, input.provenanceSpans, span);
|
|
268
|
-
checkLineFixedToType(id, input.lineFixedTo);
|
|
269
|
-
const auto = input.lineFixedTo === "auto";
|
|
270
|
-
const lineFixedTo = typeof input.lineFixedTo === "object" ? planLineStretches(id, input.lineFixedTo, span) : auto ? undefined : input.lineFixedTo;
|
|
271
|
-
this.#tracked.set(id, { center, ...(auto ? { auto: true } : {}), body: withAnchors(lineFixedTo === undefined ? body : { ...body, lineFixedTo }, input.anchors), readouts, ...(provenanceSpans === undefined ? {} : { provenanceSpans }), ...(input.description === undefined ? {} : { description: input.description }), ...(input.knownLimitations === undefined ? {} : { knownLimitations: input.knownLimitations }) });
|
|
146
|
+
/** Validates and stores one path about `center` (`planPaths.ts`). */
|
|
147
|
+
#track(input, center) {
|
|
148
|
+
this.#tracked.set(input.id, buildTracked(input, center, this.#plan.labelReaches));
|
|
272
149
|
}
|
|
273
150
|
/** Whether a body, path or group already has this id. */
|
|
274
151
|
#taken(id) {
|
|
275
|
-
return this.#bodies.has(id) || this.#tracked.has(id) || this.#groups.has(id);
|
|
152
|
+
return this.#plan.bodies.has(id) || this.#tracked.has(id) || this.#groupPlan.groups.has(id) || this.#bodySets.has(id);
|
|
276
153
|
}
|
|
277
154
|
/**
|
|
278
155
|
* 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.
|
|
279
|
-
* 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 `
|
|
156
|
+
* The orbits are given in `plane` ("ecliptic-j2000" or "EQJ"), which is required: a group without one throws `bad-group`. They 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 `check`, `load` or `mount`.
|
|
280
157
|
* @example
|
|
281
|
-
* scene.addGroup({ id: "ring", orbits: [{ id: "a", semiMajorAxisKm: 90_000, eccentricity: 0.1, inclinationDeg: 5, raanDeg: 40, argumentOfPeriapsisDeg: 70 }], color: "#9de3a8" });
|
|
158
|
+
* scene.addGroup({ id: "ring", orbits: [{ id: "a", semiMajorAxisKm: 90_000, eccentricity: 0.1, inclinationDeg: 5, raanDeg: 40, argumentOfPeriapsisDeg: 70 }], plane: "ecliptic-j2000", color: "#9de3a8" });
|
|
282
159
|
*/
|
|
283
160
|
addGroup(input) {
|
|
284
|
-
|
|
285
|
-
|
|
286
|
-
|
|
287
|
-
|
|
161
|
+
this.#editable();
|
|
162
|
+
this.#groupPlan.addGroup(frozenCopy(input));
|
|
163
|
+
return this;
|
|
164
|
+
}
|
|
165
|
+
/**
|
|
166
|
+
* Adds many small bodies about one centre as one batch: each member is a selectable dot (a ball at true size close up, its name on hover, tap or near zoom), with orbit lines coloured by its family.
|
|
167
|
+
* The members circle the scene's centre unless `center` names another body in the scene. They are all listed moons of the centre (positions come through `data`, as for `addBody`) or all made-up
|
|
168
|
+
* ones with `elements` on two-body motion. `bodies` names bodies added with `addBody` that belong to a family. A repeated id throws `duplicate-id`; a malformed set, an unlisted moon, a centre
|
|
169
|
+
* without gravity or a balance point outside the set throws `bad-body-set`. Read the result from `scene.bodySets`.
|
|
170
|
+
* @example
|
|
171
|
+
* scene.addBodySet({ id: "swarm", families: [{ id: "inner", label: "Inner swarm" }], provenance: { sourceType: "illustrative", sources: ["Made up"], accuracy: "Not real.", notes: "" }, members: [{ id: "bit-a", label: "Bit A", radiusKm: 5, family: "inner", elements: { semiMajorAxisKm: 30_000, eccentricity: 0.1, inclinationDeg: 5, raanDeg: 10, argumentOfPeriapsisDeg: 20, trueAnomalyDeg: 30 } }] });
|
|
172
|
+
*/
|
|
173
|
+
addBodySet(input) {
|
|
174
|
+
this.#editable();
|
|
175
|
+
this.#bodySets.add(input);
|
|
176
|
+
return this;
|
|
177
|
+
}
|
|
178
|
+
/**
|
|
179
|
+
* Shows the sliding panel of a planet's moons by family: its heading label, the families (each a one-line description and its moons, named or provisional), the family listed first with pictures
|
|
180
|
+
* (`featuredFamily`) and where and when the list was taken (`listSource`, `listDate`). Each moon is a body (`addBody`) or a body-set member (`addBodySet`) of the scene, checked when the scene is built;
|
|
181
|
+
* its label comes from there, and a body gets the picture the viewer's `data` brings for it. Replaces any earlier panel. A malformed panel, or a moon the scene does not hold, throws `bad-moon-panel`. Read the count and summary from `scene.moonPanel`.
|
|
182
|
+
* @example
|
|
183
|
+
* scene.setMoonPanel({ label: "Tarn", families: [{ id: "inner", label: "Inner moons", description: "Close and quick.", moons: [{ id: "bit-a" }] }], listSource: "A made-up list", listDate: "2026-10-18" });
|
|
184
|
+
*/
|
|
185
|
+
setMoonPanel(input) {
|
|
186
|
+
this.#editable();
|
|
187
|
+
this.#moonPanel.set(input);
|
|
188
|
+
return this;
|
|
189
|
+
}
|
|
190
|
+
/**
|
|
191
|
+
* Offers a choice in the viewer's top bar and phone drawer: one button per option, the one with `value` pressed when the viewer opens. Fewer than two options draw nothing. Replaces any earlier picker.
|
|
192
|
+
* A press only tells the host (`onPick` on the handle, or the prop of `AstraeusScene`): the viewer never navigates, reads or writes the page address, or keeps a time, and the pressed button does not move
|
|
193
|
+
* until the host calls `setPick` or mounts a new scene. A malformed picker, or a `value` that is not one of the options, throws `bad-picker`. Read it back from `scene.picker`.
|
|
194
|
+
* @example
|
|
195
|
+
* scene.setPicker({ id: "world", label: "World", options: [{ value: "tarn", label: "Tarn" }, { value: "mere", label: "Mere" }], value: "tarn" });
|
|
196
|
+
*/
|
|
197
|
+
setPicker(input) {
|
|
198
|
+
this.#editable();
|
|
199
|
+
this.#picker.set(input);
|
|
200
|
+
return this;
|
|
201
|
+
}
|
|
202
|
+
/**
|
|
203
|
+
* Adds the tagged places of one body, drawn as markers on it and opened in the information panel: categories (key, label, colour), places (id, name, kind, category, latitude and longitude in degrees as given,
|
|
204
|
+
* description and optional details) and the provenance shown with each. The body must be in the scene when it is built. A second call for one body throws `duplicate-id`; a malformed list throws `bad-places`.
|
|
205
|
+
* Read the result from `scene.places`.
|
|
206
|
+
* @example
|
|
207
|
+
* scene.addPlaces("tarn", { categories: [{ key: "pit", label: "Pits", color: "#9de3a8" }], places: [{ id: "deep", name: "Deep Pit", kind: "Pit", category: "pit", latitudeDeg: 12, longitudeDeg: -40, description: "A made-up pit." }], provenance: { sourceType: "illustrative", sources: ["Made up"], accuracy: "Not real.", notes: "" } });
|
|
208
|
+
*/
|
|
209
|
+
addPlaces(body, input) {
|
|
210
|
+
this.#editable();
|
|
211
|
+
this.#places.add(body, input);
|
|
288
212
|
return this;
|
|
289
213
|
}
|
|
290
214
|
/**
|
|
291
215
|
* Adds a period of activity to the timeline: a rate curve the timeline glows by, its peak mark, and where each stretch comes from. A group's `{ kind: "rate" }` readout shows its live rate
|
|
292
|
-
* (unavailable outside the period) against the peak. Without `setTimeline`, the timeline spans the activities. A repeated id
|
|
216
|
+
* (unavailable outside the period) against the peak. Without `setTimeline`, the timeline spans the activities. A repeated id throws `duplicate-id`; a bad curve, peak, source or moment throws `bad-activity`.
|
|
293
217
|
* @example
|
|
294
218
|
* scene.addActivity({ id: "burst", label: "Burst", unit: "per hour", start: "2026-08-01", end: "2026-08-20", peak: "2026-08-12", samples: [{ time: "2026-08-01", value: 2 }, { time: "2026-08-12", value: 100 }, { time: "2026-08-20", value: 5 }] });
|
|
295
219
|
*/
|
|
296
220
|
addActivity(input) {
|
|
297
|
-
|
|
298
|
-
|
|
299
|
-
throw new SceneError("bad-activity", `addActivity("${plan.window.id}"): an activity with that id is already in the scene`);
|
|
300
|
-
this.#activities.set(plan.window.id, plan);
|
|
221
|
+
this.#editable();
|
|
222
|
+
this.#groupPlan.addActivity(input);
|
|
301
223
|
return this;
|
|
302
224
|
}
|
|
303
225
|
/** Sets the moment the scene opens at. */
|
|
304
226
|
setTime(time) {
|
|
305
|
-
this.#
|
|
227
|
+
this.#editable();
|
|
228
|
+
this.#timeline.setTime(time);
|
|
306
229
|
return this;
|
|
307
230
|
}
|
|
308
231
|
/** Chooses the opening scale: `trueScale`, `readableScale` or `solarSystemScale` (true distances, the enlarged bodies drawn larger; it needs a Sun-centred scene with an enlarged body, else the scene throws `bad-scale`); the viewer can switch to the other (in a Sun-centred scene with an enlarged body, the second choice is the Solar system scale instead of the readable one), unless `{ only: true }` offers this scale alone. */
|
|
309
232
|
setScale(scale, options = {}) {
|
|
310
|
-
|
|
233
|
+
this.#editable();
|
|
234
|
+
const known = SCALES.find((candidate) => candidate.id === scale?.id);
|
|
235
|
+
if (known === undefined)
|
|
311
236
|
throw new SceneError("bad-scale", `setScale: "${String(scale?.id)}" is not a scale; use trueScale, readableScale or solarSystemScale`);
|
|
312
|
-
this.#scale =
|
|
237
|
+
this.#scale = known;
|
|
313
238
|
this.#scaleOnly = options.only === true;
|
|
314
239
|
return this;
|
|
315
240
|
}
|
|
316
|
-
/**
|
|
241
|
+
/**
|
|
242
|
+
* Sets the looks, presentation settings that change how the scene is drawn and never where anything is (`LookInput`: star, Milky Way and Sun glow brightness, marker and feature-marker sizes in pixels, the
|
|
243
|
+
* loading-cover fade in seconds, the sky shown or hidden). Replaces the whole look: a look not named keeps its default. A page address parameter, when the viewer's `address` option is on, overrides the look
|
|
244
|
+
* it names. An unknown look or a value out of its range throws `bad-look` here.
|
|
245
|
+
* @example
|
|
246
|
+
* scene.setLook({ starBrightness: 1.4, markerSwapRadiusPx: 5, loadFadeSeconds: 1 });
|
|
247
|
+
*/
|
|
248
|
+
setLook(look) {
|
|
249
|
+
this.#editable();
|
|
250
|
+
this.#look = checkedLook(look);
|
|
251
|
+
return this;
|
|
252
|
+
}
|
|
253
|
+
/**
|
|
254
|
+
* Chooses the rows a body's info card shows (a body whose `addBody` gave its own `readouts` keeps those): `"distance"` (to the parent and the Sun), `"phase"` (the lit share of its disc, for a body with a parent)
|
|
255
|
+
* and `"coordinates"`, in the order given. Replaces the earlier choice. Default `["distance"]`. An unknown kind, or a list that is not an array, throws `bad-readout`.
|
|
256
|
+
* @example
|
|
257
|
+
* scene.setBodyReadouts(["distance", "phase", "coordinates"]);
|
|
258
|
+
*/
|
|
259
|
+
setBodyReadouts(kinds) {
|
|
260
|
+
this.#editable();
|
|
261
|
+
if (!Array.isArray(kinds) || kinds.some((kind) => !BODY_READOUT_KINDS.includes(kind)))
|
|
262
|
+
throw new SceneError("bad-readout", `setBodyReadouts: give a list of ${BODY_READOUT_KINDS.map((kind) => `"${kind}"`).join(", ")}, got ${JSON.stringify(kinds)}`);
|
|
263
|
+
this.#bodyReadouts = Object.freeze([...kinds]);
|
|
264
|
+
return this;
|
|
265
|
+
}
|
|
266
|
+
/** 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; it appends. A repeated id, in one call or across calls, throws `duplicate-id`; a malformed event or provenance throws "bad-event". */
|
|
317
267
|
addEvents(events, options = {}) {
|
|
318
|
-
|
|
319
|
-
|
|
320
|
-
const batch = options.provenance === undefined ? undefined : eventProvenanceOf(options.provenance);
|
|
321
|
-
this.#events = merged;
|
|
322
|
-
for (const [id, provenance] of own)
|
|
323
|
-
this.#eventOwnProvenance.set(id, provenance);
|
|
324
|
-
if (batch !== undefined)
|
|
325
|
-
this.#eventProvenance = batch;
|
|
268
|
+
this.#editable();
|
|
269
|
+
this.#story.addEvents(events, options);
|
|
326
270
|
return this;
|
|
327
271
|
}
|
|
328
272
|
/**
|
|
329
|
-
*
|
|
330
|
-
* (a panel with an `object` still has its marker on that object). `at.
|
|
273
|
+
* Appends 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
|
|
274
|
+
* (a panel with an `object` still has its marker on that object). `at.time` is any moment inside the timeline, in any year. A bad shape throws `bad-panels` here, naming the panel and field, and a repeated id `duplicate-id`.
|
|
275
|
+
* Panel times may name events (`addEvents`) and path anchors, and `object` a body or path; these may be added later, so they are checked when the scene is built (`check`, `mount`), and a mistake throws `bad-panels` naming the panel and field.
|
|
331
276
|
*/
|
|
332
277
|
addStoryPanels(panels) {
|
|
333
|
-
this.#
|
|
278
|
+
this.#editable();
|
|
279
|
+
this.#story.addPanels(frozenCopy(panels));
|
|
280
|
+
return this;
|
|
281
|
+
}
|
|
282
|
+
/** Sets how story panels play: `pauseSeconds` and `autoOpen` (see `StoryPanelPlaybackInput`). Replaces the whole setting, so a field left out returns to its default. A bad value throws `bad-panels`. */
|
|
283
|
+
setStoryPanelPlayback(playback) {
|
|
284
|
+
this.#editable();
|
|
285
|
+
this.#story.setPanelPlayback(frozenCopy(playback));
|
|
334
286
|
return this;
|
|
335
287
|
}
|
|
336
|
-
/** Sets the timeline: its span (`start`, `end`), the speeds offered (`rates`), the speed it opens at (`rate`), `pacing` (playback that slows for encounters and speeds up for cruise: spans `{
|
|
288
|
+
/** Sets the timeline: its span (`start`, `end`), the speeds offered (`rates`), the speed it opens at (`rate`), `pacing` (playback that slows for encounters and speeds up for cruise: spans `{ start, end, rate }` and event rules `{ near: { type, withinSeconds }, rate }`, easing between speeds; a speed the visitor or host picks wins until `setRate("auto")`; see `PacingInput`) 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. */
|
|
337
289
|
setTimeline(timeline) {
|
|
338
|
-
this.#
|
|
290
|
+
this.#editable();
|
|
291
|
+
this.#timeline.setTimeline(frozenCopy(timeline));
|
|
339
292
|
return this;
|
|
340
293
|
}
|
|
341
294
|
/**
|
|
@@ -347,33 +300,37 @@ export class Scene {
|
|
|
347
300
|
* scene.setSwitches({ orbitLines: { place: "top-bar" }, labels: { place: "panel", on: false }, milkyWay: { place: "developer", on: false } });
|
|
348
301
|
*/
|
|
349
302
|
setSwitches(switches) {
|
|
350
|
-
this.#
|
|
303
|
+
this.#editable();
|
|
304
|
+
this.#viewPlan.setSwitches(switches);
|
|
351
305
|
return this;
|
|
352
306
|
}
|
|
353
307
|
/**
|
|
354
|
-
* Names views of this one scene, each listing what it shows: `
|
|
308
|
+
* Names views of this one scene, each listing what it shows: `objects` (ids of `addBody`, `addGroup` or `addTrajectory`), `events` (ids of `addEvents`) and `panels` (ids of `addStoryPanels`).
|
|
355
309
|
* Anything no view names shows in every view (shared bodies such as the planets); anything a view names shows only in the views that name it. `place` is `"top-bar"` or `"panel"` (as for `setSwitches`);
|
|
356
310
|
* `start` is the opening view (default the first). `camera` says what happens when the followed or focused object is not in the view switched to: `"stay"` (default), `"start"` (the scene's start) or
|
|
357
311
|
* `{ follow: id }` / `{ focus: id }` (that framing; the object must be in the view). Presentation only: State is unchanged and a hidden object keeps its state. May be called again; the later call replaces the views.
|
|
358
312
|
* An empty list, a repeated view id, a bad place or camera, or a `start` that is not a view throws `bad-view` here; an id the scene does not hold, or a camera target the view does not show, throws `bad-view` when the scene is built (`mount`), so the call may come before or after the objects.
|
|
359
313
|
* @example
|
|
360
|
-
* scene.setViews([{ id: "a", label: "Probe A",
|
|
314
|
+
* scene.setViews([{ id: "a", label: "Probe A", objects: ["probe-a"] }, { id: "b", label: "Probe B", objects: ["probe-b"] }, { id: "both", label: "Both" }], { place: "top-bar" });
|
|
361
315
|
*/
|
|
362
316
|
setViews(views, options) {
|
|
363
|
-
this.#
|
|
317
|
+
this.#editable();
|
|
318
|
+
this.#viewPlan.setViews(views, options);
|
|
364
319
|
return this;
|
|
365
320
|
}
|
|
366
321
|
/**
|
|
367
322
|
* 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;
|
|
368
323
|
* 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
|
|
369
|
-
* samples or provider carry velocities and for a moon from fitted data (Io); planets, Earth, the Sun
|
|
370
|
-
* `addTrajectory` path throws `bad-time`. A planet before
|
|
324
|
+
* samples or provider carry velocities and for a moon from fitted data (Io); planets, Earth, the Sun 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
|
|
325
|
+
* `addTrajectory` path throws `bad-time`. A planet or fitted moon before its data has loaded (`await scene.load({ data })`, or mount the scene and await `ready`) throws `missing-data`.
|
|
371
326
|
* @example
|
|
372
327
|
* const sunDistanceKm = Math.hypot(...scene.stateOf("earth", "2026-08-12T00:00:00Z").positionKm);
|
|
373
328
|
*/
|
|
374
329
|
stateOf(id, time) {
|
|
375
330
|
const entry = this.#tracked.get(id);
|
|
376
|
-
if (entry === undefined && !this.#bodies.has(id))
|
|
331
|
+
if (entry === undefined && !this.#plan.bodies.has(id) && this.#bodySets.setOf(id) !== undefined)
|
|
332
|
+
return this.#bodySets.stateOf(id, toUtcMs(time, `stateOf("${id}") time`), this.#bodySetContext());
|
|
333
|
+
if (entry === undefined && !this.#plan.bodies.has(id))
|
|
377
334
|
throw new SceneError("unknown-body", `stateOf("${id}"): no body or trajectory with that id has been added to the scene`);
|
|
378
335
|
const timeUtcMs = toUtcMs(time, `stateOf("${id}") time`);
|
|
379
336
|
const trajectory = entry?.body.trajectory ?? this.#catalogueSource(id);
|
|
@@ -383,11 +340,11 @@ export class Scene {
|
|
|
383
340
|
if (trajectory === undefined)
|
|
384
341
|
return this.#sunState(id, timeUtcMs);
|
|
385
342
|
try {
|
|
386
|
-
return trajectory.stateAt(timeUtcMs, entry?.center ?? this.#catalogue.get(id).definition.parentId);
|
|
343
|
+
return trajectory.stateAt(timeUtcMs, entry?.center ?? this.#plan.catalogue.get(id).definition.parentId);
|
|
387
344
|
}
|
|
388
345
|
catch (error) {
|
|
389
|
-
if (
|
|
390
|
-
throw new SceneError("missing-data", `stateOf("${id}"):
|
|
346
|
+
if (error instanceof NotLoadedError)
|
|
347
|
+
throw new SceneError("missing-data", `stateOf("${id}"): its data is not loaded yet; await scene.load({ data }) first (or mount the scene and await ready)`);
|
|
391
348
|
throw error;
|
|
392
349
|
}
|
|
393
350
|
}
|
|
@@ -396,13 +353,23 @@ export class Scene {
|
|
|
396
353
|
const entry = this.#tracked.get(id);
|
|
397
354
|
if (entry !== undefined)
|
|
398
355
|
return entry.body.provenance; // addTrajectory always sets one
|
|
399
|
-
if (!this.#bodies.has(id))
|
|
356
|
+
if (!this.#plan.bodies.has(id) && this.#bodySets.setOf(id) !== undefined)
|
|
357
|
+
return this.#bodySets.provenanceOf(id);
|
|
358
|
+
if (!this.#plan.bodies.has(id))
|
|
400
359
|
throw new SceneError("unknown-body", `provenanceOf("${id}"): no body or trajectory with that id has been added to the scene`);
|
|
401
|
-
return this.#
|
|
360
|
+
return this.#plan.provenanceOf(id);
|
|
361
|
+
}
|
|
362
|
+
/** What a body set needs of the finished scene, checked: its bodies, window and opening time. */
|
|
363
|
+
#bodySetContext() {
|
|
364
|
+
if (this.#plan.bodies.size === 0)
|
|
365
|
+
throw new SceneError("empty-scene", "the scene has no bodies; call addBody before reading a body set's members");
|
|
366
|
+
const context = { ids: [...this.#plan.bodies.keys()], catalogue: this.#plan.catalogue, orbits: this.#plan.orbits, ...this.#timelineSpan() };
|
|
367
|
+
this.#bodySets.check(context);
|
|
368
|
+
return context;
|
|
402
369
|
}
|
|
403
370
|
/** A catalogued body's state source, the one the viewer draws from, made once per scene; none for the root (the Sun). */
|
|
404
371
|
#catalogueSource(id) {
|
|
405
|
-
const binding = this.#catalogue.sources().find((source) => source.body === id);
|
|
372
|
+
const binding = this.#plan.catalogue.sources().find((source) => source.body === id);
|
|
406
373
|
if (binding === undefined)
|
|
407
374
|
return undefined;
|
|
408
375
|
const made = this.#sources.get(id) ?? binding.create(createOrbAstronomyAdapter());
|
|
@@ -411,543 +378,30 @@ export class Scene {
|
|
|
411
378
|
}
|
|
412
379
|
/** The root body is at the origin of itself and at rest. */
|
|
413
380
|
#sunState(id, timeUtcMs) {
|
|
414
|
-
return createStateResolver(this.#catalogue.definitions(), this.#catalogue.sources(), createOrbAstronomyAdapter()).stateOf(id, timeUtcMs, id);
|
|
415
|
-
}
|
|
416
|
-
/** The story panels, resolved against this scene's events, anchors, objects and timeline span. */
|
|
417
|
-
#storyPanels(window) {
|
|
418
|
-
if (this.#panels === undefined)
|
|
419
|
-
return undefined;
|
|
420
|
-
const anchors = new Map();
|
|
421
|
-
for (const { body } of this.#tracked.values())
|
|
422
|
-
body.anchorLabels?.forEach((label, index) => { if (!anchors.has(label))
|
|
423
|
-
anchors.set(label, body.anchorTimesUtcMs[index]); });
|
|
424
|
-
return panelsOf(this.#panels, { events: this.#events, anchors, objectIds: [...this.#bodies.keys(), ...this.#tracked.keys(), ...this.#groups.keys()], window });
|
|
425
|
-
}
|
|
426
|
-
/** The `views` entry of the definition: the views resolved against the finished scene once (absent when none was named). */
|
|
427
|
-
#viewsEntry(ids, storyPanels) {
|
|
428
|
-
if (this.#views === undefined)
|
|
429
|
-
return {};
|
|
430
|
-
return { views: resolveViews(this.#views, { paths: [...this.#tracked.keys()], bodies: [...ids, ...this.#groups.keys()], events: this.#events.map(({ id }) => id), panels: storyPanels?.panels.map(({ id }) => id) ?? [] }) };
|
|
431
|
-
}
|
|
432
|
-
/** Checks the groups against the finished scene: each circles its centre (default the scene's first body), which and whose clump body the scene must hold. */
|
|
433
|
-
#checkGroups(ids) {
|
|
434
|
-
for (const plan of this.#groups.values()) {
|
|
435
|
-
const center = plan.input.center ?? ids[0];
|
|
436
|
-
const clump = plan.input.clump;
|
|
437
|
-
if (!ids.includes(center))
|
|
438
|
-
throw new SceneError("bad-group", `addGroup("${plan.id}"): the orbits circle "${center}", which has not been added to the scene`);
|
|
439
|
-
if (clump !== undefined && !ids.includes(clump.near))
|
|
440
|
-
throw new SceneError("bad-group", `addGroup("${plan.id}"): clump.near "${clump.near}" has not been added to the scene`);
|
|
441
|
-
if (clump !== undefined && clump.near === center)
|
|
442
|
-
throw new SceneError("bad-group", `addGroup("${plan.id}"): the clump cannot be near the body the orbits circle ("${center}")`);
|
|
443
|
-
}
|
|
444
|
-
}
|
|
445
|
-
/** The draw layers of the groups chosen by `which` (a clump near a planet reads its position, so needs the planet series). */
|
|
446
|
-
#groupLayers(ids, window, openUtcMs, which) {
|
|
447
|
-
return [...this.#groups.values()].filter(which).map((plan) => buildGroupLayer(plan, this.#catalogue, plan.input.center ?? ids[0], openUtcMs, window));
|
|
448
|
-
}
|
|
449
|
-
/** The Sun-orbit lines that can be drawn now: all of them when the planet series are loaded, else none (they are drawn in `prepare`). */
|
|
450
|
-
#earlySunPaths(orbitIds, openUtcMs) {
|
|
451
|
-
return planetSeriesLoaded() ? orbitIds.map((id) => this.#sunPath(id, openUtcMs)) : [];
|
|
452
|
-
}
|
|
453
|
-
#checkSolarSystemScale(sunCentred) {
|
|
454
|
-
if (this.#scale.id === solarSystemScale.id && !this.#enlargedInSun(sunCentred))
|
|
455
|
-
throw new SceneError("bad-scale", "setScale: the Solar system scale needs a Sun-centred scene with an enlarged body (addBody(x, { enlarge }))");
|
|
456
|
-
}
|
|
457
|
-
/** Whether a Sun-centred scene enlarges a body, which the viewer's solar-system scale draws. */
|
|
458
|
-
#enlargedInSun(sunCentred) {
|
|
459
|
-
return sunCentred && [...this.#shape.values()].some((shape) => shape.enlarge !== undefined);
|
|
460
|
-
}
|
|
461
|
-
/** The activity windows, when any were added. */
|
|
462
|
-
#windowsEntry() {
|
|
463
|
-
return this.#activities.size === 0 ? {} : { windows: [...this.#activities.values()].map((activity) => activity.window) };
|
|
464
|
-
}
|
|
465
|
-
/** The bars of a group's info card at a moment. */
|
|
466
|
-
#groupMetrics(id, timeUtcMs) {
|
|
467
|
-
return (this.#groups.get(id)?.input.readouts ?? []).map((spec) => rateMetricOf(id, this.#activities.get(spec.activity ?? this.#firstActivity()), timeUtcMs));
|
|
468
|
-
}
|
|
469
|
-
#firstActivity() {
|
|
470
|
-
return this.#activities.keys().next().value;
|
|
471
|
-
}
|
|
472
|
-
/** A group's rate readout names an activity the scene holds. */
|
|
473
|
-
#checkGroupReadouts() {
|
|
474
|
-
for (const { id, input } of this.#groups.values()) {
|
|
475
|
-
for (const spec of input.readouts ?? []) {
|
|
476
|
-
const named = spec.activity ?? (this.#activities.size > 0 ? this.#firstActivity() : undefined);
|
|
477
|
-
if (named === undefined || !this.#activities.has(named))
|
|
478
|
-
throw new SceneError("bad-readout", `addGroup("${id}"): readout rate ${named === undefined ? "needs an activity (addActivity)" : `names activity "${named}", which has not been added to the scene`}`);
|
|
479
|
-
}
|
|
480
|
-
}
|
|
481
|
-
}
|
|
482
|
-
/** The `out-of-span` error naming the planets when the scene's window reaches outside the years the planet series cover (the series are loaded); undefined otherwise. */
|
|
483
|
-
#planetSpanError(ids, window) {
|
|
484
|
-
const planets = ids.filter(isPlanetId);
|
|
485
|
-
if (planets.length === 0 || !planetSeriesLoaded())
|
|
486
|
-
return undefined;
|
|
487
|
-
const span = planetSeriesSpan();
|
|
488
|
-
if (window.startUtcMs >= span.startUtcMs && window.endUtcMs <= span.endUtcMs)
|
|
489
|
-
return undefined;
|
|
490
|
-
const iso = (ms) => new Date(ms).toISOString().slice(0, 10);
|
|
491
|
-
return new SceneError("out-of-span", `${planets.join(", ")} is outside the years the built-in planet series covers: it covers ${iso(span.startUtcMs)} to ${iso(span.endUtcMs)}, but the scene runs ${iso(window.startUtcMs)} to ${iso(window.endUtcMs)}; set the timeline inside that span`);
|
|
492
|
-
}
|
|
493
|
-
/** Throws `out-of-span` naming the planets when the scene's window reaches outside the years the planet series cover (the series are loaded). */
|
|
494
|
-
#checkPlanetSpan(ids, window) {
|
|
495
|
-
const error = this.#planetSpanError(ids, window);
|
|
496
|
-
if (error !== undefined)
|
|
497
|
-
throw error;
|
|
381
|
+
return createStateResolver(this.#plan.catalogue.definitions(), this.#plan.catalogue.sources(), createOrbAstronomyAdapter()).stateOf(id, timeUtcMs, id);
|
|
498
382
|
}
|
|
499
383
|
/**
|
|
500
|
-
*
|
|
501
|
-
* `
|
|
502
|
-
|
|
503
|
-
|
|
504
|
-
|
|
505
|
-
|
|
506
|
-
return read();
|
|
507
|
-
}
|
|
508
|
-
catch (error) {
|
|
509
|
-
if (error instanceof TimeScaleOutOfRangeError)
|
|
510
|
-
throw this.#planetSpanError(ids, window) ?? error;
|
|
511
|
-
throw error;
|
|
512
|
-
}
|
|
513
|
-
}
|
|
514
|
-
/**
|
|
515
|
-
* A setup read in `toDefinition`: an `out-of-span` failure is recorded in `fault` and the read gives `fallback`, so `toDefinition` (and so `mount`) never throws it;
|
|
516
|
-
* `prepare` rejects with the recorded error, which is how it always arrives (once, as `ready` rejecting).
|
|
384
|
+
* Loads what `stateOf` and `provenanceOf` need without a viewer: the planet series and, for each moon the scene holds, the chunks its data package provides for the scene's window.
|
|
385
|
+
* Pass the same `data` as `mount`. Rejects with `missing-data` when a body needs a package not passed, with `out-of-span` when the window reaches outside the years covered, and with
|
|
386
|
+
* the scene's own build error as `check` does. Harmless to call twice; allowed on a scene a viewer has taken; a later `mount` re-uses what it loaded. Works in plain Node.
|
|
387
|
+
* @example
|
|
388
|
+
* await scene.load({ data: [jupiterData] });
|
|
389
|
+
* const io = scene.stateOf("io", "2016-03-01T00:00:00Z");
|
|
517
390
|
*/
|
|
518
|
-
|
|
519
|
-
|
|
520
|
-
return this.#planetRead(ids, window, read);
|
|
521
|
-
}
|
|
522
|
-
catch (error) {
|
|
523
|
-
if (error instanceof SceneError && error.code === "out-of-span") {
|
|
524
|
-
fault.error ??= error;
|
|
525
|
-
return fallback;
|
|
526
|
-
}
|
|
527
|
-
throw error;
|
|
528
|
-
}
|
|
529
|
-
}
|
|
530
|
-
/** Throws `missing-data` naming the bodies whose data package was not passed. */
|
|
531
|
-
#checkData(data) {
|
|
532
|
-
const missing = this.missingData(data);
|
|
533
|
-
if (missing.length === 0)
|
|
534
|
-
return;
|
|
535
|
-
const names = [...this.#bodies.values()].filter((body) => body.requires !== undefined && missing.includes(body.requires)).map((body) => body.id);
|
|
536
|
-
throw new SceneError("missing-data", `${names.join(", ")} needs the ${missing.join(", ")} package: install it and pass it as mount(element, scene, { data: [...] })`);
|
|
537
|
-
}
|
|
538
|
-
/** The engine's own orbit loops (the Moon's and Io's) the scene asked for. */
|
|
539
|
-
#moonPaths() {
|
|
540
|
-
return [...this.#orbits].filter((id) => moonOrbitPath(this.#catalogue, id) !== undefined).map((id) => {
|
|
541
|
-
const orbit = moonOrbitPath(this.#catalogue, id);
|
|
542
|
-
const parent = this.#catalogue.get(id).definition.parentId;
|
|
543
|
-
if (parent === undefined || !this.#bodies.has(parent))
|
|
544
|
-
throw new SceneError("no-orbit", `addBody("${id}", { orbit: true }): the orbit is drawn about ${parent}, which has not been added to the scene`);
|
|
545
|
-
return { body: id, ...orbit };
|
|
546
|
-
});
|
|
547
|
-
}
|
|
548
|
-
/** Whether the scene is centred on the Sun. */
|
|
549
|
-
#checkSunCentred(ids) {
|
|
550
|
-
return ids[0] === rootBodyId(this.#catalogue);
|
|
551
|
-
}
|
|
552
|
-
/** How far a label shows, for bodies and paths alike: the item's own `labelReach` if given, else the shared rule: a Sun-centred scene, or one that fits the zoom-out to an orbit (`fitOrbit`, whose limit changes with the canvas), sets no limit; otherwise the camera reach, at least 500. */
|
|
553
|
-
#labelReach(id, sunCentred) {
|
|
554
|
-
const own = this.#labelReaches.get(id);
|
|
555
|
-
if (own !== undefined)
|
|
556
|
-
return { labelMaxDistance: own };
|
|
557
|
-
return sunCentred || this.camera.fitted !== undefined ? {} : { labelMaxDistance: Math.max(500, this.camera.reach ?? 0) };
|
|
558
|
-
}
|
|
559
|
-
/** The shell item of a body: from the catalogue, with the scene's own words, look and label setting. Label reach is `#labelReach`. */
|
|
560
|
-
#bodyObject(body, ids, sunCentred) {
|
|
561
|
-
const own = { labelPriority: 100 - ids.indexOf(body.id), ...this.#labelReach(body.id, sunCentred), ...(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) };
|
|
562
|
-
return { ...catalogueItem(body.id, own, this.#catalogue), label: body.label };
|
|
563
|
-
}
|
|
564
|
-
/** The event provenance entries of the experience: the batch's, and each event's own. */
|
|
565
|
-
#eventProvenanceEntries() {
|
|
566
|
-
return {
|
|
567
|
-
...(this.#eventProvenance === undefined ? {} : { eventProvenance: this.#eventProvenance }),
|
|
568
|
-
...(this.#eventOwnProvenance.size === 0 ? {} : { eventProvenanceById: Object.fromEntries(this.#eventOwnProvenance) }),
|
|
569
|
-
};
|
|
570
|
-
}
|
|
571
|
-
/** The bodies that asked for a Sun-orbit line, checked: the Sun must be in the scene and the line's id free. */
|
|
572
|
-
#sunOrbitIds(ids) {
|
|
573
|
-
return [...this.#orbits].filter((id) => moonOrbitPath(this.#catalogue, id) === undefined).map((id) => {
|
|
574
|
-
if (!ids.includes(rootBodyId(this.#catalogue)))
|
|
575
|
-
throw new SceneError("no-orbit", `addBody("${id}", { orbit: true }): the orbit is drawn about the Sun, which has not been added to the scene`);
|
|
576
|
-
if (this.#taken(sunOrbitIdOf(id)))
|
|
577
|
-
throw new SceneError("duplicate-id", `addBody("${id}", { orbit: true }): the orbit line's id "${sunOrbitIdOf(id)}" is already in the scene`);
|
|
578
|
-
return id;
|
|
579
|
-
});
|
|
391
|
+
async load(options = {}) {
|
|
392
|
+
await definitionOf(this, options.data).prepare?.();
|
|
580
393
|
}
|
|
581
394
|
/**
|
|
582
|
-
*
|
|
583
|
-
*
|
|
395
|
+
* Runs the checks `mount` runs before it draws and throws the same `SceneError` for a build fault (an empty scene, a body whose data package is not in `data`, a bad view or panel, ...).
|
|
396
|
+
* Nothing is loaded and the scene is not frozen. Faults that need the planet or moon data (`out-of-span`) arrive from `load`, as they arrive from `mount`'s `ready`.
|
|
397
|
+
* @example
|
|
398
|
+
* scene.check({ data: [jupiterData] }); // throws what mount(element, scene, { data }) would throw
|
|
584
399
|
*/
|
|
585
|
-
|
|
586
|
-
|
|
587
|
-
return undefined;
|
|
588
|
-
const about = [...this.#tracked.values()].filter((entry) => entry.center === centre);
|
|
589
|
-
if (about.length === 0)
|
|
590
|
-
return undefined;
|
|
591
|
-
return () => 2 * Math.max(...about.map(({ body }) => {
|
|
592
|
-
const { startUtcMs, endUtcMs } = body.trajectory.bounds;
|
|
593
|
-
let farthest = 0;
|
|
594
|
-
for (let k = 0; k < PATH_COVER_SAMPLES; k += 1)
|
|
595
|
-
farthest = Math.max(farthest, Math.hypot(...body.trajectory.stateAt(Math.round(startUtcMs + ((endUtcMs - startUtcMs) * k) / (PATH_COVER_SAMPLES - 1)), centre).positionKm));
|
|
596
|
-
return farthest;
|
|
597
|
-
}));
|
|
598
|
-
}
|
|
599
|
-
/** 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. */
|
|
600
|
-
#fitFarthestKm(openUtcMs) {
|
|
601
|
-
const id = this.camera.fitted;
|
|
602
|
-
if (id === undefined)
|
|
603
|
-
return undefined;
|
|
604
|
-
let km;
|
|
605
|
-
const read = () => (km ??= farthestSunDistanceKm(this.#catalogue, id, openUtcMs, this.#own.get(id)));
|
|
606
|
-
if (planetSeriesLoaded())
|
|
607
|
-
read();
|
|
608
|
-
return { read, settle: () => void read() };
|
|
609
|
-
}
|
|
610
|
-
/** 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. */
|
|
611
|
-
#sunPath(id, openUtcMs) {
|
|
612
|
-
const layer = sunOrbitLayer(this.#catalogue, id, openUtcMs, this.#looks.get(id)?.color ?? "", this.#own.get(id));
|
|
613
|
-
if (layer === undefined)
|
|
614
|
-
throw new SceneError("no-orbit", `addBody("${id}", { orbit: true }): "${id}" completes no turn within thirty years and its position and the Sun's gravity do not give a bound ellipse; add it with addBodyFromElements to draw its whole orbit`);
|
|
615
|
-
return layer;
|
|
616
|
-
}
|
|
617
|
-
/** The stretches of a `lineFixedTo: "auto"` path: the innermost scene body whose sphere of influence holds each sample (`sphereOfInfluence.ts`). Reads body states, so the planet series must be loaded. */
|
|
618
|
-
#autoStretches(entry, ids) {
|
|
619
|
-
const resolver = createStateResolver(this.#catalogue.definitions(), this.#catalogue.sources(), createOrbAstronomyAdapter());
|
|
620
|
-
const norm = (v) => Math.hypot(v[0], v[1], v[2]);
|
|
621
|
-
const candidates = [];
|
|
622
|
-
for (const id of ids) {
|
|
623
|
-
const { parentId, gmKm3S2 } = this.#catalogue.get(id).definition;
|
|
624
|
-
if (parentId === undefined) {
|
|
625
|
-
candidates.push({ id, radiusKm: () => Infinity, probeDistanceKm: () => 0 });
|
|
626
|
-
continue;
|
|
627
|
-
}
|
|
628
|
-
const parentGm = this.#catalogue.get(parentId).definition.gmKm3S2;
|
|
629
|
-
if (!(gmKm3S2 > 0 && parentGm > 0))
|
|
630
|
-
continue; // no published GM: this body cannot hold a probe
|
|
631
|
-
candidates.push({
|
|
632
|
-
id,
|
|
633
|
-
radiusKm: (t) => sphereOfInfluenceKm(gmKm3S2, parentGm, norm(resolver.stateOf(id, t, parentId).positionKm)),
|
|
634
|
-
probeDistanceKm: (t) => {
|
|
635
|
-
const probe = entry.body.trajectory.stateAt(t, entry.center).positionKm;
|
|
636
|
-
const body = resolver.stateOf(id, t, entry.center).positionKm;
|
|
637
|
-
return norm([probe[0] - body[0], probe[1] - body[1], probe[2] - body[2]]);
|
|
638
|
-
},
|
|
639
|
-
});
|
|
640
|
-
}
|
|
641
|
-
return influenceStretches(entry.body.pathTimesUtcMs, candidates);
|
|
642
|
-
}
|
|
643
|
-
/** The `"auto"` paths' one resolution into `tracked`: `now` runs it (through the caller's guarded read) when the planet series are in; else `later` is true and `settle` runs it in `prepare`. */
|
|
644
|
-
#autoPaths(entries, tracked, ids) {
|
|
645
|
-
const pending = entries.some((entry) => entry.auto === true);
|
|
646
|
-
const later = pending && !planetSeriesLoaded();
|
|
647
|
-
const resolve = () => entries.forEach((entry, index) => { if (entry.auto === true)
|
|
648
|
-
tracked[index] = { ...entry.body, lineFixedTo: this.#autoStretches(entry, ids) }; });
|
|
649
|
-
return { later, now: (guard) => { if (pending && !later)
|
|
650
|
-
guard(resolve); }, settle: (guard) => { if (later)
|
|
651
|
-
guard(resolve); } };
|
|
652
|
-
}
|
|
653
|
-
/** A readout, or the body the line is fixed to, names a body the scene must hold. */
|
|
654
|
-
#checkReadouts(entry, ids) {
|
|
655
|
-
for (const { index, body } of lineBodies(entry.body.lineFixedTo)) {
|
|
656
|
-
if (!ids.includes(body))
|
|
657
|
-
throw new SceneError("bad-trajectory", `addTrajectory("${entry.body.id}"): lineFixedTo${index === null ? "" : `[${index}]`} names "${body}", which has not been added to the scene`);
|
|
658
|
-
}
|
|
659
|
-
for (const spec of entry.readouts) {
|
|
660
|
-
const named = readoutBody(spec);
|
|
661
|
-
if (named !== undefined && !ids.includes(named))
|
|
662
|
-
throw new SceneError("bad-readout", `addTrajectory("${entry.body.id}"): readout ${spec.kind} names "${named}", which has not been added to the scene`);
|
|
663
|
-
}
|
|
664
|
-
}
|
|
665
|
-
/** The data packages the added bodies need that `data` does not provide. */
|
|
666
|
-
missingData(data = []) {
|
|
667
|
-
const have = new Set(data.flatMap((source) => source.provides));
|
|
668
|
-
const named = new Set(data.map((source) => source.name));
|
|
669
|
-
return [...new Set([...this.#bodies.values()].filter((body) => body.requires !== undefined && !have.has(body.id) && !named.has(body.requires)).map((body) => body.requires))];
|
|
670
|
-
}
|
|
671
|
-
/** The app's plug-in contract for this scene. Throws if the scene is empty or a body needs a data package not passed in `data`. */
|
|
672
|
-
toDefinition(data = []) {
|
|
673
|
-
if (this.#bodies.size === 0)
|
|
674
|
-
throw new SceneError("empty-scene", "the scene has no bodies; call addBody before mount");
|
|
675
|
-
this.#checkData(data);
|
|
676
|
-
this.#checkGroupReadouts();
|
|
677
|
-
const ids = [...this.#bodies.keys()];
|
|
678
|
-
const paths = this.#moonPaths();
|
|
679
|
-
const sunCentred = this.#checkSunCentred(ids);
|
|
680
|
-
this.#checkSolarSystemScale(sunCentred);
|
|
681
|
-
for (const entry of this.#tracked.values())
|
|
682
|
-
this.#checkReadouts(entry, ids);
|
|
683
|
-
const entries = [...this.#tracked.values()];
|
|
684
|
-
const tracked = entries.map((entry) => entry.body);
|
|
685
|
-
const timeline = this.#timeline;
|
|
686
|
-
const { window, startUtcMs } = spanOf(timeline, this.#timeUtcMs, [...tracked.map((body) => body.trajectory.bounds), ...[...this.#activities.values()].map((activity) => activity.window)]);
|
|
687
|
-
const sunOrbitIds = this.#sunOrbitIds(ids);
|
|
688
|
-
// The farthest distance is worked out in setup, once: now when the planet series are in, else in `prepare` once they are; never in the frame loop.
|
|
689
|
-
const fault = {};
|
|
690
|
-
// `lineFixedTo: "auto"` paths read body states: now when the planet series are in, else in `prepare` once they are (the viewer draws only after it resolves); never per frame.
|
|
691
|
-
const auto = this.#autoPaths(entries, tracked, ids);
|
|
692
|
-
auto.now((read) => this.#deferredRead(ids, window, fault, undefined, read));
|
|
693
|
-
const fit = this.#deferredRead(ids, window, fault, undefined, () => this.#fitFarthestKm(startUtcMs));
|
|
694
|
-
// The lines read planet positions; when the planet series are not loaded yet (a consumer's mount), they are drawn in `prepare`, once the series are in. The viewer draws only after `prepare` resolves.
|
|
695
|
-
const sunPaths = this.#deferredRead(ids, window, fault, [], () => this.#earlySunPaths(sunOrbitIds, startUtcMs));
|
|
696
|
-
const target = this.camera.target;
|
|
697
|
-
const view = this.camera.view;
|
|
698
|
-
const storyPanels = this.#storyPanels(window);
|
|
699
|
-
this.#checkGroups(ids);
|
|
700
|
-
// A clump near a body reads its position; with the planet series not loaded yet, those groups are built in `prepare` (the viewer draws only after it resolves).
|
|
701
|
-
const seriesIn = planetSeriesLoaded();
|
|
702
|
-
const late = (plan) => !seriesIn && plan.input.clump !== undefined;
|
|
703
|
-
const layers = this.#deferredRead(ids, window, fault, [], () => [...this.#groupLayers(ids, window, startUtcMs, (plan) => !late(plan))]);
|
|
704
|
-
const labelled = [...this.#bodies.values(), ...tracked, ...[...this.#groups.values()]].map(({ id, label }) => ({ id, label }));
|
|
705
|
-
const catalogue = this.#catalogue;
|
|
706
|
-
checkEventObjects(this.#events, new Set(labelled.map(({ id }) => id)));
|
|
707
|
-
const definition = {
|
|
708
|
-
experience: {
|
|
709
|
-
objects: [
|
|
710
|
-
...[...this.#bodies.values()].map((body) => this.#bodyObject(body, ids, sunCentred)),
|
|
711
|
-
...[...this.#tracked.values()].map(({ body, description, knownLimitations, provenanceSpans }) => ({ id: body.id, label: body.label, color: body.color, availability: body.trajectory.bounds, labelPriority: 80, ...this.#labelReach(body.id, sunCentred), provenance: body.provenance, ...(provenanceSpans === undefined ? {} : { provenanceSpans }), ...(description === undefined ? {} : { description }), ...(knownLimitations === undefined ? {} : { knownLimitations }) })),
|
|
712
|
-
],
|
|
713
|
-
cameraPresets: cameraPresetsOf(labelled),
|
|
714
|
-
...(target === undefined ? {} : { startCameraPresetId: `${this.camera.following ? "follow" : "focus"}-${target}` }),
|
|
715
|
-
events: this.#events,
|
|
716
|
-
...this.#eventProvenanceEntries(),
|
|
717
|
-
...(storyPanels === undefined ? {} : { storyPanels }),
|
|
718
|
-
...(timeline?.none === true ? { hideTimeline: true } : {}),
|
|
719
|
-
window,
|
|
720
|
-
...this.#windowsEntry(),
|
|
721
|
-
rates: timeline?.rates ?? [60, 3_600, DAY_MS / 1000],
|
|
722
|
-
},
|
|
723
|
-
clock: clockOf(timeline, startUtcMs),
|
|
724
|
-
...pacingEntry(timeline, this.#events),
|
|
725
|
-
...groupLayersEntry(layers, this.#groups.size > 0, sunOrbitIds.length > 0),
|
|
726
|
-
...(sunOrbitIds.length === 0 ? {} : { paths: sunPaths }),
|
|
727
|
-
...(this.#catalogue === builtInCatalogue ? {} : { catalogue: this.#catalogue }),
|
|
728
|
-
...visualOverridesEntry(this.#shape),
|
|
729
|
-
composition: createComposition(this.#catalogue, { id: "scene", bodies: ids, defaultCenter: ids[0], ...(paths.length === 0 ? {} : { paths }) }),
|
|
730
|
-
scaleChoices: scaleChoicesOf(this.#scale, this.#scaleOnly, this.#enlargedInSun(sunCentred)),
|
|
731
|
-
...(this.#switches === undefined ? {} : { displaySwitches: this.#switches }),
|
|
732
|
-
...this.#viewsEntry(ids, storyPanels),
|
|
733
|
-
...viewEntries(timeline, this.camera, fit?.read, this.#pathCover(sunCentred, ids[0])),
|
|
734
|
-
...(target === undefined ? {} : { startView: { focus: target, azimuthDeg: view.azimuthDeg ?? 0, elevationDeg: view.elevationDeg ?? 30, distance: view.distance ?? 40 } }),
|
|
735
|
-
trackedBodies: tracked,
|
|
736
|
-
createMetrics: ({ resolver }) => {
|
|
737
|
-
const catalogued = bodyMetrics(resolver, ids, ["distance"], catalogue);
|
|
738
|
-
const readouts = createReadoutMetrics([...this.#tracked.values()].map(({ body, readouts: specs }) => ({ body, readouts: specs })), resolver);
|
|
739
|
-
return (objectId, timeUtcMs) => (this.#groups.has(objectId) ? this.#groupMetrics(objectId, timeUtcMs) : this.#tracked.has(objectId) ? readouts(objectId, timeUtcMs) : catalogued(objectId, timeUtcMs));
|
|
740
|
-
},
|
|
741
|
-
prepare: async () => {
|
|
742
|
-
if (fault.error !== undefined)
|
|
743
|
-
throw fault.error;
|
|
744
|
-
if (needsPlanetSeries(definition) || auto.later || sunPaths.length < sunOrbitIds.length || this.#groups.size > layers.length)
|
|
745
|
-
await loadPlanetSeries();
|
|
746
|
-
this.#checkPlanetSpan(ids, window);
|
|
747
|
-
auto.settle((read) => this.#planetRead(ids, window, read));
|
|
748
|
-
if (this.#groups.size > layers.length)
|
|
749
|
-
layers.push(...this.#planetRead(ids, window, () => this.#groupLayers(ids, window, startUtcMs, late)));
|
|
750
|
-
if (sunPaths.length < sunOrbitIds.length)
|
|
751
|
-
sunPaths.push(...this.#planetRead(ids, window, () => sunOrbitIds.map((id) => this.#sunPath(id, startUtcMs))));
|
|
752
|
-
if (fit !== undefined)
|
|
753
|
-
this.#planetRead(ids, window, () => fit.settle());
|
|
754
|
-
await installData(data, ids, window, catalogue);
|
|
755
|
-
},
|
|
756
|
-
};
|
|
757
|
-
return definition;
|
|
758
|
-
}
|
|
759
|
-
}
|
|
760
|
-
/** The playback and camera settings the scene asked for: looping, the farthest zoom-out and the ecliptic up. */
|
|
761
|
-
function viewEntries(timeline, camera, farthestKm, cover) {
|
|
762
|
-
const { reach, view, target } = camera;
|
|
763
|
-
return {
|
|
764
|
-
...(timeline?.loop === true ? { loop: true } : {}),
|
|
765
|
-
...(reach === undefined ? {} : { camera: { maxFocusDistance: reach, far: reach * 2.5 } }),
|
|
766
|
-
...(farthestKm === undefined ? {} : { camera: { fitOrbit: { farthestKm } } }),
|
|
767
|
-
...(reach !== undefined || farthestKm !== undefined || cover === undefined ? {} : { camera: { cover: { farthestKm: cover } } }),
|
|
768
|
-
...(view.up === undefined || target === undefined ? {} : { viewUp: view.up }),
|
|
769
|
-
};
|
|
770
|
-
}
|
|
771
|
-
/** The scene's layers: the points layer and the groups only when a group was added. */
|
|
772
|
-
function groupLayersEntry(layers, hasGroups, sunCentred) {
|
|
773
|
-
const sceneLayers = ["tracked-bodies", ...(hasGroups ? ["points"] : []), ...(sunCentred ? ["sun-centred"] : [])];
|
|
774
|
-
return hasGroups ? { sceneLayers, groups: layers } : { sceneLayers };
|
|
775
|
-
}
|
|
776
|
-
/** The enlargements the scene asked for, as the engine's per-body overrides. */
|
|
777
|
-
function visualOverridesEntry(shape) {
|
|
778
|
-
const overrides = {};
|
|
779
|
-
for (const [id, { enlarge }] of shape)
|
|
780
|
-
if (enlarge !== undefined)
|
|
781
|
-
overrides[id] = { exaggeration: enlarge };
|
|
782
|
-
return Object.keys(overrides).length === 0 ? {} : { visualOverrides: overrides };
|
|
783
|
-
}
|
|
784
|
-
/** Parses an elements record, naming the field a mistake is in. */
|
|
785
|
-
function parseRecord(record) {
|
|
786
|
-
try {
|
|
787
|
-
return parseElementsBodyRecord(record, "addBodyFromElements");
|
|
788
|
-
}
|
|
789
|
-
catch (error) {
|
|
790
|
-
if (error instanceof ElementsBodyError)
|
|
791
|
-
throw new SceneError("bad-element", error.message);
|
|
792
|
-
throw error;
|
|
793
|
-
}
|
|
794
|
-
}
|
|
795
|
-
/** The camera menu is automatic: Overview, and Focus and Follow for every body and path. */
|
|
796
|
-
function cameraPresetsOf(objects) {
|
|
797
|
-
return [
|
|
798
|
-
{ id: "overview", label: "Overview", request: { kind: "overview" } },
|
|
799
|
-
...objects.flatMap(({ id, label }) => [
|
|
800
|
-
{ id: `focus-${id}`, label: `Focus ${label}`, request: { kind: "focus", target: id } },
|
|
801
|
-
{ id: `follow-${id}`, label: `Follow ${label}`, request: { kind: "follow", target: id } },
|
|
802
|
-
]),
|
|
803
|
-
];
|
|
804
|
-
}
|
|
805
|
-
/** The timeline span and the moment the clock opens at; a moment outside a span the caller set is a `bad-timeline`. */
|
|
806
|
-
function spanOf(timeline, timeUtcMs, tracked) {
|
|
807
|
-
const setTime = (timeline?.none === true ? timeline.atUtcMs : undefined) ?? timeUtcMs;
|
|
808
|
-
// 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).
|
|
809
|
-
const now = setTime === undefined && timeline?.window === undefined && tracked.length === 0 ? Date.now() : undefined;
|
|
810
|
-
const window = timeline?.window ?? windowOf(tracked, setTime ?? now);
|
|
811
|
-
if (timeline?.window !== undefined && setTime !== undefined && (setTime < window.startUtcMs || setTime > window.endUtcMs)) {
|
|
812
|
-
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()})`);
|
|
813
|
-
}
|
|
814
|
-
return { window, startUtcMs: setTime ?? now ?? window.startUtcMs };
|
|
815
|
-
}
|
|
816
|
-
/** The pacing the timeline asked for, laid over the scene's events; a rule naming an event type with no events throws `bad-timeline`. */
|
|
817
|
-
function pacingEntry(timeline, events) {
|
|
818
|
-
const pacing = timeline === undefined ? undefined : pacingFor(timeline, events, timeline.rate ?? 60);
|
|
819
|
-
return pacing === undefined ? {} : { pacing };
|
|
820
|
-
}
|
|
821
|
-
/** The clock's opening: 60 times real time unless set; with no timeline and no rate, frozen. */
|
|
822
|
-
function clockOf(timeline, startUtcMs) {
|
|
823
|
-
return { startUtcMs, rate: timeline?.rate ?? 60, ...(timeline?.none === true && timeline.rate === undefined ? { playing: false } : {}) };
|
|
824
|
-
}
|
|
825
|
-
/**
|
|
826
|
-
* The scale choices offered: the opening one first, then the other unless the caller offered one alone. A Sun-centred scene with an enlarged body (`addBody(x, { enlarge })`)
|
|
827
|
-
* offers `solarSystemScale` (true distances, the named bodies enlarged) in place of the readable scale it would offer second, since the readable scale does not enlarge.
|
|
828
|
-
*/
|
|
829
|
-
function scaleChoicesOf(scale, only, enlarged) {
|
|
830
|
-
const offered = [trueScale, enlarged ? solarSystemScale : readableScale];
|
|
831
|
-
const second = scale.id === readableScale.id ? [trueScale] : offered.filter((other) => other.id !== scale.id);
|
|
832
|
-
return only ? [scale.id] : [scale.id, ...second.map((other) => other.id)];
|
|
833
|
-
}
|
|
834
|
-
/** Rotates a vector by a row-major 3x3 matrix; a missing matrix leaves it as it is. Input that is not three numbers passes through for the State checks to refuse. */
|
|
835
|
-
function rotated(matrix, v) {
|
|
836
|
-
if (matrix === null || v === undefined || v.length !== 3)
|
|
837
|
-
return v;
|
|
838
|
-
return [0, 1, 2].map((row) => matrix[3 * row] * v[0] + matrix[3 * row + 1] * v[1] + matrix[3 * row + 2] * v[2]);
|
|
839
|
-
}
|
|
840
|
-
function sampledBody(common, input, center, toEqj) {
|
|
841
|
-
const samples = input.samples.map((sample, index) => {
|
|
842
|
-
const velocityKmS = rotated(toEqj, sample.velocityKmS);
|
|
843
|
-
return { positionKm: rotated(toEqj, sample.positionKm), ...(velocityKmS === undefined ? {} : { velocityKmS }), timeUtcMs: toUtcMs(sample.time, `addTrajectory("${common.id}") sample ${index} time`) };
|
|
844
|
-
});
|
|
845
|
-
try {
|
|
846
|
-
const trajectory = new SampledTrajectory({ body: common.id, center, samples });
|
|
847
|
-
return { ...common, trajectory, pathTimesUtcMs: samples.map((sample) => sample.timeUtcMs) };
|
|
848
|
-
}
|
|
849
|
-
catch (error) {
|
|
850
|
-
if (error instanceof SceneError)
|
|
851
|
-
throw error;
|
|
852
|
-
throw new SceneError("bad-trajectory", `addTrajectory("${common.id}"): ${error instanceof Error ? error.message : String(error)}`);
|
|
853
|
-
}
|
|
854
|
-
}
|
|
855
|
-
/** `lineFixedTo` is a body id, `"auto"` or a list; anything else is `bad-trajectory` (the list's own faults are named by `planLineStretches`). */
|
|
856
|
-
function checkLineFixedToType(id, value) {
|
|
857
|
-
if (value !== undefined && typeof value !== "string" && typeof value !== "object")
|
|
858
|
-
throw new SceneError("bad-trajectory", `addTrajectory("${id}"): lineFixedTo ${String(value)} must be a body id, "auto" or a list of stretches`);
|
|
859
|
-
}
|
|
860
|
-
function providerBody(common, input, toEqj) {
|
|
861
|
-
if (typeof input.provider?.stateAt !== "function")
|
|
862
|
-
throw new SceneError("bad-trajectory", `addTrajectory("${common.id}"): provider needs a stateAt(time) function`);
|
|
863
|
-
const bounds = { startUtcMs: toUtcMs(input.bounds?.start, `addTrajectory("${common.id}") bounds.start`), endUtcMs: toUtcMs(input.bounds?.end, `addTrajectory("${common.id}") bounds.end`) };
|
|
864
|
-
if (bounds.endUtcMs <= bounds.startUtcMs)
|
|
865
|
-
throw new SceneError("bad-trajectory", `addTrajectory("${common.id}"): bounds must end after they start`);
|
|
866
|
-
const trajectory = { body: common.id, bounds, stateAt: (timeUtcMs, center) => rotatedState(toEqj, input.provider.stateAt(timeUtcMs, center)) };
|
|
867
|
-
// Whole milliseconds, because the state resolver refuses a fractional time (the line is placed against another body at these times).
|
|
868
|
-
const step = (bounds.endUtcMs - bounds.startUtcMs) / (PROVIDER_PATH_SAMPLES - 1);
|
|
869
|
-
return { ...common, trajectory, pathTimesUtcMs: Array.from({ length: PROVIDER_PATH_SAMPLES }, (_, index) => Math.round(bounds.startUtcMs + index * step)) };
|
|
870
|
-
}
|
|
871
|
-
/** A provider's State with its position and velocity rotated into EQJ; unchanged for EQJ input. */
|
|
872
|
-
function rotatedState(matrix, state) {
|
|
873
|
-
if (matrix === null)
|
|
874
|
-
return state;
|
|
875
|
-
return createState({ body: state.body, center: state.center, timeUtcMs: state.timeUtcMs, positionKm: rotated(matrix, state.positionKm), ...(state.velocityKmS === undefined ? {} : { velocityKmS: rotated(matrix, state.velocityKmS) }), orientation: state.orientation });
|
|
876
|
-
}
|
|
877
|
-
/** The timeline span: the union of the trajectories' and activities' spans, else a month about the chosen time (or about now). */
|
|
878
|
-
function windowOf(tracked, timeUtcMs) {
|
|
879
|
-
if (tracked.length > 0) {
|
|
880
|
-
const start = Math.min(...tracked.map((bounds) => bounds.startUtcMs));
|
|
881
|
-
const end = Math.max(...tracked.map((bounds) => bounds.endUtcMs));
|
|
882
|
-
if (timeUtcMs === undefined || (timeUtcMs >= start && timeUtcMs <= end))
|
|
883
|
-
return { startUtcMs: start, endUtcMs: end };
|
|
884
|
-
}
|
|
885
|
-
const centre = timeUtcMs ?? Date.now();
|
|
886
|
-
return { startUtcMs: centre - 15 * DAY_MS, endUtcMs: centre + 15 * DAY_MS };
|
|
887
|
-
}
|
|
888
|
-
/** Throws `error` unless `reach` is a positive finite number. */
|
|
889
|
-
function checkLabelReach(reach, error) {
|
|
890
|
-
if (!(typeof reach === "number" && Number.isFinite(reach) && reach > 0))
|
|
891
|
-
throw error;
|
|
892
|
-
}
|
|
893
|
-
/** Checks the colour, known limits and label reach given to `addBody`. */
|
|
894
|
-
function checkBodyLook(id, options) {
|
|
895
|
-
if (options.labelReach !== undefined)
|
|
896
|
-
checkLabelReach(options.labelReach, new SceneError("bad-body", `addBody("${id}"): labelReach ${String(options.labelReach)} must be a positive finite number`));
|
|
897
|
-
if (options.enlarge !== undefined && !(typeof options.enlarge === "number" && Number.isFinite(options.enlarge) && options.enlarge >= 1))
|
|
898
|
-
throw new SceneError("bad-body", `addBody("${id}"): enlarge ${String(options.enlarge)} must be a number of at least 1`);
|
|
899
|
-
if (options.showLabel !== undefined && typeof options.showLabel !== "boolean")
|
|
900
|
-
throw new SceneError("bad-body", `addBody("${id}"): showLabel must be true or false`);
|
|
901
|
-
if (options.color !== undefined && !(typeof options.color === "string" && /^#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$/.test(options.color)))
|
|
902
|
-
throw new SceneError("bad-body", `addBody("${id}"): color "${String(options.color)}" is not a hex colour such as "#9fd8ff"`);
|
|
903
|
-
const limits = options.knownLimitations;
|
|
904
|
-
if (limits !== undefined && !(Array.isArray(limits) && limits.every((line) => typeof line === "string" && line !== "")))
|
|
905
|
-
throw new SceneError("bad-body", `addBody("${id}"): knownLimitations must be a list of non-empty texts`);
|
|
906
|
-
}
|
|
907
|
-
const READOUT_KINDS = ["range", "speed", "distance", "altitude"];
|
|
908
|
-
/** The body a readout names, if any. */
|
|
909
|
-
function readoutBody(spec) {
|
|
910
|
-
return spec.kind === "range" ? spec.marker : spec.kind === "distance" ? spec.to : spec.kind === "altitude" ? spec.above : undefined;
|
|
911
|
-
}
|
|
912
|
-
/** Checks each readout's kind and the catalogued body it names; whether the scene holds that body is checked when the definition is built. */
|
|
913
|
-
function readoutsOf(id, readouts = []) {
|
|
914
|
-
if (!Array.isArray(readouts))
|
|
915
|
-
throw new SceneError("bad-readout", `addTrajectory("${id}"): readouts must be a list`);
|
|
916
|
-
for (const spec of readouts) {
|
|
917
|
-
if (!READOUT_KINDS.includes(spec?.kind))
|
|
918
|
-
throw new SceneError("bad-readout", `addTrajectory("${id}"): readout kind "${String(spec?.kind)}" is not one of ${READOUT_KINDS.join(", ")}`);
|
|
919
|
-
const named = readoutBody(spec);
|
|
920
|
-
if (spec.kind !== "range" && spec.kind !== "speed" && named === undefined)
|
|
921
|
-
throw new SceneError("bad-readout", `addTrajectory("${id}"): readout ${spec.kind} needs ${spec.kind === "distance" ? "`to`" : "`above`"}, the body to measure against`);
|
|
922
|
-
if (named !== undefined && !builtInCatalogue.has(named))
|
|
923
|
-
throw new SceneError("bad-readout", `addTrajectory("${id}"): readout ${spec.kind} names "${named}", which is not a catalogued body`);
|
|
924
|
-
}
|
|
925
|
-
return readouts;
|
|
926
|
-
}
|
|
927
|
-
/** The body with its anchors: sorted by time, each labelled with its id. Every anchor needs a distinct id and a moment inside the path. */
|
|
928
|
-
function withAnchors(body, anchors = []) {
|
|
929
|
-
if (!Array.isArray(anchors))
|
|
930
|
-
throw new SceneError("bad-anchor", `addTrajectory("${body.id}"): anchors must be a list`);
|
|
931
|
-
const { startUtcMs, endUtcMs } = body.trajectory.bounds;
|
|
932
|
-
const seen = new Set();
|
|
933
|
-
const placed = anchors.map((anchor) => {
|
|
934
|
-
if (typeof anchor?.id !== "string" || anchor.id === "")
|
|
935
|
-
throw new SceneError("bad-anchor", `addTrajectory("${body.id}"): every anchor needs a non-empty id`);
|
|
936
|
-
if (seen.has(anchor.id))
|
|
937
|
-
throw new SceneError("bad-anchor", `addTrajectory("${body.id}"): anchor "${anchor.id}" appears twice`);
|
|
938
|
-
seen.add(anchor.id);
|
|
939
|
-
const timeUtcMs = anchorTime(body.id, anchor);
|
|
940
|
-
if (timeUtcMs < startUtcMs || timeUtcMs > endUtcMs)
|
|
941
|
-
throw new SceneError("bad-anchor", `addTrajectory("${body.id}"): anchor "${anchor.id}" is outside the path (${new Date(startUtcMs).toISOString()} to ${new Date(endUtcMs).toISOString()})`);
|
|
942
|
-
return { id: anchor.id, timeUtcMs };
|
|
943
|
-
}).sort((a, b) => a.timeUtcMs - b.timeUtcMs);
|
|
944
|
-
return placed.length === 0 ? body : { ...body, anchorTimesUtcMs: placed.map((anchor) => anchor.timeUtcMs), anchorLabels: placed.map((anchor) => anchor.id) };
|
|
945
|
-
}
|
|
946
|
-
function anchorTime(path, anchor) {
|
|
947
|
-
try {
|
|
948
|
-
return toUtcMs(anchor.time);
|
|
400
|
+
check(options = {}) {
|
|
401
|
+
definitionOf(this, options.data);
|
|
949
402
|
}
|
|
950
|
-
|
|
951
|
-
|
|
403
|
+
/** The app's plug-in contract for this scene (`assembleScene.ts`), reached through `definitionOf`. Throws if the scene is empty or a body needs a data package not passed in `data`. */
|
|
404
|
+
#definition(data) {
|
|
405
|
+
return assembleScene({ plan: this.#plan, tracked: this.#tracked, groupPlan: this.#groupPlan, bodySets: this.#bodySets, moonPanel: this.#moonPanel, picker: this.#picker, places: this.#places, story: this.#story, timeline: this.#timeline, viewPlan: this.#viewPlan, camera: this.camera, scale: this.#scale, scaleOnly: this.#scaleOnly, look: this.#look, bodyReadouts: this.#bodyReadouts }, data);
|
|
952
406
|
}
|
|
953
407
|
}
|