astraeus 0.3.0 → 0.5.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 +37 -0
- package/README.md +92 -11
- package/data/ephemerides/planets/planets.json +1 -1
- package/package.json +1 -1
- package/src/api/AstraeusScene.d.ts +9 -1
- package/src/api/AstraeusScene.js +26 -4
- package/src/api/AstraeusScene.node.js +26 -4
- package/src/api/activity.d.ts +1 -1
- package/src/api/activity.js +1 -1
- package/src/api/bodies.d.ts +2 -0
- package/src/api/bodies.js +2 -0
- package/src/api/data.js +11 -1
- package/src/api/errors.d.ts +1 -1
- package/src/api/index.d.ts +3 -2
- package/src/api/index.js +1 -1
- package/src/api/index.node.js +1 -1
- package/src/api/mount.d.ts +16 -0
- package/src/api/mount.js +13 -1
- package/src/api/mount.node.js +13 -1
- package/src/api/pathProvenance.d.ts +10 -0
- package/src/api/pathProvenance.js +34 -0
- package/src/api/scene.d.ts +26 -5
- package/src/api/scene.js +197 -44
- package/src/api/story.d.ts +41 -1
- package/src/api/story.js +63 -1
- package/src/api/sunOrbit.d.ts +3 -3
- package/src/api/sunOrbit.js +92 -24
- package/src/api/viewerLink.d.ts +40 -0
- package/src/api/viewerLink.js +86 -0
- package/src/app/App.d.ts +4 -1
- package/src/app/App.js +42 -6
- package/src/app/App.node.js +42 -6
- package/src/app/AstraeusScene.d.ts +7 -0
- package/src/app/BodySetView.js +3 -2
- package/src/app/KeplerPoints.d.ts +1 -1
- package/src/app/KeplerPoints.js +3 -2
- package/src/app/PointsView.js +3 -2
- package/src/app/SceneLabels.d.ts +2 -0
- package/src/app/SceneLabels.js +5 -1
- package/src/app/TrackedBodyView.d.ts +9 -3
- package/src/app/TrackedBodyView.js +54 -14
- package/src/app/bodyDraw.js +3 -2
- package/src/app/dotMaterial.d.ts +11 -0
- package/src/app/dotMaterial.js +38 -0
- package/src/app/experienceDefinition.d.ts +12 -0
- package/src/app/mission.d.ts +3 -1
- package/src/app/mission.js +1 -1
- package/src/app/openClock.d.ts +1 -1
- package/src/app/openClock.js +3 -0
- package/src/app/pathRules.d.ts +7 -3
- package/src/app/pathRules.js +9 -5
- package/src/app/sceneContentsHooks.js +2 -1
- package/src/app/sceneDebug.d.ts +4 -2
- package/src/app/sceneFrame.d.ts +2 -2
- package/src/app/sceneFrame.js +7 -2
- package/src/app/sceneFraming.d.ts +1 -1
- package/src/app/sceneFraming.js +9 -3
- package/src/app/viewerPort.d.ts +33 -0
- package/src/app/viewerPort.js +1 -0
- package/src/core/bodies/io.js +1 -1
- package/src/core/bodies/jupiterMoons.d.ts +1 -1
- package/src/core/bodies/jupiterMoons.js +6 -6
- package/src/core/bodies/moonSystem.d.ts +15 -1
- package/src/core/bodies/moonSystem.js +58 -7
- package/src/core/bodies/outerPlanets.js +1 -1
- package/src/core/bodies/planetMoons.js +10 -10
- package/src/core/chebyshevEphemeris.d.ts +7 -1
- package/src/core/chebyshevEphemeris.js +24 -7
- package/src/core/clock.d.ts +8 -0
- package/src/core/clock.js +14 -0
- package/src/core/pacing.d.ts +24 -0
- package/src/core/pacing.js +35 -0
- package/src/core/planetModels.d.ts +4 -1
- package/src/core/planetModels.js +6 -1
- package/src/core/planetSeries.d.ts +3 -0
- package/src/core/planetSeries.js +8 -1
- package/src/core/scalePolicy.d.ts +2 -0
- package/src/core/scalePolicy.js +2 -0
- package/src/core/timeWindow.d.ts +2 -0
- package/src/core/timeWindow.js +4 -3
- package/src/shell/AstraeusShell.d.ts +6 -2
- package/src/shell/AstraeusShell.js +3 -3
- package/src/shell/AstraeusShell.node.js +3 -3
- package/src/shell/TimelineBar.d.ts +4 -2
- package/src/shell/TimelineBar.js +15 -6
- package/src/shell/TimelineBar.node.js +15 -6
- package/src/shell/experience.d.ts +3 -1
- package/src/shell/infoModel.js +5 -4
- package/src/shell/timelineModel.d.ts +2 -3
- package/src/shell/timelineModel.js +3 -11
- package/src/synthetic/syntheticJourneyScene.d.ts +9 -0
- package/src/synthetic/syntheticJourneyScene.js +75 -0
- package/src/synthetic/syntheticProbeDefinition.d.ts +5 -0
- package/src/synthetic/syntheticProbeDefinition.js +38 -0
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "astraeus",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "A 3D solar system engine for the browser: place bodies and recorded paths in a scene, mount it, and get time controls, camera, scale choice and body info. Planet positions and the main pictures included.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { type CSSProperties, type ReactElement } from "react";
|
|
2
2
|
import "../app/style.css";
|
|
3
3
|
import type { DataSource, Scene } from "./scene.js";
|
|
4
|
+
import { type TimeInput } from "./time.js";
|
|
5
|
+
import { type ViewerChange } from "./viewerLink.js";
|
|
4
6
|
/** Props of `AstraeusScene`. */
|
|
5
7
|
export interface AstraeusSceneProps {
|
|
6
8
|
/** The scene to draw. Passing a different `Scene` object rebuilds the viewer; changing the same object in place does not. */
|
|
@@ -11,6 +13,12 @@ export interface AstraeusSceneProps {
|
|
|
11
13
|
readonly onReady?: () => void;
|
|
12
14
|
/** Called when the scene cannot be built (a `SceneError`) or its data fails to load. */
|
|
13
15
|
readonly onError?: (error: Error) => void;
|
|
16
|
+
/** Moves the viewer to this moment (ISO text, a `Date` or Unix milliseconds) once it is drawn, and again whenever the moment changes. Outside the timeline reports `bad-time` to `onError`. Not a controlled value: the viewer keeps running from there, so the current time arrives through `onChange`. */
|
|
17
|
+
readonly time?: TimeInput;
|
|
18
|
+
/** Sets the playback speed once drawn and whenever it changes; must be one of the speeds the timeline offers (or `"auto"`, to hand it back to the scene's pacing), else `bad-timeline` goes to `onError`. */
|
|
19
|
+
readonly rate?: number | "auto";
|
|
20
|
+
/** Called whenever the viewer's time, speed or playing state changes: playback running, a visitor using the timeline, or the `time` / `rate` props. About ten times a second while playing. */
|
|
21
|
+
readonly onChange?: (change: ViewerChange) => void;
|
|
14
22
|
/** Class for the wrapper element, which fills its parent's width and height unless `style` says otherwise. */
|
|
15
23
|
readonly className?: string;
|
|
16
24
|
/** Style for the wrapper element. */
|
|
@@ -24,4 +32,4 @@ export interface AstraeusSceneProps {
|
|
|
24
32
|
* return <div style={{ height: "100vh" }}><AstraeusScene scene={scene} onError={console.error} /></div>;
|
|
25
33
|
* }
|
|
26
34
|
*/
|
|
27
|
-
export declare function AstraeusScene({ scene, data, onReady, onError, className, style }: AstraeusSceneProps): ReactElement;
|
|
35
|
+
export declare function AstraeusScene({ scene, data, onReady, onError, time, rate, onChange, className, style }: AstraeusSceneProps): ReactElement;
|
package/src/api/AstraeusScene.js
CHANGED
|
@@ -3,6 +3,7 @@ import { useEffect, useRef, useState } from "react";
|
|
|
3
3
|
import "../app/style.css";
|
|
4
4
|
import { App } from "../app/App.js";
|
|
5
5
|
import { prepareScene } from "./prepared.js";
|
|
6
|
+
import { ViewerLink } from "./viewerLink.js";
|
|
6
7
|
const FILL = { width: "100%", height: "100%" };
|
|
7
8
|
const asError = (cause) => (cause instanceof Error ? cause : new Error(String(cause)));
|
|
8
9
|
/**
|
|
@@ -13,11 +14,32 @@ const asError = (cause) => (cause instanceof Error ? cause : new Error(String(ca
|
|
|
13
14
|
* return <div style={{ height: "100vh" }}><AstraeusScene scene={scene} onError={console.error} /></div>;
|
|
14
15
|
* }
|
|
15
16
|
*/
|
|
16
|
-
export function AstraeusScene({ scene, data, onReady, onError, className, style }) {
|
|
17
|
+
export function AstraeusScene({ scene, data, onReady, onError, time, rate, onChange, className, style }) {
|
|
17
18
|
const [definition, setDefinition] = useState();
|
|
18
19
|
// The latest data and callbacks, read when the scene is built, so a new array or arrow function each render does not rebuild it.
|
|
19
|
-
const latest = useRef({ data, onReady, onError });
|
|
20
|
-
latest.current = { data, onReady, onError };
|
|
20
|
+
const latest = useRef({ data, onReady, onError, onChange });
|
|
21
|
+
latest.current = { data, onReady, onError, onChange };
|
|
22
|
+
const [link] = useState(() => new ViewerLink());
|
|
23
|
+
useEffect(() => {
|
|
24
|
+
const stop = link.onChange((change) => latest.current.onChange?.(change));
|
|
25
|
+
return () => { stop(); link.close(); };
|
|
26
|
+
}, [link]);
|
|
27
|
+
// A Date made fresh each render must not seek again, so the moment is compared by value.
|
|
28
|
+
const timeKey = time instanceof Date ? time.getTime() : time;
|
|
29
|
+
// After the viewer is drawn (its own effects have attached the clock by now), the props take effect.
|
|
30
|
+
useEffect(() => {
|
|
31
|
+
if (definition === undefined)
|
|
32
|
+
return;
|
|
33
|
+
try {
|
|
34
|
+
if (timeKey !== undefined)
|
|
35
|
+
link.setTime(timeKey);
|
|
36
|
+
if (rate !== undefined)
|
|
37
|
+
link.setRate(rate);
|
|
38
|
+
}
|
|
39
|
+
catch (cause) {
|
|
40
|
+
latest.current.onError?.(asError(cause));
|
|
41
|
+
}
|
|
42
|
+
}, [definition, link, timeKey, rate]);
|
|
21
43
|
useEffect(() => {
|
|
22
44
|
let open = true;
|
|
23
45
|
setDefinition(undefined);
|
|
@@ -34,5 +56,5 @@ export function AstraeusScene({ scene, data, onReady, onError, className, style
|
|
|
34
56
|
}
|
|
35
57
|
return () => { open = false; };
|
|
36
58
|
}, [scene]);
|
|
37
|
-
return _jsx("div", { className: className, style: { ...FILL, isolation: "isolate", ...style }, children: definition ? _jsx(App, { definition: definition, writeTitle: false }) : null });
|
|
59
|
+
return _jsx("div", { className: className, style: { ...FILL, isolation: "isolate", ...style }, children: definition ? _jsx(App, { definition: definition, writeTitle: false, host: link }) : null });
|
|
38
60
|
}
|
|
@@ -2,6 +2,7 @@ import { jsx as _jsx } from "react/jsx-runtime";
|
|
|
2
2
|
import { useEffect, useRef, useState } from "react";
|
|
3
3
|
import { App } from "../app/App.node.js";
|
|
4
4
|
import { prepareScene } from "./prepared.js";
|
|
5
|
+
import { ViewerLink } from "./viewerLink.js";
|
|
5
6
|
const FILL = { width: "100%", height: "100%" };
|
|
6
7
|
const asError = (cause) => (cause instanceof Error ? cause : new Error(String(cause)));
|
|
7
8
|
/**
|
|
@@ -12,11 +13,32 @@ const asError = (cause) => (cause instanceof Error ? cause : new Error(String(ca
|
|
|
12
13
|
* return <div style={{ height: "100vh" }}><AstraeusScene scene={scene} onError={console.error} /></div>;
|
|
13
14
|
* }
|
|
14
15
|
*/
|
|
15
|
-
export function AstraeusScene({ scene, data, onReady, onError, className, style }) {
|
|
16
|
+
export function AstraeusScene({ scene, data, onReady, onError, time, rate, onChange, className, style }) {
|
|
16
17
|
const [definition, setDefinition] = useState();
|
|
17
18
|
// The latest data and callbacks, read when the scene is built, so a new array or arrow function each render does not rebuild it.
|
|
18
|
-
const latest = useRef({ data, onReady, onError });
|
|
19
|
-
latest.current = { data, onReady, onError };
|
|
19
|
+
const latest = useRef({ data, onReady, onError, onChange });
|
|
20
|
+
latest.current = { data, onReady, onError, onChange };
|
|
21
|
+
const [link] = useState(() => new ViewerLink());
|
|
22
|
+
useEffect(() => {
|
|
23
|
+
const stop = link.onChange((change) => latest.current.onChange?.(change));
|
|
24
|
+
return () => { stop(); link.close(); };
|
|
25
|
+
}, [link]);
|
|
26
|
+
// A Date made fresh each render must not seek again, so the moment is compared by value.
|
|
27
|
+
const timeKey = time instanceof Date ? time.getTime() : time;
|
|
28
|
+
// After the viewer is drawn (its own effects have attached the clock by now), the props take effect.
|
|
29
|
+
useEffect(() => {
|
|
30
|
+
if (definition === undefined)
|
|
31
|
+
return;
|
|
32
|
+
try {
|
|
33
|
+
if (timeKey !== undefined)
|
|
34
|
+
link.setTime(timeKey);
|
|
35
|
+
if (rate !== undefined)
|
|
36
|
+
link.setRate(rate);
|
|
37
|
+
}
|
|
38
|
+
catch (cause) {
|
|
39
|
+
latest.current.onError?.(asError(cause));
|
|
40
|
+
}
|
|
41
|
+
}, [definition, link, timeKey, rate]);
|
|
20
42
|
useEffect(() => {
|
|
21
43
|
let open = true;
|
|
22
44
|
setDefinition(undefined);
|
|
@@ -33,5 +55,5 @@ export function AstraeusScene({ scene, data, onReady, onError, className, style
|
|
|
33
55
|
}
|
|
34
56
|
return () => { open = false; };
|
|
35
57
|
}, [scene]);
|
|
36
|
-
return _jsx("div", { className: className, style: { ...FILL, isolation: "isolate", ...style }, children: definition ? _jsx(App, { definition: definition, writeTitle: false }) : null });
|
|
58
|
+
return _jsx("div", { className: className, style: { ...FILL, isolation: "isolate", ...style }, children: definition ? _jsx(App, { definition: definition, writeTitle: false, host: link }) : null });
|
|
37
59
|
}
|
package/src/api/activity.d.ts
CHANGED
|
@@ -22,7 +22,7 @@ export interface ActivityInput {
|
|
|
22
22
|
readonly id: string;
|
|
23
23
|
/** Name shown on the timeline and with the rate bar. */
|
|
24
24
|
readonly label: string;
|
|
25
|
-
/** What the rate counts, per unit of time, such as "
|
|
25
|
+
/** What the rate counts, per unit of time, such as "events per hour". */
|
|
26
26
|
readonly unit: string;
|
|
27
27
|
/** The first and last moment of the activity. The curve's samples lie inside it, and the rate is unavailable outside it. */
|
|
28
28
|
readonly start: TimeInput;
|
package/src/api/activity.js
CHANGED
|
@@ -12,7 +12,7 @@ function checkFields(input) {
|
|
|
12
12
|
if (!isText(input.label))
|
|
13
13
|
throw bad(id, "the activity needs a non-empty label");
|
|
14
14
|
if (!isText(input.unit))
|
|
15
|
-
throw bad(id, "the activity needs a unit such as \"
|
|
15
|
+
throw bad(id, "the activity needs a unit such as \"events per hour\"");
|
|
16
16
|
if (!Array.isArray(input.samples) || input.samples.length < 2)
|
|
17
17
|
throw bad(id, "the curve needs at least two samples");
|
|
18
18
|
if (input.peakLabel !== undefined && !isText(input.peakLabel))
|
package/src/api/bodies.d.ts
CHANGED
|
@@ -15,6 +15,8 @@ export declare const venus: BodyRef;
|
|
|
15
15
|
export declare const earth: BodyRef;
|
|
16
16
|
/** Moon. */
|
|
17
17
|
export declare const moon: BodyRef;
|
|
18
|
+
/** The scene centre when a path is added before any body: Earth, the documented default (the only place the fallback is named; ARCH-06). */
|
|
19
|
+
export declare const FALLBACK_SCENE_CENTRE: BodyId;
|
|
18
20
|
/** Mars. */
|
|
19
21
|
export declare const mars: BodyRef;
|
|
20
22
|
/** Jupiter. */
|
package/src/api/bodies.js
CHANGED
|
@@ -9,6 +9,8 @@ export const venus = ref("venus", "Venus");
|
|
|
9
9
|
export const earth = ref("earth", "Earth");
|
|
10
10
|
/** Moon. */
|
|
11
11
|
export const moon = ref("moon", "Moon");
|
|
12
|
+
/** The scene centre when a path is added before any body: Earth, the documented default (the only place the fallback is named; ARCH-06). */
|
|
13
|
+
export const FALLBACK_SCENE_CENTRE = earth.id;
|
|
12
14
|
/** Mars. */
|
|
13
15
|
export const mars = ref("mars", "Mars");
|
|
14
16
|
/** Jupiter. */
|
package/src/api/data.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { JUPITER_MOON_SYSTEM } from "../core/bodies/jupiterMoons.js";
|
|
2
2
|
import { MARS_MOON_SYSTEM, NEPTUNE_MOON_SYSTEM, PLUTO_MOON_SYSTEM, SATURN_MOON_SYSTEM, URANUS_MOON_SYSTEM } from "../core/bodies/planetMoons.js";
|
|
3
|
+
import { MoonOutOfSpanError } from "../core/bodies/moonSystem.js";
|
|
3
4
|
import { catalogue } from "../assets/catalogue.js";
|
|
5
|
+
import { SceneError } from "./errors.js";
|
|
4
6
|
import { registerPictures } from "../assets/pictures.js";
|
|
5
7
|
const SYSTEMS = {
|
|
6
8
|
jupiter: JUPITER_MOON_SYSTEM,
|
|
@@ -27,8 +29,16 @@ export async function installData(data, sceneBodies, window) {
|
|
|
27
29
|
system.provideIndex(positions.loadIndex);
|
|
28
30
|
const moons = sceneBodies.filter((id) => catalogue.has(id) && catalogue.get(id).definition.parentId === positions.centre);
|
|
29
31
|
if (moons.length > 0)
|
|
30
|
-
await system.load({ window, bodies: moons, chunkUrls: positions.chunkUrls });
|
|
32
|
+
await system.load({ window, bodies: moons, chunkUrls: positions.chunkUrls }).catch(outOfSpan(source.name));
|
|
31
33
|
}
|
|
32
34
|
for (const source of data)
|
|
33
35
|
await source.prepare?.();
|
|
34
36
|
}
|
|
37
|
+
/** Turns a moon's span refusal into the public error, naming the package that holds the positions (once: the load promise is shared). */
|
|
38
|
+
function outOfSpan(packageName) {
|
|
39
|
+
return (error) => {
|
|
40
|
+
if (error instanceof MoonOutOfSpanError)
|
|
41
|
+
throw new SceneError("out-of-span", `${error.body} is outside the years ${packageName} covers: ${error.message}; set the timeline inside that span, or refit the data for the longer years`);
|
|
42
|
+
throw error;
|
|
43
|
+
};
|
|
44
|
+
}
|
package/src/api/errors.d.ts
CHANGED
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
/** Why a scene call was refused; `code` is stable so a caller can branch on it. */
|
|
2
|
-
export type SceneErrorCode = "unknown-body" | "duplicate-id" | "bad-time" | "bad-trajectory" | "bad-scale" | "missing-data" | "empty-scene" | "bad-element" | "no-orbit" | "bad-anchor" | "bad-readout" | "bad-event" | "bad-panels" | "bad-timeline" | "bad-switch" | "bad-body" | "bad-group" | "bad-activity" | "bad-camera";
|
|
2
|
+
export type SceneErrorCode = "unknown-body" | "duplicate-id" | "bad-time" | "bad-trajectory" | "bad-scale" | "missing-data" | "out-of-span" | "empty-scene" | "bad-element" | "no-orbit" | "bad-anchor" | "bad-readout" | "bad-event" | "bad-panels" | "bad-timeline" | "bad-switch" | "bad-body" | "bad-group" | "bad-activity" | "bad-camera";
|
|
3
3
|
/** The one error the public API throws for bad input; the message names the offending value. */
|
|
4
4
|
export declare class SceneError extends RangeError {
|
|
5
5
|
readonly code: SceneErrorCode;
|
package/src/api/index.d.ts
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
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";
|
|
2
|
+
export { type EventInput, type AddEventsOptions, type TimelineInput, type PacingInput, type StoryPanelsInput } from "./story.js";
|
|
3
3
|
export { type SwitchesInput } from "./switches.js";
|
|
4
4
|
export { mount, type MountOptions, type MountedScene } from "./mount.js";
|
|
5
5
|
export { AstraeusScene, type AstraeusSceneProps } from "./AstraeusScene.js";
|
|
6
|
+
export { type ViewerChange, type RateSource } from "./viewerLink.js";
|
|
6
7
|
export { SceneError, type SceneErrorCode } from "./errors.js";
|
|
7
8
|
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";
|
|
8
|
-
export { trueScale, readableScale, type ScalePolicy } from "../core/scalePolicy.js";
|
|
9
|
+
export { trueScale, readableScale, solarSystemScale, type ScalePolicy } from "../core/scalePolicy.js";
|
|
9
10
|
export type { State } from "../core/state.js";
|
|
10
11
|
export type { Provenance, ProvenanceSourceType } from "../core/provenance.js";
|
|
11
12
|
export type { Pictures } from "../assets/pictures.js";
|
package/src/api/index.js
CHANGED
|
@@ -4,5 +4,5 @@ export { mount } from "./mount.js";
|
|
|
4
4
|
export { AstraeusScene } from "./AstraeusScene.js";
|
|
5
5
|
export { SceneError } from "./errors.js";
|
|
6
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";
|
|
7
|
+
export { trueScale, readableScale, solarSystemScale } from "../core/scalePolicy.js";
|
|
8
8
|
export { APPROXIMATE_LIMIT_FRACTION, INDICATIVE_LIMIT_FRACTION, classifyPositionError, parseElementsBodyRecord } from "../core/elementsBody.js";
|
package/src/api/index.node.js
CHANGED
|
@@ -4,5 +4,5 @@ export { mount } from "./mount.node.js";
|
|
|
4
4
|
export { AstraeusScene } from "./AstraeusScene.node.js";
|
|
5
5
|
export { SceneError } from "./errors.js";
|
|
6
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";
|
|
7
|
+
export { trueScale, readableScale, solarSystemScale } from "../core/scalePolicy.js";
|
|
8
8
|
export { APPROXIMATE_LIMIT_FRACTION, INDICATIVE_LIMIT_FRACTION, classifyPositionError, parseElementsBodyRecord } from "../core/elementsBody.js";
|
package/src/api/mount.d.ts
CHANGED
|
@@ -1,9 +1,13 @@
|
|
|
1
1
|
import "../app/style.css";
|
|
2
2
|
import type { DataSource, Scene } from "./scene.js";
|
|
3
|
+
import type { TimeInput } from "./time.js";
|
|
4
|
+
import { type ViewerChange } from "./viewerLink.js";
|
|
3
5
|
/** Options of `mount`. */
|
|
4
6
|
export interface MountOptions {
|
|
5
7
|
/** Data packages the scene's bodies need, such as moon pictures or positions; nothing is looked up behind the caller's back. */
|
|
6
8
|
readonly data?: readonly DataSource[];
|
|
9
|
+
/** Called whenever the viewer's time, speed or playing state changes: playback running, a visitor using the timeline, or the host's own `setTime` / `setRate`. About ten times a second while playing. */
|
|
10
|
+
readonly onChange?: (change: ViewerChange) => void;
|
|
7
11
|
}
|
|
8
12
|
/** What `mount` returns. */
|
|
9
13
|
export interface MountedScene {
|
|
@@ -11,6 +15,16 @@ export interface MountedScene {
|
|
|
11
15
|
readonly ready: Promise<void>;
|
|
12
16
|
/** Removes the scene, its canvas and its listeners from the page. Safe to call twice. */
|
|
13
17
|
unmount(): void;
|
|
18
|
+
/** The viewer's time in Unix milliseconds UTC; undefined until `ready` has resolved and after `unmount`. */
|
|
19
|
+
readonly time: number | undefined;
|
|
20
|
+
/** The playback speed (simulated seconds per real second); undefined like `time`. */
|
|
21
|
+
readonly rate: number | undefined;
|
|
22
|
+
/** Moves the viewer to `time` (ISO text, a `Date` or Unix milliseconds). Outside the timeline throws `bad-time`; before `ready` or after `unmount` throws `missing-data`. */
|
|
23
|
+
setTime(time: TimeInput): void;
|
|
24
|
+
/** Sets the playback speed to one of the speeds the timeline offers (`setTimeline({ rates })`); any other number throws `bad-timeline`. `"auto"` gives the speed back to the scene's `setTimeline({ pacing })` (throws `bad-timeline` when it has none). Before `ready` or after `unmount` throws `missing-data`. */
|
|
25
|
+
setRate(rate: number | "auto"): void;
|
|
26
|
+
/** Calls `listener` on every change (see `MountOptions.onChange`); returns the function that stops it. No callbacks arrive after `unmount`. */
|
|
27
|
+
onChange(listener: (change: ViewerChange) => void): () => void;
|
|
14
28
|
}
|
|
15
29
|
/**
|
|
16
30
|
* Draws `scene` into `element` with the full viewer. The caller writes no React. The element needs a size.
|
|
@@ -19,6 +33,8 @@ export interface MountedScene {
|
|
|
19
33
|
* const scene = new Scene().addBody(earth).addBody(moon, { orbit: true });
|
|
20
34
|
* const mounted = mount(document.getElementById("app")!, scene);
|
|
21
35
|
* await mounted.ready; // drawn
|
|
36
|
+
* mounted.setTime("2026-08-12T21:00:00Z"); // the viewer moves there; outside the timeline throws bad-time
|
|
37
|
+
* mounted.onChange(({ time, rate }) => console.log(new Date(time).toISOString(), rate));
|
|
22
38
|
* mounted.unmount(); // removes it again
|
|
23
39
|
*/
|
|
24
40
|
export declare function mount(element: HTMLElement, scene: Scene, options?: MountOptions): MountedScene;
|
package/src/api/mount.js
CHANGED
|
@@ -4,6 +4,7 @@ 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
|
+
import { ViewerLink } from "./viewerLink.js";
|
|
7
8
|
/**
|
|
8
9
|
* Draws `scene` into `element` with the full viewer. The caller writes no React. The element needs a size.
|
|
9
10
|
* @example
|
|
@@ -11,6 +12,8 @@ import { prepareScene } from "./prepared.js";
|
|
|
11
12
|
* const scene = new Scene().addBody(earth).addBody(moon, { orbit: true });
|
|
12
13
|
* const mounted = mount(document.getElementById("app")!, scene);
|
|
13
14
|
* await mounted.ready; // drawn
|
|
15
|
+
* mounted.setTime("2026-08-12T21:00:00Z"); // the viewer moves there; outside the timeline throws bad-time
|
|
16
|
+
* mounted.onChange(({ time, rate }) => console.log(new Date(time).toISOString(), rate));
|
|
14
17
|
* mounted.unmount(); // removes it again
|
|
15
18
|
*/
|
|
16
19
|
export function mount(element, scene, options = {}) {
|
|
@@ -21,16 +24,25 @@ export function mount(element, scene, options = {}) {
|
|
|
21
24
|
element.style.isolation = "isolate";
|
|
22
25
|
const root = createRoot(element);
|
|
23
26
|
let open = true;
|
|
27
|
+
const link = new ViewerLink();
|
|
28
|
+
if (options.onChange !== undefined)
|
|
29
|
+
link.onChange(options.onChange);
|
|
24
30
|
const ready = loaded.then(() => {
|
|
25
31
|
if (open)
|
|
26
|
-
root.render(createElement(App, { definition, writeTitle: false }));
|
|
32
|
+
root.render(createElement(App, { definition, writeTitle: false, host: link }));
|
|
27
33
|
});
|
|
28
34
|
return {
|
|
29
35
|
ready,
|
|
36
|
+
get time() { return link.time; },
|
|
37
|
+
get rate() { return link.rate; },
|
|
38
|
+
setTime: (time) => link.setTime(time),
|
|
39
|
+
setRate: (rate) => link.setRate(rate),
|
|
40
|
+
onChange: (listener) => link.onChange(listener),
|
|
30
41
|
unmount() {
|
|
31
42
|
if (!open)
|
|
32
43
|
return;
|
|
33
44
|
open = false;
|
|
45
|
+
link.close();
|
|
34
46
|
root.unmount();
|
|
35
47
|
},
|
|
36
48
|
};
|
package/src/api/mount.node.js
CHANGED
|
@@ -3,6 +3,7 @@ import { createRoot } from "react-dom/client";
|
|
|
3
3
|
import { App } from "../app/App.node.js";
|
|
4
4
|
import { SceneError } from "./errors.js";
|
|
5
5
|
import { prepareScene } from "./prepared.js";
|
|
6
|
+
import { ViewerLink } from "./viewerLink.js";
|
|
6
7
|
/**
|
|
7
8
|
* Draws `scene` into `element` with the full viewer. The caller writes no React. The element needs a size.
|
|
8
9
|
* @example
|
|
@@ -10,6 +11,8 @@ import { prepareScene } from "./prepared.js";
|
|
|
10
11
|
* const scene = new Scene().addBody(earth).addBody(moon, { orbit: true });
|
|
11
12
|
* const mounted = mount(document.getElementById("app")!, scene);
|
|
12
13
|
* await mounted.ready; // drawn
|
|
14
|
+
* mounted.setTime("2026-08-12T21:00:00Z"); // the viewer moves there; outside the timeline throws bad-time
|
|
15
|
+
* mounted.onChange(({ time, rate }) => console.log(new Date(time).toISOString(), rate));
|
|
13
16
|
* mounted.unmount(); // removes it again
|
|
14
17
|
*/
|
|
15
18
|
export function mount(element, scene, options = {}) {
|
|
@@ -20,16 +23,25 @@ export function mount(element, scene, options = {}) {
|
|
|
20
23
|
element.style.isolation = "isolate";
|
|
21
24
|
const root = createRoot(element);
|
|
22
25
|
let open = true;
|
|
26
|
+
const link = new ViewerLink();
|
|
27
|
+
if (options.onChange !== undefined)
|
|
28
|
+
link.onChange(options.onChange);
|
|
23
29
|
const ready = loaded.then(() => {
|
|
24
30
|
if (open)
|
|
25
|
-
root.render(createElement(App, { definition, writeTitle: false }));
|
|
31
|
+
root.render(createElement(App, { definition, writeTitle: false, host: link }));
|
|
26
32
|
});
|
|
27
33
|
return {
|
|
28
34
|
ready,
|
|
35
|
+
get time() { return link.time; },
|
|
36
|
+
get rate() { return link.rate; },
|
|
37
|
+
setTime: (time) => link.setTime(time),
|
|
38
|
+
setRate: (rate) => link.setRate(rate),
|
|
39
|
+
onChange: (listener) => link.onChange(listener),
|
|
29
40
|
unmount() {
|
|
30
41
|
if (!open)
|
|
31
42
|
return;
|
|
32
43
|
open = false;
|
|
44
|
+
link.close();
|
|
33
45
|
root.unmount();
|
|
34
46
|
},
|
|
35
47
|
};
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
import type { WindowProvenanceSpan } from "../core/timeWindow.js";
|
|
2
|
+
import type { ActivitySourceInput } from "./activity.js";
|
|
3
|
+
/**
|
|
4
|
+
* Checks a path's provenance by time span (the same `{ start, end, provenance }` shape as an activity's) and returns it in milliseconds.
|
|
5
|
+
* Spans are sorted, do not overlap and lie inside the path's bounds; any fault is a `bad-trajectory` naming the path and the span's index.
|
|
6
|
+
*/
|
|
7
|
+
export declare function planPathProvenance(id: string, spans: readonly ActivitySourceInput[], boundsUtcMs: {
|
|
8
|
+
readonly startUtcMs: number;
|
|
9
|
+
readonly endUtcMs: number;
|
|
10
|
+
}): readonly WindowProvenanceSpan[];
|
|
@@ -0,0 +1,34 @@
|
|
|
1
|
+
import { createProvenance } from "../core/provenance.js";
|
|
2
|
+
import { SceneError } from "./errors.js";
|
|
3
|
+
import { toUtcMs } from "./time.js";
|
|
4
|
+
/**
|
|
5
|
+
* Checks a path's provenance by time span (the same `{ start, end, provenance }` shape as an activity's) and returns it in milliseconds.
|
|
6
|
+
* Spans are sorted, do not overlap and lie inside the path's bounds; any fault is a `bad-trajectory` naming the path and the span's index.
|
|
7
|
+
*/
|
|
8
|
+
export function planPathProvenance(id, spans, boundsUtcMs) {
|
|
9
|
+
const bad = (index, message) => new SceneError("bad-trajectory", `addTrajectory("${id}"): provenanceSpans[${index}] ${message}`);
|
|
10
|
+
if (!Array.isArray(spans))
|
|
11
|
+
throw new SceneError("bad-trajectory", `addTrajectory("${id}"): provenanceSpans must be a list`);
|
|
12
|
+
let previousEnd = -Infinity;
|
|
13
|
+
return spans.map((span, index) => {
|
|
14
|
+
let startUtcMs;
|
|
15
|
+
let endUtcMs;
|
|
16
|
+
let provenance;
|
|
17
|
+
try {
|
|
18
|
+
startUtcMs = toUtcMs(span?.start, `addTrajectory("${id}") provenanceSpans[${index}] start`);
|
|
19
|
+
endUtcMs = toUtcMs(span?.end, `addTrajectory("${id}") provenanceSpans[${index}] end`);
|
|
20
|
+
provenance = createProvenance(span?.provenance);
|
|
21
|
+
}
|
|
22
|
+
catch (error) {
|
|
23
|
+
throw bad(index, error instanceof Error ? error.message : String(error));
|
|
24
|
+
}
|
|
25
|
+
if (endUtcMs <= startUtcMs)
|
|
26
|
+
throw bad(index, "must end after it starts");
|
|
27
|
+
if (startUtcMs < boundsUtcMs.startUtcMs || endUtcMs > boundsUtcMs.endUtcMs)
|
|
28
|
+
throw bad(index, "lies outside the path");
|
|
29
|
+
if (startUtcMs < previousEnd)
|
|
30
|
+
throw bad(index, "overlaps or is out of order; spans must be sorted and not overlap");
|
|
31
|
+
previousEnd = endUtcMs;
|
|
32
|
+
return { startUtcMs, endUtcMs, provenance };
|
|
33
|
+
});
|
|
34
|
+
}
|
package/src/api/scene.d.ts
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
1
|
import type { BodyId } from "../core/body.js";
|
|
2
2
|
import { type Provenance } from "../core/provenance.js";
|
|
3
|
+
import type { ActivitySourceInput } from "./activity.js";
|
|
3
4
|
import { type ScalePolicy } from "../core/scalePolicy.js";
|
|
4
|
-
import type
|
|
5
|
+
import { type State } from "../core/state.js";
|
|
5
6
|
import { type ElementsBodyRecord } from "../core/elementsBody.js";
|
|
6
7
|
import type { ExperienceDefinition } from "../app/experienceDefinition.js";
|
|
7
8
|
import { type BodyRef } from "./bodies.js";
|
|
@@ -27,6 +28,8 @@ export interface AddBodyOptions {
|
|
|
27
28
|
readonly enlarge?: number;
|
|
28
29
|
/** 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
30
|
readonly showLabel?: boolean;
|
|
31
|
+
/** How far from the camera the body's label shows, in the camera's `distance` units (as `camera.setReach`); a positive finite number. When absent the scene's shared rule applies: no limit in a Sun-centred or fitted scene, else the camera reach (at least 500). */
|
|
32
|
+
readonly labelReach?: number;
|
|
30
33
|
/** One or two plain sentences for the body's info card. */
|
|
31
34
|
readonly description?: string;
|
|
32
35
|
/** 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`. */
|
|
@@ -56,7 +59,7 @@ export type ReadoutInput = {
|
|
|
56
59
|
readonly kind: "altitude";
|
|
57
60
|
readonly above: BodyId;
|
|
58
61
|
};
|
|
59
|
-
/** One sample of a recorded path: position in km (and optionally velocity in km/s) about the trajectory's centre
|
|
62
|
+
/** One sample of a recorded path: position in km (and optionally velocity in km/s) about the trajectory's centre, in equatorial J2000 (EQJ) axes unless the path says `plane: "ecliptic-j2000"`. */
|
|
60
63
|
export interface TrajectorySampleInput {
|
|
61
64
|
readonly time: TimeInput;
|
|
62
65
|
readonly positionKm: ArrayLike<number>;
|
|
@@ -66,9 +69,27 @@ interface TrajectoryBase {
|
|
|
66
69
|
readonly id: string;
|
|
67
70
|
readonly label?: string;
|
|
68
71
|
readonly color?: string;
|
|
69
|
-
/** The body the positions are measured from; defaults to "earth". */
|
|
72
|
+
/** The body the positions are measured from; defaults to the scene's centre (its first body, whichever you add first; "earth" if none is a catalogued body). */
|
|
70
73
|
readonly center?: BodyId;
|
|
74
|
+
/**
|
|
75
|
+
* The body the path's line is drawn against: each sample is placed from this body at the sample's own time, then the line is carried to
|
|
76
|
+
* this body's place from the scene centre at the clock time. Defaults to the scene centre; name the Sun for a probe crossing a Sun-centred scene.
|
|
77
|
+
* Throws `bad-trajectory` at build if the scene does not hold the body.
|
|
78
|
+
*/
|
|
79
|
+
readonly lineFixedTo?: BodyId;
|
|
80
|
+
/**
|
|
81
|
+
* The frame the positions and velocities are given in, about `center`: "EQJ" (equatorial J2000, the default) or "ecliptic-j2000" (the vectors JPL Horizons
|
|
82
|
+
* publishes by default). Ecliptic input is rotated to EQJ once, as it is read, so drawing, `stateOf` and readouts all see EQJ. Any other value throws `bad-trajectory`.
|
|
83
|
+
*/
|
|
84
|
+
readonly plane?: "EQJ" | "ecliptic-j2000";
|
|
85
|
+
/** How far from the camera the path's label shows, in the camera's `distance` units (as `camera.setReach`); a positive finite number. When absent the scene's shared rule applies: no limit in a Sun-centred or fitted scene, else the camera reach (at least 500). */
|
|
86
|
+
readonly labelReach?: number;
|
|
71
87
|
readonly provenance?: Provenance;
|
|
88
|
+
/**
|
|
89
|
+
* Where each stretch of the path comes from, shown with the path as time moves (the same `{ start, end, provenance }` list as an activity's `provenance`).
|
|
90
|
+
* Sorted, not overlapping, inside the path's span; a fault throws `bad-trajectory` naming the index. Where no span covers the time, `provenance` (or the illustrative default) shows.
|
|
91
|
+
*/
|
|
92
|
+
readonly provenanceSpans?: readonly ActivitySourceInput[];
|
|
72
93
|
/** One or two plain sentences for the path's info card. */
|
|
73
94
|
readonly description?: string;
|
|
74
95
|
/** Published limits of the data, shown with the provenance. */
|
|
@@ -175,7 +196,7 @@ export declare class Scene {
|
|
|
175
196
|
addActivity(input: ActivityInput): this;
|
|
176
197
|
/** Sets the moment the scene opens at. */
|
|
177
198
|
setTime(time: TimeInput): this;
|
|
178
|
-
/** Chooses the opening scale: `trueScale` or `
|
|
199
|
+
/** 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. */
|
|
179
200
|
setScale(scale: ScalePolicy, options?: {
|
|
180
201
|
readonly only?: boolean;
|
|
181
202
|
}): this;
|
|
@@ -186,7 +207,7 @@ export declare class Scene {
|
|
|
186
207
|
* (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
208
|
*/
|
|
188
209
|
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. */
|
|
210
|
+
/** 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 `{ from, to, rate }` and event rules `{ near: { type, within }, 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. */
|
|
190
211
|
setTimeline(timeline: TimelineInput): this;
|
|
191
212
|
/**
|
|
192
213
|
* 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
|