astraeus 0.1.0 → 0.2.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 +27 -0
- package/README.md +39 -6
- package/package.json +9 -6
- package/src/api/AstraeusScene.d.ts +27 -0
- package/src/api/AstraeusScene.js +38 -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 +83 -0
- package/src/api/group.js +121 -0
- package/src/api/index.d.ts +5 -1
- package/src/api/index.js +2 -1
- package/src/api/mount.d.ts +10 -1
- package/src/api/mount.js +12 -3
- package/src/api/prepared.d.ts +10 -0
- package/src/api/prepared.js +5 -0
- package/src/api/scene.d.ts +121 -8
- package/src/api/scene.js +464 -57
- package/src/api/story.d.ts +63 -0
- package/src/api/story.js +52 -0
- package/src/api/sunOrbit.d.ts +14 -0
- package/src/api/sunOrbit.js +61 -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.js +35 -17
- 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 +18 -0
- package/src/app/PanelLoadBoundary.js +17 -0
- 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 +5 -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/sceneDebug.d.ts +1 -1
- package/src/app/sceneDebug.js +1 -1
- package/src/app/skyModel.js +2 -0
- 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/core/bodies/index.d.ts +3 -0
- package/src/core/bodies/index.js +3 -1
- package/src/core/planetSeries.d.ts +2 -0
- package/src/core/planetSeries.js +4 -0
- package/src/core/provenance.d.ts +2 -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 +7 -3
- package/src/shell/DisplaySwitches.d.ts +16 -0
- package/src/shell/DisplaySwitches.js +31 -0
- package/src/shell/TimelineBar.css +4 -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/experience.d.ts +2 -0
- package/src/shell/phone.css +3 -0
- package/src/shell/topBarIcons.d.ts +1 -0
- package/src/shell/topBarIcons.js +1 -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
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,12 @@
|
|
|
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";
|
package/src/api/index.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
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";
|
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,14 +3,23 @@ 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);
|
|
11
20
|
const root = createRoot(element);
|
|
12
21
|
let open = true;
|
|
13
|
-
const ready =
|
|
22
|
+
const ready = loaded.then(() => {
|
|
14
23
|
if (open)
|
|
15
24
|
root.render(createElement(App, { definition }));
|
|
16
25
|
});
|
|
@@ -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,93 @@ 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
104
|
constructor(has: (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
|
+
* 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.
|
|
112
|
+
*/
|
|
113
|
+
setReach(distance: number): this;
|
|
114
|
+
/** The farthest zoom-out set with `setReach`, if any. */
|
|
115
|
+
get reach(): number | undefined;
|
|
56
116
|
get target(): string | undefined;
|
|
117
|
+
/** Whether the opening view follows its target (`follow`) rather than only looking at it (`lookAt`). */
|
|
118
|
+
get following(): boolean;
|
|
57
119
|
get view(): FollowView;
|
|
58
120
|
}
|
|
59
|
-
/**
|
|
121
|
+
/**
|
|
122
|
+
* 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.
|
|
123
|
+
* @example
|
|
124
|
+
* const scene = new Scene()
|
|
125
|
+
* .addBody(earth)
|
|
126
|
+
* .addBody(moon, { orbit: true })
|
|
127
|
+
* .setTime("2026-01-01T00:00:00Z");
|
|
128
|
+
* scene.camera.follow("moon", { distance: 60 });
|
|
129
|
+
*/
|
|
60
130
|
export declare class Scene {
|
|
61
131
|
#private;
|
|
132
|
+
/** The camera: `scene.camera.follow(id)` opens framed on a body or trajectory. */
|
|
62
133
|
readonly camera: SceneCamera;
|
|
63
134
|
constructor();
|
|
64
135
|
/** 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
136
|
addBody(body: BodyRef | BodyId, options?: AddBodyOptions): this;
|
|
137
|
+
/**
|
|
138
|
+
* 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
|
|
139
|
+
* (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
|
|
140
|
+
* 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`
|
|
141
|
+
* naming the field; a repeated id throws `duplicate-id`.
|
|
142
|
+
* @example
|
|
143
|
+
* scene.addBody(sun).addBodyFromElements(record, { orbit: true, showLabel: false });
|
|
144
|
+
*/
|
|
145
|
+
addBodyFromElements(record: ElementsBodyRecord, options?: AddBodyOptions): this;
|
|
66
146
|
/** Adds a path to follow and draw, from sampled states or a provider with `stateAt(time)`. */
|
|
67
147
|
addTrajectory(input: TrajectoryInput): this;
|
|
148
|
+
/**
|
|
149
|
+
* 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.
|
|
150
|
+
* 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, clump or centre throws `bad-group`.
|
|
151
|
+
* @example
|
|
152
|
+
* scene.addGroup({ id: "ring", orbits: [{ id: "a", semiMajorAxisKm: 90_000, eccentricity: 0.1, inclinationDeg: 5, raanDeg: 40, argumentOfPeriapsisDeg: 70 }], color: "#9de3a8" });
|
|
153
|
+
*/
|
|
154
|
+
addGroup(input: GroupInput): this;
|
|
155
|
+
/**
|
|
156
|
+
* 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
|
|
157
|
+
* (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`.
|
|
158
|
+
* @example
|
|
159
|
+
* 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 }] });
|
|
160
|
+
*/
|
|
161
|
+
addActivity(input: ActivityInput): this;
|
|
68
162
|
/** Sets the moment the scene opens at. */
|
|
69
163
|
setTime(time: TimeInput): this;
|
|
70
|
-
/** Chooses the opening scale: `trueScale` or `readableScale`; the viewer can switch to the other. */
|
|
71
|
-
setScale(scale: ScalePolicy
|
|
164
|
+
/** 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. */
|
|
165
|
+
setScale(scale: ScalePolicy, options?: {
|
|
166
|
+
readonly only?: boolean;
|
|
167
|
+
}): this;
|
|
168
|
+
/** Adds timed events to the timeline, each with an id, a label and a moment; `provenance` says where the times come from and is shown with every event. May be called more than once. */
|
|
169
|
+
addEvents(events: readonly EventInput[], options?: AddEventsOptions): this;
|
|
170
|
+
/** Adds story panels that open as playback reaches them. 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. */
|
|
171
|
+
addStoryPanels(panels: StoryPanelsInput): this;
|
|
172
|
+
/** Sets the timeline: its span (`start`, `end`), the speeds offered (`rates`), the speed it opens at (`rate`) and whether playback wraps from the end to the start (`loop`), or `{ none: true }` for no timeline bar, with time frozen at `at` or running at `rate`. Without this call the span follows the paths and the speeds are 1 minute, 1 hour and 1 day per second. */
|
|
173
|
+
setTimeline(timeline: TimelineInput): this;
|
|
174
|
+
/**
|
|
175
|
+
* 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
|
|
176
|
+
* `"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
|
|
177
|
+
* 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.
|
|
178
|
+
* A bad switch name, place or `on` throws `bad-switch`.
|
|
179
|
+
* @example
|
|
180
|
+
* scene.setSwitches({ orbitLines: { place: "top-bar" }, labels: { place: "panel", on: false }, milkyWay: { place: "developer", on: false } });
|
|
181
|
+
*/
|
|
182
|
+
setSwitches(switches: SwitchesInput): this;
|
|
183
|
+
/** The state of a trajectory added with `addTrajectory` at a moment, about its centre body (position in km, velocity in km/s): for figures a story quotes, such as a peak speed. Throws `unknown-body` for any other id and `bad-time` for a moment outside the path. */
|
|
184
|
+
stateOf(id: string, time: TimeInput): State;
|
|
72
185
|
/** The data packages the added bodies need that `data` does not provide. */
|
|
73
186
|
missingData(data?: readonly DataSource[]): readonly string[];
|
|
74
187
|
/** 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`. */
|