astraeus 0.8.1 → 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 +67 -0
- package/README.md +28 -15
- 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 +9 -1
- 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 +27 -4
- package/src/api/viewerHandle.js +6 -0
- package/src/api/viewerLink.d.ts +49 -4
- package/src/api/viewerLink.js +25 -0
- package/src/api/viewerPanels.d.ts +26 -0
- package/src/api/viewerPanels.js +42 -0
- package/src/api/viewerSelection.d.ts +1 -1
- package/src/api/viewerSelection.js +3 -3
- package/src/app/App.js +100 -18
- package/src/app/App.node.js +100 -18
- package/src/app/AstraeusScene.d.ts +20 -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 +5 -3
- package/src/app/sceneCamera.js +66 -3
- 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 +30 -3
- 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/bodies/moonSystem.js +1 -15
- package/src/core/lookValues.d.ts +9 -0
- package/src/core/lookValues.js +24 -0
- 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 +15 -6
- package/src/shell/AstraeusShell.js +76 -20
- package/src/shell/AstraeusShell.node.js +76 -20
- 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
package/src/api/errors.d.ts
CHANGED
|
@@ -50,13 +50,21 @@ export type SceneErrorCode =
|
|
|
50
50
|
| "bad-picker"
|
|
51
51
|
/** A body's places (`addPlaces`) are malformed, or name a body the scene does not hold. */
|
|
52
52
|
| "bad-places"
|
|
53
|
+
/** A sky figure (`addSkyFigures`) is malformed: its id, label, kind, segments, points or label position. */
|
|
54
|
+
| "bad-sky-figure"
|
|
55
|
+
/** `traceSkyFigure` or `clearSkyTrace` was given a figure id the viewer does not draw (see `handle.skyFigures`). */
|
|
56
|
+
| "unknown-sky-figure"
|
|
57
|
+
/** `traceSkyFigure` was given options that are not `{ durationSeconds?, after? }`, a `durationSeconds` outside 0.1 to 60, or an `after` other than `stay` or `fade`; or `clearSkyTrace` was given options that are not `{ durationSeconds? }` or a `durationSeconds` outside 0 to 60. */
|
|
58
|
+
| "bad-sky-trace"
|
|
59
|
+
/** A sky figure names a star whose Hipparcos number is not in the engine's star list (stars of magnitude 6.5 or brighter). Found when the scene is built, as the star list loads then. */
|
|
60
|
+
| "unknown-star"
|
|
53
61
|
/** An activity curve is malformed. */
|
|
54
62
|
| "bad-activity"
|
|
55
63
|
/** A camera call or pose is malformed, or names an object the view cannot show. */
|
|
56
64
|
| "bad-camera"
|
|
57
65
|
/** A scene view is malformed, repeated, or not one of the scene's views. */
|
|
58
66
|
| "bad-view"
|
|
59
|
-
/** `setSelected` was given something other than an id of an object the showing view shows, or `undefined`. */
|
|
67
|
+
/** `setSelected` was given something other than an id of an object the showing view shows, a sky figure, or `undefined`. */
|
|
60
68
|
| "bad-selection"
|
|
61
69
|
/** A look (`setLook`) is unknown or out of its range. */
|
|
62
70
|
| "bad-look"
|
package/src/api/index.d.ts
CHANGED
|
@@ -1,16 +1,19 @@
|
|
|
1
|
-
export { Scene, type SceneCamera, type AddBodyOptions, type CardFactInput, type OrbitLapInput, type BodyReadoutKind, type AnchorInput, type ReadoutInput, type DataSource, type SceneLoadOptions, type SceneBodyRead, type SceneActivityRead, type ScenePathRead, type SceneGroupRead, type SceneBodySetRead, type SceneMoonPanelRead, type ScenePlacesRead, type SceneEventRead, type ScenePanelRead, type SceneViewRead, type SceneViewsRead, type SceneTimelineRead, type MoonPositions, type MoonIndex, type FollowView, type GroupInput, type GroupOrbitInput, type GroupClumpInput, type GroupReadoutInput, type ActivityInput, type ActivitySampleInput, type ActivitySourceInput, type ElementsBodyRecord, type TimeInput, type TrajectoryInput, type TrajectorySampleInput, type TrajectoryBase } from "./scene.js";
|
|
1
|
+
export { Scene, type SceneCamera, type AddBodyOptions, type CardFactInput, type OrbitLapInput, type BodyReadoutKind, type AnchorInput, type ReadoutInput, type DataSource, type SceneLoadOptions, type SceneBodyRead, type SceneActivityRead, type ScenePathRead, type SceneGroupRead, type SceneBodySetRead, type SceneMoonPanelRead, type ScenePlacesRead, type SceneSkyFigureRead, type SceneEventRead, type ScenePanelRead, type SceneViewRead, type SceneViewsRead, type SceneTimelineRead, type MoonPositions, type MoonIndex, type FollowView, type GroupInput, type GroupOrbitInput, type GroupClumpInput, type GroupReadoutInput, type ActivityInput, type ActivitySampleInput, type ActivitySourceInput, type ElementsBodyRecord, type TimeInput, type TrajectoryInput, type TrajectorySampleInput, type TrajectoryBase } from "./scene.js";
|
|
2
2
|
export type { MoonPanelInput, MoonPanelFamilyInput, MoonPanelMoonInput, PlacesInput, PlaceInput, PlaceCategoryInput } from "./moonPanelInput.js";
|
|
3
|
+
export type { SkyFigureInput, SkyFigureEnd } from "./skyFigureInput.js";
|
|
4
|
+
export type { SkyClearOptions, SkyTraceOptions } from "./skyTraceInput.js";
|
|
3
5
|
export type { PickerInput, PickerOptionInput, PickChange } from "./pickerInput.js";
|
|
4
6
|
export type { BodySetInput, BodySetFamilyInput, BodySetMemberInput, BodySetElementsInput, BodySetBodyInput, BodySetBalanceInput } from "./bodySetInput.js";
|
|
5
7
|
export { type EventInput, type AddEventsOptions, type TimelineInput, type PacingInput, type StoryPanelAt, type StoryPanelInput, type StoryPanelPlaybackInput } from "./story.js";
|
|
6
8
|
export { type SwitchesInput } from "./switches.js";
|
|
7
|
-
export { type LookInput, type LookRead, type SunGlowLook } from "./look.js";
|
|
9
|
+
export { type LookInput, type LookRead, type SunGlowLook, type SkyLinesLook, type LabelsLook } from "./look.js";
|
|
8
10
|
export { type ViewsOptions, type ViewInput, type ViewCameraInput } from "./views.js";
|
|
9
11
|
export { mount, type MountOptions, type MountedScene } from "./mount.js";
|
|
10
12
|
export { type ViewerHandle } from "./viewerHandle.js";
|
|
11
13
|
export { AstraeusScene, type AstraeusSceneProps } from "./AstraeusScene.js";
|
|
12
14
|
export { type SelectionChange } from "./viewerSelection.js";
|
|
13
|
-
export { type
|
|
15
|
+
export { type PanelChange } from "./viewerPanels.js";
|
|
16
|
+
export { type ViewerChange, type EventZoneChange, type CameraPose, type OrbitPose, type SkyPose, type SkyDirection, type LookOutTarget, type CameraTarget } from "./viewerLink.js";
|
|
14
17
|
export { SceneError, type SceneErrorCode } from "./errors.js";
|
|
15
18
|
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, listedMoons, type BodyRef } from "./bodies.js";
|
|
16
19
|
export { trueScale, readableScale, solarSystemScale, type ScalePolicy, type SolarSystemScalePolicy } from "../core/scalePolicy.js";
|
package/src/api/look.d.ts
CHANGED
|
@@ -7,6 +7,32 @@ export interface SunGlowLook {
|
|
|
7
7
|
/** The glow is at least this many times the Sun's projected diameter, 1 to 6, so close up it frames the disc. Default 2.5. */
|
|
8
8
|
readonly scale?: number;
|
|
9
9
|
}
|
|
10
|
+
/** The colours of the lines drawn on the sky and of their names, as CSS colour texts (`#8fb4ff`, `rgb(143, 180, 255)`, `hsl(...)` with commas, or a colour name). Every field is optional and keeps its default when absent. A figure's own colours (`SkyFigureInput`) win over these. */
|
|
11
|
+
export interface SkyLinesLook {
|
|
12
|
+
/** Lines of figures added with `addSkyFigures`. Default `"#8fb4ff"`. */
|
|
13
|
+
readonly figure?: string;
|
|
14
|
+
/** The names of the sky figures and outlines. Default `"#cfe0ff"`. */
|
|
15
|
+
readonly label?: string;
|
|
16
|
+
/** Outlines (`kind: "boundary"`). Default `"#5f7a9c"`. */
|
|
17
|
+
readonly boundary?: string;
|
|
18
|
+
/** The ecliptic circle. Default `"#e0b25a"`. */
|
|
19
|
+
readonly ecliptic?: string;
|
|
20
|
+
/** The celestial equator circle. Default `"#7fd1b9"`. */
|
|
21
|
+
readonly equator?: string;
|
|
22
|
+
/** A figure line that has been traced. Default `"#ffd166"`. */
|
|
23
|
+
readonly traced?: string;
|
|
24
|
+
/** A figure line that is fading back after a trace. Default `"#44546d"`. */
|
|
25
|
+
readonly faded?: string;
|
|
26
|
+
/** The lines and name of the selected sky figure. Default `"#ffffff"`. */
|
|
27
|
+
readonly selected?: string;
|
|
28
|
+
}
|
|
29
|
+
/** The font and size of every label in the viewer (bodies, paths, sky figures and anchors). Every field is optional and keeps its default when absent. A sky figure's own `labelFont` and `labelSizePx` win over these. */
|
|
30
|
+
export interface LabelsLook {
|
|
31
|
+
/** A CSS font-family text such as `"Georgia, serif"`; not empty. Default `"inherit"`: the page's own font. */
|
|
32
|
+
readonly fontFamily?: string;
|
|
33
|
+
/** Text size in pixels, 8 to 24. Default 12. */
|
|
34
|
+
readonly sizePx?: number;
|
|
35
|
+
}
|
|
10
36
|
/** The looks a scene may set with `Scene.setLook`: presentation settings that change how the scene is drawn, never where anything is. Each is optional and keeps its default when absent. */
|
|
11
37
|
export interface LookInput {
|
|
12
38
|
/** Brightness of the catalogue stars, 0 to 2; 1 is the baseline star curve and 0 hides them in effect. Default 1. */
|
|
@@ -25,8 +51,14 @@ export interface LookInput {
|
|
|
25
51
|
readonly featureMinBodyPx?: number;
|
|
26
52
|
/** How long the host's loading cover fades out at the first drawn frame, in seconds, 0 to 3. Default 0.6 (a value saved from the Developer drawer stands in its place). */
|
|
27
53
|
readonly loadFadeSeconds?: number;
|
|
54
|
+
/** How long sky figures, outlines and the reference circles take to fade in, lines and names together, when they appear (when the viewer opens, or when their switch turns on), in seconds, 0 to 3; 0 shows them at once. Default 0.5. A person who asked for less motion sees them at once. Figures shown only when traced appear by their trace instead. */
|
|
55
|
+
readonly skyFadeInSeconds?: number;
|
|
28
56
|
/** Whether bodies with a larger desktop picture use it on a wide screen (default false: the phone-sized picture everywhere). Read when the viewer is built: a later `setLook` neither swaps pictures nor changes what `look` reads. */
|
|
29
57
|
readonly desktopPictures?: boolean;
|
|
58
|
+
/** Colours of the sky lines and their names. Default: see `SkyLinesLook`. */
|
|
59
|
+
readonly skyLines?: SkyLinesLook;
|
|
60
|
+
/** The font and size of every label. Default: the page's font at 12 pixels, as before. */
|
|
61
|
+
readonly labels?: LabelsLook;
|
|
30
62
|
}
|
|
31
63
|
/** The looks a running viewer shows, every one filled in (`ViewerHandle.look`): the scene's `setLook`, the page address and the Developer drawer laid over the defaults. `sunGlow` is absent in a scene without the Sun. */
|
|
32
64
|
export interface LookRead {
|
|
@@ -42,6 +74,23 @@ export interface LookRead {
|
|
|
42
74
|
readonly markerSwapRadiusPx: number;
|
|
43
75
|
readonly featureMinBodyPx: number;
|
|
44
76
|
readonly loadFadeSeconds: number;
|
|
77
|
+
readonly skyFadeInSeconds: number;
|
|
45
78
|
/** Whether wide screens use the larger desktop pictures: the value the viewer was built with (the scene's look, or the page address); `setLook` does not change it. */
|
|
46
79
|
readonly desktopPictures: boolean;
|
|
80
|
+
/** The sky line colours in force, every one filled in. */
|
|
81
|
+
readonly skyLines: {
|
|
82
|
+
readonly figure: string;
|
|
83
|
+
readonly label: string;
|
|
84
|
+
readonly boundary: string;
|
|
85
|
+
readonly ecliptic: string;
|
|
86
|
+
readonly equator: string;
|
|
87
|
+
readonly traced: string;
|
|
88
|
+
readonly faded: string;
|
|
89
|
+
readonly selected: string;
|
|
90
|
+
};
|
|
91
|
+
/** The label font and size in force. */
|
|
92
|
+
readonly labels: {
|
|
93
|
+
readonly fontFamily: string;
|
|
94
|
+
readonly sizePx: number;
|
|
95
|
+
};
|
|
47
96
|
}
|
package/src/api/lookInput.d.ts
CHANGED
|
@@ -1,3 +1,3 @@
|
|
|
1
1
|
import type { LookInput } from "./look.js";
|
|
2
|
-
/** Checks a `setLook` argument: an object of known looks, each a finite number in its range or a
|
|
2
|
+
/** Checks a `setLook` argument: an object of known looks, each a finite number in its range, a boolean, a CSS colour or a font-family text as its field says. Returns a frozen copy (the scene keeps no reference to the caller's object). */
|
|
3
3
|
export declare function checkedLook(input: LookInput): LookInput;
|
package/src/api/lookInput.js
CHANGED
|
@@ -1,7 +1,8 @@
|
|
|
1
|
+
import { isCssColour, isFontFamily } from "../core/lookValues.js";
|
|
1
2
|
import { LOOK_FIELDS, lookName, lookValue, lookWith } from "../app/look.js";
|
|
2
3
|
import { SceneError } from "./errors.js";
|
|
3
4
|
const TOP_LEVEL = [...new Set(LOOK_FIELDS.map(({ path }) => path[0]))];
|
|
4
|
-
/** Checks a `setLook` argument: an object of known looks, each a finite number in its range or a
|
|
5
|
+
/** Checks a `setLook` argument: an object of known looks, each a finite number in its range, a boolean, a CSS colour or a font-family text as its field says. Returns a frozen copy (the scene keeps no reference to the caller's object). */
|
|
5
6
|
export function checkedLook(input) {
|
|
6
7
|
const bad = (message) => new SceneError("bad-look", `setLook: ${message}`);
|
|
7
8
|
const isObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
|
|
@@ -37,5 +38,9 @@ function valueProblem(field, value) {
|
|
|
37
38
|
const { spec } = field;
|
|
38
39
|
if (spec.kind === "range")
|
|
39
40
|
return typeof value === "number" && Number.isFinite(value) && value >= spec.min && value <= spec.max ? null : `must be a number from ${spec.min} to ${spec.max}`;
|
|
41
|
+
if (spec.kind === "colour")
|
|
42
|
+
return isCssColour(value) ? null : "must be a CSS colour such as \"#8fb4ff\" or \"rgb(143, 180, 255)\"";
|
|
43
|
+
if (spec.kind === "font")
|
|
44
|
+
return isFontFamily(value) ? null : "must be a non-empty CSS font-family text";
|
|
40
45
|
return typeof value === "boolean" ? null : "must be true or false";
|
|
41
46
|
}
|
package/src/api/planCamera.d.ts
CHANGED
|
@@ -4,7 +4,7 @@ import type { EccentricSampling } from "../core/sunCentredSources.js";
|
|
|
4
4
|
import type { ExperienceDefinition } from "../app/experienceDefinition.js";
|
|
5
5
|
import type { BodyRef } from "./bodies.js";
|
|
6
6
|
import type { FollowView } from "./scene.js";
|
|
7
|
-
import type { CameraPose } from "./viewerLink.js";
|
|
7
|
+
import type { CameraPose, SkyDirection } from "./viewerLink.js";
|
|
8
8
|
import type { TimelineSetting } from "./story.js";
|
|
9
9
|
/** The scene's camera: what it opens on. */
|
|
10
10
|
export declare class SceneCamera {
|
|
@@ -15,9 +15,23 @@ export declare class SceneCamera {
|
|
|
15
15
|
/** 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 `focus` wins. */
|
|
16
16
|
focus(id: string, view?: FollowView): this;
|
|
17
17
|
/**
|
|
18
|
-
* Opens
|
|
19
|
-
* `
|
|
20
|
-
*
|
|
18
|
+
* Opens standing inside a body (at its centre) and looking out, with no camera button pressed. `body` must be a body or trajectory already added (else `unknown-body`).
|
|
19
|
+
* `look` is checked by the rule `setCamera`'s look-out uses: `direction` is a star-map position (`{ raDeg, decDeg }`, J2000 degrees; default 0, 0) or the id of an object or sky figure to turn toward
|
|
20
|
+
* (a figure may be added later); `fovDeg` is the vertical field of view, 5 to 100 degrees (default 60). A malformed look throws `bad-camera`; an id the opening view cannot turn toward throws `bad-camera` when the scene is built.
|
|
21
|
+
* The viewer turns toward an id on its first frame as `setCamera` does; until then `pose` and `ViewerHandle.camera` are undefined. The last of `follow`, `focus`, `lookOut` and `setStartView` wins.
|
|
22
|
+
* @example
|
|
23
|
+
* scene.camera.lookOut("earth", { direction: { raDeg: 83.6, decDeg: 22 }, fovDeg: 40 });
|
|
24
|
+
* scene.camera.lookOut("earth", { direction: "Leo", fovDeg: 80 });
|
|
25
|
+
*/
|
|
26
|
+
lookOut(body: BodyRef | BodyId, look?: {
|
|
27
|
+
readonly direction?: SkyDirection | string;
|
|
28
|
+
readonly fovDeg?: number;
|
|
29
|
+
}): this;
|
|
30
|
+
/**
|
|
31
|
+
* Opens at a pose with no camera button pressed (neither Focus nor Follow shows as pressed, and choosing another body moves the camera as it does without a start). The pose is what `ViewerHandle.camera` reads, either kind:
|
|
32
|
+
* an orbit pose `{ focus, azimuthDeg, elevationDeg, distance }` (distance in Earth radii), or a sky pose `{ lookOut, raDeg, decDeg, fovDeg }` (standing inside a body, looking out).
|
|
33
|
+
* `focus` or `lookOut` must be a body or trajectory already added (else `unknown-body`); a bad angle, distance or field of view throws `bad-camera`.
|
|
34
|
+
* The last of `follow`, `focus`, `lookOut` and `setStartView` wins. Default: none.
|
|
21
35
|
* @example
|
|
22
36
|
* scene.camera.setStartView({ focus: "earth", azimuthDeg: 20, elevationDeg: 30, distance: 40 });
|
|
23
37
|
*/
|
|
@@ -29,6 +43,13 @@ export declare class SceneCamera {
|
|
|
29
43
|
* scene.camera.setFollowChoices(["moon"]);
|
|
30
44
|
*/
|
|
31
45
|
setFollowChoices(ids: readonly (BodyRef | BodyId)[]): this;
|
|
46
|
+
/**
|
|
47
|
+
* Chooses the bodies whose "Look out from" entry the camera menu offers, by body, id or path already added to the scene (else `unknown-body`); the entry stands inside the body and looks out, and any other camera entry leaves it.
|
|
48
|
+
* Default: none. An empty list offers none. The opening view is separate: `lookOut` opens looking out whether or not the body is listed.
|
|
49
|
+
* @example
|
|
50
|
+
* scene.camera.setLookOutChoices(["earth", "mars"]);
|
|
51
|
+
*/
|
|
52
|
+
setLookOutChoices(ids: readonly (BodyRef | BodyId)[]): this;
|
|
32
53
|
/**
|
|
33
54
|
* 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`.
|
|
34
55
|
* Also sets the camera's far plane (where drawing stops) to 2.5 times `distance`, so what lies out to the reach is still drawn; `farEarthRadii` (a finite number at least `distance`, in Earth radii) sets the far plane itself instead.
|
|
@@ -54,15 +75,22 @@ export declare class SceneCamera {
|
|
|
54
75
|
get reachEarthRadii(): number | undefined;
|
|
55
76
|
/** The far plane set with `setReach`'s `farEarthRadii`, if any. */
|
|
56
77
|
get farEarthRadii(): number | undefined;
|
|
57
|
-
/** The pose `setStartView` set, if it is the last opening call. */
|
|
78
|
+
/** The pose `setStartView` or `lookOut` set, if it is the last opening call (undefined after a `lookOut` toward an id). */
|
|
58
79
|
get pose(): CameraPose | undefined;
|
|
59
80
|
/** The objects offering Follow (`setFollowChoices`); undefined: every one. */
|
|
60
81
|
get followChoices(): readonly string[] | undefined;
|
|
82
|
+
/** The bodies offering "Look out from" (`setLookOutChoices`); none by default. */
|
|
83
|
+
get lookOutChoices(): readonly string[];
|
|
61
84
|
get target(): string | undefined;
|
|
62
85
|
/** Whether the opening view follows its target (`follow`) rather than only looking at it (`focus`). */
|
|
63
86
|
get following(): boolean;
|
|
64
87
|
get view(): FollowView;
|
|
65
88
|
}
|
|
89
|
+
/**
|
|
90
|
+
* Refuses an opening look-out toward an id `setCamera` would refuse on the opening view (`checkToward`, the same check and wording): the direction must name an object the opening view shows or a sky figure.
|
|
91
|
+
* Called when the scene is built, after every figure is in.
|
|
92
|
+
*/
|
|
93
|
+
export declare function checkOpeningLook(camera: SceneCamera, definition: ExperienceDefinition, groupIds: Iterable<string>, figureIds: Iterable<string>): void;
|
|
66
94
|
/** The fitted body's farthest Sun distance, read once when the viewer first needs it (a planet's reads the planet series, loaded by then); undefined when no orbit is fitted. */
|
|
67
95
|
export declare function fitFarthestKm(camera: SceneCamera, catalogue: BodyCatalogue, own: ReadonlyMap<BodyId, EccentricSampling>, openUtcMs: number): {
|
|
68
96
|
readonly read: () => number;
|
|
@@ -76,8 +104,8 @@ export declare function startPresetEntry(camera: SceneCamera): {
|
|
|
76
104
|
export declare function startViewEntry(camera: SceneCamera): Pick<ExperienceDefinition, "startView">;
|
|
77
105
|
/** The playback and camera settings the scene asked for: looping, the farthest zoom-out and the ecliptic up. */
|
|
78
106
|
export declare function viewEntries(timeline: TimelineSetting | undefined, camera: SceneCamera, farthestKm: (() => number) | undefined, cover: (() => number) | undefined): Pick<ExperienceDefinition, "loop" | "camera" | "viewUp">;
|
|
79
|
-
/** The camera menu: Overview, Focus for every body and path,
|
|
107
|
+
/** The camera menu: Overview, Focus for every body and path, Follow for every one unless `setFollowChoices` named fewer, and "Look out from" for the bodies `setLookOutChoices` listed (the look is toward right ascension 0, declination 0 until the visitor turns). */
|
|
80
108
|
export declare function cameraPresetsOf(objects: readonly {
|
|
81
109
|
readonly id: string;
|
|
82
110
|
readonly label: string;
|
|
83
|
-
}[], followChoices?: readonly string[]): ExperienceDefinition["experience"]["cameraPresets"];
|
|
111
|
+
}[], followChoices?: readonly string[], lookOutChoices?: readonly string[]): ExperienceDefinition["experience"]["cameraPresets"];
|
package/src/api/planCamera.js
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
import { SceneError } from "./errors.js";
|
|
2
2
|
import { frozenCopy } from "./frozenCopy.js";
|
|
3
|
-
import {
|
|
3
|
+
import { eqjUnitVector, SKY_OPENING_FOV_DEG, validateCameraView } from "../core/startView.js";
|
|
4
|
+
import { hiddenByView, viewById } from "../app/viewHiding.js";
|
|
5
|
+
import { cameraRequestOf, checkToward } from "./cameraRequest.js";
|
|
4
6
|
import { farthestSunDistanceKm } from "./sunOrbit.js";
|
|
5
7
|
import { planetSeriesLoaded } from "../core/planetSeries.js";
|
|
8
|
+
/** Each camera's opening look-out toward an id, kept out of the public class: the request the viewer runs on its first frame, as it runs a `setCamera` one. */
|
|
9
|
+
const towardIds = new WeakMap();
|
|
6
10
|
/** The scene's camera: what it opens on. */
|
|
7
11
|
export class SceneCamera {
|
|
8
12
|
#target;
|
|
@@ -12,6 +16,7 @@ export class SceneCamera {
|
|
|
12
16
|
#far;
|
|
13
17
|
#pose;
|
|
14
18
|
#followIds;
|
|
19
|
+
#lookOutIds = Object.freeze([]);
|
|
15
20
|
#fit;
|
|
16
21
|
#has;
|
|
17
22
|
#circlesSun;
|
|
@@ -37,24 +42,57 @@ export class SceneCamera {
|
|
|
37
42
|
throw new SceneError("bad-camera", `camera.${call}("${id}"): up "${String(view.up)}" must be "equatorial" or "ecliptic"`);
|
|
38
43
|
this.#target = id;
|
|
39
44
|
this.#pose = undefined;
|
|
45
|
+
towardIds.delete(this);
|
|
40
46
|
this.#following = following;
|
|
41
47
|
this.#view = frozenCopy(view);
|
|
42
48
|
return this;
|
|
43
49
|
}
|
|
44
50
|
/**
|
|
45
|
-
* Opens
|
|
46
|
-
* `
|
|
47
|
-
*
|
|
51
|
+
* Opens standing inside a body (at its centre) and looking out, with no camera button pressed. `body` must be a body or trajectory already added (else `unknown-body`).
|
|
52
|
+
* `look` is checked by the rule `setCamera`'s look-out uses: `direction` is a star-map position (`{ raDeg, decDeg }`, J2000 degrees; default 0, 0) or the id of an object or sky figure to turn toward
|
|
53
|
+
* (a figure may be added later); `fovDeg` is the vertical field of view, 5 to 100 degrees (default 60). A malformed look throws `bad-camera`; an id the opening view cannot turn toward throws `bad-camera` when the scene is built.
|
|
54
|
+
* The viewer turns toward an id on its first frame as `setCamera` does; until then `pose` and `ViewerHandle.camera` are undefined. The last of `follow`, `focus`, `lookOut` and `setStartView` wins.
|
|
55
|
+
* @example
|
|
56
|
+
* scene.camera.lookOut("earth", { direction: { raDeg: 83.6, decDeg: 22 }, fovDeg: 40 });
|
|
57
|
+
* scene.camera.lookOut("earth", { direction: "Leo", fovDeg: 80 });
|
|
58
|
+
*/
|
|
59
|
+
lookOut(body, look = {}) {
|
|
60
|
+
this.#editable();
|
|
61
|
+
const id = typeof body === "string" ? body : body?.id;
|
|
62
|
+
if (typeof look !== "object" || look === null || Array.isArray(look) || "lookOut" in look)
|
|
63
|
+
throw new SceneError("bad-camera", `camera.lookOut: the look must be { direction?, fovDeg? }, got ${JSON.stringify(look)}`);
|
|
64
|
+
const request = cameraRequestOf({ ...look, lookOut: id }, "camera.lookOut", undefined);
|
|
65
|
+
if (typeof request.direction !== "string") {
|
|
66
|
+
// Already checked: the nested or flat position, else right ascension 0, declination 0.
|
|
67
|
+
const record = look;
|
|
68
|
+
const { raDeg, decDeg } = (record.direction ?? ("raDeg" in record ? record : { raDeg: 0, decDeg: 0 }));
|
|
69
|
+
return this.#start({ lookOut: id, raDeg, decDeg, fovDeg: request.fovDeg ?? SKY_OPENING_FOV_DEG }, "camera.lookOut");
|
|
70
|
+
}
|
|
71
|
+
if (!this.#has(request.body))
|
|
72
|
+
throw new SceneError("unknown-body", `camera.lookOut: "${request.body}" has not been added to the scene`);
|
|
73
|
+
this.#reset();
|
|
74
|
+
towardIds.set(this, request);
|
|
75
|
+
return this;
|
|
76
|
+
}
|
|
77
|
+
/**
|
|
78
|
+
* Opens at a pose with no camera button pressed (neither Focus nor Follow shows as pressed, and choosing another body moves the camera as it does without a start). The pose is what `ViewerHandle.camera` reads, either kind:
|
|
79
|
+
* an orbit pose `{ focus, azimuthDeg, elevationDeg, distance }` (distance in Earth radii), or a sky pose `{ lookOut, raDeg, decDeg, fovDeg }` (standing inside a body, looking out).
|
|
80
|
+
* `focus` or `lookOut` must be a body or trajectory already added (else `unknown-body`); a bad angle, distance or field of view throws `bad-camera`.
|
|
81
|
+
* The last of `follow`, `focus`, `lookOut` and `setStartView` wins. Default: none.
|
|
48
82
|
* @example
|
|
49
83
|
* scene.camera.setStartView({ focus: "earth", azimuthDeg: 20, elevationDeg: 30, distance: 40 });
|
|
50
84
|
*/
|
|
51
85
|
setStartView(pose) {
|
|
86
|
+
return this.#start(pose, "camera.setStartView");
|
|
87
|
+
}
|
|
88
|
+
#start(pose, call) {
|
|
52
89
|
this.#editable();
|
|
53
|
-
const
|
|
54
|
-
|
|
55
|
-
|
|
90
|
+
const record = pose;
|
|
91
|
+
const named = record?.lookOut ?? record?.focus;
|
|
92
|
+
if (typeof named === "string" && !this.#has(named))
|
|
93
|
+
throw new SceneError("unknown-body", `${call}: "${named}" has not been added to the scene`);
|
|
56
94
|
try {
|
|
57
|
-
this.#pose =
|
|
95
|
+
this.#pose = validateCameraView(pose, `${call} pose`);
|
|
58
96
|
}
|
|
59
97
|
catch (error) {
|
|
60
98
|
if (error instanceof RangeError)
|
|
@@ -64,8 +102,16 @@ export class SceneCamera {
|
|
|
64
102
|
this.#target = undefined;
|
|
65
103
|
this.#following = false;
|
|
66
104
|
this.#view = {};
|
|
105
|
+
towardIds.delete(this);
|
|
67
106
|
return this;
|
|
68
107
|
}
|
|
108
|
+
/** Clears every opening call before a look-out toward an id. */
|
|
109
|
+
#reset() {
|
|
110
|
+
this.#target = undefined;
|
|
111
|
+
this.#pose = undefined;
|
|
112
|
+
this.#following = false;
|
|
113
|
+
this.#view = {};
|
|
114
|
+
}
|
|
69
115
|
/**
|
|
70
116
|
* Chooses the objects whose Follow button the camera menu offers, by body, id, path or group already added to the scene (else `unknown-body`); the others offer Focus only. An empty list offers Follow on none.
|
|
71
117
|
* Default: every body, path and group. A scene whose opening view follows an object (`follow`) must list it, else the scene throws `bad-camera` when it is built.
|
|
@@ -83,6 +129,23 @@ export class SceneCamera {
|
|
|
83
129
|
this.#followIds = Object.freeze([...new Set(named)]);
|
|
84
130
|
return this;
|
|
85
131
|
}
|
|
132
|
+
/**
|
|
133
|
+
* Chooses the bodies whose "Look out from" entry the camera menu offers, by body, id or path already added to the scene (else `unknown-body`); the entry stands inside the body and looks out, and any other camera entry leaves it.
|
|
134
|
+
* Default: none. An empty list offers none. The opening view is separate: `lookOut` opens looking out whether or not the body is listed.
|
|
135
|
+
* @example
|
|
136
|
+
* scene.camera.setLookOutChoices(["earth", "mars"]);
|
|
137
|
+
*/
|
|
138
|
+
setLookOutChoices(ids) {
|
|
139
|
+
this.#editable();
|
|
140
|
+
if (!Array.isArray(ids))
|
|
141
|
+
throw new SceneError("bad-camera", "camera.setLookOutChoices: give a list of bodies or ids");
|
|
142
|
+
const named = ids.map((item) => (typeof item === "string" ? item : item?.id));
|
|
143
|
+
for (const id of named)
|
|
144
|
+
if (typeof id !== "string" || !this.#has(id))
|
|
145
|
+
throw new SceneError("unknown-body", `camera.setLookOutChoices("${String(id)}"): no body or trajectory with that id has been added to the scene`);
|
|
146
|
+
this.#lookOutIds = Object.freeze([...new Set(named)]);
|
|
147
|
+
return this;
|
|
148
|
+
}
|
|
86
149
|
/**
|
|
87
150
|
* 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`.
|
|
88
151
|
* Also sets the camera's far plane (where drawing stops) to 2.5 times `distance`, so what lies out to the reach is still drawn; `farEarthRadii` (a finite number at least `distance`, in Earth radii) sets the far plane itself instead.
|
|
@@ -128,15 +191,31 @@ export class SceneCamera {
|
|
|
128
191
|
get reachEarthRadii() { return this.#reach; }
|
|
129
192
|
/** The far plane set with `setReach`'s `farEarthRadii`, if any. */
|
|
130
193
|
get farEarthRadii() { return this.#far; }
|
|
131
|
-
/** The pose `setStartView` set, if it is the last opening call. */
|
|
194
|
+
/** The pose `setStartView` or `lookOut` set, if it is the last opening call (undefined after a `lookOut` toward an id). */
|
|
132
195
|
get pose() { return this.#pose; }
|
|
133
196
|
/** The objects offering Follow (`setFollowChoices`); undefined: every one. */
|
|
134
197
|
get followChoices() { return this.#followIds; }
|
|
198
|
+
/** The bodies offering "Look out from" (`setLookOutChoices`); none by default. */
|
|
199
|
+
get lookOutChoices() { return this.#lookOutIds; }
|
|
135
200
|
get target() { return this.#target; }
|
|
136
201
|
/** Whether the opening view follows its target (`follow`) rather than only looking at it (`focus`). */
|
|
137
202
|
get following() { return this.#following; }
|
|
138
203
|
get view() { return this.#view; }
|
|
139
204
|
}
|
|
205
|
+
/**
|
|
206
|
+
* Refuses an opening look-out toward an id `setCamera` would refuse on the opening view (`checkToward`, the same check and wording): the direction must name an object the opening view shows or a sky figure.
|
|
207
|
+
* Called when the scene is built, after every figure is in.
|
|
208
|
+
*/
|
|
209
|
+
export function checkOpeningLook(camera, definition, groupIds, figureIds) {
|
|
210
|
+
const toward = towardIds.get(camera);
|
|
211
|
+
if (toward === undefined)
|
|
212
|
+
return;
|
|
213
|
+
const views = definition.views;
|
|
214
|
+
const hidden = hiddenByView(views, viewById(views, views?.start ?? ""), definition.experience).objects;
|
|
215
|
+
const shown = [...definition.experience.objects.map(({ id }) => id), ...groupIds].filter((id) => !hidden.has(id));
|
|
216
|
+
if (typeof toward.direction === "string")
|
|
217
|
+
checkToward(toward.direction, "camera.lookOut", shown, [...figureIds], "the opening view");
|
|
218
|
+
}
|
|
140
219
|
/** The fitted body's farthest Sun distance, read once when the viewer first needs it (a planet's reads the planet series, loaded by then); undefined when no orbit is fitted. */
|
|
141
220
|
export function fitFarthestKm(camera, catalogue, own, openUtcMs) {
|
|
142
221
|
const id = camera.fitted;
|
|
@@ -155,6 +234,9 @@ export function startPresetEntry(camera) {
|
|
|
155
234
|
}
|
|
156
235
|
/** The `startView` entry of the definition: the opening framing of the camera's target (absent when none was asked for). */
|
|
157
236
|
export function startViewEntry(camera) {
|
|
237
|
+
const toward = towardIds.get(camera);
|
|
238
|
+
if (toward !== undefined)
|
|
239
|
+
return { startView: toward };
|
|
158
240
|
if (camera.pose !== undefined)
|
|
159
241
|
return { startView: { ...camera.pose } };
|
|
160
242
|
const target = camera.target;
|
|
@@ -172,13 +254,14 @@ export function viewEntries(timeline, camera, farthestKm, cover) {
|
|
|
172
254
|
...(view.up === undefined || target === undefined ? {} : { viewUp: view.up }),
|
|
173
255
|
};
|
|
174
256
|
}
|
|
175
|
-
/** The camera menu: Overview, Focus for every body and path,
|
|
176
|
-
export function cameraPresetsOf(objects, followChoices) {
|
|
257
|
+
/** The camera menu: Overview, Focus for every body and path, Follow for every one unless `setFollowChoices` named fewer, and "Look out from" for the bodies `setLookOutChoices` listed (the look is toward right ascension 0, declination 0 until the visitor turns). */
|
|
258
|
+
export function cameraPresetsOf(objects, followChoices, lookOutChoices = []) {
|
|
177
259
|
return [
|
|
178
260
|
{ id: "overview", label: "Overview", request: { kind: "overview" } },
|
|
179
261
|
...objects.flatMap(({ id, label }) => [
|
|
180
262
|
{ id: `focus-${id}`, label: `Focus ${label}`, request: { kind: "focus", target: id } },
|
|
181
263
|
...(followChoices === undefined || followChoices.includes(id) ? [{ id: `follow-${id}`, label: `Follow ${label}`, request: { kind: "follow", target: id } }] : []),
|
|
264
|
+
...(lookOutChoices.includes(id) ? [{ id: `lookout-${id}`, label: `Look out from ${label}`, request: { kind: "lookOut", body: id, direction: eqjUnitVector(0, 0) } }] : []),
|
|
182
265
|
]),
|
|
183
266
|
];
|
|
184
267
|
}
|
|
@@ -0,0 +1,22 @@
|
|
|
1
|
+
import { type StarById } from "../assets/sky.js";
|
|
2
|
+
import { type SkyFigureLayer } from "../app/skyFigures.js";
|
|
3
|
+
import type { SkyFigureCard } from "../shell/experience.js";
|
|
4
|
+
import type { SkyFigureInput } from "./skyFigureInput.js";
|
|
5
|
+
import { type SceneSkyFigureRead } from "./sceneReads.js";
|
|
6
|
+
/** What a `Scene` has planned for sky figures, in the order added. */
|
|
7
|
+
export declare class SkyFigurePlan {
|
|
8
|
+
private readonly taken;
|
|
9
|
+
readonly figures: Map<string, SkyFigureInput>;
|
|
10
|
+
constructor(taken: (id: string) => boolean);
|
|
11
|
+
/** Checks every figure (shape, then ids against the scene and each other) and adds them all, or none. */
|
|
12
|
+
add(figures: readonly SkyFigureInput[]): void;
|
|
13
|
+
has(id: string): boolean;
|
|
14
|
+
/** The figures in the order added: id, label, kind, and the card words as given (`listed` true unless said false). */
|
|
15
|
+
reads(): readonly SceneSkyFigureRead[];
|
|
16
|
+
/** What the viewer's info card and object menu read for each figure (no star list needed). */
|
|
17
|
+
cards(): readonly SkyFigureCard[];
|
|
18
|
+
/** Whether any end names a catalogue star, so the star list is needed to place it. */
|
|
19
|
+
get needsStars(): boolean;
|
|
20
|
+
/** The drawable figures. `stars` finds a star by its Hipparcos number; a number it does not hold throws `unknown-star`. Called when the scene is built (the star list loads asynchronously, so not at the `addSkyFigures` call). */
|
|
21
|
+
layers(stars: ReadonlyMap<number, StarById>): readonly SkyFigureLayer[];
|
|
22
|
+
}
|
|
@@ -0,0 +1,145 @@
|
|
|
1
|
+
import { isCssColour, isFontFamily, LABEL_SIZE_LIMITS } from "../core/lookValues.js";
|
|
2
|
+
import { eqjUnit } from "../assets/sky.js";
|
|
3
|
+
import { meanDirection } from "../app/skyFigures.js";
|
|
4
|
+
import { createProvenance } from "../core/provenance.js";
|
|
5
|
+
import { SceneError } from "./errors.js";
|
|
6
|
+
import { frozenCopy } from "./frozenCopy.js";
|
|
7
|
+
import { frozenList } from "./sceneReads.js";
|
|
8
|
+
const bad = (id, message) => new SceneError("bad-sky-figure", `addSkyFigures("${String(id)}"): ${message}`);
|
|
9
|
+
const isText = (value) => typeof value === "string" && value !== "";
|
|
10
|
+
const isNumber = (value) => typeof value === "number" && Number.isFinite(value);
|
|
11
|
+
const isPosition = (value) => typeof value === "object" && value !== null && isNumber(value.raDeg) && isNumber(value.decDeg) && Math.abs(value.decDeg) <= 90;
|
|
12
|
+
const isStar = (value) => typeof value === "object" && value !== null && Number.isInteger(value.star) && value.star > 0;
|
|
13
|
+
function checkEnd(id, end, where) {
|
|
14
|
+
if (!isStar(end) && !isPosition(end))
|
|
15
|
+
throw bad(id, `${where} must be { star: <Hipparcos number> } or { raDeg, decDeg } with a declination within ±90, got ${JSON.stringify(end)}`);
|
|
16
|
+
}
|
|
17
|
+
/** Checks the card fields (description, facts, sources, provenance) and the menu flag, as `addBody` and `addTrajectory` check theirs. */
|
|
18
|
+
function checkCard(id, figure) {
|
|
19
|
+
if (figure.description !== undefined && !isText(figure.description))
|
|
20
|
+
throw bad(id, `description must be a non-empty text, got ${JSON.stringify(figure.description)}`);
|
|
21
|
+
const { facts, sources } = figure;
|
|
22
|
+
if (facts !== undefined && !(Array.isArray(facts) && facts.every((fact) => isText(fact?.label) && isText(fact?.value))))
|
|
23
|
+
throw bad(id, "facts must be a list of { label, value } with both texts non-empty");
|
|
24
|
+
if (sources !== undefined && !(Array.isArray(sources) && sources.every(isText)))
|
|
25
|
+
throw bad(id, "sources must be a list of non-empty texts");
|
|
26
|
+
if (figure.listed !== undefined && typeof figure.listed !== "boolean")
|
|
27
|
+
throw bad(id, `listed must be true or false, got ${JSON.stringify(figure.listed)}`);
|
|
28
|
+
if (figure.provenance !== undefined) {
|
|
29
|
+
try {
|
|
30
|
+
createProvenance(figure.provenance);
|
|
31
|
+
}
|
|
32
|
+
catch (error) {
|
|
33
|
+
throw bad(id, `provenance is malformed (${error instanceof Error ? error.message : String(error)})`);
|
|
34
|
+
}
|
|
35
|
+
}
|
|
36
|
+
}
|
|
37
|
+
/** The provenance a figure's card shows: the one given (default: illustrative, supplied by the caller, as for a path) with `sources` added after its own. */
|
|
38
|
+
function provenanceOf(figure) {
|
|
39
|
+
const own = figure.provenance ?? createProvenance({ sourceType: "illustrative", sources: ["Supplied by the caller"], accuracy: "As supplied; the engine makes no claim.", notes: "The figure's lines were passed to addSkyFigures." });
|
|
40
|
+
return createProvenance({ ...own, sources: [...own.sources, ...(figure.sources ?? [])] });
|
|
41
|
+
}
|
|
42
|
+
/** Checks a figure's own colours, label font and label size. */
|
|
43
|
+
function checkLooks(id, figure) {
|
|
44
|
+
if (figure.color !== undefined && !isCssColour(figure.color))
|
|
45
|
+
throw bad(id, `color must be a CSS colour such as "#8fb4ff", got ${JSON.stringify(figure.color)}`);
|
|
46
|
+
if (figure.labelColor !== undefined && !isCssColour(figure.labelColor))
|
|
47
|
+
throw bad(id, `labelColor must be a CSS colour such as "#cfe0ff", got ${JSON.stringify(figure.labelColor)}`);
|
|
48
|
+
if (figure.labelFont !== undefined && !isFontFamily(figure.labelFont))
|
|
49
|
+
throw bad(id, `labelFont must be a non-empty CSS font-family text, got ${JSON.stringify(figure.labelFont)}`);
|
|
50
|
+
if (figure.labelSizePx !== undefined && !(isNumber(figure.labelSizePx) && figure.labelSizePx >= LABEL_SIZE_LIMITS.min && figure.labelSizePx <= LABEL_SIZE_LIMITS.max))
|
|
51
|
+
throw bad(id, `labelSizePx must be a number from ${LABEL_SIZE_LIMITS.min} to ${LABEL_SIZE_LIMITS.max}, got ${JSON.stringify(figure.labelSizePx)}`);
|
|
52
|
+
}
|
|
53
|
+
/** Checks one figure's shape; throws `bad-sky-figure` naming the field. */
|
|
54
|
+
function checkShape(figure) {
|
|
55
|
+
if (typeof figure !== "object" || figure === null)
|
|
56
|
+
throw bad(figure, "give a { id, label, segments } or { id, label, kind: \"boundary\", points } object");
|
|
57
|
+
const { id, kind = "figure" } = figure;
|
|
58
|
+
if (!isText(id))
|
|
59
|
+
throw bad(id, "id must be a non-empty text");
|
|
60
|
+
if (!isText(figure.label))
|
|
61
|
+
throw bad(id, "label must be a non-empty text");
|
|
62
|
+
if (kind !== "figure" && kind !== "boundary")
|
|
63
|
+
throw bad(id, `kind must be "figure" or "boundary", got ${JSON.stringify(kind)}`);
|
|
64
|
+
if (kind === "figure") {
|
|
65
|
+
if (figure.points !== undefined)
|
|
66
|
+
throw bad(id, "a figure has segments, not points (use kind: \"boundary\" for points)");
|
|
67
|
+
if (!Array.isArray(figure.segments) || figure.segments.length === 0)
|
|
68
|
+
throw bad(id, "a figure needs segments: a non-empty list of [end, end] pairs");
|
|
69
|
+
figure.segments.forEach((pair, index) => {
|
|
70
|
+
if (!Array.isArray(pair) || pair.length !== 2)
|
|
71
|
+
throw bad(id, `segments[${index}] must be a pair [end, end]`);
|
|
72
|
+
checkEnd(id, pair[0], `segments[${index}][0]`);
|
|
73
|
+
checkEnd(id, pair[1], `segments[${index}][1]`);
|
|
74
|
+
});
|
|
75
|
+
}
|
|
76
|
+
else {
|
|
77
|
+
if (figure.segments !== undefined)
|
|
78
|
+
throw bad(id, "a boundary has points, not segments");
|
|
79
|
+
if (!Array.isArray(figure.points) || figure.points.length < 3)
|
|
80
|
+
throw bad(id, "a boundary needs points: a closed loop of at least three { raDeg, decDeg }");
|
|
81
|
+
figure.points.forEach((point, index) => { if (!isPosition(point))
|
|
82
|
+
throw bad(id, `points[${index}] must be { raDeg, decDeg } with a declination within ±90, got ${JSON.stringify(point)}`); });
|
|
83
|
+
}
|
|
84
|
+
if (figure.labelAt !== undefined && !isPosition(figure.labelAt))
|
|
85
|
+
throw bad(id, `labelAt must be { raDeg, decDeg } with a declination within ±90, got ${JSON.stringify(figure.labelAt)}`);
|
|
86
|
+
if (figure.shown !== undefined && figure.shown !== "always" && figure.shown !== "whenTraced")
|
|
87
|
+
throw bad(id, `shown must be "always" or "whenTraced", got ${JSON.stringify(figure.shown)}`);
|
|
88
|
+
checkLooks(id, figure);
|
|
89
|
+
checkCard(id, figure);
|
|
90
|
+
}
|
|
91
|
+
const endsOf = (figure) => (figure.segments ?? []).flat();
|
|
92
|
+
/** What a `Scene` has planned for sky figures, in the order added. */
|
|
93
|
+
export class SkyFigurePlan {
|
|
94
|
+
taken;
|
|
95
|
+
figures = new Map();
|
|
96
|
+
constructor(taken) {
|
|
97
|
+
this.taken = taken;
|
|
98
|
+
}
|
|
99
|
+
/** Checks every figure (shape, then ids against the scene and each other) and adds them all, or none. */
|
|
100
|
+
add(figures) {
|
|
101
|
+
if (!Array.isArray(figures) || figures.length === 0)
|
|
102
|
+
throw bad("", "give a non-empty list of figures");
|
|
103
|
+
const copies = figures.map((figure) => { checkShape(figure); return frozenCopy(figure); });
|
|
104
|
+
const seen = new Set();
|
|
105
|
+
for (const { id } of copies) {
|
|
106
|
+
if (this.figures.has(id) || seen.has(id) || this.taken(id))
|
|
107
|
+
throw new SceneError("duplicate-id", `addSkyFigures("${id}"): that id is already in the scene`);
|
|
108
|
+
seen.add(id);
|
|
109
|
+
}
|
|
110
|
+
for (const copy of copies)
|
|
111
|
+
this.figures.set(copy.id, copy);
|
|
112
|
+
}
|
|
113
|
+
has(id) { return this.figures.has(id); }
|
|
114
|
+
/** The figures in the order added: id, label, kind, and the card words as given (`listed` true unless said false). */
|
|
115
|
+
reads() {
|
|
116
|
+
return frozenList([...this.figures.values()].map((figure) => ({ id: figure.id, label: figure.label, kind: figure.kind ?? "figure", listed: figure.listed !== false, provenance: provenanceOf(figure), ...(figure.description === undefined ? {} : { description: figure.description }), ...(figure.facts === undefined ? {} : { facts: figure.facts }) })));
|
|
117
|
+
}
|
|
118
|
+
/** What the viewer's info card and object menu read for each figure (no star list needed). */
|
|
119
|
+
cards() {
|
|
120
|
+
return [...this.figures.values()].map((figure) => ({ id: figure.id, label: figure.label, listed: figure.listed !== false, provenance: provenanceOf(figure), ...(figure.description === undefined ? {} : { description: figure.description }), ...(figure.facts === undefined ? {} : { facts: figure.facts }) }));
|
|
121
|
+
}
|
|
122
|
+
/** Whether any end names a catalogue star, so the star list is needed to place it. */
|
|
123
|
+
get needsStars() { return [...this.figures.values()].some((figure) => endsOf(figure).some((end) => "star" in end)); }
|
|
124
|
+
/** The drawable figures. `stars` finds a star by its Hipparcos number; a number it does not hold throws `unknown-star`. Called when the scene is built (the star list loads asynchronously, so not at the `addSkyFigures` call). */
|
|
125
|
+
layers(stars) {
|
|
126
|
+
const direction = (id, end) => {
|
|
127
|
+
if ("star" in end) {
|
|
128
|
+
const found = stars.get(end.star);
|
|
129
|
+
if (found === undefined)
|
|
130
|
+
throw new SceneError("unknown-star", `addSkyFigures("${id}"): star ${end.star} is not in the star list (Hipparcos numbers of stars of magnitude 6.5 or brighter)`);
|
|
131
|
+
return found.direction;
|
|
132
|
+
}
|
|
133
|
+
return eqjUnit(end.raDeg, end.decDeg);
|
|
134
|
+
};
|
|
135
|
+
return [...this.figures.values()].map((figure) => {
|
|
136
|
+
const kind = figure.kind ?? "figure";
|
|
137
|
+
const segments = kind === "figure"
|
|
138
|
+
? figure.segments.map(([from, to]) => [direction(figure.id, from), direction(figure.id, to)])
|
|
139
|
+
: figure.points.map((point, index) => [eqjUnit(point.raDeg, point.decDeg), eqjUnit(figure.points[(index + 1) % figure.points.length].raDeg, figure.points[(index + 1) % figure.points.length].decDeg)]);
|
|
140
|
+
const labelAt = figure.labelAt === undefined ? meanDirection(segments.flatMap(([from, to]) => [from, to])) : eqjUnit(figure.labelAt.raDeg, figure.labelAt.decDeg);
|
|
141
|
+
const own = ["color", "labelColor", "labelFont", "labelSizePx"].filter((key) => figure[key] !== undefined);
|
|
142
|
+
return { id: figure.id, label: figure.label, kind, segments, labelAt, ...(figure.shown === "whenTraced" ? { whenTraced: true } : {}), ...Object.fromEntries(own.map((key) => [key, figure[key]])) };
|
|
143
|
+
});
|
|
144
|
+
}
|
|
145
|
+
}
|
package/src/api/planStory.d.ts
CHANGED
|
@@ -16,11 +16,11 @@ export declare class StoryPlan {
|
|
|
16
16
|
/** The events name only objects the scene holds. */
|
|
17
17
|
checkObjects(ids: ReadonlySet<string>): void;
|
|
18
18
|
/** The story panels, resolved against this scene's events, the anchors of its paths, its objects and timeline span. */
|
|
19
|
-
panels(window: TimeBounds, tracked: Iterable<Tracked>, objectIds: readonly string[]): StoryPanelSet | undefined;
|
|
19
|
+
panels(window: TimeBounds, tracked: Iterable<Tracked>, objectIds: readonly string[], figureIds: readonly string[]): StoryPanelSet | undefined;
|
|
20
20
|
/** The events sorted by time, each with its own provenance, else the batch's. */
|
|
21
21
|
eventReads(): readonly SceneEventRead[];
|
|
22
22
|
/** The story panels as the public list states them (resolved as `panels` resolves them); empty when none were added. */
|
|
23
|
-
panelReads(window: TimeBounds, tracked: Iterable<Tracked>, objectIds: readonly string[]): readonly ScenePanelRead[];
|
|
23
|
+
panelReads(window: TimeBounds, tracked: Iterable<Tracked>, objectIds: readonly string[], figureIds: readonly string[]): readonly ScenePanelRead[];
|
|
24
24
|
/** The event provenance entries of the experience: the batch's, and each event's own. */
|
|
25
25
|
provenanceEntries(): Pick<ExperienceConfig, "eventProvenance" | "eventProvenanceById">;
|
|
26
26
|
}
|