astraeus 0.8.1 → 0.9.1

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.
Files changed (131) hide show
  1. package/CHANGELOG.md +85 -0
  2. package/README.md +104 -31
  3. package/package.json +1 -1
  4. package/src/api/AstraeusScene.d.ts +1 -1
  5. package/src/api/AstraeusScene.js +4 -1
  6. package/src/api/AstraeusScene.node.js +4 -1
  7. package/src/api/assembleScene.d.ts +2 -0
  8. package/src/api/assembleScene.js +28 -6
  9. package/src/api/cameraRequest.d.ts +15 -0
  10. package/src/api/cameraRequest.js +89 -0
  11. package/src/api/errors.d.ts +9 -1
  12. package/src/api/index.d.ts +6 -3
  13. package/src/api/look.d.ts +49 -0
  14. package/src/api/lookInput.d.ts +1 -1
  15. package/src/api/lookInput.js +6 -1
  16. package/src/api/planBodies.d.ts +2 -1
  17. package/src/api/planBodies.js +6 -1
  18. package/src/api/planCamera.d.ts +35 -7
  19. package/src/api/planCamera.js +94 -11
  20. package/src/api/planPaths.d.ts +2 -0
  21. package/src/api/planPaths.js +14 -9
  22. package/src/api/planSkyFigures.d.ts +22 -0
  23. package/src/api/planSkyFigures.js +145 -0
  24. package/src/api/planStory.d.ts +2 -2
  25. package/src/api/planStory.js +14 -9
  26. package/src/api/planViews.js +1 -1
  27. package/src/api/providerPathTimes.d.ts +10 -0
  28. package/src/api/providerPathTimes.js +109 -0
  29. package/src/api/scene.d.ts +23 -4
  30. package/src/api/scene.js +23 -5
  31. package/src/api/sceneReads.d.ts +21 -2
  32. package/src/api/shownDuring.d.ts +12 -0
  33. package/src/api/shownDuring.js +30 -0
  34. package/src/api/skyFigureInput.d.ts +45 -0
  35. package/src/api/skyFigureInput.js +1 -0
  36. package/src/api/skyTraceInput.d.ts +33 -0
  37. package/src/api/skyTraceInput.js +45 -0
  38. package/src/api/story.d.ts +13 -4
  39. package/src/api/story.js +45 -2
  40. package/src/api/viewerCamera.d.ts +4 -3
  41. package/src/api/viewerCamera.js +10 -32
  42. package/src/api/viewerHandle.d.ts +27 -4
  43. package/src/api/viewerHandle.js +6 -0
  44. package/src/api/viewerLink.d.ts +49 -4
  45. package/src/api/viewerLink.js +25 -0
  46. package/src/api/viewerPanels.d.ts +26 -0
  47. package/src/api/viewerPanels.js +42 -0
  48. package/src/api/viewerSelection.d.ts +1 -1
  49. package/src/api/viewerSelection.js +3 -3
  50. package/src/app/App.js +129 -30
  51. package/src/app/App.node.js +129 -30
  52. package/src/app/AstraeusScene.d.ts +20 -5
  53. package/src/app/AstraeusScene.js +3 -3
  54. package/src/app/CameraController.d.ts +19 -1
  55. package/src/app/CameraController.js +38 -11
  56. package/src/app/DeveloperSettings.d.ts +11 -3
  57. package/src/app/DeveloperSettings.js +13 -3
  58. package/src/app/SceneLabels.d.ts +20 -2
  59. package/src/app/SceneLabels.js +46 -6
  60. package/src/app/SkyFiguresView.d.ts +56 -0
  61. package/src/app/SkyFiguresView.js +242 -0
  62. package/src/app/StoryMarkers.d.ts +2 -2
  63. package/src/app/StoryMarkers.js +2 -2
  64. package/src/app/displaySwitches.d.ts +13 -3
  65. package/src/app/displaySwitches.js +17 -3
  66. package/src/app/experienceDefinition.d.ts +9 -3
  67. package/src/app/experienceDefinition.js +4 -2
  68. package/src/app/labelStyle.d.ts +17 -0
  69. package/src/app/labelStyle.js +13 -0
  70. package/src/app/liveLook.js +8 -0
  71. package/src/app/look.d.ts +9 -5
  72. package/src/app/look.js +11 -0
  73. package/src/app/lookOut.d.ts +32 -0
  74. package/src/app/lookOut.js +50 -0
  75. package/src/app/sceneCamera.d.ts +5 -3
  76. package/src/app/sceneCamera.js +66 -3
  77. package/src/app/sceneContentsHooks.d.ts +2 -1
  78. package/src/app/sceneContentsHooks.js +3 -2
  79. package/src/app/sceneFrame.d.ts +22 -4
  80. package/src/app/sceneFrame.js +67 -22
  81. package/src/app/sceneFraming.d.ts +7 -0
  82. package/src/app/sceneFraming.js +12 -0
  83. package/src/app/sceneHooks.d.ts +2 -0
  84. package/src/app/sceneHooks.js +4 -1
  85. package/src/app/scenePicking.d.ts +20 -0
  86. package/src/app/scenePicking.js +49 -0
  87. package/src/app/scenePointer.d.ts +3 -1
  88. package/src/app/scenePointer.js +3 -2
  89. package/src/app/skyFigures.d.ts +73 -0
  90. package/src/app/skyFigures.js +50 -0
  91. package/src/app/style.css +2 -1
  92. package/src/app/viewHiding.d.ts +10 -1
  93. package/src/app/viewHiding.js +30 -1
  94. package/src/app/viewLink.d.ts +8 -8
  95. package/src/app/viewLink.js +24 -4
  96. package/src/app/viewerPort.d.ts +30 -3
  97. package/src/assets/sky.d.ts +13 -4
  98. package/src/assets/sky.js +33 -8
  99. package/src/assets/stars/hyg-v42-naked-eye.json +1 -1
  100. package/src/core/bodies/moonSystem.js +1 -15
  101. package/src/core/lookValues.d.ts +9 -0
  102. package/src/core/lookValues.js +24 -0
  103. package/src/core/pacing.d.ts +38 -6
  104. package/src/core/pacing.js +141 -21
  105. package/src/core/readBytes.d.ts +1 -0
  106. package/src/core/readBytes.js +15 -0
  107. package/src/core/skyTrace.d.ts +49 -0
  108. package/src/core/skyTrace.js +39 -0
  109. package/src/core/startView.d.ts +39 -0
  110. package/src/core/startView.js +56 -0
  111. package/src/core/storyPanels.d.ts +51 -3
  112. package/src/core/storyPanels.js +52 -12
  113. package/src/shell/AstraeusShell.d.ts +17 -6
  114. package/src/shell/AstraeusShell.js +100 -26
  115. package/src/shell/AstraeusShell.node.js +100 -26
  116. package/src/shell/ObjectControls.js +11 -8
  117. package/src/shell/StoryPanelView.d.ts +12 -3
  118. package/src/shell/StoryPanelView.js +2 -2
  119. package/src/shell/experience.d.ts +31 -0
  120. package/src/shell/experience.js +4 -1
  121. package/src/shell/infoModel.js +9 -1
  122. package/src/shell/objectModel.d.ts +9 -4
  123. package/src/shell/objectModel.js +16 -5
  124. package/src/shell/phone.css +1 -1
  125. package/src/shell/storyPanels.d.ts +1 -1
  126. package/src/shell/storyPanels.js +1 -1
  127. package/src/shell/style.css +9 -1
  128. package/src/shell/topBarIcons.d.ts +1 -0
  129. package/src/shell/topBarIcons.js +1 -0
  130. package/src/shell/useStoryPanels.d.ts +9 -6
  131. package/src/shell/useStoryPanels.js +10 -6
@@ -8,9 +8,10 @@ import { needsPlanetSeries } from "../app/planetNeeds.js";
8
8
  import { createReadoutMetrics } from "../app/trackedMetrics.js";
9
9
  import { checkDataSources, installData } from "./data.js";
10
10
  import { SceneError } from "./errors.js";
11
- import { cameraPresetsOf, fitFarthestKm, startPresetEntry, startViewEntry, viewEntries } from "./planCamera.js";
11
+ import { cameraPresetsOf, checkOpeningLook, fitFarthestKm, startPresetEntry, startViewEntry, viewEntries } from "./planCamera.js";
12
12
  import { groupLayersEntry, lateGroups } from "./planGroups.js";
13
13
  import { autoPaths, checkNamedReadouts, checkReadouts, pathCover } from "./planPaths.js";
14
+ import { loadStarCatalogue, starIdsOf } from "../assets/sky.js";
14
15
  /** The `out-of-span` error naming the planets when the scene's window reaches outside the years the planet series cover (the series are loaded); undefined otherwise. */
15
16
  function planetSpanError(ids, window) {
16
17
  const planets = ids.filter(isPlanetId);
@@ -61,7 +62,7 @@ function deferredRead(ids, window, fault, fallback, read) {
61
62
  }
62
63
  /** The app's plug-in contract for a scene's planners. Throws if the scene is empty or a body needs a data package not passed in `data`. */
63
64
  export function assembleScene(parts, data) {
64
- const { plan, groupPlan, bodySets, moonPanel, places, story, timeline: timelinePlan, viewPlan, camera, tracked: trackedMap } = parts;
65
+ const { plan, groupPlan, bodySets, moonPanel, places, story, timeline: timelinePlan, viewPlan, camera, tracked: trackedMap, skyFigures } = parts;
65
66
  if (plan.bodies.size === 0)
66
67
  throw new SceneError("empty-scene", "the scene has no bodies; call addBody before mount");
67
68
  checkDataSources(data);
@@ -89,7 +90,7 @@ export function assembleScene(parts, data) {
89
90
  const fit = deferredRead(ids, window, fault, undefined, () => fitFarthestKm(camera, plan.catalogue, plan.own, startUtcMs));
90
91
  // The lines read planet positions; when the planet series are not loaded yet (a consumer's mount), they are drawn in `prepare`, once the series are in. The viewer draws only after `prepare` resolves.
91
92
  const sunPaths = deferredRead(ids, window, fault, [], () => plan.earlySunPaths(sunOrbitIds, startUtcMs, planetSeriesLoaded()));
92
- const storyPanels = story.panels(window, trackedMap.values(), [...plan.bodies.keys(), ...trackedMap.keys(), ...groupPlan.groups.keys(), ...bodySets.memberIds()]);
93
+ const storyPanels = story.panels(window, trackedMap.values(), [...plan.bodies.keys(), ...trackedMap.keys(), ...groupPlan.groups.keys(), ...bodySets.memberIds()], [...skyFigures.figures.keys()]);
93
94
  groupPlan.check(ids);
94
95
  bodySets.check({ ids, catalogue: plan.catalogue, orbits: plan.orbits });
95
96
  // A clump near a body reads its position; with the planet series not loaded yet, those groups are built in `prepare` (the viewer draws only after it resolves).
@@ -101,23 +102,25 @@ export function assembleScene(parts, data) {
101
102
  const catalogue = plan.catalogue;
102
103
  if (camera.following && camera.target !== undefined && camera.followChoices !== undefined && !camera.followChoices.includes(camera.target))
103
104
  throw new SceneError("bad-camera", `camera.follow("${camera.target}"): the opening view follows "${camera.target}", which camera.setFollowChoices does not list`);
104
- story.checkObjects(new Set(labelled.map(({ id }) => id)));
105
+ story.checkObjects(new Set([...labelled.map(({ id }) => id), ...skyFigures.figures.keys()]));
105
106
  const objects = [
106
107
  ...[...plan.bodies.values()].map((body) => plan.bodyObject(body, ids, sunCentred, camera)),
107
- ...[...trackedMap.values()].map(({ body, description, knownLimitations, provenanceSpans }) => ({ id: body.id, label: body.label, color: body.color, availability: body.trajectory.bounds, labelPriority: 80, ...plan.labelReach(body.id, sunCentred, camera), provenance: body.provenance, ...(provenanceSpans === undefined ? {} : { provenanceSpans }), ...(description === undefined ? {} : { description }), ...(knownLimitations === undefined ? {} : { knownLimitations }) })),
108
+ ...[...trackedMap.values()].map(({ body, description, knownLimitations, provenanceSpans, shownDuring }) => ({ id: body.id, label: body.label, color: body.color, availability: body.trajectory.bounds, labelPriority: 80, ...plan.labelReach(body.id, sunCentred, camera), provenance: body.provenance, ...(provenanceSpans === undefined ? {} : { provenanceSpans }), ...(shownDuring === undefined ? {} : { shownDuring }), ...(description === undefined ? {} : { description }), ...(knownLimitations === undefined ? {} : { knownLimitations }) })),
108
109
  ...bodySets.objects({ ids, catalogue: plan.catalogue }),
109
110
  ];
110
111
  const pictures = mergePictures(data.map((source) => source.pictures));
111
112
  const members = new Set(bodySets.memberIds());
112
113
  const moonFamilies = moonPanel.list(new Map(objects.filter(({ id }) => plan.bodies.has(id) || members.has(id)).map(({ id, label }) => [id, label])), new Set(ids), plan.catalogue, (picture) => pictures[picture]?.url);
114
+ const figures = skyFigureLayers(skyFigures);
113
115
  const bodyFeatures = places.featureSets(new Map(objects.map(({ id, label }) => [id, label])));
114
116
  const definition = {
115
117
  experience: {
116
118
  objects,
117
- cameraPresets: cameraPresetsOf(labelled, camera.followChoices),
119
+ cameraPresets: cameraPresetsOf(labelled, camera.followChoices, camera.lookOutChoices),
118
120
  ...startPresetEntry(camera),
119
121
  ...(moonFamilies === undefined ? {} : { moonFamilies }),
120
122
  ...(bodyFeatures.length === 0 ? {} : { bodyFeatures }),
123
+ ...(skyFigures.figures.size === 0 ? {} : { skyFigures: skyFigures.cards() }),
121
124
  events: story.events,
122
125
  ...story.provenanceEntries(),
123
126
  ...(storyPanels === undefined ? {} : { storyPanels }),
@@ -131,6 +134,7 @@ export function assembleScene(parts, data) {
131
134
  ...groupLayersEntry(layers, groupPlan.groups.size > 0, sunOrbitIds.length > 0),
132
135
  ...(sunOrbitIds.length === 0 ? {} : { paths: sunPaths }),
133
136
  ...(setLayers.length === 0 ? {} : { bodySets: setLayers }),
137
+ ...figures.entry,
134
138
  ...(plan.catalogue === builtInCatalogue ? {} : { catalogue: plan.catalogue }),
135
139
  ...plan.visualOverrides(),
136
140
  // The viewer draws only the pictures of the packages passed to it (T-252); nothing is shared between viewers.
@@ -164,8 +168,10 @@ export function assembleScene(parts, data) {
164
168
  if (fit !== undefined)
165
169
  planetRead(ids, window, () => fit.settle());
166
170
  await installData(data, ids, window, catalogue, bodySets.load());
171
+ await figures.settle();
167
172
  },
168
173
  };
174
+ checkOpeningLook(camera, definition, groupPlan.groups.keys(), skyFigures.figures.keys());
169
175
  return definition;
170
176
  }
171
177
  /** The viewer's own pictures (those of the packages passed to it); absent when no package brings any. */
@@ -173,3 +179,19 @@ function picturesEntry(data) {
173
179
  const pictures = mergePictures(data.map((source) => source.pictures));
174
180
  return Object.keys(pictures).length === 0 ? {} : { pictures };
175
181
  }
182
+ /** The sky figures' drawable layers: placed now when no end names a star, else by `settle` (in `prepare`), once the star list has loaded (the viewer draws only after `prepare` resolves). */
183
+ function skyFigureLayers(plan) {
184
+ const layers = plan.needsStars ? [] : [...plan.layers(new Map())];
185
+ return {
186
+ entry: plan.figures.size === 0 ? {} : { skyFigures: layers },
187
+ settle: async () => { if (plan.needsStars && layers.length === 0)
188
+ layers.push(...plan.layers(await starsOf())); },
189
+ };
190
+ }
191
+ /** The star list's stars by Hipparcos number, for placing figures that name stars; the list unreadable throws `missing-data`. */
192
+ async function starsOf() {
193
+ const loaded = await loadStarCatalogue();
194
+ if (loaded === null)
195
+ throw new SceneError("missing-data", "a sky figure names a star, but the engine's star list could not be read; check that the star file is served with the app, or place the figure by { raDeg, decDeg }");
196
+ return starIdsOf(loaded);
197
+ }
@@ -0,0 +1,15 @@
1
+ import type { CameraRequest } from "../app/CameraController.js";
2
+ import type { CameraPose } from "./viewerLink.js";
3
+ /**
4
+ * Checks the shape of a camera target (what `setCamera` takes) and turns it into the request the scene camera runs; a malformed one throws `bad-camera` leading with `call`.
5
+ * It does not look at the scene: which ids exist is the caller's check. A look-out target without a direction takes the one `now` looks along while looking out, else right ascension 0, declination 0;
6
+ * with `keepDirection` it is left out of the request instead, and the camera keeps its own when the request runs (a story panel's camera, decided as it opens).
7
+ */
8
+ export declare function cameraRequestOf(target: unknown, call: string, now: CameraPose | undefined, keepDirection?: boolean): CameraRequest;
9
+ /**
10
+ * Checks the ids a camera request names against what the viewer can turn toward: each body or object must be one of `shown` (the objects the view named by `view` shows),
11
+ * and a look-out direction id one of those or of `figures` (the scene's sky figures). Throws `bad-camera` leading with `call`. `setCamera` runs it as it is called; the opening look-out runs `checkToward` when the scene is built.
12
+ */
13
+ export declare function checkCameraIds(request: CameraRequest, call: string, shown: readonly string[], figures: readonly string[], view?: string): void;
14
+ /** The look-out direction id half of `checkCameraIds`: `toward` must be an object `view` shows or a sky figure, else `bad-camera` naming it. */
15
+ export declare function checkToward(toward: string, call: string, shown: readonly string[], figures: readonly string[], view?: string): void;
@@ -0,0 +1,89 @@
1
+ import { cameraIdsOf } from "../core/storyPanels.js";
2
+ import { eqjUnitVector, validateSkyDirection, validateSkyFov, validateSkyPosition, validateStartView } from "../core/startView.js";
3
+ import { SceneError } from "./errors.js";
4
+ /**
5
+ * Checks the shape of a camera target (what `setCamera` takes) and turns it into the request the scene camera runs; a malformed one throws `bad-camera` leading with `call`.
6
+ * It does not look at the scene: which ids exist is the caller's check. A look-out target without a direction takes the one `now` looks along while looking out, else right ascension 0, declination 0;
7
+ * with `keepDirection` it is left out of the request instead, and the camera keeps its own when the request runs (a story panel's camera, decided as it opens).
8
+ */
9
+ export function cameraRequestOf(target, call, now, keepDirection = false) {
10
+ const bad = (why) => new SceneError("bad-camera", `${call}: ${why}; give { follow: id }, { focus: id }, { lookOut: id, direction?, fovDeg? } or a pose from camera`);
11
+ if (typeof target !== "object" || target === null || Array.isArray(target))
12
+ throw bad(`${String(target)} is not an object`);
13
+ const record = target;
14
+ if ("lookOut" in record)
15
+ return lookOutOf(record, now, keepDirection, bad);
16
+ // A pose names its object with `focus` too; its angle and distance fields tell it from `{ focus: id }`.
17
+ const isPose = ["azimuthDeg", "elevationDeg", "distance"].some((key) => key in record) || !("follow" in record || "focus" in record);
18
+ const named = ["follow", "focus"].filter((key) => key in record);
19
+ if (isPose) {
20
+ try {
21
+ return { kind: "pose", view: validateStartView(record, "pose") };
22
+ }
23
+ catch (cause) {
24
+ throw bad(cause instanceof Error ? cause.message : "a malformed pose");
25
+ }
26
+ }
27
+ const id = record[named[0]];
28
+ if (named.length > 1 || Object.keys(record).length > 1 || typeof id !== "string" || id === "")
29
+ throw bad("the target must be exactly one of follow or focus, naming a non-empty id");
30
+ return { kind: named[0], target: id };
31
+ }
32
+ /**
33
+ * Checks the ids a camera request names against what the viewer can turn toward: each body or object must be one of `shown` (the objects the view named by `view` shows),
34
+ * and a look-out direction id one of those or of `figures` (the scene's sky figures). Throws `bad-camera` leading with `call`. `setCamera` runs it as it is called; the opening look-out runs `checkToward` when the scene is built.
35
+ */
36
+ export function checkCameraIds(request, call, shown, figures, view = "the showing view") {
37
+ const { bodies, toward } = cameraIdsOf(request);
38
+ for (const id of bodies)
39
+ if (!shown.includes(id))
40
+ throw new SceneError("bad-camera", `${call}: "${id}" is not an object ${view} shows (${shown.join(", ")})`);
41
+ if (toward !== undefined)
42
+ checkToward(toward, call, shown, figures, view);
43
+ }
44
+ /** The look-out direction id half of `checkCameraIds`: `toward` must be an object `view` shows or a sky figure, else `bad-camera` naming it. */
45
+ export function checkToward(toward, call, shown, figures, view = "the showing view") {
46
+ if (!shown.includes(toward) && !figures.includes(toward))
47
+ throw new SceneError("bad-camera", `${call}: "${toward}" is neither an object ${view} shows (${shown.join(", ")}) nor a sky figure the viewer draws (${figures.join(", ") || "none added"})`);
48
+ }
49
+ /** A look-out target or a sky pose: the body, a direction (`direction`, or `raDeg` and `decDeg` together), and a field of view. */
50
+ function lookOutOf(record, now, keepDirection, bad) {
51
+ const body = record.lookOut;
52
+ if (typeof body !== "string" || body === "")
53
+ throw bad("lookOut must name a non-empty body id");
54
+ for (const key of Object.keys(record))
55
+ if (!["lookOut", "direction", "fovDeg", "raDeg", "decDeg"].includes(key))
56
+ throw bad(`${key} is not a look-out field`);
57
+ try {
58
+ const fovDeg = record.fovDeg === undefined ? undefined : validateSkyFov(record.fovDeg, "lookOut");
59
+ const direction = lookDirection(record, body, now, keepDirection, bad);
60
+ return { kind: "lookOut", body, ...(direction === undefined ? {} : { direction }), ...(fovDeg === undefined ? {} : { fovDeg }) };
61
+ }
62
+ catch (cause) {
63
+ throw cause instanceof RangeError ? bad(cause.message) : cause;
64
+ }
65
+ }
66
+ /** The look direction a look-out target names: `raDeg` and `decDeg` together (a sky pose), `direction` as a position or an object id, else the one already looked along (else right ascension 0, declination 0). Throws a `bad-camera` SceneError (or a RangeError from the range checks, which the caller turns into one). */
67
+ function lookDirection(record, body, now, keepDirection, bad) {
68
+ const flat = "raDeg" in record || "decDeg" in record;
69
+ const given = record.direction;
70
+ if (flat && given !== undefined)
71
+ throw bad("give direction or raDeg and decDeg, not both");
72
+ if (flat)
73
+ return pointOf(record.raDeg, record.decDeg, "lookOut");
74
+ if (typeof given === "string") {
75
+ if (given === "" || given === body)
76
+ throw bad("direction must name an object other than the body looked out from");
77
+ return given;
78
+ }
79
+ if (given === undefined && keepDirection)
80
+ return undefined;
81
+ if (given === undefined)
82
+ return now !== undefined && "lookOut" in now ? pointOf(now.raDeg, now.decDeg, "lookOut") : pointOf(0, 0, "lookOut");
83
+ const position = validateSkyPosition(given, "direction");
84
+ return eqjUnitVector(position.raDeg, position.decDeg);
85
+ }
86
+ const pointOf = (raDeg, decDeg, where) => {
87
+ const checked = validateSkyDirection(raDeg, decDeg, where);
88
+ return eqjUnitVector(checked.raDeg, checked.decDeg);
89
+ };
@@ -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"
@@ -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 ShownDuringInput, 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 ViewerChange, type EventZoneChange, type CameraPose, type CameraTarget } from "./viewerLink.js";
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
  }
@@ -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 boolean as its field says. Returns a frozen copy (the scene keeps no reference to the caller's object). */
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;
@@ -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 boolean as its field says. Returns a frozen copy (the scene keeps no reference to the caller's object). */
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
  }
@@ -4,7 +4,7 @@ import { type BodyCatalogue } from "../assets/catalogue.js";
4
4
  import { type ElementsBodyRecord } from "../core/elementsBody.js";
5
5
  import type { CompositionPath } from "../assets/compositions.js";
6
6
  import type { ExperienceDefinition, PathLayer } from "../app/experienceDefinition.js";
7
- import type { ExperienceObject } from "../shell/experience.js";
7
+ import type { ExperienceObject, ShownSpan } from "../shell/experience.js";
8
8
  import type { EccentricSampling } from "../core/sunCentredSources.js";
9
9
  import { type BodyRef } from "./bodies.js";
10
10
  import type { DataSource } from "./data.js";
@@ -30,6 +30,7 @@ export declare class BodyPlan {
30
30
  readonly laps: Map<string, OrbitLapInput>;
31
31
  readonly cards: Map<string, Pick<AddBodyOptions, "facts" | "labelPriority" | "listed" | "sources">>;
32
32
  readonly looks: Map<string, Pick<AddBodyOptions, "color" | "knownLimitations">>;
33
+ readonly shown: Map<string, ShownSpan>;
33
34
  catalogue: BodyCatalogue;
34
35
  /** `taken` says whether the scene already holds an id; `firstBody` runs when the scene's first body arrives (it is a built-in one). */
35
36
  constructor(taken: (id: string) => boolean, firstBody: (id: BodyId) => void);
@@ -1,6 +1,7 @@
1
1
  import { readableScale, solarSystemScale, trueScale } from "../core/scalePolicy.js";
2
2
  import { catalogue as builtInCatalogue, extendCatalogue, extendCatalogueWithMoons, rootBodyId } from "../assets/catalogue.js";
3
3
  import { buildElementsBody, ElementsBodyError, parseElementsBodyRecord } from "../core/elementsBody.js";
4
+ import { planShownDuring } from "./shownDuring.js";
4
5
  import { catalogueItem } from "../app/catalogueItem.js";
5
6
  import { circlesTheSun, sunOrbitIdOf, sunOrbitLayer } from "./sunOrbit.js";
6
7
  import { listedMoonBodyOf } from "../core/bodies/listedMoonBodies.js";
@@ -99,6 +100,7 @@ export class BodyPlan {
99
100
  laps = new Map();
100
101
  cards = new Map();
101
102
  looks = new Map();
103
+ shown = new Map();
102
104
  catalogue = builtInCatalogue;
103
105
  #taken;
104
106
  #firstBody;
@@ -191,7 +193,10 @@ export class BodyPlan {
191
193
  if (this.#taken(id))
192
194
  throw new SceneError("duplicate-id", `${call}("${id}"): already in the scene`);
193
195
  checkBodyLook(id, options);
196
+ const shown = planShownDuring(call, id, "bad-body", options.shownDuring);
194
197
  this.#remember(call, id, options);
198
+ if (shown !== undefined)
199
+ this.shown.set(id, shown);
195
200
  this.bodies.set(id, ref);
196
201
  if (this.bodies.size === 1 && builtInCatalogue.has(id))
197
202
  this.#firstBody(id);
@@ -294,7 +299,7 @@ export class BodyPlan {
294
299
  const card = this.cards.get(body.id);
295
300
  const sources = card?.sources;
296
301
  const base = this.catalogue.get(body.id).definition.accuracy.position;
297
- const own = { labelPriority: card?.labelPriority ?? 100 - ids.indexOf(body.id), ...(card?.listed === undefined ? {} : { listed: card.listed }), ...(card?.facts === undefined ? {} : { facts: card.facts }), ...(sources === undefined ? {} : { provenance: withSources(base, sources) }), ...this.labelReach(body.id, sunCentred, camera), ...(this.shape.get(body.id)?.showLabel === undefined ? {} : { showLabel: this.shape.get(body.id).showLabel }), ...(this.notes.has(body.id) ? { description: this.notes.get(body.id) } : {}), ...this.looks.get(body.id) };
302
+ const own = { labelPriority: card?.labelPriority ?? 100 - ids.indexOf(body.id), ...(card?.listed === undefined ? {} : { listed: card.listed }), ...(card?.facts === undefined ? {} : { facts: card.facts }), ...(sources === undefined ? {} : { provenance: withSources(base, sources) }), ...this.labelReach(body.id, sunCentred, camera), ...(this.shape.get(body.id)?.showLabel === undefined ? {} : { showLabel: this.shape.get(body.id).showLabel }), ...(this.notes.has(body.id) ? { description: this.notes.get(body.id) } : {}), ...(this.shown.has(body.id) ? { shownDuring: this.shown.get(body.id) } : {}), ...this.looks.get(body.id) };
298
303
  return { ...catalogueItem(body.id, own, this.catalogue), label: body.label };
299
304
  }
300
305
  }
@@ -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 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:
19
- * `{ focus, azimuthDeg, elevationDeg, distance }`, distance in Earth radii. `focus` must be a body or trajectory already added (else `unknown-body`); a bad angle or distance throws `bad-camera`.
20
- * The last of `follow`, `focus` and `setStartView` wins. Default: none.
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, and Follow for every one unless `setFollowChoices` named fewer. */
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"];