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.
Files changed (121) hide show
  1. package/CHANGELOG.md +67 -0
  2. package/README.md +28 -15
  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 +27 -5
  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/planCamera.d.ts +35 -7
  17. package/src/api/planCamera.js +94 -11
  18. package/src/api/planSkyFigures.d.ts +22 -0
  19. package/src/api/planSkyFigures.js +145 -0
  20. package/src/api/planStory.d.ts +2 -2
  21. package/src/api/planStory.js +14 -9
  22. package/src/api/planViews.js +1 -1
  23. package/src/api/scene.d.ts +17 -4
  24. package/src/api/scene.js +23 -5
  25. package/src/api/sceneReads.d.ts +21 -2
  26. package/src/api/skyFigureInput.d.ts +45 -0
  27. package/src/api/skyFigureInput.js +1 -0
  28. package/src/api/skyTraceInput.d.ts +33 -0
  29. package/src/api/skyTraceInput.js +45 -0
  30. package/src/api/story.d.ts +12 -3
  31. package/src/api/story.js +44 -1
  32. package/src/api/viewerCamera.d.ts +4 -3
  33. package/src/api/viewerCamera.js +10 -32
  34. package/src/api/viewerHandle.d.ts +27 -4
  35. package/src/api/viewerHandle.js +6 -0
  36. package/src/api/viewerLink.d.ts +49 -4
  37. package/src/api/viewerLink.js +25 -0
  38. package/src/api/viewerPanels.d.ts +26 -0
  39. package/src/api/viewerPanels.js +42 -0
  40. package/src/api/viewerSelection.d.ts +1 -1
  41. package/src/api/viewerSelection.js +3 -3
  42. package/src/app/App.js +100 -18
  43. package/src/app/App.node.js +100 -18
  44. package/src/app/AstraeusScene.d.ts +20 -5
  45. package/src/app/AstraeusScene.js +3 -3
  46. package/src/app/CameraController.d.ts +17 -0
  47. package/src/app/CameraController.js +34 -9
  48. package/src/app/DeveloperSettings.d.ts +11 -3
  49. package/src/app/DeveloperSettings.js +13 -3
  50. package/src/app/SceneLabels.d.ts +20 -2
  51. package/src/app/SceneLabels.js +46 -6
  52. package/src/app/SkyFiguresView.d.ts +56 -0
  53. package/src/app/SkyFiguresView.js +242 -0
  54. package/src/app/StoryMarkers.d.ts +2 -2
  55. package/src/app/StoryMarkers.js +2 -2
  56. package/src/app/displaySwitches.d.ts +13 -3
  57. package/src/app/displaySwitches.js +17 -3
  58. package/src/app/experienceDefinition.d.ts +9 -3
  59. package/src/app/experienceDefinition.js +4 -2
  60. package/src/app/labelStyle.d.ts +17 -0
  61. package/src/app/labelStyle.js +13 -0
  62. package/src/app/liveLook.js +8 -0
  63. package/src/app/look.d.ts +9 -5
  64. package/src/app/look.js +11 -0
  65. package/src/app/lookOut.d.ts +32 -0
  66. package/src/app/lookOut.js +50 -0
  67. package/src/app/sceneCamera.d.ts +5 -3
  68. package/src/app/sceneCamera.js +66 -3
  69. package/src/app/sceneContentsHooks.d.ts +2 -1
  70. package/src/app/sceneContentsHooks.js +3 -2
  71. package/src/app/sceneFrame.d.ts +10 -1
  72. package/src/app/sceneFrame.js +45 -10
  73. package/src/app/sceneFraming.d.ts +7 -0
  74. package/src/app/sceneFraming.js +12 -0
  75. package/src/app/sceneHooks.d.ts +2 -0
  76. package/src/app/sceneHooks.js +4 -1
  77. package/src/app/scenePicking.d.ts +20 -0
  78. package/src/app/scenePicking.js +49 -0
  79. package/src/app/scenePointer.d.ts +3 -1
  80. package/src/app/scenePointer.js +3 -2
  81. package/src/app/skyFigures.d.ts +73 -0
  82. package/src/app/skyFigures.js +50 -0
  83. package/src/app/style.css +2 -1
  84. package/src/app/viewHiding.d.ts +2 -0
  85. package/src/app/viewHiding.js +7 -1
  86. package/src/app/viewLink.d.ts +8 -8
  87. package/src/app/viewLink.js +24 -4
  88. package/src/app/viewerPort.d.ts +30 -3
  89. package/src/assets/sky.d.ts +13 -4
  90. package/src/assets/sky.js +33 -8
  91. package/src/assets/stars/hyg-v42-naked-eye.json +1 -1
  92. package/src/core/bodies/moonSystem.js +1 -15
  93. package/src/core/lookValues.d.ts +9 -0
  94. package/src/core/lookValues.js +24 -0
  95. package/src/core/readBytes.d.ts +1 -0
  96. package/src/core/readBytes.js +15 -0
  97. package/src/core/skyTrace.d.ts +49 -0
  98. package/src/core/skyTrace.js +39 -0
  99. package/src/core/startView.d.ts +39 -0
  100. package/src/core/startView.js +56 -0
  101. package/src/core/storyPanels.d.ts +51 -3
  102. package/src/core/storyPanels.js +52 -12
  103. package/src/shell/AstraeusShell.d.ts +15 -6
  104. package/src/shell/AstraeusShell.js +76 -20
  105. package/src/shell/AstraeusShell.node.js +76 -20
  106. package/src/shell/ObjectControls.js +11 -8
  107. package/src/shell/StoryPanelView.d.ts +12 -3
  108. package/src/shell/StoryPanelView.js +2 -2
  109. package/src/shell/experience.d.ts +24 -0
  110. package/src/shell/experience.js +4 -1
  111. package/src/shell/infoModel.js +9 -1
  112. package/src/shell/objectModel.d.ts +6 -2
  113. package/src/shell/objectModel.js +10 -1
  114. package/src/shell/phone.css +1 -1
  115. package/src/shell/storyPanels.d.ts +1 -1
  116. package/src/shell/storyPanels.js +1 -1
  117. package/src/shell/style.css +9 -1
  118. package/src/shell/topBarIcons.d.ts +1 -0
  119. package/src/shell/topBarIcons.js +1 -0
  120. package/src/shell/useStoryPanels.d.ts +9 -6
  121. package/src/shell/useStoryPanels.js +10 -6
@@ -0,0 +1,50 @@
1
+ // Sky figures as the app draws them: figures, outlines and the two reference circles, all as unit directions in the EQJ frame at infinity (ARCH-02: presentation only, no State).
2
+ import { createOrbTwoBodyAdapter } from "../core/twoBodyAdapter.js";
3
+ import { DEFAULT_SKY_FADE_IN_SECONDS } from "../core/skyTrace.js";
4
+ /** The starting state of the four switches: the figures show, the rest wait for the app to ask. */
5
+ export const DEFAULT_SKY_LINES = Object.freeze({ figures: true, boundaries: false, ecliptic: false, celestialEquator: false });
6
+ export const DEFAULT_SKY_COLOURS = Object.freeze({ figure: "#8fb4ff", label: "#cfe0ff", boundary: "#5f7a9c", ecliptic: "#e0b25a", equator: "#7fd1b9", traced: "#ffd166", faded: "#44546d", selected: "#ffffff" });
7
+ /** True when the person asked the system for less motion (`prefers-reduced-motion: reduce`); false where the browser cannot say. */
8
+ export function prefersReducedMotion() {
9
+ return typeof globalThis.matchMedia === "function" && globalThis.matchMedia("(prefers-reduced-motion: reduce)").matches;
10
+ }
11
+ /** The sky colours in force: the look's `skyLines`, every one not named at its default. */
12
+ export function skyColoursOf(look) {
13
+ return { ...DEFAULT_SKY_COLOURS, ...look.skyLines };
14
+ }
15
+ /** How long sky lines and their names fade in when they appear: the look's `skyFadeInSeconds`, else the default. */
16
+ export function skyFadeInSecondsOf(look) {
17
+ return look.skyFadeInSeconds ?? DEFAULT_SKY_FADE_IN_SECONDS;
18
+ }
19
+ /** How many segments a built-in great circle is cut into (about 2 degrees each). */
20
+ const CIRCLE_SEGMENTS = 180;
21
+ /** The mean of the unit directions, normalised; the first when they cancel out. */
22
+ export function meanDirection(directions) {
23
+ const sum = directions.reduce((acc, d) => [acc[0] + d[0], acc[1] + d[1], acc[2] + d[2]], [0, 0, 0]);
24
+ const length = Math.hypot(sum[0], sum[1], sum[2]);
25
+ return length > 1e-9 ? [sum[0] / length, sum[1] / length, sum[2] / length] : directions[0];
26
+ }
27
+ function circleSegments(point) {
28
+ const around = Array.from({ length: CIRCLE_SEGMENTS + 1 }, (_, i) => point((2 * Math.PI * i) / CIRCLE_SEGMENTS));
29
+ return around.slice(1).map((end, i) => [around[i], end]);
30
+ }
31
+ /** The celestial equator: declination 0, as segments. */
32
+ export function celestialEquatorSegments() {
33
+ return circleSegments((angle) => [Math.cos(angle), Math.sin(angle), 0]);
34
+ }
35
+ /** The ecliptic of J2000 as segments, turned to EQJ by the engine's own ecliptic-to-equator matrix (STYLE-07: that is the one obliquity). */
36
+ export function eclipticSegments() {
37
+ const m = createOrbTwoBodyAdapter().eclipticJ2000ToEqjMatrix();
38
+ return circleSegments((angle) => {
39
+ const x = Math.cos(angle);
40
+ const y = Math.sin(angle);
41
+ return [m[0] * x + m[1] * y, m[3] * x + m[4] * y, m[6] * x + m[7] * y];
42
+ });
43
+ }
44
+ /** A camera request with a look-out direction that names a sky figure turned into that figure's label point (the one place a figure id becomes a direction); any other request is returned as it is. */
45
+ export function aimAtFigure(request, figures) {
46
+ if (request.kind !== "lookOut" || typeof request.direction !== "string")
47
+ return request;
48
+ const figure = figures.find(({ id }) => id === request.direction);
49
+ return figure === undefined ? request : { ...request, direction: figure.labelAt };
50
+ }
package/src/app/style.css CHANGED
@@ -140,7 +140,8 @@
140
140
  top: 0;
141
141
  left: 0;
142
142
  margin: -14px 0 0 6px;
143
- font-size: 12px;
143
+ font-family: var(--label-font, inherit);
144
+ font-size: var(--label-size, 12px);
144
145
  line-height: 1.2;
145
146
  white-space: nowrap;
146
147
  text-shadow: 0 0 2px #000, 0 0 3px #000;
@@ -11,3 +11,5 @@ export declare function viewById(settings: ViewSettings | undefined, id: string)
11
11
  export declare function hiddenByView(settings: ViewSettings | undefined, view: ResolvedView | undefined, experience?: ExperienceConfig): ViewHidden;
12
12
  /** The experience as the view shows it: its objects, timeline events and story panels. The same object when there are no views, so a scene without views is untouched. */
13
13
  export declare function experienceInView(experience: ExperienceConfig, settings: ViewSettings | undefined, view: ResolvedView | undefined): ExperienceConfig;
14
+ /** `hidden` with the body the camera stands inside added while it looks out. The same object when nothing is added, so a normal frame allocates nothing. */
15
+ export declare function hiddenWithLookOut(hidden: ViewHidden | undefined, body: string | null): ViewHidden | undefined;
@@ -32,6 +32,12 @@ export function experienceInView(experience, settings, view) {
32
32
  ...experience,
33
33
  objects: experience.objects.filter((object) => !objects.has(object.id)),
34
34
  events: experience.events.filter((event) => !hiddenEvents.has(event.id)),
35
- ...(storySet === undefined ? {} : { storyPanels: { ...storySet, panels: storySet.panels.filter((panel) => !panels.has(panel.id)) } }),
35
+ ...(storySet === undefined ? {} : { storyPanels: { ...storySet, panels: storySet.panels.filter((panel) => !panels.has(panel.id)), ...(storySet.steps === undefined ? {} : { steps: storySet.steps.filter((step) => !panels.has(step.id)) }) } }),
36
36
  };
37
37
  }
38
+ /** `hidden` with the body the camera stands inside added while it looks out. The same object when nothing is added, so a normal frame allocates nothing. */
39
+ export function hiddenWithLookOut(hidden, body) {
40
+ if (body === null)
41
+ return hidden;
42
+ return { objects: new Set([...(hidden?.objects ?? []), body]), panels: hidden?.panels ?? new Set() };
43
+ }
@@ -1,20 +1,20 @@
1
- import { validateStartView, type StartView } from "../core/startView.js";
2
- export { validateStartView, type StartView };
1
+ import { validateStartView, type CameraView, type SkyView, type StartView } from "../core/startView.js";
2
+ export { validateStartView, type CameraView, type SkyView, type StartView };
3
3
  /** The view as the camera reports it (radians), as a StartView rounded the way a link rounds it. */
4
4
  export declare function viewFromAngles(focus: string, azimuthRad: number, elevationRad: number, distance: number): StartView;
5
- /** `focus,az,el,distance`. */
6
- export declare function formatView(view: StartView): string;
7
- /** Parses `focus,az,el,distance`; throws a RangeError naming the field. */
8
- export declare function parseView(text: string): StartView;
5
+ /** `focus,az,el,distance` for an orbit view; `body,raDeg,decDeg,fovDeg,sky` for a sky view (the fifth part tells them apart). */
6
+ export declare function formatView(view: CameraView): string;
7
+ /** Parses either form of `formatView`; throws a RangeError naming the field. */
8
+ export declare function parseView(text: string): CameraView;
9
9
  /** The view in `?view=`, or undefined when absent or malformed (a bad link opens the experience's own view rather than failing). */
10
- export declare function viewFromSearch(search: string): StartView | undefined;
10
+ export declare function viewFromSearch(search: string): CameraView | undefined;
11
11
  /** `?t=<ISO UTC>` as milliseconds, or undefined. */
12
12
  export declare function timeFromSearch(search: string): number | undefined;
13
13
  /** `?scale=<id>`, or undefined. The caller checks the id against the scale choices it offers. */
14
14
  export declare function scaleFromSearch(search: string): string | undefined;
15
15
  /** What a copied link carries. `show` is the id of the scene view showing, left out in a scene without views. */
16
16
  export interface ViewLinkState {
17
- view: StartView;
17
+ view: CameraView;
18
18
  scaleId: string;
19
19
  up: string;
20
20
  timeUtcMs: number;
@@ -1,4 +1,4 @@
1
- import { MAX_ELEVATION_DEG, validateStartView, wrapAzimuth } from "../core/startView.js";
1
+ import { isSkyView, MAX_ELEVATION_DEG, validateSkyView, validateStartView, wrapAzimuth } from "../core/startView.js";
2
2
  export { validateStartView };
3
3
  const round = (value, places) => Number(value.toFixed(places));
4
4
  /** The view as the camera reports it (radians), as a StartView rounded the way a link rounds it. */
@@ -11,15 +11,19 @@ export function viewFromAngles(focus, azimuthRad, elevationRad, distance) {
11
11
  distance: Number(distance.toPrecision(5)),
12
12
  };
13
13
  }
14
- /** `focus,az,el,distance`. */
14
+ /** `focus,az,el,distance` for an orbit view; `body,raDeg,decDeg,fovDeg,sky` for a sky view (the fifth part tells them apart). */
15
15
  export function formatView(view) {
16
+ if (isSkyView(view))
17
+ return [encodeURIComponent(view.lookOut), view.raDeg, view.decDeg, view.fovDeg, "sky"].join(",");
16
18
  return [encodeURIComponent(view.focus), view.azimuthDeg, view.elevationDeg, view.distance].join(",");
17
19
  }
18
- /** Parses `focus,az,el,distance`; throws a RangeError naming the field. */
20
+ /** Parses either form of `formatView`; throws a RangeError naming the field. */
19
21
  export function parseView(text) {
20
22
  const parts = text.split(",");
23
+ if (parts.length === 5 && parts[4] === "sky")
24
+ return parseSkyView(parts);
21
25
  if (parts.length !== 4)
22
- throw new RangeError(`view must be focus,azimuthDeg,elevationDeg,distance (4 parts), got ${parts.length}`);
26
+ throw new RangeError(`view must be focus,azimuthDeg,elevationDeg,distance (4 parts) or body,raDeg,decDeg,fovDeg,sky (5 parts), got ${parts.length}`);
23
27
  const [focus, az, el, distance] = parts;
24
28
  const numeric = (name, value) => {
25
29
  if (value.trim() === "")
@@ -35,6 +39,22 @@ export function parseView(text) {
35
39
  }
36
40
  return validateStartView({ focus: decoded, azimuthDeg: numeric("azimuth", az), elevationDeg: numeric("elevation", el), distance: numeric("distance", distance) }, "view");
37
41
  }
42
+ function parseSkyView(parts) {
43
+ const [body, ra, dec, fov] = parts;
44
+ const numeric = (name, value) => {
45
+ if (value.trim() === "")
46
+ throw new RangeError(`view ${name} is empty`);
47
+ return Number(value);
48
+ };
49
+ let decoded;
50
+ try {
51
+ decoded = decodeURIComponent(body);
52
+ }
53
+ catch {
54
+ throw new RangeError("view body is not valid text");
55
+ }
56
+ return validateSkyView({ lookOut: decoded, raDeg: numeric("right ascension", ra), decDeg: numeric("declination", dec), fovDeg: numeric("field of view", fov) }, "view");
57
+ }
38
58
  /** The view in `?view=`, or undefined when absent or malformed (a bad link opens the experience's own view rather than failing). */
39
59
  export function viewFromSearch(search) {
40
60
  const raw = new URLSearchParams(search).get("view");
@@ -1,8 +1,10 @@
1
1
  import type { TimelineEvent } from "../core/events.js";
2
2
  import type { TimeBounds } from "../core/trajectory.js";
3
3
  import type { CameraRequest } from "./CameraController.js";
4
- import type { StartView } from "./viewLink.js";
4
+ import type { CameraView } from "./viewLink.js";
5
5
  import type { LookInput, LookRead } from "../api/look.js";
6
+ import type { SkyTraceAfter } from "../core/skyTrace.js";
7
+ import type { Provenance } from "../core/provenance.js";
6
8
  /** The one clock's reading as a host sees it. */
7
9
  export interface ViewerState {
8
10
  readonly timeUtcMs: number;
@@ -17,6 +19,8 @@ export interface ViewerState {
17
19
  readonly zones?: readonly string[];
18
20
  /** The id of the object whose information the viewer has selected; absent when nothing is selected. */
19
21
  readonly selected?: string;
22
+ /** The id of the story panel open; absent when none is. */
23
+ readonly panel?: string;
20
24
  /** The id of the scale showing. */
21
25
  readonly scale: string;
22
26
  /** The looks in force, every one filled in. */
@@ -55,6 +59,23 @@ export interface ViewerControl {
55
59
  setLook(look: LookInput): void;
56
60
  /** Turns the display switch `id` (one of the keys of `read().switches`) on or off, as a visitor's switch does. */
57
61
  setSwitch(id: string, on: boolean): void;
62
+ /** The sky figures the viewer draws, in the order added (id, label, kind); empty or absent when the scene added none. */
63
+ readonly skyFigures?: readonly {
64
+ readonly id: string;
65
+ readonly label: string;
66
+ readonly kind: "figure" | "boundary";
67
+ readonly listed: boolean;
68
+ readonly provenance: Provenance;
69
+ readonly description?: string;
70
+ readonly facts?: readonly {
71
+ readonly label: string;
72
+ readonly value: string;
73
+ }[];
74
+ }[];
75
+ /** Starts tracing a sky figure (an id from `skyFigures`, already checked), as `SkyTraceOptions` says; a trace already running on it restarts. Takes effect at the next frame, in call order with the other host calls. */
76
+ traceSkyFigure(id: string, seconds: number, after: SkyTraceAfter): void;
77
+ /** Removes a sky figure's trace (an id from `skyFigures`, already checked) over `seconds` (0: at once); none running does nothing. Takes effect at the next frame, in call order with the other host calls. */
78
+ clearSkyTrace(id: string, seconds: number): void;
58
79
  /** The host's picker (`Scene.setPicker`): its id, the option values and the one pressed at the start; absent without a picker. */
59
80
  readonly picker?: {
60
81
  readonly id: string;
@@ -63,10 +84,14 @@ export interface ViewerControl {
63
84
  };
64
85
  /** The ids of the objects the showing view shows, which a host may point the camera at. */
65
86
  cameraTargets(): readonly string[];
66
- /** The camera as the viewer's view link writes it; undefined until the scene has drawn its first frame. */
67
- readCamera(): StartView | undefined;
87
+ /** The camera as the viewer's view link writes it (an orbit view, or a sky view while looking out); undefined until the scene has drawn its first frame. */
88
+ readCamera(): CameraView | undefined;
68
89
  /** Selects the object with this id (one of `cameraTargets()`), or clears the selection (`undefined`); `read()` shows it at once. */
69
90
  setSelected(id: string | undefined): void;
91
+ /** The ids of the story panels (moment panels and steps) the showing view shows, which a host may open. */
92
+ panels(): readonly string[];
93
+ /** Opens the story panel with this id (one of `panels()`), or closes the open one (`undefined`); `read()` shows it at once. */
94
+ setPanel(id: string | undefined): void;
70
95
  /** Asks the scene camera for a follow, focus or pose through its own request path (the same one a view's camera rule uses). */
71
96
  setCamera(request: CameraRequest): void;
72
97
  }
@@ -80,6 +105,8 @@ export interface ViewerPort {
80
105
  publish(state: ViewerState, cause: ViewerChangeCause): void;
81
106
  /** The viewer's selected object changed. `byMove`: the selection followed a move of the clock or the view (a drop, or a view rule's framing target; the cause is whatever last moved them); otherwise the visitor chose it. */
82
107
  publishSelection(state: ViewerState, byMove: boolean): void;
108
+ /** The viewer's open story panel changed (a visitor, a host call, playback crossing a panel, or `"move"`: a view switch dropped it, and the cause is whatever last moved the view). */
109
+ publishPanel(state: ViewerState, cause: ViewerChangeCause | "move"): void;
83
110
  /** The pressed option of the host's picker now (undefined until attached and without a picker). */
84
111
  pickNow(): string | undefined;
85
112
  /** Calls `watcher` when the pressed option moves (the host's `setPick`, or an attach or detach); returns the function that stops it. */
@@ -46,18 +46,27 @@ export interface PictureSet {
46
46
  readonly licence: string;
47
47
  readonly source: string;
48
48
  }
49
- /** One catalogue row: J2000 right ascension and declination (degrees), V magnitude, B-V colour index (null when unknown). */
50
- export type StarRow = readonly [raDeg: number, decDeg: number, vMag: number, bMinusV: number | null];
49
+ /** One catalogue row: J2000 right ascension and declination (degrees), V magnitude, B-V colour index (null when unknown), Hipparcos number (0 or absent when HYG gives none). */
50
+ export type StarRow = readonly [raDeg: number, decDeg: number, vMag: number, bMinusV: number | null, hip?: number];
51
51
  export interface StarCatalogue {
52
52
  readonly stars: readonly StarRow[];
53
53
  /** The file's own provenance header, if it has one. */
54
54
  readonly provenance?: Readonly<Record<string, unknown>>;
55
55
  }
56
- /** Validates a parsed star file (`{ provenance?, stars: [[ra, dec, v, bv|null], ...] }`); throws naming the first bad row. */
56
+ /** Validates a parsed star file (`{ provenance?, stars: [[ra, dec, v, bv|null, hip?], ...] }`); throws naming the first bad row. */
57
57
  export declare function parseStarFile(json: unknown): StarCatalogue;
58
58
  /** Rights for the committed HYG star file (PROV-02). The licence covers the star file only; the Astraeus code is MIT. */
59
59
  export declare const HYG_STAR_LICENCE: AssetLicence;
60
- /** The star catalogue: the committed HYG file served with the app. Absent (null) when it cannot be read or is not a valid star file. */
60
+ /** A listed star found by its Hipparcos number: its EQJ unit direction (x, y, z) and V magnitude. */
61
+ export interface StarById {
62
+ readonly direction: Vec3;
63
+ readonly vMag: number;
64
+ }
65
+ /** One table from Hipparcos number to direction and magnitude, built once per star load (rows with no number, 0 or absent, are not listed). On a repeated number the first row wins. */
66
+ export declare function starIdTable(stars: readonly StarRow[]): ReadonlyMap<number, StarById>;
67
+ /** The id table of a loaded catalogue, built on first use and kept for that catalogue. */
68
+ export declare function starIdsOf(catalogue: StarCatalogue): ReadonlyMap<number, StarById>;
69
+ /** The star catalogue: the committed HYG file served with the app (read from disk in Node, by the engine's one bundled-file reader). Absent (null) when it cannot be read or is not a valid star file. */
61
70
  export declare function loadStarCatalogue(): Promise<StarCatalogue | null>;
62
71
  /** Temperature in kelvin from B-V (Ballesteros 2012). */
63
72
  export declare function temperatureFromBV(bMinusV: number): number;
package/src/assets/sky.js CHANGED
@@ -1,3 +1,7 @@
1
+ // The sky behind every experience: directions at infinity in the EQJ (J2000 equatorial) frame. Frame layer only; it never
2
+ // touches State (ARCH-02). The stars come from the committed HYG file (tools/data/fetch-hyg-stars.mjs, CC BY-SA 4.0); the Milky Way image is committed
3
+ // with its licence (PROV-02).
4
+ import { fetchBytesOf } from "../core/readBytes.js";
1
5
  const hygStarsUrl = new URL("./stars/hyg-v42-naked-eye.json", import.meta.url).href;
2
6
  const RAD = Math.PI / 180;
3
7
  // ---------------------------------------------------------------- galactic frame
@@ -53,18 +57,19 @@ export function milkyWayUv(eqj) {
53
57
  // ---------------------------------------------------------------- picture (tiled)
54
58
  /** The most a tile may measure on a side: phone GPUs commonly cap textures at 4096. */
55
59
  export const MAX_TILE_PX = 4096;
56
- /** Validates a parsed star file (`{ provenance?, stars: [[ra, dec, v, bv|null], ...] }`); throws naming the first bad row. */
60
+ /** Validates a parsed star file (`{ provenance?, stars: [[ra, dec, v, bv|null, hip?], ...] }`); throws naming the first bad row. */
57
61
  export function parseStarFile(json) {
58
62
  const file = json;
59
63
  if (file === null || typeof file !== "object" || !Array.isArray(file.stars))
60
64
  throw new TypeError("star file needs a stars array");
61
65
  file.stars.forEach((row, index) => {
62
- const ok = Array.isArray(row) && row.length === 4
66
+ const ok = Array.isArray(row) && (row.length === 4 || row.length === 5)
63
67
  && [0, 1, 2].every((i) => Number.isFinite(row[i]))
64
68
  && (row[3] === null || Number.isFinite(row[3]))
69
+ && (row.length === 4 || (Number.isInteger(row[4]) && row[4] >= 0))
65
70
  && row[1] >= -90 && row[1] <= 90;
66
71
  if (!ok)
67
- throw new RangeError(`star ${index} must be [raDeg, decDeg, vMag, bMinusV|null]`);
72
+ throw new RangeError(`star ${index} must be [raDeg, decDeg, vMag, bMinusV|null, hip?]`);
68
73
  });
69
74
  const provenance = file.provenance !== null && typeof file.provenance === "object" ? file.provenance : undefined;
70
75
  return { stars: file.stars, ...(provenance === undefined ? {} : { provenance }) };
@@ -74,20 +79,40 @@ export const HYG_STAR_LICENCE = Object.freeze({
74
79
  source: "HYG database v4.2 (Hipparcos, Yale Bright Star, Gliese catalogues), astronexus",
75
80
  url: "https://www.astronexus.com/projects/hyg",
76
81
  licence: "CC BY-SA 4.0",
77
- attribution: "HYG database v4.2, astronexus (astronexus.com), CC BY-SA 4.0. Stars of V 6.5 or brighter kept, right ascension converted from hours to degrees; no other change.",
78
- accessed: "2026-10-16",
82
+ attribution: "HYG database v4.2, astronexus (astronexus.com), CC BY-SA 4.0. Stars of V 6.5 or brighter kept, right ascension converted from hours to degrees, Hipparcos number added; no other change.",
83
+ accessed: "2026-11-10",
79
84
  });
85
+ /** One table from Hipparcos number to direction and magnitude, built once per star load (rows with no number, 0 or absent, are not listed). On a repeated number the first row wins. */
86
+ export function starIdTable(stars) {
87
+ const table = new Map();
88
+ for (const row of stars) {
89
+ const hip = row[4];
90
+ if (hip === undefined || hip <= 0 || table.has(hip))
91
+ continue;
92
+ table.set(hip, { direction: eqjUnit(row[0], row[1]), vMag: row[2] });
93
+ }
94
+ return table;
95
+ }
96
+ const starIdCache = new WeakMap();
97
+ /** The id table of a loaded catalogue, built on first use and kept for that catalogue. */
98
+ export function starIdsOf(catalogue) {
99
+ let table = starIdCache.get(catalogue);
100
+ if (table === undefined) {
101
+ table = starIdTable(catalogue.stars);
102
+ starIdCache.set(catalogue, table);
103
+ }
104
+ return table;
105
+ }
80
106
  let starRequest;
81
107
  async function fetchStarFile(url) {
82
108
  try {
83
- const response = await fetch(url);
84
- return response.ok ? parseStarFile(JSON.parse(await response.text())) : null;
109
+ return parseStarFile(JSON.parse(new TextDecoder().decode(await fetchBytesOf(url))));
85
110
  }
86
111
  catch {
87
112
  return null;
88
113
  }
89
114
  }
90
- /** The star catalogue: the committed HYG file served with the app. Absent (null) when it cannot be read or is not a valid star file. */
115
+ /** The star catalogue: the committed HYG file served with the app (read from disk in Node, by the engine's one bundled-file reader). Absent (null) when it cannot be read or is not a valid star file. */
91
116
  export function loadStarCatalogue() {
92
117
  starRequest ??= fetchStarFile(hygStarsUrl);
93
118
  return starRequest;