astraeus 0.8.0 → 0.9.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 +80 -0
- package/README.md +46 -17
- package/data/ephemerides/planets/planets.json +1 -1
- package/package.json +1 -1
- package/src/api/AstraeusScene.d.ts +1 -1
- package/src/api/AstraeusScene.js +4 -1
- package/src/api/AstraeusScene.node.js +4 -1
- package/src/api/assembleScene.d.ts +2 -0
- package/src/api/assembleScene.js +27 -5
- package/src/api/cameraRequest.d.ts +15 -0
- package/src/api/cameraRequest.js +89 -0
- package/src/api/errors.d.ts +10 -0
- package/src/api/index.d.ts +6 -3
- package/src/api/look.d.ts +49 -0
- package/src/api/lookInput.d.ts +1 -1
- package/src/api/lookInput.js +6 -1
- package/src/api/planCamera.d.ts +35 -7
- package/src/api/planCamera.js +94 -11
- package/src/api/planSkyFigures.d.ts +22 -0
- package/src/api/planSkyFigures.js +145 -0
- package/src/api/planStory.d.ts +2 -2
- package/src/api/planStory.js +14 -9
- package/src/api/planViews.js +1 -1
- package/src/api/scene.d.ts +17 -4
- package/src/api/scene.js +23 -5
- package/src/api/sceneReads.d.ts +21 -2
- package/src/api/skyFigureInput.d.ts +45 -0
- package/src/api/skyFigureInput.js +1 -0
- package/src/api/skyTraceInput.d.ts +33 -0
- package/src/api/skyTraceInput.js +45 -0
- package/src/api/story.d.ts +12 -3
- package/src/api/story.js +44 -1
- package/src/api/viewerCamera.d.ts +4 -3
- package/src/api/viewerCamera.js +10 -32
- package/src/api/viewerHandle.d.ts +34 -5
- package/src/api/viewerHandle.js +7 -0
- package/src/api/viewerLink.d.ts +50 -4
- package/src/api/viewerLink.js +33 -2
- package/src/api/viewerPanels.d.ts +26 -0
- package/src/api/viewerPanels.js +42 -0
- package/src/api/viewerSelection.d.ts +6 -1
- package/src/api/viewerSelection.js +15 -0
- package/src/api/views.d.ts +3 -1
- package/src/api/views.js +5 -1
- package/src/app/App.js +118 -16
- package/src/app/App.node.js +118 -16
- package/src/app/AstraeusScene.d.ts +22 -5
- package/src/app/AstraeusScene.js +3 -3
- package/src/app/CameraController.d.ts +17 -0
- package/src/app/CameraController.js +34 -9
- package/src/app/DeveloperSettings.d.ts +11 -3
- package/src/app/DeveloperSettings.js +13 -3
- package/src/app/SceneLabels.d.ts +20 -2
- package/src/app/SceneLabels.js +46 -6
- package/src/app/SkyFiguresView.d.ts +56 -0
- package/src/app/SkyFiguresView.js +242 -0
- package/src/app/StoryMarkers.d.ts +2 -2
- package/src/app/StoryMarkers.js +2 -2
- package/src/app/displaySwitches.d.ts +13 -3
- package/src/app/displaySwitches.js +17 -3
- package/src/app/experienceDefinition.d.ts +9 -3
- package/src/app/experienceDefinition.js +4 -2
- package/src/app/labelStyle.d.ts +17 -0
- package/src/app/labelStyle.js +13 -0
- package/src/app/liveLook.js +8 -0
- package/src/app/look.d.ts +9 -5
- package/src/app/look.js +11 -0
- package/src/app/lookOut.d.ts +32 -0
- package/src/app/lookOut.js +50 -0
- package/src/app/sceneCamera.d.ts +7 -3
- package/src/app/sceneCamera.js +68 -4
- package/src/app/sceneContentsHooks.d.ts +2 -1
- package/src/app/sceneContentsHooks.js +3 -2
- package/src/app/sceneFrame.d.ts +10 -1
- package/src/app/sceneFrame.js +45 -10
- package/src/app/sceneFraming.d.ts +7 -0
- package/src/app/sceneFraming.js +12 -0
- package/src/app/sceneHooks.d.ts +2 -0
- package/src/app/sceneHooks.js +4 -1
- package/src/app/scenePicking.d.ts +20 -0
- package/src/app/scenePicking.js +49 -0
- package/src/app/scenePointer.d.ts +3 -1
- package/src/app/scenePointer.js +3 -2
- package/src/app/skyFigures.d.ts +73 -0
- package/src/app/skyFigures.js +50 -0
- package/src/app/style.css +2 -1
- package/src/app/viewHiding.d.ts +2 -0
- package/src/app/viewHiding.js +7 -1
- package/src/app/viewLink.d.ts +8 -8
- package/src/app/viewLink.js +24 -4
- package/src/app/viewerPort.d.ts +32 -3
- package/src/app/views.d.ts +2 -0
- package/src/assets/sky.d.ts +13 -4
- package/src/assets/sky.js +33 -8
- package/src/assets/stars/hyg-v42-naked-eye.json +1 -1
- package/src/core/astronomyAdapter.d.ts +1 -1
- package/src/core/astronomyAdapter.js +3 -3
- package/src/core/bodies/index.js +13 -12
- package/src/core/bodies/jupiter.js +1 -1
- package/src/core/bodies/mars.js +1 -1
- package/src/core/bodies/mercury.js +1 -1
- package/src/core/bodies/moonSystem.js +1 -15
- package/src/core/bodies/outerPlanets.d.ts +2 -3
- package/src/core/bodies/outerPlanets.js +4 -13
- package/src/core/bodies/planetMoons.d.ts +0 -2
- package/src/core/bodies/planetMoons.js +1 -18
- package/src/core/bodies/planetRecords.d.ts +8 -2
- package/src/core/bodies/planetRecords.js +13 -5
- package/src/core/bodies/planetTrajectory.d.ts +21 -4
- package/src/core/bodies/planetTrajectory.js +28 -4
- package/src/core/bodies/venus.js +1 -1
- package/src/core/lookValues.d.ts +9 -0
- package/src/core/lookValues.js +24 -0
- package/src/core/planetModels.d.ts +1 -1
- package/src/core/planetModels.js +1 -1
- package/src/core/planetSeries.d.ts +2 -2
- package/src/core/planetSeries.js +1 -1
- package/src/core/readBytes.d.ts +1 -0
- package/src/core/readBytes.js +15 -0
- package/src/core/skyTrace.d.ts +49 -0
- package/src/core/skyTrace.js +39 -0
- package/src/core/startView.d.ts +39 -0
- package/src/core/startView.js +56 -0
- package/src/core/storyPanels.d.ts +51 -3
- package/src/core/storyPanels.js +52 -12
- package/src/shell/AstraeusShell.d.ts +27 -6
- package/src/shell/AstraeusShell.js +104 -18
- package/src/shell/AstraeusShell.node.js +104 -18
- package/src/shell/ObjectControls.js +11 -8
- package/src/shell/StoryPanelView.d.ts +12 -3
- package/src/shell/StoryPanelView.js +2 -2
- package/src/shell/experience.d.ts +24 -0
- package/src/shell/experience.js +4 -1
- package/src/shell/infoModel.js +9 -1
- package/src/shell/objectModel.d.ts +6 -2
- package/src/shell/objectModel.js +10 -1
- package/src/shell/phone.css +1 -1
- package/src/shell/storyPanels.d.ts +1 -1
- package/src/shell/storyPanels.js +1 -1
- package/src/shell/style.css +9 -1
- package/src/shell/topBarIcons.d.ts +1 -0
- package/src/shell/topBarIcons.js +1 -0
- package/src/shell/useStoryPanels.d.ts +9 -6
- package/src/shell/useStoryPanels.js +10 -6
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import type { Provenance } from "../core/provenance.js";
|
|
2
|
+
import type { CardFactInput } from "./scene.js";
|
|
3
|
+
import type { SkyDirection } from "./viewerLink.js";
|
|
4
|
+
/** One end of a figure's line: a catalogue star by its Hipparcos number (`{ star: 11767 }`), or a star-map position (`{ raDeg, decDeg }`, J2000 degrees). */
|
|
5
|
+
export type SkyFigureEnd = {
|
|
6
|
+
readonly star: number;
|
|
7
|
+
} | SkyDirection;
|
|
8
|
+
/**
|
|
9
|
+
* A figure or an outline drawn on the sky at infinity, as `Scene.addSkyFigures` takes it. A `"figure"` (the default) has `segments`, each a pair of ends; a `"boundary"` has `points`, a closed loop of at least three positions
|
|
10
|
+
* (the last joins the first). `labelAt` places the label; without it the label stands at the mean direction of the ends.
|
|
11
|
+
*/
|
|
12
|
+
export interface SkyFigureInput {
|
|
13
|
+
/** Unique among the scene's bodies, paths, groups, body sets and sky figures. */
|
|
14
|
+
readonly id: string;
|
|
15
|
+
/** The name drawn on the sky. */
|
|
16
|
+
readonly label: string;
|
|
17
|
+
/** `"figure"` (the default, drawn from `segments`) or `"boundary"` (drawn from `points`). The display switches `skyFigures` and `skyBoundaries` act on one kind each. */
|
|
18
|
+
readonly kind?: "figure" | "boundary";
|
|
19
|
+
/** The lines of a figure: pairs of ends. Required for a figure, refused for a boundary. */
|
|
20
|
+
readonly segments?: readonly (readonly [SkyFigureEnd, SkyFigureEnd])[];
|
|
21
|
+
/** The corners of a boundary, in order. Required for a boundary, refused for a figure. */
|
|
22
|
+
readonly points?: readonly SkyDirection[];
|
|
23
|
+
/** Where the label stands. */
|
|
24
|
+
readonly labelAt?: SkyDirection;
|
|
25
|
+
/** `"always"` (the default): the figure is drawn whenever its switch is on. `"whenTraced"`: nothing of it (lines or label) is drawn until `traceSkyFigure` starts a trace of it; the trace then draws its lines and shows its label, and `after` decides whether they stay or fade (`clearSkyTrace` removes them at any time). */
|
|
26
|
+
readonly shown?: "always" | "whenTraced";
|
|
27
|
+
/** This figure's line colour, a CSS colour text; default: the look's `skyLines.figure` or `skyLines.boundary`. */
|
|
28
|
+
readonly color?: string;
|
|
29
|
+
/** This figure's label colour, a CSS colour text; default: the look's `skyLines.label`. */
|
|
30
|
+
readonly labelColor?: string;
|
|
31
|
+
/** This figure's label font, a CSS font-family text; default: the look's `labels.fontFamily`. */
|
|
32
|
+
readonly labelFont?: string;
|
|
33
|
+
/** This figure's label size in pixels, 8 to 24; default: the look's `labels.sizePx`. */
|
|
34
|
+
readonly labelSizePx?: number;
|
|
35
|
+
/** One or two plain sentences for the figure's info card (shown when a visitor taps it or picks it from the object menu). None by default. */
|
|
36
|
+
readonly description?: string;
|
|
37
|
+
/** Labelled facts for the card, in order, as for `addBody`: both texts non-empty. None by default. */
|
|
38
|
+
readonly facts?: readonly CardFactInput[];
|
|
39
|
+
/** Sources added to the card's provenance after its own, each a non-empty text. None by default. */
|
|
40
|
+
readonly sources?: readonly string[];
|
|
41
|
+
/** Where the figure's drawn lines come from, shown on the card. Default: illustrative, supplied by the caller (as for `addTrajectory`). */
|
|
42
|
+
readonly provenance?: Provenance;
|
|
43
|
+
/** False leaves the figure out of the viewer's object menu (default true, as for `addBody`); it stays tappable and the menu shows it while it is the selected one. */
|
|
44
|
+
readonly listed?: boolean;
|
|
45
|
+
}
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
export {};
|
|
@@ -0,0 +1,33 @@
|
|
|
1
|
+
import { type SkyTraceAfter } from "../core/skyTrace.js";
|
|
2
|
+
/** What `handle.traceSkyFigure` takes besides the figure's id. */
|
|
3
|
+
export interface SkyTraceOptions {
|
|
4
|
+
/** How long the trace takes, in real seconds, 0.1 to 60 (default 2). The segments are drawn in the order they were added, each growing from its first end, each for an equal share of the time. Real time: pausing or changing the scene clock does not change it. */
|
|
5
|
+
readonly durationSeconds?: number;
|
|
6
|
+
/** What follows: `"stay"` (the default) keeps the traced lines in the look's `skyLines.traced` colour until the figure is traced again or `clearSkyTrace` removes them; `"fade"` eases them to `skyLines.faded` over a second and removes them. */
|
|
7
|
+
readonly after?: "stay" | "fade";
|
|
8
|
+
}
|
|
9
|
+
/** What `handle.clearSkyTrace` takes besides the figure's id. */
|
|
10
|
+
export interface SkyClearOptions {
|
|
11
|
+
/** How long the trace takes to fade away, in real seconds, 0 to 60 (default 1, the time a `fade` takes); 0 removes it at once. */
|
|
12
|
+
readonly durationSeconds?: number;
|
|
13
|
+
}
|
|
14
|
+
/** A checked clear request: the figure and how long its trace takes to go. */
|
|
15
|
+
export interface CheckedClear {
|
|
16
|
+
readonly id: string;
|
|
17
|
+
readonly seconds: number;
|
|
18
|
+
}
|
|
19
|
+
/** A checked trace request: the figure and what to do with it. */
|
|
20
|
+
export interface CheckedTrace {
|
|
21
|
+
readonly id: string;
|
|
22
|
+
readonly seconds: number;
|
|
23
|
+
readonly after: SkyTraceAfter;
|
|
24
|
+
}
|
|
25
|
+
/** Checks the options of a trace (`traceSkyFigure`'s, or a story panel's `trace`) and fills the defaults; throws `bad-sky-trace`. */
|
|
26
|
+
export declare function traceOptionsOf(options: unknown, verb?: string): {
|
|
27
|
+
readonly seconds: number;
|
|
28
|
+
readonly after: SkyTraceAfter;
|
|
29
|
+
};
|
|
30
|
+
/** Checks a trace request against the figures the viewer draws; throws `unknown-sky-figure` (the id) or `bad-sky-trace` (the options). */
|
|
31
|
+
export declare function checkedTrace(id: unknown, options: unknown, known: readonly string[]): CheckedTrace;
|
|
32
|
+
/** Checks a clear request as `checkedTrace` checks a trace; `durationSeconds` may be 0 (at once). */
|
|
33
|
+
export declare function checkedClear(id: unknown, options: unknown, known: readonly string[]): CheckedClear;
|
|
@@ -0,0 +1,45 @@
|
|
|
1
|
+
import { SceneError } from "./errors.js";
|
|
2
|
+
import { DEFAULT_TRACE_SECONDS, SKY_TRACE_AFTER, TRACE_FADE_SECONDS, TRACE_SECONDS_LIMITS } from "../core/skyTrace.js";
|
|
3
|
+
const bad = (message, verb = "traceSkyFigure") => new SceneError("bad-sky-trace", `${verb}: ${message}`);
|
|
4
|
+
/** Throws `unknown-sky-figure` unless `id` is one of the figures the viewer draws. */
|
|
5
|
+
function knownFigure(id, known, verb) {
|
|
6
|
+
if (typeof id !== "string" || !known.includes(id)) {
|
|
7
|
+
throw new SceneError("unknown-sky-figure", `${verb}: ${typeof id === "string" ? `"${id}"` : String(id)} is not a sky figure this viewer draws (${known.length === 0 ? "the scene added none; add them with addSkyFigures" : known.join(", ")})`);
|
|
8
|
+
}
|
|
9
|
+
}
|
|
10
|
+
/** The options object of a call as a record, or throws `bad-sky-trace` when it is neither an object nor nothing, or has a key outside `allowed`. */
|
|
11
|
+
function optionsOf(options, allowed, verb) {
|
|
12
|
+
if (options !== undefined && (typeof options !== "object" || options === null || Array.isArray(options)))
|
|
13
|
+
throw bad(`expected an options object or nothing, got ${String(options)}`, verb);
|
|
14
|
+
const given = (options ?? {});
|
|
15
|
+
for (const key of Object.keys(given))
|
|
16
|
+
if (!allowed.includes(key))
|
|
17
|
+
throw bad(`"${key}" is not an option (${allowed.join(", ")})`, verb);
|
|
18
|
+
return given;
|
|
19
|
+
}
|
|
20
|
+
/** Checks the options of a trace (`traceSkyFigure`'s, or a story panel's `trace`) and fills the defaults; throws `bad-sky-trace`. */
|
|
21
|
+
export function traceOptionsOf(options, verb = "traceSkyFigure") {
|
|
22
|
+
const given = optionsOf(options, ["durationSeconds", "after"], verb);
|
|
23
|
+
const seconds = given.durationSeconds ?? DEFAULT_TRACE_SECONDS;
|
|
24
|
+
const { min, max } = TRACE_SECONDS_LIMITS;
|
|
25
|
+
if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds < min || seconds > max)
|
|
26
|
+
throw bad(`durationSeconds must be a number from ${min} to ${max}, got ${String(seconds)}`, verb);
|
|
27
|
+
const after = given.after ?? "stay";
|
|
28
|
+
if (!SKY_TRACE_AFTER.includes(after))
|
|
29
|
+
throw bad(`after must be one of ${SKY_TRACE_AFTER.join(", ")}, got ${String(after)}`, verb);
|
|
30
|
+
return { seconds, after: after };
|
|
31
|
+
}
|
|
32
|
+
/** Checks a trace request against the figures the viewer draws; throws `unknown-sky-figure` (the id) or `bad-sky-trace` (the options). */
|
|
33
|
+
export function checkedTrace(id, options, known) {
|
|
34
|
+
knownFigure(id, known, "traceSkyFigure");
|
|
35
|
+
return { id, ...traceOptionsOf(options) };
|
|
36
|
+
}
|
|
37
|
+
/** Checks a clear request as `checkedTrace` checks a trace; `durationSeconds` may be 0 (at once). */
|
|
38
|
+
export function checkedClear(id, options, known) {
|
|
39
|
+
knownFigure(id, known, "clearSkyTrace");
|
|
40
|
+
const given = optionsOf(options, ["durationSeconds"], "clearSkyTrace");
|
|
41
|
+
const seconds = given.durationSeconds ?? TRACE_FADE_SECONDS;
|
|
42
|
+
if (typeof seconds !== "number" || !Number.isFinite(seconds) || seconds < 0 || seconds > TRACE_SECONDS_LIMITS.max)
|
|
43
|
+
throw bad(`durationSeconds must be a number from 0 to ${TRACE_SECONDS_LIMITS.max}, got ${String(seconds)}`, "clearSkyTrace");
|
|
44
|
+
return { id, seconds };
|
|
45
|
+
}
|
package/src/api/story.d.ts
CHANGED
|
@@ -3,6 +3,8 @@ import { type Pacing } from "../core/pacing.js";
|
|
|
3
3
|
import { type Provenance } from "../core/provenance.js";
|
|
4
4
|
import type { TimeBounds } from "../core/trajectory.js";
|
|
5
5
|
import { type CheckedPanel, type PanelLookup, type PanelPlayback, type StoryPanelSet } from "../core/storyPanels.js";
|
|
6
|
+
import { type SkyTraceOptions } from "./skyTraceInput.js";
|
|
7
|
+
import type { CameraTarget } from "./viewerLink.js";
|
|
6
8
|
import { type TimeInput } from "./time.js";
|
|
7
9
|
/** A timed event: a labelled moment on the timeline. The id is unique among the scene's events: a repeat throws `duplicate-id`. */
|
|
8
10
|
export interface EventInput {
|
|
@@ -13,7 +15,7 @@ export interface EventInput {
|
|
|
13
15
|
readonly type?: string;
|
|
14
16
|
/** Where this event's time comes from. Shown with the event; an event without one shows the `provenance` of `addEvents`. Malformed: `addEvents` throws "bad-event" naming the event. */
|
|
15
17
|
readonly provenance?: Provenance;
|
|
16
|
-
/** The body or
|
|
18
|
+
/** The body, trajectory or sky figure (its id) this event is about. Go to this event seeks to its time and, for a body or trajectory, frames the object as `camera.focus` does; for a sky figure it seeks, selects it and turns toward it only while the camera looks out. Not in the scene when the scene is built (`mount`): "bad-event" naming the event and the id. Without one, Go to only seeks. */
|
|
17
19
|
readonly object?: string;
|
|
18
20
|
/**
|
|
19
21
|
* Gives the event a zone of its own: from `withinSeconds` before its time to `withinSeconds` after it (simulated seconds, positive and finite). A host hears entering and leaving it
|
|
@@ -104,7 +106,8 @@ export type StoryPanelAt = {
|
|
|
104
106
|
export interface StoryPanelInput {
|
|
105
107
|
/** Unique among the scene's panels: a repeat throws `duplicate-id`. */
|
|
106
108
|
readonly id: string;
|
|
107
|
-
|
|
109
|
+
/** When the panel opens. Left out, it is a step: steps keep the order added, never open from playback, and show Back and Next. */
|
|
110
|
+
readonly at?: StoryPanelAt;
|
|
108
111
|
readonly title: string;
|
|
109
112
|
/** Paragraphs, in order; one text is one paragraph. */
|
|
110
113
|
readonly body: string | readonly string[];
|
|
@@ -112,8 +115,14 @@ export interface StoryPanelInput {
|
|
|
112
115
|
readonly details?: string | readonly string[];
|
|
113
116
|
/** Where the panel's facts come from. The badge shows the word for `sourceType`; `sources`, `accuracy` and `notes` show in the panel's folded section. `sources` is never empty and `accuracy` is never blank: where a source states none, say so. */
|
|
114
117
|
readonly provenance: Provenance;
|
|
115
|
-
/** The id of a body or
|
|
118
|
+
/** The id of a body, path or sky figure the panel is about; a body or path gets a marker that reopens the panel. */
|
|
116
119
|
readonly object?: string;
|
|
120
|
+
/** Turns the camera when the panel opens (anything `setCamera` takes). */
|
|
121
|
+
readonly camera?: CameraTarget;
|
|
122
|
+
/** True: selects the `object`. */
|
|
123
|
+
readonly select?: boolean;
|
|
124
|
+
/** Traces the `object`, a sky figure. */
|
|
125
|
+
readonly trace?: true | SkyTraceOptions;
|
|
117
126
|
}
|
|
118
127
|
/** The playback settings of a scene's story panels. */
|
|
119
128
|
export interface StoryPanelPlaybackInput {
|
package/src/api/story.js
CHANGED
|
@@ -3,6 +3,8 @@ import { zoneAround } from "../core/pacing.js";
|
|
|
3
3
|
import { createProvenance } from "../core/provenance.js";
|
|
4
4
|
import { checkPanelPlayback, checkStoryPanel, resolveStoryPanels, StoryPanelError } from "../core/storyPanels.js";
|
|
5
5
|
import { SceneError } from "./errors.js";
|
|
6
|
+
import { cameraRequestOf } from "./cameraRequest.js";
|
|
7
|
+
import { traceOptionsOf } from "./skyTraceInput.js";
|
|
6
8
|
import { rejectRenamed } from "./renamedInputs.js";
|
|
7
9
|
import { toUtcMs } from "./time.js";
|
|
8
10
|
/** Throws "bad-event" naming the first event whose `object` is not among the scene's `objectIds`. */
|
|
@@ -44,6 +46,16 @@ export function eventsOf(inputs, known) {
|
|
|
44
46
|
});
|
|
45
47
|
return createEvents([...known, ...added].sort((a, b) => a.timeUtcMs - b.timeUtcMs));
|
|
46
48
|
}
|
|
49
|
+
/** A rate that crosses the whole span in under this many real seconds is probably a unit mistake (milliseconds given for seconds). */
|
|
50
|
+
const MIN_CROSSING_REAL_SECONDS = 1;
|
|
51
|
+
/** Warns (never throws: a short span at a fast rate can be meant) when a `rate` or an offered rate crosses the whole timeline span in under a real second; I-163. */
|
|
52
|
+
function warnOfFastRates(window, input) {
|
|
53
|
+
const spanSeconds = (window.endUtcMs - window.startUtcMs) / 1000;
|
|
54
|
+
const fast = [...new Set([...(input.rates ?? []), ...(input.rate === undefined ? [] : [input.rate])].filter((rate) => spanSeconds / Math.abs(rate) < MIN_CROSSING_REAL_SECONDS))];
|
|
55
|
+
if (fast.length === 0)
|
|
56
|
+
return;
|
|
57
|
+
console.warn(`setTimeline: rate ${fast.join(", ")} is in simulated seconds per real second and would cross the whole ${spanSeconds}-second span in under a real second; if the value is in milliseconds (for example DAY_MS), divide it by 1000`);
|
|
58
|
+
}
|
|
47
59
|
/** Checks a `setTimeline` argument and converts its moments. */
|
|
48
60
|
export function timelineOf(input) {
|
|
49
61
|
const bad = (message) => new SceneError("bad-timeline", `setTimeline: ${message}`);
|
|
@@ -62,6 +74,7 @@ export function timelineOf(input) {
|
|
|
62
74
|
if (rates !== undefined && (!Array.isArray(rates) || rates.length === 0 || !rates.every((rate) => Number.isFinite(rate) && rate > 0)))
|
|
63
75
|
throw bad("rates must be a non-empty list of positive numbers");
|
|
64
76
|
const pacing = pacingOf(input.pacing, bad);
|
|
77
|
+
warnOfFastRates(window, input);
|
|
65
78
|
return { none: false, window, ...(rates === undefined ? {} : { rates }), ...(pacing === undefined ? {} : { pacing }), ...(input.rate === undefined ? {} : { rate: input.rate }), ...(input.loop === true ? { loop: true } : {}) };
|
|
66
79
|
}
|
|
67
80
|
/** Runs a core panel check, turning a `StoryPanelError` into a `bad-panels` SceneError that leads with `call`. */
|
|
@@ -86,13 +99,43 @@ export function panelBatchOf(inputs, known) {
|
|
|
86
99
|
const where = `addStoryPanels: story panel ${typeof named === "string" ? named : `#${index + 1}`}`;
|
|
87
100
|
rejectRenamed("StoryPanelInput", input, where);
|
|
88
101
|
rejectRenamed("StoryPanelAt", input?.at, `${where} at`);
|
|
89
|
-
const
|
|
102
|
+
const checked = panelCheck("addStoryPanels", () => checkStoryPanel(input, index));
|
|
103
|
+
const panel = { ...checked, ...panelActionsOf(input, checked.id, checked.object) };
|
|
90
104
|
if (ids.has(panel.id))
|
|
91
105
|
throw new SceneError("duplicate-id", `${where}: that id is already in the scene's panels`);
|
|
92
106
|
ids.add(panel.id);
|
|
93
107
|
return panel;
|
|
94
108
|
});
|
|
95
109
|
}
|
|
110
|
+
/** The actions of a panel (`camera`, `select`, `trace`), checked in shape; a mistake throws `bad-panels` naming the panel and field. What they name is checked when the scene is built. */
|
|
111
|
+
function panelActionsOf(input, id, object) {
|
|
112
|
+
const bad = (field, why) => new SceneError("bad-panels", `addStoryPanels: story panel ${id}: ${field} ${why}`);
|
|
113
|
+
let camera;
|
|
114
|
+
if (input.camera !== undefined) {
|
|
115
|
+
try {
|
|
116
|
+
camera = cameraRequestOf(input.camera, "camera", undefined, true);
|
|
117
|
+
}
|
|
118
|
+
catch (error) {
|
|
119
|
+
throw bad("camera", `is not a camera target (${error instanceof Error ? error.message : String(error)})`);
|
|
120
|
+
}
|
|
121
|
+
}
|
|
122
|
+
if (input.select !== undefined && typeof input.select !== "boolean")
|
|
123
|
+
throw bad("select", "must be true or false");
|
|
124
|
+
if (input.select === true && object === undefined)
|
|
125
|
+
throw bad("select", "needs an object to select");
|
|
126
|
+
let trace;
|
|
127
|
+
if (input.trace !== undefined && input.trace !== false) {
|
|
128
|
+
if (object === undefined)
|
|
129
|
+
throw bad("trace", "needs an object that names a sky figure");
|
|
130
|
+
try {
|
|
131
|
+
trace = traceOptionsOf(input.trace === true ? undefined : input.trace);
|
|
132
|
+
}
|
|
133
|
+
catch (error) {
|
|
134
|
+
throw bad("trace", `is not true or trace options (${error instanceof Error ? error.message : String(error)})`);
|
|
135
|
+
}
|
|
136
|
+
}
|
|
137
|
+
return { ...(camera === undefined ? {} : { camera }), ...(input.select === true ? { select: true } : {}), ...(trace === undefined ? {} : { trace }) };
|
|
138
|
+
}
|
|
96
139
|
/** Checks a `setStoryPanelPlayback` argument; a mistake throws `bad-panels`. */
|
|
97
140
|
export function panelPlaybackOf(input) {
|
|
98
141
|
return panelCheck("setStoryPanelPlayback", () => checkPanelPlayback(input));
|
|
@@ -11,11 +11,12 @@ export declare class ViewerCamera {
|
|
|
11
11
|
onCameraChange(listener: (camera: CameraPose) => void): () => void;
|
|
12
12
|
/** A viewer publish (its tick, or a host or visitor action): reports the pose when it differs from the last one. */
|
|
13
13
|
publish(): void;
|
|
14
|
-
/** The camera pose, or undefined before the viewer is drawn and after it is gone; before its first frame it is the opening camera. */
|
|
14
|
+
/** The camera pose, or undefined before the viewer is drawn and after it is gone; before its first frame it is the opening camera, or undefined when the opening look-out turns toward an id (resolved on that frame). */
|
|
15
15
|
get camera(): CameraPose | undefined;
|
|
16
16
|
/**
|
|
17
|
-
* Points the camera: `{ follow: id }` keeps the distance, `{ focus: id }` frames the object,
|
|
18
|
-
*
|
|
17
|
+
* Points the camera: `{ follow: id }` keeps the distance, `{ focus: id }` frames the object, `{ lookOut: id, direction?, fovDeg? }` stands inside a body looking out,
|
|
18
|
+
* a pose (from `camera`, either kind) puts the camera back where it was read (an orbit pose relative to its object).
|
|
19
|
+
* Every id must be an object the showing view shows (a look-out `direction` may name a sky figure too); an unknown or hidden id, a direction or field of view out of range, or a malformed argument, throws `bad-camera`.
|
|
19
20
|
* Before the viewer is drawn or after it is gone, `not-mounted`. The move eases in as a view's camera rule does.
|
|
20
21
|
*/
|
|
21
22
|
setCamera(target: CameraTarget): void;
|
package/src/api/viewerCamera.js
CHANGED
|
@@ -1,8 +1,9 @@
|
|
|
1
|
-
import {
|
|
2
|
-
import { SceneError } from "./errors.js";
|
|
1
|
+
import { cameraRequestOf, checkCameraIds } from "./cameraRequest.js";
|
|
3
2
|
import { callListeners } from "./listeners.js";
|
|
4
3
|
/** The shortest time between two reports, a little under the viewer's 100 ms tick so a tick is never skipped. */
|
|
5
4
|
const MIN_GAP_MS = 80;
|
|
5
|
+
/** Whether two readings say the same: both orbit or both sky, with every field equal (a reading's keys always come in one order). */
|
|
6
|
+
const samePose = (a, b) => JSON.stringify(a) === JSON.stringify(b);
|
|
6
7
|
/** The host link's camera: the pose read and `setCamera`, with its request check. */
|
|
7
8
|
export class ViewerCamera {
|
|
8
9
|
access;
|
|
@@ -35,7 +36,7 @@ export class ViewerCamera {
|
|
|
35
36
|
this.#last = pose;
|
|
36
37
|
return;
|
|
37
38
|
} // the first frame's pose is the opening one
|
|
38
|
-
if (pose
|
|
39
|
+
if (samePose(pose, last))
|
|
39
40
|
return;
|
|
40
41
|
const now = performance.now();
|
|
41
42
|
if (now - this.#reportedAt < MIN_GAP_MS)
|
|
@@ -44,41 +45,18 @@ export class ViewerCamera {
|
|
|
44
45
|
this.#reportedAt = now;
|
|
45
46
|
callListeners(this.#listeners, pose);
|
|
46
47
|
}
|
|
47
|
-
/** The camera pose, or undefined before the viewer is drawn and after it is gone; before its first frame it is the opening camera. */
|
|
48
|
+
/** The camera pose, or undefined before the viewer is drawn and after it is gone; before its first frame it is the opening camera, or undefined when the opening look-out turns toward an id (resolved on that frame). */
|
|
48
49
|
get camera() { return this.access.control()?.readCamera(); }
|
|
49
50
|
/**
|
|
50
|
-
* Points the camera: `{ follow: id }` keeps the distance, `{ focus: id }` frames the object,
|
|
51
|
-
*
|
|
51
|
+
* Points the camera: `{ follow: id }` keeps the distance, `{ focus: id }` frames the object, `{ lookOut: id, direction?, fovDeg? }` stands inside a body looking out,
|
|
52
|
+
* a pose (from `camera`, either kind) puts the camera back where it was read (an orbit pose relative to its object).
|
|
53
|
+
* Every id must be an object the showing view shows (a look-out `direction` may name a sky figure too); an unknown or hidden id, a direction or field of view out of range, or a malformed argument, throws `bad-camera`.
|
|
52
54
|
* Before the viewer is drawn or after it is gone, `not-mounted`. The move eases in as a view's camera rule does.
|
|
53
55
|
*/
|
|
54
56
|
setCamera(target) {
|
|
55
57
|
const control = this.access.open("setCamera");
|
|
56
|
-
const request =
|
|
57
|
-
|
|
58
|
-
if (!control.cameraTargets().includes(id)) {
|
|
59
|
-
throw new SceneError("bad-camera", `setCamera: "${id}" is not an object the showing view shows (${control.cameraTargets().join(", ")})`);
|
|
60
|
-
}
|
|
58
|
+
const request = cameraRequestOf(target, "setCamera", this.camera);
|
|
59
|
+
checkCameraIds(request, "setCamera", control.cameraTargets(), (control.skyFigures ?? []).map(({ id }) => id));
|
|
61
60
|
control.setCamera(request);
|
|
62
61
|
}
|
|
63
|
-
#request(target) {
|
|
64
|
-
const bad = (why) => new SceneError("bad-camera", `setCamera: ${why}; give { follow: id }, { focus: id } or a pose from camera`);
|
|
65
|
-
if (typeof target !== "object" || target === null || Array.isArray(target))
|
|
66
|
-
throw bad(`${String(target)} is not an object`);
|
|
67
|
-
const record = target;
|
|
68
|
-
// A pose names its object with `focus` too; its angle and distance fields tell it from `{ focus: id }`.
|
|
69
|
-
const isPose = ["azimuthDeg", "elevationDeg", "distance"].some((key) => key in record) || !("follow" in record || "focus" in record);
|
|
70
|
-
const named = ["follow", "focus"].filter((key) => key in record);
|
|
71
|
-
if (isPose) {
|
|
72
|
-
try {
|
|
73
|
-
return { kind: "pose", view: validateStartView(record, "pose") };
|
|
74
|
-
}
|
|
75
|
-
catch (cause) {
|
|
76
|
-
throw bad(cause instanceof Error ? cause.message : "a malformed pose");
|
|
77
|
-
}
|
|
78
|
-
}
|
|
79
|
-
const id = record[named[0]];
|
|
80
|
-
if (named.length > 1 || Object.keys(record).length > 1 || typeof id !== "string" || id === "")
|
|
81
|
-
throw bad("the target must be exactly one of follow or focus, naming a non-empty id");
|
|
82
|
-
return { kind: named[0], target: id };
|
|
83
|
-
}
|
|
84
62
|
}
|
|
@@ -1,7 +1,10 @@
|
|
|
1
1
|
import type { LookInput, LookRead } from "./look.js";
|
|
2
2
|
import type { PickChange } from "./pickerInput.js";
|
|
3
3
|
import type { TimeInput } from "./time.js";
|
|
4
|
+
import type { SceneSkyFigureRead } from "./sceneReads.js";
|
|
5
|
+
import type { SkyClearOptions, SkyTraceOptions } from "./skyTraceInput.js";
|
|
4
6
|
import type { SelectionChange } from "./viewerSelection.js";
|
|
7
|
+
import type { PanelChange } from "./viewerPanels.js";
|
|
5
8
|
import type { CameraPose, CameraTarget, EventZoneChange, ViewerChange, ViewerLink } from "./viewerLink.js";
|
|
6
9
|
/** Everything a host reads, sets and listens to on a drawn viewer: the handle `mount` returns (as `MountedScene`). Every call before the viewer is drawn or after it is gone throws `not-mounted`; reads are then undefined. */
|
|
7
10
|
export interface ViewerHandle {
|
|
@@ -21,9 +24,9 @@ export interface ViewerHandle {
|
|
|
21
24
|
setRate(rate: number | "auto"): void;
|
|
22
25
|
/** Switches to the view with this id (`setViews`). An unknown id, or a scene without views, throws `bad-view`; before `ready` or after `unmount` throws `not-mounted`. `onChange` hears it with `cause: "host"`. */
|
|
23
26
|
setView(id: string): void;
|
|
24
|
-
/** The camera as a plain value ({ focus, azimuthDeg, elevationDeg, distance }, the pose a copied view link carries); undefined until `ready` and after `unmount`; before the first frame is drawn it is the opening camera. Keep it and hand it to `setCamera` to put the camera back. */
|
|
27
|
+
/** The camera as a plain value (an orbit pose `{ focus, azimuthDeg, elevationDeg, distance }`, or a sky pose `{ lookOut, raDeg, decDeg, fovDeg }` while looking out; the pose a copied view link carries); undefined until `ready` and after `unmount`; before the first frame is drawn it is the opening camera (undefined for a look-out toward an id). Keep it and hand it to `setCamera` to put the camera back. */
|
|
25
28
|
readonly camera: CameraPose | undefined;
|
|
26
|
-
/** Points the camera: `{ follow: id }` keeps the distance, `{ focus: id }` frames the object, or a pose from `camera` puts it back where it was read (relative to its object, which a moving object carries along). The object must be one the showing view shows; an unknown or hidden id, or a malformed argument, throws `bad-camera`; before `ready` or after `unmount`, `not-mounted`. The camera eases there. */
|
|
29
|
+
/** Points the camera: `{ follow: id }` keeps the distance, `{ focus: id }` frames the object, `{ lookOut: id, direction?, fovDeg? }` stands inside a body looking out (direction: `{ raDeg, decDeg }` or an object id), or a pose from `camera` (either kind) puts it back where it was read (an orbit pose relative to its object, which a moving object carries along). The object must be one the showing view shows; an unknown or hidden id (the body or the object to turn toward), a direction or field of view out of range, or a malformed argument, throws `bad-camera`; before `ready` or after `unmount`, `not-mounted`. The camera eases there. */
|
|
27
30
|
setCamera(target: CameraTarget): void;
|
|
28
31
|
/** The ids of the events whose zone (`withinSeconds` of an event, or a pacing rule) holds the viewer's time now, among the zones the showing view has (an empty list in a scene without event zones); undefined until `ready` and after `unmount`. */
|
|
29
32
|
readonly eventZones: readonly string[] | undefined;
|
|
@@ -32,16 +35,28 @@ export interface ViewerHandle {
|
|
|
32
35
|
* `cause` is `playback` (the clock ran), `visitor` (timeline or view choice) or `host` (`setTime`, `setView`); overlapping zones report separately. A zone already active when the viewer opens reports `entered` once, with the first report after `ready` (within a tenth of a second), so a listener added right after `await ready` hears it. The engine moves nothing in response: a host composes its own behaviour, for example `setCamera`. No callbacks arrive after `unmount`. A listener that throws is reported to the page (`reportError`) and does not stop the listeners after it.
|
|
33
36
|
*/
|
|
34
37
|
onEventZone(listener: (change: EventZoneChange) => void): () => void;
|
|
35
|
-
/** The id of the object whose information the viewer has open (the one the object menu, a click or a view switch chose); undefined until `ready` has resolved, after `unmount`, and when nothing is selected.
|
|
38
|
+
/** The id of the object whose information the viewer has open (the one the object menu, a click or a view switch chose); undefined until `ready` has resolved, after `unmount`, and when nothing is selected. Set it with `setSelected`. */
|
|
36
39
|
readonly selected: string | undefined;
|
|
40
|
+
/**
|
|
41
|
+
* Selects the object (or sky figure, see `skyFigures`) with this id, or clears the selection with `undefined`; `selected` reads it at once and `onSelect` hears it with `cause: "host"` (nothing is reported when the selection is already that).
|
|
42
|
+
* The object must be one the showing view shows: an unknown or hidden id, an empty or non-string id throws `bad-selection`; before `ready` or after `unmount`, `not-mounted`. Like the object menu it opens the object's card, but the camera stays where it is (`setCamera` points the camera); a clear closes the card.
|
|
43
|
+
* Like every host call it is the last word: made straight after `await ready`, before the first frame, or inside an `onChange` report of a view switch, it holds; a later view switch that no longer shows the object drops it as it drops a visitor's choice.
|
|
44
|
+
*/
|
|
45
|
+
setSelected(id: string | undefined): void;
|
|
37
46
|
/**
|
|
38
47
|
* Calls `listener({ object?, timeUtcMs, cause })` when the selected object changes: `object` is the new id, absent when the selection was dropped (a view switch that no longer shows it, with nothing to take its place).
|
|
39
|
-
* `cause` is `visitor` (the object menu, a click, or a time, speed or view the visitor chose), `host` (a drop caused by the host's own `setTime`, `setRate`, `setPlaying` or `setView`) or `playback` (a drop caused by the clock running); a drop takes the cause `onChange` reported for the move that caused it. The selection the viewer opens with is read from `selected`, not reported. The engine moves nothing in response.
|
|
48
|
+
* `cause` is `visitor` (the object menu, a click, or a time, speed or view the visitor chose), `host` (`setSelected`, or a drop caused by the host's own `setTime`, `setRate`, `setPlaying` or `setView`) or `playback` (a drop caused by the clock running); a drop takes the cause `onChange` reported for the move that caused it. The selection the viewer opens with is read from `selected`, not reported. The engine moves nothing in response.
|
|
40
49
|
* No callbacks arrive after `unmount`. A listener that throws is reported to the page (`reportError`) and does not stop the listeners after it. Returns the function that stops it.
|
|
41
50
|
*/
|
|
42
51
|
onSelect(listener: (change: SelectionChange) => void): () => void;
|
|
52
|
+
/** The id of the open story panel or step; undefined until `ready`, after `unmount`, and when none is open. Set it with `setPanel`. */
|
|
53
|
+
readonly panel: string | undefined;
|
|
54
|
+
/** Opens the story panel or step with this id, or closes the open one with `undefined`; `onPanel` hears it with `cause: "host"`. Moves nothing else. An id the showing view does not show throws `bad-panels`; before `ready` or after `unmount`, `not-mounted`. */
|
|
55
|
+
setPanel(id: string | undefined): void;
|
|
56
|
+
/** Calls `listener({ panel?, timeUtcMs, cause })` when the open panel changes: `cause` is `visitor`, `host` (`setPanel`, or a drop by `setView`) or `playback` (a moment panel opened by itself). The opening panel is read, not reported. Returns the function that stops it. */
|
|
57
|
+
onPanel(listener: (change: PanelChange) => void): () => void;
|
|
43
58
|
/**
|
|
44
|
-
* Calls `listener(pose)` with the camera as a plain value (
|
|
59
|
+
* Calls `listener(pose)` with the camera as a plain value (an orbit pose or a sky pose, what `camera` reads) when it changes: a visitor's drag, zoom or pick, a view's camera rule, or your own `setCamera`
|
|
45
60
|
* (it reports as the camera eases, then stops when the pose settles). At most about ten times a second; an unchanged pose reports nothing, and neither does a camera following a moving object at a fixed pose.
|
|
46
61
|
* The pose the viewer opens with is read from `camera`, not reported. The engine moves nothing in response. No callbacks arrive after `unmount`. A listener that throws is reported to the page (`reportError`) and does not stop the listeners after it. Returns the function that stops it.
|
|
47
62
|
*/
|
|
@@ -54,6 +69,20 @@ export interface ViewerHandle {
|
|
|
54
69
|
readonly scale: string | undefined;
|
|
55
70
|
/** Switches to one of the scales the viewer offers (`Scene.scales`); any other id throws `bad-scale`; before `ready` or after `unmount`, `not-mounted`. `onChange` hears it with `cause: "host"`. */
|
|
56
71
|
setScale(id: string): void;
|
|
72
|
+
/** The sky figures the viewer draws (`Scene.addSkyFigures`), in the order added: id, label and kind; empty when the scene added none; undefined until `ready` has resolved and after `unmount`. */
|
|
73
|
+
readonly skyFigures: readonly SceneSkyFigureRead[] | undefined;
|
|
74
|
+
/**
|
|
75
|
+
* Traces the sky figure `id` (one of `skyFigures`) line by line: its segments are drawn in the order added, each growing from its first end, over `durationSeconds` (0.1 to 60, default 2) in the look's `skyLines.traced` colour; then `after` decides: `"stay"` (default) keeps them, `"fade"` eases them to `skyLines.faded` and removes them.
|
|
76
|
+
* The trace is drawn over the figure and follows the figure's switch (`skyFigures` or `skyBoundaries`): with the switch off it runs unseen. It runs on real time, so pausing or changing the scene clock does not change it; calling again restarts it. With `prefers-reduced-motion: reduce` the whole figure shows at once, stays for `seconds`, and then `after` applies (a `fade` removes it at once).
|
|
77
|
+
* An id that is not a figure the viewer draws throws `unknown-sky-figure`; options other than `{ durationSeconds?, after? }`, a `durationSeconds` outside its range or an `after` other than `stay` or `fade` throws `bad-sky-trace`; before `ready` or after `unmount`, `not-mounted`. It takes its place in call order with the other host calls.
|
|
78
|
+
*/
|
|
79
|
+
traceSkyFigure(id: string, options?: SkyTraceOptions): void;
|
|
80
|
+
/**
|
|
81
|
+
* Removes the trace of the sky figure `id` at any time (while it runs, after `stay`, or during a `fade`): the traced lines ease out over `durationSeconds` (0 to 60, default 1; 0 removes them at once), keeping the part drawn so far.
|
|
82
|
+
* A figure shown only when traced (`shown: "whenTraced"`) is then hidden, lines and label; an always-shown figure only loses the trace highlight and keeps its ordinary look. A figure with no trace is left alone (no error), and a later trace starts from nothing. With `prefers-reduced-motion: reduce` it removes the trace at once.
|
|
83
|
+
* An id that is not a figure the viewer draws throws `unknown-sky-figure`; options other than `{ durationSeconds? }` or a `durationSeconds` outside its range throws `bad-sky-trace`; before `ready` or after `unmount`, `not-mounted`. It takes its place in call order with the other host calls.
|
|
84
|
+
*/
|
|
85
|
+
clearSkyTrace(id: string, options?: SkyClearOptions): void;
|
|
57
86
|
/** The display switches the scene placed (`setSwitches`, wherever it placed them) that have something to act on, each on or off, by id (`orbitLines`, `labels`, `milkyWay`); empty when it placed none; undefined until `ready` has resolved and after `unmount`. */
|
|
58
87
|
readonly switches: Readonly<Record<string, boolean>> | undefined;
|
|
59
88
|
/** Turns a display switch the scene placed on or off, as the visitor's switch does; an id it did not place, or a non-boolean, throws `bad-switch`; before `ready` or after `unmount`, `not-mounted`. `onChange` hears it with `cause: "host"`. */
|
package/src/api/viewerHandle.js
CHANGED
|
@@ -8,17 +8,24 @@ export function viewerHandleOf(link) {
|
|
|
8
8
|
get camera() { return link.camera; },
|
|
9
9
|
get eventZones() { return link.eventZones; },
|
|
10
10
|
get selected() { return link.selected; },
|
|
11
|
+
get panel() { return link.panel; },
|
|
11
12
|
get look() { return link.look; },
|
|
12
13
|
get scale() { return link.scale; },
|
|
13
14
|
get switches() { return link.switches; },
|
|
15
|
+
get skyFigures() { return link.skyFigures; },
|
|
14
16
|
get pick() { return link.pick; },
|
|
15
17
|
setPick: (value) => link.setPick(value),
|
|
16
18
|
onPick: (listener) => link.onPick(listener),
|
|
17
19
|
setLook: (look) => link.setLook(look),
|
|
18
20
|
setScale: (id) => link.setScale(id),
|
|
19
21
|
setSwitch: (id, on) => link.setSwitch(id, on),
|
|
22
|
+
traceSkyFigure: (id, options) => link.traceSkyFigure(id, options),
|
|
23
|
+
clearSkyTrace: (id, options) => link.clearSkyTrace(id, options),
|
|
20
24
|
setView: (id) => link.setView(id),
|
|
21
25
|
setCamera: (target) => link.setCamera(target),
|
|
26
|
+
setSelected: (id) => link.setSelected(id),
|
|
27
|
+
setPanel: (id) => link.setPanel(id),
|
|
28
|
+
onPanel: (listener) => link.onPanel(listener),
|
|
22
29
|
setTime: (time) => link.setTime(time),
|
|
23
30
|
setRate: (rate) => link.setRate(rate),
|
|
24
31
|
setPlaying: (playing) => link.setPlaying(playing),
|
package/src/api/viewerLink.d.ts
CHANGED
|
@@ -2,8 +2,11 @@ import type { ViewerChangeCause, ViewerPort, ViewerState } from "../app/viewerPo
|
|
|
2
2
|
import type { ViewerControl } from "../app/viewerPort.js";
|
|
3
3
|
import type { LookInput, LookRead } from "./look.js";
|
|
4
4
|
import { type SelectionChange } from "./viewerSelection.js";
|
|
5
|
+
import { type PanelChange } from "./viewerPanels.js";
|
|
5
6
|
import type { PickChange } from "./pickerInput.js";
|
|
6
7
|
import type { TimeInput } from "./time.js";
|
|
8
|
+
import type { SceneSkyFigureRead } from "./sceneReads.js";
|
|
9
|
+
import { type SkyClearOptions, type SkyTraceOptions } from "./skyTraceInput.js";
|
|
7
10
|
/** What a host is told when the viewer's time, speed or playing state changes. */
|
|
8
11
|
export interface ViewerChange {
|
|
9
12
|
/** The viewer's time, Unix milliseconds UTC. */
|
|
@@ -38,8 +41,8 @@ export interface EventZoneChange {
|
|
|
38
41
|
/** What the report is about: `time` (playback crossed the zone, or a seek moved the clock across it) or `view` (a view switch showed or hid the zone). After a `view` leave the view's own camera rule owns the camera, so a host that restores a camera should do it only for `time`. */
|
|
39
42
|
readonly via: "time" | "view";
|
|
40
43
|
}
|
|
41
|
-
/** The camera as a plain value: the object it is centred on and where it stands from it.
|
|
42
|
-
export interface
|
|
44
|
+
/** The camera orbiting an object, as a plain value: the object it is centred on and where it stands from it. One of the two kinds of `CameraPose`. */
|
|
45
|
+
export interface OrbitPose {
|
|
43
46
|
/** The id of the object the camera is centred on (and follows as it moves). */
|
|
44
47
|
readonly focus: string;
|
|
45
48
|
/** Degrees about the up direction, 0 up to 360 (rounded to 0.01). */
|
|
@@ -49,12 +52,44 @@ export interface CameraPose {
|
|
|
49
52
|
/** Camera-to-object distance in the scene's scaled units (Earth radii), to five significant figures. */
|
|
50
53
|
readonly distance: number;
|
|
51
54
|
}
|
|
52
|
-
/**
|
|
55
|
+
/** A star-map position: J2000 equatorial degrees (the engine's EQJ frame). */
|
|
56
|
+
export interface SkyDirection {
|
|
57
|
+
/** Right ascension in degrees, 0 up to 360 (a value outside wraps). */
|
|
58
|
+
readonly raDeg: number;
|
|
59
|
+
/** Declination in degrees, within ±90. */
|
|
60
|
+
readonly decDeg: number;
|
|
61
|
+
}
|
|
62
|
+
/** The camera standing inside a body and looking out, as a plain value: the body, where it points and its field of view. One of the two kinds of `CameraPose`. */
|
|
63
|
+
export interface SkyPose {
|
|
64
|
+
/** The id of the body the camera stands in (at its centre). */
|
|
65
|
+
readonly lookOut: string;
|
|
66
|
+
/** Right ascension of the look direction, degrees 0 up to 360, J2000 equatorial (rounded to 0.01). */
|
|
67
|
+
readonly raDeg: number;
|
|
68
|
+
/** Declination of the look direction, degrees within ±90, J2000 equatorial (rounded to 0.01). */
|
|
69
|
+
readonly decDeg: number;
|
|
70
|
+
/** Vertical field of view in degrees, 5 to 100: the zoom (rounded to 0.01). */
|
|
71
|
+
readonly fovDeg: number;
|
|
72
|
+
}
|
|
73
|
+
/**
|
|
74
|
+
* What `MountedScene.camera` reads and `onCameraChange` reports: an orbit pose (has `distance`) while the camera orbits an object, or a sky pose
|
|
75
|
+
* (has `lookOut`) while it stands inside a body looking out. Tell them apart with `"lookOut" in pose`; put either back with `setCamera`.
|
|
76
|
+
*/
|
|
77
|
+
export type CameraPose = OrbitPose | SkyPose;
|
|
78
|
+
/** Stand inside a body (at its centre) and look out: turned to a star-map position or toward an object, with an optional field of view. */
|
|
79
|
+
export interface LookOutTarget {
|
|
80
|
+
/** The id of the body to stand in; a body the showing view shows. */
|
|
81
|
+
readonly lookOut: string;
|
|
82
|
+
/** Where to point: a star-map position, or the id of an object or sky figure to turn toward. Omitted: the direction it already looks while looking out, else right ascension 0, declination 0. */
|
|
83
|
+
readonly direction?: SkyDirection | string;
|
|
84
|
+
/** Vertical field of view in degrees, 5 to 100. Omitted: the current one while looking out, else 60. */
|
|
85
|
+
readonly fovDeg?: number;
|
|
86
|
+
}
|
|
87
|
+
/** What `setCamera` takes: follow an object (keep the distance), focus it (frame it), look out from a body, or put the camera back on a pose from `camera`. */
|
|
53
88
|
export type CameraTarget = {
|
|
54
89
|
readonly follow: string;
|
|
55
90
|
} | {
|
|
56
91
|
readonly focus: string;
|
|
57
|
-
} | CameraPose;
|
|
92
|
+
} | LookOutTarget | CameraPose;
|
|
58
93
|
/** Where the playback rate comes from. `scene` is the rate the scene opened at; `chosen` is one a visitor or the host picked, which stays until it is released. */
|
|
59
94
|
export type RateSource = "scene" | "chosen";
|
|
60
95
|
/** What the host-link parts share: the one attached control, read through here so no part keeps a copy of it. */
|
|
@@ -88,8 +123,10 @@ export declare class ViewerLink implements ViewerPort {
|
|
|
88
123
|
get eventZones(): readonly string[] | undefined;
|
|
89
124
|
get view(): string | undefined;
|
|
90
125
|
get selected(): string | undefined;
|
|
126
|
+
get panel(): string | undefined;
|
|
91
127
|
get camera(): CameraPose | undefined;
|
|
92
128
|
get pick(): string | undefined;
|
|
129
|
+
get skyFigures(): readonly SceneSkyFigureRead[] | undefined;
|
|
93
130
|
get look(): LookRead | undefined;
|
|
94
131
|
get scale(): string | undefined;
|
|
95
132
|
get switches(): Readonly<Record<string, boolean>> | undefined;
|
|
@@ -101,8 +138,15 @@ export declare class ViewerLink implements ViewerPort {
|
|
|
101
138
|
setLook(look: LookInput): void;
|
|
102
139
|
setScale(id: string): void;
|
|
103
140
|
setSwitch(id: string, on: boolean): void;
|
|
141
|
+
setSelected(id: string | undefined): void;
|
|
142
|
+
setPanel(id: string | undefined): void;
|
|
143
|
+
onPanel(listener: (change: PanelChange) => void): () => void;
|
|
104
144
|
onChange(listener: (change: ViewerChange) => void): () => void;
|
|
105
145
|
onEventZone(listener: (change: EventZoneChange) => void): () => void;
|
|
146
|
+
/** Traces a sky figure line by line (checked here, `unknown-sky-figure` or `bad-sky-trace`); the viewer starts it at its next frame, after any host call made before it. */
|
|
147
|
+
traceSkyFigure(id: string, options?: SkyTraceOptions): void;
|
|
148
|
+
/** Removes a figure's trace (checked here, `unknown-sky-figure` or `bad-sky-trace`); a figure with no trace is left alone. Takes its place in call order like `traceSkyFigure`. */
|
|
149
|
+
clearSkyTrace(id: string, options?: SkyClearOptions): void;
|
|
106
150
|
setPick(value: string): void;
|
|
107
151
|
onPick(listener: (change: PickChange) => void): () => void;
|
|
108
152
|
pickNow(): string | undefined;
|
|
@@ -115,4 +159,6 @@ export declare class ViewerLink implements ViewerPort {
|
|
|
115
159
|
publish(state: ViewerState, cause: ViewerChangeCause): void;
|
|
116
160
|
/** The selection changed. A drop by time or the view names whatever last moved them (`onChange` names the same), so the cause is never a second opinion. */
|
|
117
161
|
publishSelection(state: ViewerState, byMove: boolean): void;
|
|
162
|
+
/** The open story panel changed. A drop by a view switch names whatever last moved the view (`onChange` names the same). */
|
|
163
|
+
publishPanel(state: ViewerState, cause: ViewerChangeCause | "move"): void;
|
|
118
164
|
}
|