astraeus 0.1.1 → 0.3.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +51 -0
- package/README.md +76 -7
- package/package.json +10 -6
- package/src/api/AstraeusScene.d.ts +27 -0
- package/src/api/AstraeusScene.js +38 -0
- package/src/api/AstraeusScene.node.js +37 -0
- package/src/api/activity.d.ts +50 -0
- package/src/api/activity.js +62 -0
- package/src/api/bodies.d.ts +24 -0
- package/src/api/bodies.js +24 -0
- package/src/api/errors.d.ts +1 -1
- package/src/api/group.d.ts +89 -0
- package/src/api/group.js +121 -0
- package/src/api/index.d.ts +6 -1
- package/src/api/index.js +3 -1
- package/src/api/index.node.js +8 -0
- package/src/api/mount.d.ts +10 -1
- package/src/api/mount.js +15 -4
- package/src/api/mount.node.js +36 -0
- package/src/api/prepared.d.ts +10 -0
- package/src/api/prepared.js +5 -0
- package/src/api/scene.d.ts +148 -9
- package/src/api/scene.js +563 -59
- package/src/api/story.d.ts +69 -0
- package/src/api/story.js +63 -0
- package/src/api/sunOrbit.d.ts +20 -0
- package/src/api/sunOrbit.js +85 -0
- package/src/api/switches.d.ts +14 -0
- package/src/api/switches.js +19 -0
- package/src/api/time.d.ts +4 -0
- package/src/api/time.js +8 -0
- package/src/app/App.d.ts +6 -2
- package/src/app/App.js +43 -21
- package/src/app/App.node.js +401 -0
- package/src/app/AstraeusScene.d.ts +1 -1
- package/src/app/DebugOverlay.d.ts +3 -52
- package/src/app/DebugOverlay.js +2 -29
- package/src/app/PanelLoadBoundary.d.ts +19 -0
- package/src/app/PanelLoadBoundary.js +17 -0
- package/src/app/SkyView.d.ts +3 -3
- package/src/app/SkyView.js +19 -10
- package/src/app/debugReadout.d.ts +53 -0
- package/src/app/debugReadout.js +30 -0
- package/src/app/developerPanels.d.ts +6 -0
- package/src/app/developerPanels.js +11 -0
- package/src/app/displaySwitches.d.ts +54 -0
- package/src/app/displaySwitches.js +48 -0
- package/src/app/experienceDefinition.d.ts +13 -1
- package/src/app/listSwitch.d.ts +16 -0
- package/src/{experiences/showers/showerChoice.js → app/listSwitch.js} +1 -9
- package/src/app/metricReadouts.d.ts +1 -1
- package/src/app/metricReadouts.js +1 -1
- package/src/app/openClock.d.ts +7 -0
- package/src/app/openClock.js +14 -0
- package/src/app/sceneContentsHooks.d.ts +3 -3
- package/src/app/sceneContentsHooks.js +2 -2
- package/src/app/sceneDebug.d.ts +1 -1
- package/src/app/sceneDebug.js +1 -1
- package/src/app/sceneFrame.js +4 -3
- package/src/app/sceneFraming.d.ts +13 -0
- package/src/app/sceneFraming.js +22 -0
- package/src/app/skyModel.js +3 -1
- package/src/app/trackedMetrics.d.ts +53 -0
- package/src/{experiences/apollo11/spacecraftMetrics.js → app/trackedMetrics.js} +40 -56
- package/src/assets/licence.d.ts +1 -0
- package/src/assets/pictures.d.ts +1 -1
- package/src/assets/sky.d.ts +4 -4
- package/src/assets/sky.js +12 -13
- package/src/core/bodies/index.d.ts +3 -0
- package/src/core/bodies/index.js +3 -1
- package/src/core/bodies/io.js +1 -1
- package/src/core/bodies/jupiterData.js +2 -2
- package/src/core/bodies/jupiterMoons.js +8 -12
- package/src/core/bodies/moon.d.ts +8 -0
- package/src/core/bodies/moon.js +28 -5
- package/src/core/bodies/outerPlanetData.js +7 -7
- package/src/core/bodies/planetMoons.js +18 -27
- package/src/core/bodies/swiftTuttle.js +2 -0
- package/src/core/elementsBody.d.ts +2 -0
- package/src/core/elementsBody.js +3 -0
- package/src/core/moonTrajectory.js +3 -5
- package/src/core/planetModels.js +1 -1
- package/src/core/planetSeries.d.ts +2 -0
- package/src/core/planetSeries.js +4 -0
- package/src/core/provenance.d.ts +7 -2
- package/src/core/provenance.js +3 -1
- package/src/core/scalePolicy.d.ts +3 -0
- package/src/core/scalePolicy.js +2 -0
- package/src/core/state.d.ts +1 -0
- package/src/shell/AstraeusShell.d.ts +4 -1
- package/src/shell/AstraeusShell.js +12 -6
- package/src/shell/AstraeusShell.node.js +225 -0
- package/src/shell/DisplaySwitches.d.ts +16 -0
- package/src/shell/DisplaySwitches.js +31 -0
- package/src/shell/StoryPanelView.js +3 -1
- package/src/shell/TimelineBar.css +4 -0
- package/src/shell/TimelineBar.node.js +75 -0
- package/src/shell/TopBar.css +20 -0
- package/src/shell/TopBar.d.ts +4 -1
- package/src/shell/TopBar.js +3 -2
- package/src/shell/TopBar.node.js +14 -0
- package/src/shell/experience.d.ts +4 -0
- package/src/shell/infoModel.js +3 -1
- package/src/shell/phone.css +4 -1
- package/src/shell/topBarIcons.d.ts +1 -0
- package/src/shell/topBarIcons.js +1 -0
- package/src/shell/useDrawers.js +1 -1
- package/src/shell/useZoomThrough.d.ts +7 -0
- package/src/shell/useZoomThrough.js +51 -0
- package/src/synthetic/syntheticDefinition.js +3 -3
- package/src/experiences/apollo11/spacecraftMetrics.d.ts +0 -34
- package/src/experiences/showers/showerChoice.d.ts +0 -25
|
@@ -0,0 +1,89 @@
|
|
|
1
|
+
import type { BodyId } from "../core/body.js";
|
|
2
|
+
import { type Provenance } from "../core/provenance.js";
|
|
3
|
+
import type { TimeBounds } from "../core/trajectory.js";
|
|
4
|
+
import { type BodyCatalogue } from "../assets/catalogue.js";
|
|
5
|
+
import type { GroupLayer } from "../app/experienceDefinition.js";
|
|
6
|
+
import { type TimeInput } from "./time.js";
|
|
7
|
+
/** One listed orbit of a group: its own id (the record it came from) and its shape and orientation. Angles in degrees, length in km. The orbit carries no position along itself; the group chooses that. */
|
|
8
|
+
export interface GroupOrbitInput {
|
|
9
|
+
/** The orbit's own id, such as the record it was listed under; distinct within the group. */
|
|
10
|
+
readonly id: string;
|
|
11
|
+
readonly semiMajorAxisKm: number;
|
|
12
|
+
/** At least 0 and below 1: a bound orbit. */
|
|
13
|
+
readonly eccentricity: number;
|
|
14
|
+
readonly inclinationDeg: number;
|
|
15
|
+
readonly raanDeg: number;
|
|
16
|
+
readonly argumentOfPeriapsisDeg: number;
|
|
17
|
+
/** The moment the record was measured, kept with the record; it does not place the dot. Defaults to the group's reference time. */
|
|
18
|
+
readonly time?: TimeInput;
|
|
19
|
+
}
|
|
20
|
+
/** A stated share of the dots drawn near a body's position along its orbit: a model, not a measurement. */
|
|
21
|
+
export interface GroupClumpInput {
|
|
22
|
+
/** A body in the scene to clump near: a catalogued body or one added with `addBodyFromElements` (add it before the group). Only where it is along its orbit about the group's centre at the reference time is used. */
|
|
23
|
+
readonly near: BodyId;
|
|
24
|
+
/** Share of the dots, 0 to 1. */
|
|
25
|
+
readonly fraction: number;
|
|
26
|
+
/** Half-width of the clump in degrees along the orbit, above 0 and at most 180. */
|
|
27
|
+
readonly widthDeg: number;
|
|
28
|
+
}
|
|
29
|
+
/** A bar on a group's info card: `rate` is the live rate of an activity (`addActivity`; the scene's first when `activity` is absent) against its peak. */
|
|
30
|
+
export interface GroupReadoutInput {
|
|
31
|
+
readonly kind: "rate";
|
|
32
|
+
/** The id of an activity added with `addActivity`. */
|
|
33
|
+
readonly activity?: string;
|
|
34
|
+
}
|
|
35
|
+
/**
|
|
36
|
+
* A group of listed orbits drawn as one set of dots: one dot per orbit, on its own ellipse, one colour and dot size, one menu item and one info card.
|
|
37
|
+
* The group's id joins the camera menu (`focus-<id>`, `follow-<id>`) and may be named by story panels. The orbits' shapes are as listed; where each dot sits
|
|
38
|
+
* along its orbit is a drawing choice (an even spread, shuffled by `seed`) and the info card says so.
|
|
39
|
+
*/
|
|
40
|
+
export interface GroupInput {
|
|
41
|
+
/** The group's id: its menu item, camera target and panel `object`. Not shared with any body, path or other group. */
|
|
42
|
+
readonly id: string;
|
|
43
|
+
/** The listed orbits; at least one, ids distinct. */
|
|
44
|
+
readonly orbits: readonly GroupOrbitInput[];
|
|
45
|
+
/** Name on the menu and info card; the id when absent. */
|
|
46
|
+
readonly label?: string;
|
|
47
|
+
/** The body the orbits circle; the scene's centre (its first body) when absent. It must be in the scene. */
|
|
48
|
+
readonly center?: BodyId;
|
|
49
|
+
/** The plane the elements are given in: "ecliptic-j2000" (default) or "EQJ" (the equator of J2000). */
|
|
50
|
+
readonly plane?: "ecliptic-j2000" | "EQJ";
|
|
51
|
+
/** The dots' colour as a CSS hex colour such as "#9de3a8"; default "#9de3a8". */
|
|
52
|
+
readonly color?: string;
|
|
53
|
+
/** Dot size in screen pixels; default 2.5. */
|
|
54
|
+
readonly dotSizePx?: number;
|
|
55
|
+
/** The moment each orbit's dot is placed from (then it moves by two-body motion); the scene's opening time when absent. */
|
|
56
|
+
readonly referenceTime?: TimeInput;
|
|
57
|
+
/** A whole number from 0 to 4294967295 that shuffles which orbit takes which place along its orbit; the same seed gives the same picture. Default 0. */
|
|
58
|
+
readonly seed?: number;
|
|
59
|
+
/** Draws a share of the dots near a body's position along its orbit. */
|
|
60
|
+
readonly clump?: GroupClumpInput;
|
|
61
|
+
/** How often, in simulated milliseconds, the dots are placed again exactly; between fills the picture blends the two nearest. Presentation only. Default five minutes. */
|
|
62
|
+
readonly refillAfterMs?: number;
|
|
63
|
+
/** Milliseconds of each frame the dots layer may spend computing the next fill ahead of time, so a large group does not hitch; 0 or a positive number. 0 makes every fill whole in one frame. Presentation only. Default 8. */
|
|
64
|
+
readonly refillSliceMs?: number;
|
|
65
|
+
/**
|
|
66
|
+
* Where the orbit list came from. The group's own card always shows `sourceType` "illustrative", because the position along each orbit is a drawing choice;
|
|
67
|
+
* the orbits' `sourceType` here is kept in the accuracy line as "Orbit elements are as listed (<sourceType>); the position along each orbit is illustrative."
|
|
68
|
+
* Your `sources` stay, and the group appends this note to your `notes`: "Each orbit's shape and orientation come from its record, but the records give no
|
|
69
|
+
* position along the orbit: that position is an even spread of mean anomaly at the reference time, a drawing choice (illustrative), advanced by unperturbed
|
|
70
|
+
* two-body motion about the centre." (plus a sentence naming the clump, when `clump` is set). Defaults to an "as supplied" notice.
|
|
71
|
+
*/
|
|
72
|
+
readonly provenance?: Provenance;
|
|
73
|
+
/** One or two plain sentences for the info card; a count and placement sentence when absent. */
|
|
74
|
+
readonly description?: string;
|
|
75
|
+
/** Limits of the list, shown first on the info card; the group adds its own placement and motion limits. */
|
|
76
|
+
readonly knownLimitations?: readonly string[];
|
|
77
|
+
/** Bars for the info card, in order. Absent: none. */
|
|
78
|
+
readonly readouts?: readonly GroupReadoutInput[];
|
|
79
|
+
}
|
|
80
|
+
/** A validated group, built into a draw layer once the scene's centre and opening time are known. */
|
|
81
|
+
export interface PlannedGroup {
|
|
82
|
+
readonly id: string;
|
|
83
|
+
readonly label: string;
|
|
84
|
+
readonly input: GroupInput;
|
|
85
|
+
}
|
|
86
|
+
/** Checks what can be checked before the scene is complete; the centre, the clump body and the id clash with other things are checked at build. */
|
|
87
|
+
export declare function planGroup(input: GroupInput, catalogue?: BodyCatalogue): PlannedGroup;
|
|
88
|
+
/** Builds the draw layer: the listed-orbit group and its one shell item. `center` and `openUtcMs` come from the finished scene; a group error from the engine is renamed `bad-group`. */
|
|
89
|
+
export declare function buildGroupLayer(plan: PlannedGroup, catalogue: BodyCatalogue, center: BodyId, openUtcMs: number, window: TimeBounds): GroupLayer;
|
package/src/api/group.js
ADDED
|
@@ -0,0 +1,121 @@
|
|
|
1
|
+
import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
|
|
2
|
+
import { createListedOrbitGroup } from "../core/listedOrbitGroup.js";
|
|
3
|
+
import { createProvenance } from "../core/provenance.js";
|
|
4
|
+
import { createOrbTwoBodyAdapter } from "../core/twoBodyAdapter.js";
|
|
5
|
+
import { catalogue as builtInCatalogue } from "../assets/catalogue.js";
|
|
6
|
+
import { SceneError } from "./errors.js";
|
|
7
|
+
import { toUtcMs } from "./time.js";
|
|
8
|
+
const GROUP_COLOR = "#9de3a8";
|
|
9
|
+
const HEX = /^#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$/;
|
|
10
|
+
const bad = (id, message) => new SceneError("bad-group", `addGroup("${String(id)}"): ${message}`);
|
|
11
|
+
/** Checks what can be checked before the scene is complete; the centre, the clump body and the id clash with other things are checked at build. */
|
|
12
|
+
export function planGroup(input, catalogue = builtInCatalogue) {
|
|
13
|
+
const id = input?.id;
|
|
14
|
+
if (typeof id !== "string" || id === "")
|
|
15
|
+
throw bad(id, "the group needs a non-empty id");
|
|
16
|
+
checkOrbits(id, input.orbits);
|
|
17
|
+
checkLook(id, input);
|
|
18
|
+
if (input.clump !== undefined)
|
|
19
|
+
checkClump(id, input.clump, catalogue);
|
|
20
|
+
checkReadouts(id, input.readouts);
|
|
21
|
+
if (input.center !== undefined && !catalogue.has(input.center))
|
|
22
|
+
throw new SceneError("unknown-body", `addGroup("${id}"): centre "${String(input.center)}" is not a catalogued body`);
|
|
23
|
+
return { id, label: input.label ?? id, input };
|
|
24
|
+
}
|
|
25
|
+
function checkOrbits(id, orbits) {
|
|
26
|
+
if (!Array.isArray(orbits) || orbits.length === 0)
|
|
27
|
+
throw bad(id, "the group needs at least one orbit; the list is empty");
|
|
28
|
+
const seen = new Set();
|
|
29
|
+
for (const orbit of orbits) {
|
|
30
|
+
if (typeof orbit?.id !== "string" || orbit.id === "")
|
|
31
|
+
throw bad(id, "every orbit needs a non-empty id");
|
|
32
|
+
if (seen.has(orbit.id))
|
|
33
|
+
throw bad(id, `orbit "${orbit.id}" appears twice`);
|
|
34
|
+
seen.add(orbit.id);
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
const positive = (value) => value === undefined || (Number.isFinite(value) && value > 0);
|
|
38
|
+
function checkLook(id, input) {
|
|
39
|
+
if (input.color !== undefined && !(typeof input.color === "string" && HEX.test(input.color)))
|
|
40
|
+
throw bad(id, `color "${String(input.color)}" is not a hex colour such as "#9de3a8"`);
|
|
41
|
+
if (!positive(input.dotSizePx))
|
|
42
|
+
throw bad(id, "dotSizePx must be above 0");
|
|
43
|
+
if (!positive(input.refillAfterMs))
|
|
44
|
+
throw bad(id, "refillAfterMs must be above 0");
|
|
45
|
+
if (input.refillSliceMs !== undefined && !(Number.isFinite(input.refillSliceMs) && input.refillSliceMs >= 0))
|
|
46
|
+
throw bad(id, "refillSliceMs must be 0 or above");
|
|
47
|
+
const limits = input.knownLimitations;
|
|
48
|
+
if (limits !== undefined && !(Array.isArray(limits) && limits.every((line) => typeof line === "string" && line !== "")))
|
|
49
|
+
throw bad(id, "knownLimitations must be a list of non-empty texts");
|
|
50
|
+
}
|
|
51
|
+
function checkReadouts(id, readouts) {
|
|
52
|
+
if (readouts === undefined)
|
|
53
|
+
return;
|
|
54
|
+
if (!Array.isArray(readouts))
|
|
55
|
+
throw new SceneError("bad-readout", `addGroup("${id}"): readouts must be a list`);
|
|
56
|
+
for (const spec of readouts) {
|
|
57
|
+
if (spec?.kind !== "rate")
|
|
58
|
+
throw new SceneError("bad-readout", `addGroup("${id}"): readout kind "${String(spec?.kind)}" is not one of rate`);
|
|
59
|
+
if (spec.activity !== undefined && (typeof spec.activity !== "string" || spec.activity === ""))
|
|
60
|
+
throw new SceneError("bad-readout", `addGroup("${id}"): readout rate needs \`activity\` to be the id of an activity`);
|
|
61
|
+
}
|
|
62
|
+
}
|
|
63
|
+
function checkClump(id, clump, catalogue) {
|
|
64
|
+
if (typeof clump.near !== "string" || !catalogue.has(clump.near) || catalogue.get(clump.near).source === undefined)
|
|
65
|
+
throw bad(id, `clump.near "${String(clump?.near)}" is not a catalogued body with a position`);
|
|
66
|
+
if (!(clump.fraction >= 0 && clump.fraction <= 1))
|
|
67
|
+
throw bad(id, `clump.fraction must be from 0 to 1, got ${String(clump.fraction)}`);
|
|
68
|
+
if (!(clump.widthDeg > 0 && clump.widthDeg <= 180))
|
|
69
|
+
throw bad(id, `clump.widthDeg must be above 0 and at most 180, got ${String(clump.widthDeg)}`);
|
|
70
|
+
}
|
|
71
|
+
const PLACEMENT_LIMIT = "The position of each dot along its orbit is illustrative: the list gives the orbit's shape and orientation, and the dots are spread evenly along them.";
|
|
72
|
+
const MOTION_LIMIT = "Motion is unperturbed two-body motion about the centre.";
|
|
73
|
+
const CLUMP_LIMIT = (catalogue, near, fraction) => `${Math.round(fraction * 100)}% of the dots are drawn near ${catalogue.get(near).definition.label}'s position along its orbit. That clump is a model, not a measurement.`;
|
|
74
|
+
const AS_SUPPLIED = createProvenance({ sourceType: "illustrative", sources: ["Supplied by the caller"], accuracy: "As supplied; the engine makes no claim.", notes: "The orbits were passed to addGroup." });
|
|
75
|
+
/** Builds the draw layer: the listed-orbit group and its one shell item. `center` and `openUtcMs` come from the finished scene; a group error from the engine is renamed `bad-group`. */
|
|
76
|
+
export function buildGroupLayer(plan, catalogue, center, openUtcMs, window) {
|
|
77
|
+
const { id, input } = plan;
|
|
78
|
+
const referenceUtcMs = input.referenceTime === undefined ? openUtcMs : toUtcMs(input.referenceTime, `addGroup("${id}") referenceTime`);
|
|
79
|
+
const members = input.orbits.map((orbit) => ({
|
|
80
|
+
recordId: orbit.id,
|
|
81
|
+
epochUtcMs: orbit.time === undefined ? referenceUtcMs : toUtcMs(orbit.time, `addGroup("${id}") orbit "${orbit.id}" time`),
|
|
82
|
+
elements: { semiMajorAxisKm: orbit.semiMajorAxisKm, eccentricity: orbit.eccentricity, inclinationDeg: orbit.inclinationDeg, raanDeg: orbit.raanDeg, argumentOfPeriapsisDeg: orbit.argumentOfPeriapsisDeg },
|
|
83
|
+
}));
|
|
84
|
+
const clump = input.clump;
|
|
85
|
+
try {
|
|
86
|
+
const group = createListedOrbitGroup({
|
|
87
|
+
id,
|
|
88
|
+
center,
|
|
89
|
+
plane: input.plane ?? "ecliptic-j2000",
|
|
90
|
+
members,
|
|
91
|
+
phase: {
|
|
92
|
+
referenceUtcMs,
|
|
93
|
+
...(input.seed === undefined ? {} : { seed: input.seed }),
|
|
94
|
+
...(clump === undefined ? {} : { concentration: { around: catalogue.get(clump.near).source.create(createOrbAstronomyAdapter()), fraction: clump.fraction, widthDeg: clump.widthDeg } }),
|
|
95
|
+
},
|
|
96
|
+
bounds: window,
|
|
97
|
+
provenance: input.provenance ?? AS_SUPPLIED,
|
|
98
|
+
}, createOrbTwoBodyAdapter());
|
|
99
|
+
const color = input.color ?? GROUP_COLOR;
|
|
100
|
+
return {
|
|
101
|
+
group,
|
|
102
|
+
color,
|
|
103
|
+
pointSizePx: input.dotSizePx ?? 2.5,
|
|
104
|
+
...(input.refillAfterMs === undefined ? {} : { refillAfterMs: input.refillAfterMs }),
|
|
105
|
+
...(input.refillSliceMs === undefined ? {} : { refillSliceMs: input.refillSliceMs }),
|
|
106
|
+
object: {
|
|
107
|
+
id,
|
|
108
|
+
label: plan.label,
|
|
109
|
+
color,
|
|
110
|
+
labelPriority: 80,
|
|
111
|
+
description: input.description ?? `${group.count} listed orbit${group.count === 1 ? "" : "s"}, each drawn as one dot. One item stands for the whole group; its focus point is the centroid of the dots.`,
|
|
112
|
+
knownLimitations: [...(input.knownLimitations ?? []), PLACEMENT_LIMIT, ...(clump === undefined ? [] : [CLUMP_LIMIT(catalogue, clump.near, clump.fraction)]), MOTION_LIMIT],
|
|
113
|
+
},
|
|
114
|
+
};
|
|
115
|
+
}
|
|
116
|
+
catch (error) {
|
|
117
|
+
if (error instanceof SceneError)
|
|
118
|
+
throw error;
|
|
119
|
+
throw bad(id, error instanceof Error ? error.message : String(error));
|
|
120
|
+
}
|
|
121
|
+
}
|
package/src/api/index.d.ts
CHANGED
|
@@ -1,8 +1,13 @@
|
|
|
1
|
-
export { Scene, SceneCamera, type AddBodyOptions, type DataSource, type MoonPositions, type FollowView, type TimeInput, type TrajectoryInput, type TrajectorySampleInput } from "./scene.js";
|
|
1
|
+
export { Scene, SceneCamera, type AddBodyOptions, type AnchorInput, type ReadoutInput, type DataSource, type MoonPositions, type FollowView, type GroupInput, type GroupOrbitInput, type GroupClumpInput, type GroupReadoutInput, type ActivityInput, type ActivitySampleInput, type ActivitySourceInput, type ElementsBodyRecord, type TimeInput, type TrajectoryInput, type TrajectorySampleInput } from "./scene.js";
|
|
2
|
+
export { type EventInput, type AddEventsOptions, type TimelineInput, type StoryPanelsInput } from "./story.js";
|
|
3
|
+
export { type SwitchesInput } from "./switches.js";
|
|
2
4
|
export { mount, type MountOptions, type MountedScene } from "./mount.js";
|
|
5
|
+
export { AstraeusScene, type AstraeusSceneProps } from "./AstraeusScene.js";
|
|
3
6
|
export { SceneError, type SceneErrorCode } from "./errors.js";
|
|
4
7
|
export { sun, mercury, venus, earth, moon, mars, jupiter, saturn, uranus, neptune, pluto, io, europa, ganymede, callisto, mimas, enceladus, tethys, dione, rhea, titan, iapetus, triton, charon, phobos, deimos, type BodyRef } from "./bodies.js";
|
|
5
8
|
export { trueScale, readableScale, type ScalePolicy } from "../core/scalePolicy.js";
|
|
6
9
|
export type { State } from "../core/state.js";
|
|
10
|
+
export type { Provenance, ProvenanceSourceType } from "../core/provenance.js";
|
|
7
11
|
export type { Pictures } from "../assets/pictures.js";
|
|
8
12
|
export type { AssetLicence, TextureRef } from "../assets/licence.js";
|
|
13
|
+
export { APPROXIMATE_LIMIT_FRACTION, INDICATIVE_LIMIT_FRACTION, classifyPositionError, parseElementsBodyRecord, type AccuracyClassification } from "../core/elementsBody.js";
|
package/src/api/index.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
|
-
// The engine's public API (0.
|
|
1
|
+
// The engine's public API (0.2 preview): everything not exported here is internal.
|
|
2
2
|
export { Scene, SceneCamera } from "./scene.js";
|
|
3
3
|
export { mount } from "./mount.js";
|
|
4
|
+
export { AstraeusScene } from "./AstraeusScene.js";
|
|
4
5
|
export { SceneError } from "./errors.js";
|
|
5
6
|
export { sun, mercury, venus, earth, moon, mars, jupiter, saturn, uranus, neptune, pluto, io, europa, ganymede, callisto, mimas, enceladus, tethys, dione, rhea, titan, iapetus, triton, charon, phobos, deimos } from "./bodies.js";
|
|
6
7
|
export { trueScale, readableScale } from "../core/scalePolicy.js";
|
|
8
|
+
export { APPROXIMATE_LIMIT_FRACTION, INDICATIVE_LIMIT_FRACTION, classifyPositionError, parseElementsBodyRecord } from "../core/elementsBody.js";
|
|
@@ -0,0 +1,8 @@
|
|
|
1
|
+
// The engine's public API (0.2 preview): everything not exported here is internal.
|
|
2
|
+
export { Scene, SceneCamera } from "./scene.js";
|
|
3
|
+
export { mount } from "./mount.node.js";
|
|
4
|
+
export { AstraeusScene } from "./AstraeusScene.node.js";
|
|
5
|
+
export { SceneError } from "./errors.js";
|
|
6
|
+
export { sun, mercury, venus, earth, moon, mars, jupiter, saturn, uranus, neptune, pluto, io, europa, ganymede, callisto, mimas, enceladus, tethys, dione, rhea, titan, iapetus, triton, charon, phobos, deimos } from "./bodies.js";
|
|
7
|
+
export { trueScale, readableScale } from "../core/scalePolicy.js";
|
|
8
|
+
export { APPROXIMATE_LIMIT_FRACTION, INDICATIVE_LIMIT_FRACTION, classifyPositionError, parseElementsBodyRecord } from "../core/elementsBody.js";
|
package/src/api/mount.d.ts
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import "../app/style.css";
|
|
2
2
|
import type { DataSource, Scene } from "./scene.js";
|
|
3
|
+
/** Options of `mount`. */
|
|
3
4
|
export interface MountOptions {
|
|
4
5
|
/** Data packages the scene's bodies need, such as moon pictures or positions; nothing is looked up behind the caller's back. */
|
|
5
6
|
readonly data?: readonly DataSource[];
|
|
@@ -11,5 +12,13 @@ export interface MountedScene {
|
|
|
11
12
|
/** Removes the scene, its canvas and its listeners from the page. Safe to call twice. */
|
|
12
13
|
unmount(): void;
|
|
13
14
|
}
|
|
14
|
-
/**
|
|
15
|
+
/**
|
|
16
|
+
* Draws `scene` into `element` with the full viewer. The caller writes no React. The element needs a size.
|
|
17
|
+
* @example
|
|
18
|
+
* import { Scene, earth, moon, mount } from "astraeus";
|
|
19
|
+
* const scene = new Scene().addBody(earth).addBody(moon, { orbit: true });
|
|
20
|
+
* const mounted = mount(document.getElementById("app")!, scene);
|
|
21
|
+
* await mounted.ready; // drawn
|
|
22
|
+
* mounted.unmount(); // removes it again
|
|
23
|
+
*/
|
|
15
24
|
export declare function mount(element: HTMLElement, scene: Scene, options?: MountOptions): MountedScene;
|
package/src/api/mount.js
CHANGED
|
@@ -3,16 +3,27 @@ import { createRoot } from "react-dom/client";
|
|
|
3
3
|
import "../app/style.css";
|
|
4
4
|
import { App } from "../app/App.js";
|
|
5
5
|
import { SceneError } from "./errors.js";
|
|
6
|
-
|
|
6
|
+
import { prepareScene } from "./prepared.js";
|
|
7
|
+
/**
|
|
8
|
+
* Draws `scene` into `element` with the full viewer. The caller writes no React. The element needs a size.
|
|
9
|
+
* @example
|
|
10
|
+
* import { Scene, earth, moon, mount } from "astraeus";
|
|
11
|
+
* const scene = new Scene().addBody(earth).addBody(moon, { orbit: true });
|
|
12
|
+
* const mounted = mount(document.getElementById("app")!, scene);
|
|
13
|
+
* await mounted.ready; // drawn
|
|
14
|
+
* mounted.unmount(); // removes it again
|
|
15
|
+
*/
|
|
7
16
|
export function mount(element, scene, options = {}) {
|
|
8
17
|
if (!(element instanceof Object) || typeof element.appendChild !== "function")
|
|
9
18
|
throw new SceneError("bad-element", "mount: the first argument must be an element of the page");
|
|
10
|
-
const definition = scene
|
|
19
|
+
const { definition, ready: loaded } = prepareScene(scene, options.data);
|
|
20
|
+
// Its own stacking context, so the viewer's z-index values cannot rise above the host page's overlays.
|
|
21
|
+
element.style.isolation = "isolate";
|
|
11
22
|
const root = createRoot(element);
|
|
12
23
|
let open = true;
|
|
13
|
-
const ready =
|
|
24
|
+
const ready = loaded.then(() => {
|
|
14
25
|
if (open)
|
|
15
|
-
root.render(createElement(App, { definition }));
|
|
26
|
+
root.render(createElement(App, { definition, writeTitle: false }));
|
|
16
27
|
});
|
|
17
28
|
return {
|
|
18
29
|
ready,
|
|
@@ -0,0 +1,36 @@
|
|
|
1
|
+
import { createElement } from "react";
|
|
2
|
+
import { createRoot } from "react-dom/client";
|
|
3
|
+
import { App } from "../app/App.node.js";
|
|
4
|
+
import { SceneError } from "./errors.js";
|
|
5
|
+
import { prepareScene } from "./prepared.js";
|
|
6
|
+
/**
|
|
7
|
+
* Draws `scene` into `element` with the full viewer. The caller writes no React. The element needs a size.
|
|
8
|
+
* @example
|
|
9
|
+
* import { Scene, earth, moon, mount } from "astraeus";
|
|
10
|
+
* const scene = new Scene().addBody(earth).addBody(moon, { orbit: true });
|
|
11
|
+
* const mounted = mount(document.getElementById("app")!, scene);
|
|
12
|
+
* await mounted.ready; // drawn
|
|
13
|
+
* mounted.unmount(); // removes it again
|
|
14
|
+
*/
|
|
15
|
+
export function mount(element, scene, options = {}) {
|
|
16
|
+
if (!(element instanceof Object) || typeof element.appendChild !== "function")
|
|
17
|
+
throw new SceneError("bad-element", "mount: the first argument must be an element of the page");
|
|
18
|
+
const { definition, ready: loaded } = prepareScene(scene, options.data);
|
|
19
|
+
// Its own stacking context, so the viewer's z-index values cannot rise above the host page's overlays.
|
|
20
|
+
element.style.isolation = "isolate";
|
|
21
|
+
const root = createRoot(element);
|
|
22
|
+
let open = true;
|
|
23
|
+
const ready = loaded.then(() => {
|
|
24
|
+
if (open)
|
|
25
|
+
root.render(createElement(App, { definition, writeTitle: false }));
|
|
26
|
+
});
|
|
27
|
+
return {
|
|
28
|
+
ready,
|
|
29
|
+
unmount() {
|
|
30
|
+
if (!open)
|
|
31
|
+
return;
|
|
32
|
+
open = false;
|
|
33
|
+
root.unmount();
|
|
34
|
+
},
|
|
35
|
+
};
|
|
36
|
+
}
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { DataSource, Scene } from "./scene.js";
|
|
2
|
+
import type { ExperienceDefinition } from "../app/experienceDefinition.js";
|
|
3
|
+
/** A scene turned into the viewer's definition, with the promise of its data. The one path `mount` and `AstraeusScene` share. */
|
|
4
|
+
export interface PreparedScene {
|
|
5
|
+
readonly definition: ExperienceDefinition;
|
|
6
|
+
/** Resolves once the definition's data has loaded; rejects if loading failed. */
|
|
7
|
+
readonly ready: Promise<void>;
|
|
8
|
+
}
|
|
9
|
+
/** Builds the definition (throws a `SceneError` for a missing data package or an empty scene) and starts loading its data. */
|
|
10
|
+
export declare function prepareScene(scene: Scene, data?: readonly DataSource[]): PreparedScene;
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
/** Builds the definition (throws a `SceneError` for a missing data package or an empty scene) and starts loading its data. */
|
|
2
|
+
export function prepareScene(scene, data = []) {
|
|
3
|
+
const definition = scene.toDefinition(data);
|
|
4
|
+
return { definition, ready: definition.prepare?.() ?? Promise.resolve() };
|
|
5
|
+
}
|
package/src/api/scene.d.ts
CHANGED
|
@@ -2,17 +2,60 @@ import type { BodyId } from "../core/body.js";
|
|
|
2
2
|
import { type Provenance } from "../core/provenance.js";
|
|
3
3
|
import { type ScalePolicy } from "../core/scalePolicy.js";
|
|
4
4
|
import type { State } from "../core/state.js";
|
|
5
|
+
import { type ElementsBodyRecord } from "../core/elementsBody.js";
|
|
5
6
|
import type { ExperienceDefinition } from "../app/experienceDefinition.js";
|
|
6
7
|
import { type BodyRef } from "./bodies.js";
|
|
7
8
|
import { type DataSource } from "./data.js";
|
|
9
|
+
import { type ActivityInput } from "./activity.js";
|
|
10
|
+
import { type GroupInput } from "./group.js";
|
|
11
|
+
export type { GroupInput, GroupOrbitInput, GroupClumpInput, GroupReadoutInput } from "./group.js";
|
|
12
|
+
export type { ActivityInput, ActivitySampleInput, ActivitySourceInput } from "./activity.js";
|
|
8
13
|
export type { DataSource, MoonPositions } from "./data.js";
|
|
14
|
+
import { type TimeInput } from "./time.js";
|
|
15
|
+
import { type SwitchesInput } from "./switches.js";
|
|
16
|
+
import { type AddEventsOptions, type EventInput, type StoryPanelsInput, type TimelineInput } from "./story.js";
|
|
17
|
+
export { toUtcMs, type TimeInput } from "./time.js";
|
|
18
|
+
export type { ElementsBodyRecord } from "../core/elementsBody.js";
|
|
9
19
|
/** Options of `addBody`. */
|
|
10
20
|
export interface AddBodyOptions {
|
|
11
|
-
/**
|
|
21
|
+
/**
|
|
22
|
+
* Draws the body's orbit as a line: the Moon's about Earth and Io's about Jupiter, or, in a scene that holds the Sun, one full turn round the Sun of any body that
|
|
23
|
+
* circles it (the planets, Earth's year, a body added with `addBodyFromElements`), from the scene's opening time (an own body from its periapsis). Others throw `no-orbit`.
|
|
24
|
+
*/
|
|
12
25
|
readonly orbit?: boolean;
|
|
26
|
+
/** Draws the body this many times larger than life so a planet can be seen; a number of at least 1 (distances stay true). In a scene centred on the Sun the viewer offers its \"solar-system\" scale (true distances, the named bodies enlarged) as the second scale choice in place of the readable scale. A bad value throws `bad-body`. */
|
|
27
|
+
readonly enlarge?: number;
|
|
28
|
+
/** False starts the body's label off (the body stays in the menu and selectable; the viewer's labels switch can turn it on). Default true. */
|
|
29
|
+
readonly showLabel?: boolean;
|
|
30
|
+
/** One or two plain sentences for the body's info card. */
|
|
31
|
+
readonly description?: string;
|
|
32
|
+
/** The body's colour on its info card and label, as a CSS hex colour such as "#9fd8ff"; the catalogue's own when absent. A bad value throws `bad-body`. */
|
|
33
|
+
readonly color?: string;
|
|
34
|
+
/** Known limits shown with the body's provenance, replacing the catalogue's own; a list of non-empty texts. A bad value throws `bad-body`. */
|
|
35
|
+
readonly knownLimitations?: readonly string[];
|
|
36
|
+
}
|
|
37
|
+
/** A source anchor on a path: a point the data was published at, drawn as a dot and labelled with its id. Its time must fall within the path. */
|
|
38
|
+
export interface AnchorInput {
|
|
39
|
+
readonly id: string;
|
|
40
|
+
readonly time: TimeInput;
|
|
13
41
|
}
|
|
14
|
-
/**
|
|
15
|
-
|
|
42
|
+
/**
|
|
43
|
+
* A bar on a path's info card: `range` (distance from the path's centre body; `marker` also marks where a named body is now), `speed` (its bar scaled
|
|
44
|
+
* to the path's highest speed at its anchors), `distance` (centre to centre to a named body) and `altitude` (above a named body's mean radius).
|
|
45
|
+
* A named body must be in the scene.
|
|
46
|
+
*/
|
|
47
|
+
export type ReadoutInput = {
|
|
48
|
+
readonly kind: "range";
|
|
49
|
+
readonly marker?: BodyId;
|
|
50
|
+
} | {
|
|
51
|
+
readonly kind: "speed";
|
|
52
|
+
} | {
|
|
53
|
+
readonly kind: "distance";
|
|
54
|
+
readonly to: BodyId;
|
|
55
|
+
} | {
|
|
56
|
+
readonly kind: "altitude";
|
|
57
|
+
readonly above: BodyId;
|
|
58
|
+
};
|
|
16
59
|
/** One sample of a recorded path: position in km (and optionally velocity in km/s) about the trajectory's centre. */
|
|
17
60
|
export interface TrajectorySampleInput {
|
|
18
61
|
readonly time: TimeInput;
|
|
@@ -26,6 +69,14 @@ interface TrajectoryBase {
|
|
|
26
69
|
/** The body the positions are measured from; defaults to "earth". */
|
|
27
70
|
readonly center?: BodyId;
|
|
28
71
|
readonly provenance?: Provenance;
|
|
72
|
+
/** One or two plain sentences for the path's info card. */
|
|
73
|
+
readonly description?: string;
|
|
74
|
+
/** Published limits of the data, shown with the provenance. */
|
|
75
|
+
readonly knownLimitations?: readonly string[];
|
|
76
|
+
/** Source anchors, drawn as dots on the path and labelled with their ids. */
|
|
77
|
+
readonly anchors?: readonly AnchorInput[];
|
|
78
|
+
/** Bars for the info card, in order. */
|
|
79
|
+
readonly readouts?: readonly ReadoutInput[];
|
|
29
80
|
}
|
|
30
81
|
/** A path given as sampled states, or as a provider with `stateAt(time)` and the span it covers. */
|
|
31
82
|
export type TrajectoryInput = (TrajectoryBase & {
|
|
@@ -44,31 +95,119 @@ export interface FollowView {
|
|
|
44
95
|
readonly azimuthDeg?: number;
|
|
45
96
|
readonly elevationDeg?: number;
|
|
46
97
|
readonly distance?: number;
|
|
98
|
+
/** Which direction is up as the viewer orbits: "equatorial" (celestial north, the default) or "ecliptic" (the ecliptic's north pole, so the planets' plane reads flat). Any other value throws `bad-camera`. */
|
|
99
|
+
readonly up?: "equatorial" | "ecliptic";
|
|
47
100
|
}
|
|
48
|
-
/** Converts a moment to Unix milliseconds, or throws a `bad-time` SceneError naming it. */
|
|
49
|
-
export declare function toUtcMs(time: TimeInput, what?: string): number;
|
|
50
101
|
/** The scene's camera: what it opens on. */
|
|
51
102
|
export declare class SceneCamera {
|
|
52
103
|
#private;
|
|
53
|
-
constructor(has: (id: string) => boolean);
|
|
104
|
+
constructor(has: (id: string) => boolean, circlesSun: (id: string) => boolean);
|
|
54
105
|
/** Opens framed on a body or trajectory already added to the scene and already following it (the viewer's Follow button shows as pressed). */
|
|
55
106
|
follow(id: string, view?: FollowView): this;
|
|
107
|
+
/** 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. */
|
|
108
|
+
lookAt(id: string, view?: FollowView): this;
|
|
109
|
+
/**
|
|
110
|
+
* 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`.
|
|
111
|
+
* 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.
|
|
112
|
+
* 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.
|
|
113
|
+
* `setReach` and `fitOrbit` set the same limit, so the later call wins and replaces the earlier one.
|
|
114
|
+
*/
|
|
115
|
+
setReach(distance: number): this;
|
|
116
|
+
/**
|
|
117
|
+
* 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
|
|
118
|
+
* 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
|
|
119
|
+
* 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
|
|
120
|
+
* 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
|
|
121
|
+
* same limit, so the later call wins and replaces the earlier one.
|
|
122
|
+
* @example
|
|
123
|
+
* scene.camera.fitOrbit("c-2025-a1");
|
|
124
|
+
*/
|
|
125
|
+
fitOrbit(body: BodyRef | BodyId): this;
|
|
126
|
+
/** The body `fitOrbit` fits the zoom-out to, if any. */
|
|
127
|
+
get fitted(): string | undefined;
|
|
128
|
+
/** The farthest zoom-out set with `setReach`, if any. */
|
|
129
|
+
get reach(): number | undefined;
|
|
56
130
|
get target(): string | undefined;
|
|
131
|
+
/** Whether the opening view follows its target (`follow`) rather than only looking at it (`lookAt`). */
|
|
132
|
+
get following(): boolean;
|
|
57
133
|
get view(): FollowView;
|
|
58
134
|
}
|
|
59
|
-
/**
|
|
135
|
+
/**
|
|
136
|
+
* A scene built with imperative calls. `mount(element, scene)` draws it; `toDefinition()` is what the app is given. Every method returns the scene, so calls chain.
|
|
137
|
+
* @example
|
|
138
|
+
* const scene = new Scene()
|
|
139
|
+
* .addBody(earth)
|
|
140
|
+
* .addBody(moon, { orbit: true })
|
|
141
|
+
* .setTime("2026-01-01T00:00:00Z");
|
|
142
|
+
* scene.camera.follow("moon", { distance: 60 });
|
|
143
|
+
*/
|
|
60
144
|
export declare class Scene {
|
|
61
145
|
#private;
|
|
146
|
+
/** The camera: `scene.camera.follow(id)` opens framed on a body or trajectory. */
|
|
62
147
|
readonly camera: SceneCamera;
|
|
63
148
|
constructor();
|
|
64
149
|
/** 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. */
|
|
65
150
|
addBody(body: BodyRef | BodyId, options?: AddBodyOptions): this;
|
|
151
|
+
/**
|
|
152
|
+
* 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
|
|
153
|
+
* (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
|
|
154
|
+
* and the stated limits show on its info card. The options are `addBody`'s (`{ orbit: true }` draws its whole orbit from periapsis). A bad record throws `bad-element`
|
|
155
|
+
* naming the field; a repeated id throws `duplicate-id`.
|
|
156
|
+
* @example
|
|
157
|
+
* scene.addBody(sun).addBodyFromElements(record, { orbit: true, showLabel: false });
|
|
158
|
+
*/
|
|
159
|
+
addBodyFromElements(record: ElementsBodyRecord, options?: AddBodyOptions): this;
|
|
66
160
|
/** Adds a path to follow and draw, from sampled states or a provider with `stateAt(time)`. */
|
|
67
161
|
addTrajectory(input: TrajectoryInput): this;
|
|
162
|
+
/**
|
|
163
|
+
* 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.
|
|
164
|
+
* The orbits circle the scene's centre unless `center` names another body. A repeated id throws `duplicate-id`; an empty list, a bad orbit, colour or clump throws `bad-group`. A `center` that is not a catalogued body throws `unknown-body`; a catalogued one the finished scene does not hold throws `bad-group` from `toDefinition`.
|
|
165
|
+
* @example
|
|
166
|
+
* scene.addGroup({ id: "ring", orbits: [{ id: "a", semiMajorAxisKm: 90_000, eccentricity: 0.1, inclinationDeg: 5, raanDeg: 40, argumentOfPeriapsisDeg: 70 }], color: "#9de3a8" });
|
|
167
|
+
*/
|
|
168
|
+
addGroup(input: GroupInput): this;
|
|
169
|
+
/**
|
|
170
|
+
* 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
|
|
171
|
+
* (unavailable outside the period) against the peak. Without `setTimeline`, the timeline spans the activities. A repeated id, or a bad curve, peak, source or moment, throws `bad-activity`.
|
|
172
|
+
* @example
|
|
173
|
+
* 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 }] });
|
|
174
|
+
*/
|
|
175
|
+
addActivity(input: ActivityInput): this;
|
|
68
176
|
/** Sets the moment the scene opens at. */
|
|
69
177
|
setTime(time: TimeInput): this;
|
|
70
|
-
/** Chooses the opening scale: `trueScale` or `readableScale`; the viewer can switch to the other. */
|
|
71
|
-
setScale(scale: ScalePolicy
|
|
178
|
+
/** Chooses the opening scale: `trueScale` or `readableScale`; the viewer can switch to the other (in a Sun-centred scene with an enlarged body, to the \"solar-system\" scale instead of the readable one), unless `{ only: true }` offers this scale alone. */
|
|
179
|
+
setScale(scale: ScalePolicy, options?: {
|
|
180
|
+
readonly only?: boolean;
|
|
181
|
+
}): this;
|
|
182
|
+
/** Adds timed events to the timeline, each with an id, a label and a moment; `provenance` says where the times come from and is shown with every event that has none of its own (`EventInput.provenance`). May be called more than once. Malformed provenance throws "bad-event". */
|
|
183
|
+
addEvents(events: readonly EventInput[], options?: AddEventsOptions): this;
|
|
184
|
+
/**
|
|
185
|
+
* Adds story panels that open as playback reaches them. A panel opens only when forward playback crosses its time, so one at the opening instant never opens by itself
|
|
186
|
+
* (a panel with an `object` still has its marker on that object). `at.utc` may be any instant inside the timeline, in any year. Their times may name events (`addEvents`) and path anchors, and `object` a body or path; these are checked when the scene is built (`mount`), and a mistake throws `bad-panels` naming the panel and field.
|
|
187
|
+
*/
|
|
188
|
+
addStoryPanels(panels: StoryPanelsInput): this;
|
|
189
|
+
/** Sets the timeline: its span (`start`, `end`), the speeds offered (`rates`), the speed it opens at (`rate`) and whether playback wraps from the end to the start (`loop`; ignored with `{ none: true }`, which has no span to wrap, and when `setTimeline` is not called), or `{ none: true }` for no timeline bar, with time frozen at `at` or running at `rate`. Without this call the span follows the paths and the speeds are 1 minute, 1 hour and 1 day per second. */
|
|
190
|
+
setTimeline(timeline: TimelineInput): this;
|
|
191
|
+
/**
|
|
192
|
+
* Places the display switches: for each of `orbitLines` (orbit ring, trailing arc and moon orbits), `labels` (body and anchor labels) and `milkyWay` (the sky picture), `place` is
|
|
193
|
+
* `"top-bar"` (a button in the bar), `"panel"` (a row in one switch panel opened from the bar) or `"developer"` (only in the Developer drawer, where every switch stays), and `on` is
|
|
194
|
+
* whether it starts on (default on). A switch the scene has nothing for (orbit lines with no orbit drawn) shows nowhere. May be called more than once; later calls replace the same switch.
|
|
195
|
+
* A bad switch name, place or `on` throws `bad-switch`.
|
|
196
|
+
* @example
|
|
197
|
+
* scene.setSwitches({ orbitLines: { place: "top-bar" }, labels: { place: "panel", on: false }, milkyWay: { place: "developer", on: false } });
|
|
198
|
+
*/
|
|
199
|
+
setSwitches(switches: SwitchesInput): this;
|
|
200
|
+
/**
|
|
201
|
+
* 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;
|
|
202
|
+
* 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
|
|
203
|
+
* samples or provider carry velocities and for a moon from fitted data (Io); planets, Earth, the Sun, the built-in comet and elements bodies give position only, so check it before use. An id the scene does not hold throws `unknown-body`. Ready-made and elements bodies answer at any date (they have no data cut-off); only a moment outside an
|
|
204
|
+
* `addTrajectory` path throws `bad-time`. A planet before the planet series have loaded (they load at mount) throws `missing-data`.
|
|
205
|
+
* @example
|
|
206
|
+
* const sunDistanceKm = Math.hypot(...scene.stateOf("earth", "2026-08-12T00:00:00Z").positionKm);
|
|
207
|
+
*/
|
|
208
|
+
stateOf(id: string, time: TimeInput): State;
|
|
209
|
+
/** The Provenance of a body's position, as its info card shows it: for a ready-made or elements body the catalogue's position record, for a path the one passed to `addTrajectory`. Carries `accuracyClass` and `maxErrorFraction` where a comparison with an independent ephemeris exists. An id the scene does not hold throws `unknown-body`. */
|
|
210
|
+
provenanceOf(id: string): Provenance;
|
|
72
211
|
/** The data packages the added bodies need that `data` does not provide. */
|
|
73
212
|
missingData(data?: readonly DataSource[]): readonly string[];
|
|
74
213
|
/** 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`. */
|