astraeus 0.9.2 → 0.9.4
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 +13 -0
- package/README.md +14 -3
- package/package.json +1 -1
- package/src/api/cameraRequest.js +2 -1
- package/src/api/group.d.ts +14 -9
- package/src/api/group.js +28 -6
- package/src/api/groupLookInput.d.ts +19 -0
- package/src/api/groupLookInput.js +26 -0
- package/src/api/index.d.ts +1 -0
- package/src/api/lookInput.js +2 -1
- package/src/api/plainObject.d.ts +5 -0
- package/src/api/plainObject.js +10 -0
- package/src/api/sceneReads.d.ts +1 -1
- package/src/api/viewerHandle.d.ts +5 -0
- package/src/api/viewerHandle.js +2 -0
- package/src/api/viewerLink.d.ts +4 -0
- package/src/api/viewerLink.js +3 -0
- package/src/api/viewerLooks.d.ts +5 -0
- package/src/api/viewerLooks.js +12 -0
- package/src/app/App.js +12 -2
- package/src/app/App.node.js +12 -2
- package/src/app/AstraeusScene.d.ts +3 -0
- package/src/app/PointsView.d.ts +14 -0
- package/src/app/PointsView.js +25 -4
- package/src/app/SceneLabels.d.ts +2 -0
- package/src/app/SceneLabels.js +9 -0
- package/src/app/sceneFrame.d.ts +2 -0
- package/src/app/sceneFrame.js +16 -0
- package/src/app/viewerPort.d.ts +12 -0
- package/src/core/listedOrbitGroup.d.ts +24 -10
- package/src/core/listedOrbitGroup.js +65 -13
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,19 @@
|
|
|
2
2
|
|
|
3
3
|
Versions follow [semantic versioning](https://semver.org). While the version starts with `0.`, the public API (the names exported from `astraeus`) may still change between minor versions; each change is listed here.
|
|
4
4
|
|
|
5
|
+
## 0.9.4 (2026-11-21)
|
|
6
|
+
|
|
7
|
+
First download of the packed example (`npm run measure:example`): 1,777,827 bytes raw, 511,436 bytes gzip (code and styles loaded on first open), against 1,775,354 raw and 510,719 gzip at 0.9.3 (+2,473 raw, +717 gzip). Additions and one input fix (G-022); every `astraeus-data*` package still peers on `>=0.9.0 <0.10.0`.
|
|
8
|
+
|
|
9
|
+
- Added: `handle.setGroupLook(id, { color?, dotSizePx? })` and `handle.groupLook(id)` on the `mount` handle and the `AstraeusScene` ref (types `GroupLookInput`, `GroupLookRead`). A host changes a point group's dot colour and size on a mounted viewer: the dots take it on the next drawn frame, also while paused, on either way the group is drawn, with no new scene, geometry, refill or re-plan, so the dots stay where they are; the group's name label takes the colour (the card shows no colour and is unchanged). Fields left out keep their value; `groupLook` reads the look in force, `undefined` before `ready`, after `unmount` and for a non-group id. `scene.groups` keeps describing the scene as built. A non-group id, a bad colour, a size that is not a finite number above 0 or an unknown field throws `bad-group`; before `ready` or after `unmount`, `not-mounted` (no new error code). Presentation only: State, positions, provenance, views and selection are unchanged. 25 calls on 25 groups of 126,000 dots in all took under 0.3 ms in headless Chromium with SwiftShader, against about 1.4 s to rebuild the scene.
|
|
10
|
+
- Fixed: `setGroupLook`, `setLook` and `setCamera` now refuse an argument that is not a plain object (a `Map`, a `Date`, a class instance) with their own error code (`bad-group`, `bad-look`, `bad-camera`) instead of reading it as an empty object.
|
|
11
|
+
|
|
12
|
+
## 0.9.3 (2026-11-20)
|
|
13
|
+
|
|
14
|
+
First download of the packed example (`npm run measure:example`): 1,775,354 bytes raw, 510,719 bytes gzip (code and styles loaded on first open), against 1,773,029 raw and 510,085 gzip at 0.9.2 (+2,325 raw, +634 gzip). Additions only (G-021); every `astraeus-data*` package still peers on `>=0.9.0 <0.10.0`.
|
|
15
|
+
|
|
16
|
+
- Added: `GroupOrbitInput.meanAnomalyDeg`, an orbit's catalogue mean anomaly in degrees at its own `time` (its epoch); finite, wrapping to 0 to 360. When every orbit of an `addGroup` gives it, each dot sits at its record's real position, advanced from its epoch by unperturbed two-body motion about the centre with the same GM the group moves with, instead of the illustrative even spread. An orbit without `time` has its mean anomaly read at `referenceTime`; when every orbit gives `time`, `referenceTime` makes no difference. The card and `scene.groups[].provenance` keep the caller's `sourceType`, sources and accuracy, add the note "Each dot's position along its orbit comes from its record's mean anomaly at the record's epoch, advanced by unperturbed two-body motion about the centre.", and replace the illustrative placement limit with one on two-body drift from each epoch. A list where some orbits give it and some do not, a non-finite value, or `seed` or `clump` with it throws `bad-group` (no new error code). Groups without it are unchanged, card text included. 110,000 orbits in one group build in about 0.4 s and fill once in about 0.1 s in Node.
|
|
17
|
+
|
|
5
18
|
## 0.9.2 (2026-11-17)
|
|
6
19
|
|
|
7
20
|
First download of the packed example (`npm run measure:example`): 1,773,029 bytes raw, 510,085 bytes gzip (code and styles loaded on first open), against 1,764,446 raw and 507,330 gzip at 0.9.1 (+8,583 raw, +2,755 gzip). Additions and fixes only (G-020); every `astraeus-data*` package still peers on `>=0.9.0 <0.10.0`.
|
package/README.md
CHANGED
|
@@ -87,7 +87,7 @@ The full reference, generated from the types and doc comments, is at <https://as
|
|
|
87
87
|
| `scene.addBodyFromElements(record, options?)` | Your own body that circles the Sun, from published orbit elements: `record` is `{ id, label, elements: { semiMajorAxisAu, eccentricity, inclinationDeg, ascendingNodeDeg, argumentOfPerihelionDeg, meanAnomalyDeg or perihelionJdTdb }, epoch: { jd, timeScale, ttMinusUtcSeconds? }, plane: "ecliptic-j2000", source: { name, url, solution, accessed }, radius?, accuracy: { classification, statement, valid: { start, end }, limitations }, marker?: { color, sizePx } }`; `accuracy.valid` is `{ start, end }`, each ISO text such as `2030-01-01T00:00:00Z` (a record is usually JSON), a `Date` or milliseconds. Drawn as a marker on unperturbed two-body motion about the Sun; colours: with a `color` option (`addBody`'s) the orbit line and the label take it and the dot takes `marker.color`, and without one all three take `marker.color` (default a pale blue); the source, accuracy and limits show on its info card, with a live "Distance from Sun" row. `options` are `addBody`'s, `shownDuring` included (`{ orbit: true }` draws its whole orbit from periapsis, smooth even for a sharp comet orbit). A bad record throws `bad-element` naming the field; a repeated id throws `duplicate-id`. |
|
|
88
88
|
| `scene.addBodySet({ id, families, members, provenance, center?, bodies?, centerGmKm3S2?, balancePoint?, orbitHistoryMs? })` | Many small bodies about one centre as one batch of dots, each selectable with an info card, with orbit lines coloured by family. `families` is one to sixteen of `{ id, label, color?, brightness? }` (colour a CSS hex colour, default the palette in family order; `brightness` the orbit-line multiplier, default 1). A member is `{ id, family, label?, radiusKm?, elements?, description?, facts?, provenance?, knownLimitations?, listed? }`: with no `elements` it is a listed moon of `center` (`listedMoons(planet)`; its positions come through `data`, as for `addBody`, and its label and radius default to the list's); with `elements` (`semiMajorAxisKm`, `eccentricity`, `inclinationDeg`, `raanDeg`, `argumentOfPeriapsisDeg`, `trueAnomalyDeg`, `time?`, `plane?`) it is a made-up member on two-body motion and needs `label` and `radiusKm`. A set is one kind or the other. `center` is a body in the scene (default the scene's first); `centerGmKm3S2` sizes each orbit line to one lap (default the centre's moon system, else its catalogue record; neither is `bad-body-set`). `bodies` are bodies added with `addBody` that belong to a family: their orbit lines take its colour, and one with no `orbit` of its own, if it is a listed moon of `center`, gets its line in this batch. `balancePoint` (`{ body, gmKm3S2 }`, a member or such a body) draws the lines about the balance point of the centre and that body (default the centre's moon system's own when its body is drawn here). `orbitHistoryMs` loads positions that long before the window so a line can reach back (default 0). Members are not in the Object menu unless `listed: true`. `stateOf` and `provenanceOf` accept member ids; story panels may name them; a view cannot name a set or a member. A repeated id throws `duplicate-id`; a mistake throws `bad-body-set`. |
|
|
89
89
|
| `scene.addPlaces(body, { categories, places, provenance, knownLimitations? })` | The tagged surface places of one body, drawn as markers on it and opened in the information panel. `categories` are `{ key, label, color }` (a CSS hex colour); `places` are `{ id, name, kind, category, latitudeDeg, longitudeDeg, description, details? }` (`id` unique within the body, `kind` shown as the place's kind such as "Crater", an unknown `category` draws white, longitude east-positive as the marker draws it, coordinates kept exactly as given, `details` card facts). `provenance` is shown with every place (PROV-01). The body must be in the scene when it is built; a second call for one body throws `duplicate-id`; a mistake throws `bad-places`. The place lists of 24 bodies ship as data in `astraeus-data` (`astraeus-data/bodies/<body>/{features,categories,map,overview}.json`, with `catalogue.json`); an app converts them to this input. |
|
|
90
|
-
| `scene.addGroup({ id, orbits, plane, label?, center?, color?, dotSizePx?, referenceTime?, seed?, clump?, refillAfterMs?, refillSliceMs?, provenance?, description?, knownLimitations? })` | A list of orbits drawn as one group of dots: `orbits` is `[{ id, semiMajorAxisKm, eccentricity, inclinationDeg, raanDeg, argumentOfPeriapsisDeg, time? }]` (bound orbits, ids distinct), measured about `center` (default the scene's centre; it must be in the scene) in `plane`, which you must give (`"ecliptic-j2000"` or `"EQJ"`; a group without one throws `bad-group`). One colour (`color`, a hex colour), dot size (`dotSizePx`), menu item, info card, provenance and known limits. Where each dot sits along its orbit is a drawing choice, marked illustrative: an even spread shuffled by `seed`, fixed at `referenceTime` (default the opening time), then two-body motion. `clump: { near, fraction, widthDeg }` draws a share of the dots near a body's place along its orbit (a model; the body must be in the scene and not the centre; it may be one added with `addBodyFromElements` before the group). `refillAfterMs` is how often the dots are placed again; `refillSliceMs` (0 or more) is how much of a frame may go on computing the next fill ahead of time.
|
|
90
|
+
| `scene.addGroup({ id, orbits, plane, label?, center?, color?, dotSizePx?, referenceTime?, seed?, clump?, refillAfterMs?, refillSliceMs?, provenance?, description?, knownLimitations? })` | A list of orbits drawn as one group of dots: `orbits` is `[{ id, semiMajorAxisKm, eccentricity, inclinationDeg, raanDeg, argumentOfPeriapsisDeg, time?, meanAnomalyDeg? }]` (bound orbits, ids distinct), measured about `center` (default the scene's centre; it must be in the scene) in `plane`, which you must give (`"ecliptic-j2000"` or `"EQJ"`; a group without one throws `bad-group`). One colour (`color`, a hex colour), dot size (`dotSizePx`), menu item, info card, provenance and known limits. Where each dot sits along its orbit is either measured or a drawing choice. Measured: when every orbit gives `meanAnomalyDeg` (its catalogue mean anomaly in degrees at its own `time`, the record's epoch; finite, wrapping to 0 to 360), each dot sits at that record's position, advanced by unperturbed two-body motion about the centre (mean motion `√(GM / a³)` from the centre's GM); an orbit without `time` has its mean anomaly read at `referenceTime`, so `referenceTime` makes no difference only when every orbit gives `time`; `seed` or `clump` with it throws `bad-group`, and so does a list where some orbits give it and some do not (naming the first without one). The dots drift from the true positions the further the time is from each epoch, since perturbations are ignored. Otherwise the placement is marked illustrative: an even spread shuffled by `seed`, fixed at `referenceTime` (default the opening time), then two-body motion. `clump: { near, fraction, widthDeg }` draws a share of the dots near a body's place along its orbit (a model; the body must be in the scene and not the centre; it may be one added with `addBodyFromElements` before the group). `refillAfterMs` is how often the dots are placed again; `refillSliceMs` (0 or more) is how much of a frame may go on computing the next fill ahead of time. A measured group's card keeps your `provenance` (its `sourceType`, sources and accuracy) and adds a note that each position comes from its record's mean anomaly, and a limit on two-body drift from each epoch; an illustrative group's card shows "illustrative" as its source type, with the elements' own type in the accuracy sentence. The id joins the camera menu (`focus-<id>`, `follow-<id>`) and may be a panel's `object`. A mistake throws `bad-group`. |
|
|
91
91
|
|
|
92
92
|
### Time, events and story
|
|
93
93
|
|
|
@@ -155,7 +155,7 @@ A sky-only viewer (Look out and its switches, no orbit-camera buttons): `scene.c
|
|
|
155
155
|
| `scene.picker` | The picker as set (`{ id, label, options, value }`, frozen), or `undefined` before `setPicker`. |
|
|
156
156
|
| `scene.places` | `{ body, count }` per `addPlaces`, in the order added; a fresh frozen list on every read. |
|
|
157
157
|
| `scene.skyFigures` | `{ id, label, kind, listed, provenance, description?, facts? }` per `addSkyFigures` figure, in the order added; a fresh frozen list on every read. |
|
|
158
|
-
| `scene.groups` | `{ id, label, count, center, plane, provenance, description, knownLimitations }` per `addGroup`: `provenance`, `description` and `knownLimitations` are what the group's card shows (
|
|
158
|
+
| `scene.groups` | `{ id, label, count, center, plane, provenance, description, knownLimitations }` per `addGroup`: `provenance`, `description` and `knownLimitations` are what the group's card shows (the caller's source type for measured positions, else illustrative; with the engine's placement and motion limits). |
|
|
159
159
|
| `scene.activities` | `{ id, label, unit, windowStartUtcMs, windowEndUtcMs, peak: { label, value, timeUtcMs? }, samples: [{ timeUtcMs, value }], provenance?: [{ stretchStartUtcMs, stretchEndUtcMs, provenance }], type? }` per `addActivity`, in the order added; a fresh frozen copy. `peak.value` is the highest sample when no peak moment was given. |
|
|
160
160
|
| `scene.events` | `{ id, label, timeUtcMs, type?, object?, withinSeconds?, provenance? }` per `addEvents`, sorted by time; `provenance` is the event's own, else the batch's. |
|
|
161
161
|
| `scene.panels` | `{ id, timeUtcMs?, title, body, details, provenance, object? }` per `addStoryPanels` (the actions are not read): the moment panels sorted by time, the times resolved as `mount` resolves them, then the steps (no `timeUtcMs`) in the order added (a bad panel throws `bad-panels`). |
|
|
@@ -170,7 +170,7 @@ A sky-only viewer (Look out and its switches, no orbit-camera buttons): `scene.c
|
|
|
170
170
|
|
|
171
171
|
| Call | What it does |
|
|
172
172
|
|---|---|
|
|
173
|
-
| `mount(element, scene, { data?, onChange?, address?, developerTools? })` | Draws the scene with the full viewer. Returns `{ ready, unmount(), timeUtcMs, rate, playing, view, camera, eventZones, selected, panel, look, scale, switches, skyFigures, pick, setTime(t), setRate(r), setPlaying(p), setView(id), setCamera(target), setSelected(id), setPanel(id), setLook(look), setScale(id), setSwitch(id), traceSkyFigure(id), clearSkyTrace(id), setPick(value), onChange(fn), onEventZone(fn), onSelect(fn), onPanel(fn), onCameraChange(fn), onFirstDraw(fn), onPick(fn) }`. `data` is a list of data packages (below); `address` is off by default (see "Page address"); `developerTools` is off by default (the cog and the Developer drawer are not drawn, and the drawer's code is never fetched; the demo site turns it on); the time and speed members are described under "Reading and setting the time". |
|
|
173
|
+
| `mount(element, scene, { data?, onChange?, address?, developerTools? })` | Draws the scene with the full viewer. Returns `{ ready, unmount(), timeUtcMs, rate, playing, view, camera, eventZones, selected, panel, look, scale, switches, skyFigures, pick, setTime(t), setRate(r), setPlaying(p), setView(id), setCamera(target), setSelected(id), setPanel(id), setLook(look), setScale(id), setSwitch(id), groupLook(id), setGroupLook(id), traceSkyFigure(id), clearSkyTrace(id), setPick(value), onChange(fn), onEventZone(fn), onSelect(fn), onPanel(fn), onCameraChange(fn), onFirstDraw(fn), onPick(fn) }`. `data` is a list of data packages (below); `address` is off by default (see "Page address"); `developerTools` is off by default (the cog and the Developer drawer are not drawn, and the drawer's code is never fetched; the demo site turns it on); the time and speed members are described under "Reading and setting the time". |
|
|
174
174
|
| `<AstraeusScene scene data? ref? onReady? onError? time? rate? view? camera? onChange? onEventZone? onPick? onFirstDraw? address? developerTools? className? style? />` | The same viewer as a React component (below). |
|
|
175
175
|
| `SceneError` | Thrown for bad input. `error.code` is one of the documented `SceneErrorCode` values (for example `unknown-body`, `bad-time`, `missing-data`, `no-orbit`) and the message says what to do. |
|
|
176
176
|
|
|
@@ -240,6 +240,17 @@ The speed menu shows exactly the `rates` the scene gives (`setTimeline({ rates }
|
|
|
240
240
|
| `handle.pick`, `handle.setPick(value)`, `handle.onPick(fn)` or `<AstraeusScene onPick />` | `pick` reads the value of the pressed option of the scene's picker (`undefined` until `ready`, after `unmount`, and without a picker). `setPick(value)` moves the pressed option and does nothing else (no signal); a scene without a picker, or an unknown value, throws `bad-picker`; before `ready` or after `unmount`, `not-mounted`. `fn({ picker, value })` is called when a visitor presses an option other than the pressed one; the pressed option stays where it was until the host calls `setPick` (or builds a new scene). To keep the clock across a choice, read `handle.timeUtcMs` inside `fn`, build the next scene and call `setTime` on it once ready. Returns a function that stops it. A listener that throws is reported to the page (`reportError`) and does not stop the next; nothing arrives after `unmount`. |
|
|
241
241
|
| `handle.scale`, `handle.setScale(id)` | The id of the scale showing, and a switch to one of `scene.scales` as if a visitor pressed the scale button; any other id throws `bad-scale`. |
|
|
242
242
|
| `handle.switches`, `handle.setSwitch(id, on)` | The display switches the scene placed with `setSwitches` (`orbitLines`, `labels`, `milkyWay`, `skyFigures`, `skyBoundaries`, `ecliptic`, `celestialEquator`; wherever it placed them) that have something to act on, each `true` (on) or `false`; `{}` when it placed none. `setSwitch` turns one on or off as the visitor's button does; an id the scene did not place, or a non-boolean, throws `bad-switch`. |
|
|
243
|
+
| `handle.groupLook(id)`, `handle.setGroupLook(id, { color?, dotSizePx? })` | `groupLook` reads the colour and dot size the point group `id` (one added with `scene.addGroup`) is drawn with now, `{ color, dotSizePx }`: the group's own (`addGroup`'s `color` and `dotSizePx`, default `"#9de3a8"` and 2.5) until you change them; `undefined` until `ready`, after `unmount`, and for an id that is not a group. `setGroupLook` changes them: `color` a hex colour as `addGroup` takes it, `dotSizePx` a number above 0, a field left out keeps its value. The dots take it on the next drawn frame, also while paused, however the group is drawn; nothing is rebuilt, refilled or re-planned, so the dots stay exactly where they are (25 calls on 126,000 dots took under 0.3 ms in headless Chromium). The group's name label takes the colour too; its card shows no colour and is unchanged. Presentation only: `stateOf`, positions, provenance, views, `shownDuring` and selection are unchanged, `onChange` hears nothing, and `scene.groups` keeps describing the scene as built. A viewer rebuilt with a new scene starts from that scene's own looks. An id that is not a group, a bad colour, a size that is not a finite number above 0 or another field throws `bad-group`; before `ready` or after `unmount`, `not-mounted`. Like every host call it lands in call order (the last call wins). |
|
|
244
|
+
|
|
245
|
+
Dim every group but two, for example the regions either side of a gap, and put them back later, without rebuilding the scene:
|
|
246
|
+
|
|
247
|
+
```ts
|
|
248
|
+
const original = new Map(scene.groups.map((group) => [group.id, handle.groupLook(group.id)!]));
|
|
249
|
+
const bright = new Set(["inner-edge", "outer-edge"]);
|
|
250
|
+
for (const id of original.keys()) handle.setGroupLook(id, bright.has(id) ? { color: "#ffd27a", dotSizePx: 2.5 } : { color: "#3a4a55", dotSizePx: 1.5 });
|
|
251
|
+
// later: every group back to its own look
|
|
252
|
+
for (const [id, look] of original) handle.setGroupLook(id, look);
|
|
253
|
+
```
|
|
243
254
|
|
|
244
255
|
### Sky traces
|
|
245
256
|
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "astraeus",
|
|
3
|
-
"version": "0.9.
|
|
3
|
+
"version": "0.9.4",
|
|
4
4
|
"description": "A 3D solar system engine for the browser: place bodies and recorded paths in a scene, mount it, and get time controls, camera, scale choice and body info. Planet positions and the main pictures included.",
|
|
5
5
|
"license": "MIT",
|
|
6
6
|
"type": "module",
|
package/src/api/cameraRequest.js
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import { cameraIdsOf } from "../core/storyPanels.js";
|
|
2
2
|
import { eqjUnitVector, validateSkyDirection, validateSkyFov, validateSkyPosition, validateStartView } from "../core/startView.js";
|
|
3
3
|
import { SceneError } from "./errors.js";
|
|
4
|
+
import { isPlainObject } from "./plainObject.js";
|
|
4
5
|
/**
|
|
5
6
|
* 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
7
|
* 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;
|
|
@@ -8,7 +9,7 @@ import { SceneError } from "./errors.js";
|
|
|
8
9
|
*/
|
|
9
10
|
export function cameraRequestOf(target, call, now, keepDirection = false) {
|
|
10
11
|
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 (
|
|
12
|
+
if (!isPlainObject(target))
|
|
12
13
|
throw bad(`${String(target)} is not an object`);
|
|
13
14
|
const record = target;
|
|
14
15
|
if ("lookOut" in record)
|
package/src/api/group.d.ts
CHANGED
|
@@ -4,7 +4,7 @@ import type { TimeBounds } from "../core/trajectory.js";
|
|
|
4
4
|
import { type BodyCatalogue } from "../assets/catalogue.js";
|
|
5
5
|
import type { GroupLayer } from "../app/experienceDefinition.js";
|
|
6
6
|
import { type TimeInput } from "./time.js";
|
|
7
|
-
/** One listed orbit of a group: its own id (the record it came from)
|
|
7
|
+
/** One listed orbit of a group: its own id (the record it came from), its shape and orientation, and optionally where along itself it is (`meanAnomalyDeg`). Angles in degrees, length in km. */
|
|
8
8
|
export interface GroupOrbitInput {
|
|
9
9
|
/** The orbit's own id, such as the record it was listed under; distinct within the group. */
|
|
10
10
|
readonly id: string;
|
|
@@ -14,8 +14,10 @@ export interface GroupOrbitInput {
|
|
|
14
14
|
readonly inclinationDeg: number;
|
|
15
15
|
readonly raanDeg: number;
|
|
16
16
|
readonly argumentOfPeriapsisDeg: number;
|
|
17
|
-
/** The moment the record was measured
|
|
17
|
+
/** The moment the record was measured (its epoch); it places the dot only with `meanAnomalyDeg`. Defaults to the group's reference time. */
|
|
18
18
|
readonly time?: TimeInput;
|
|
19
|
+
/** The mean anomaly in degrees at `time`, as a catalogue lists it (finite; wraps). Give it for every orbit or none: then each dot sits at its record's position. A mix throws `bad-group`. */
|
|
20
|
+
readonly meanAnomalyDeg?: number;
|
|
19
21
|
}
|
|
20
22
|
/** A stated share of the dots drawn near a body's position along its orbit: a model, not a measurement. */
|
|
21
23
|
export interface GroupClumpInput {
|
|
@@ -34,8 +36,8 @@ export interface GroupReadoutInput {
|
|
|
34
36
|
}
|
|
35
37
|
/**
|
|
36
38
|
* A group of listed orbits drawn as one set of dots: one dot per orbit, on its own ellipse, one colour and dot size, one menu item and one info card.
|
|
37
|
-
* The group's id joins the camera menu (`focus-<id>`, `follow-<id>`) and may be named by story panels. The orbits' shapes are as listed
|
|
38
|
-
* along its orbit is a drawing choice (an even spread, shuffled by `seed`)
|
|
39
|
+
* The group's id joins the camera menu (`focus-<id>`, `follow-<id>`) and may be named by story panels. The orbits' shapes are as listed. Where each dot sits
|
|
40
|
+
* along its orbit is measured when every orbit gives `meanAnomalyDeg`, else a drawing choice (an even spread, shuffled by `seed`); the card says which.
|
|
39
41
|
*/
|
|
40
42
|
export interface GroupInput {
|
|
41
43
|
/** The group's id: its menu item, camera target and panel `object`. Not shared with any body, path or other group. */
|
|
@@ -54,16 +56,17 @@ export interface GroupInput {
|
|
|
54
56
|
readonly dotSizePx?: number;
|
|
55
57
|
/** The moment each orbit's dot is placed from (then it moves by two-body motion); the scene's opening time when absent. */
|
|
56
58
|
readonly referenceTime?: TimeInput;
|
|
57
|
-
/** A whole number from 0 to 4294967295 that shuffles which orbit takes which place along its orbit; the same seed gives the same picture. Default 0. */
|
|
59
|
+
/** A whole number from 0 to 4294967295 that shuffles which orbit takes which place along its orbit; the same seed gives the same picture. Default 0. Not with `meanAnomalyDeg` (`bad-group`). */
|
|
58
60
|
readonly seed?: number;
|
|
59
|
-
/** Draws a share of the dots near a body's position along its orbit. */
|
|
61
|
+
/** Draws a share of the dots near a body's position along its orbit. Not with `meanAnomalyDeg` (`bad-group`). */
|
|
60
62
|
readonly clump?: GroupClumpInput;
|
|
61
63
|
/** How often, in simulated milliseconds, the dots are placed again exactly; between fills the picture blends the two nearest. Presentation only. Default five minutes. */
|
|
62
64
|
readonly refillAfterMs?: number;
|
|
63
65
|
/** Milliseconds of each frame the dots layer may spend computing the next fill ahead of time, so a large group does not hitch; 0 or a positive number. 0 makes every fill whole in one frame. Presentation only. Default 8. */
|
|
64
66
|
readonly refillSliceMs?: number;
|
|
65
67
|
/**
|
|
66
|
-
* Where the orbit list came from.
|
|
68
|
+
* Where the orbit list came from. With `meanAnomalyDeg` the card keeps this, with a note that each position comes from its record's mean anomaly.
|
|
69
|
+
* Otherwise the group's own card shows `sourceType` "illustrative", because the position along each orbit is a drawing choice;
|
|
67
70
|
* the orbits' `sourceType` here is kept in the accuracy line as "Orbit elements are as listed (<sourceType>); the position along each orbit is illustrative."
|
|
68
71
|
* Your `sources` stay, and the group appends this note to your `notes`: "Each orbit's shape and orientation come from its record, but the records give no
|
|
69
72
|
* position along the orbit: that position is an even spread of mean anomaly at the reference time, a drawing choice (illustrative), advanced by unperturbed
|
|
@@ -83,13 +86,15 @@ export interface PlannedGroup {
|
|
|
83
86
|
readonly label: string;
|
|
84
87
|
readonly input: GroupInput;
|
|
85
88
|
}
|
|
89
|
+
/** A hex colour as `addGroup` (and `setGroupLook`) takes it: `#rgb` or `#rrggbb`. */
|
|
90
|
+
export declare const HEX: RegExp;
|
|
86
91
|
/** Checks what can be checked before the scene is complete; the centre, the clump body and the id clash with other things are checked at build. */
|
|
87
92
|
export declare function planGroup(input: GroupInput, catalogue?: BodyCatalogue): PlannedGroup;
|
|
88
|
-
/** The provenance a group's card shows (`Scene.groups`): the
|
|
93
|
+
/** The provenance a group's card shows (`Scene.groups`): the caller's source with the engine's placement statement (measured or illustrative). */
|
|
89
94
|
export declare function groupCardProvenance(input: GroupInput): Provenance;
|
|
90
95
|
/** The words on a group's card: the caller's, else a sentence stating the count. */
|
|
91
96
|
export declare function groupDescription(input: GroupInput, count: number): string;
|
|
92
|
-
/** The known limits on a group's card: the caller's, then the engine's own about placement, the clump and motion. */
|
|
97
|
+
/** The known limits on a group's card: the caller's, then the engine's own about placement (measured or illustrative), the clump and motion. */
|
|
93
98
|
export declare function groupLimitations(input: GroupInput, catalogue: BodyCatalogue): readonly string[];
|
|
94
99
|
/** Builds the draw layer: the listed-orbit group and its one shell item. `center` and `openUtcMs` come from the finished scene; a group error from the engine is renamed `bad-group`. */
|
|
95
100
|
export declare function buildGroupLayer(plan: PlannedGroup, catalogue: BodyCatalogue, center: BodyId, openUtcMs: number, window: TimeBounds): GroupLayer;
|
package/src/api/group.js
CHANGED
|
@@ -6,7 +6,8 @@ import { catalogue as builtInCatalogue } from "../assets/catalogue.js";
|
|
|
6
6
|
import { SceneError } from "./errors.js";
|
|
7
7
|
import { toUtcMs } from "./time.js";
|
|
8
8
|
const GROUP_COLOR = "#9de3a8";
|
|
9
|
-
|
|
9
|
+
/** A hex colour as `addGroup` (and `setGroupLook`) takes it: `#rgb` or `#rrggbb`. */
|
|
10
|
+
export const HEX = /^#[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$/;
|
|
10
11
|
const bad = (id, message) => new SceneError("bad-group", `addGroup("${String(id)}"): ${message}`);
|
|
11
12
|
/** Checks what can be checked before the scene is complete; the centre, the clump body and the id clash with other things are checked at build. */
|
|
12
13
|
export function planGroup(input, catalogue = builtInCatalogue) {
|
|
@@ -15,7 +16,11 @@ export function planGroup(input, catalogue = builtInCatalogue) {
|
|
|
15
16
|
throw bad(id, "the group needs a non-empty id");
|
|
16
17
|
if (input.plane !== "ecliptic-j2000" && input.plane !== "EQJ")
|
|
17
18
|
throw bad(id, `plane must be "ecliptic-j2000" or "EQJ", got ${input.plane === undefined ? "nothing" : JSON.stringify(input.plane)}; say which plane the elements are given in`);
|
|
18
|
-
checkOrbits(id, input.orbits);
|
|
19
|
+
const measured = checkOrbits(id, input.orbits);
|
|
20
|
+
if (measured && input.seed !== undefined)
|
|
21
|
+
throw bad(id, "seed only shuffles illustrative positions; every orbit gives meanAnomalyDeg, so the positions are measured: drop seed");
|
|
22
|
+
if (measured && input.clump !== undefined)
|
|
23
|
+
throw bad(id, "clump only shapes illustrative positions; every orbit gives meanAnomalyDeg, so the positions are measured: drop clump");
|
|
19
24
|
checkLook(id, input);
|
|
20
25
|
if (input.clump !== undefined)
|
|
21
26
|
checkClump(id, input.clump, catalogue);
|
|
@@ -24,9 +29,11 @@ export function planGroup(input, catalogue = builtInCatalogue) {
|
|
|
24
29
|
throw new SceneError("unknown-body", `addGroup("${id}"): centre "${String(input.center)}" is not a catalogued body`);
|
|
25
30
|
return { id, label: input.label ?? id, input };
|
|
26
31
|
}
|
|
32
|
+
/** Checks ids and the all-or-none mean anomaly rule; returns whether the group has measured positions. */
|
|
27
33
|
function checkOrbits(id, orbits) {
|
|
28
34
|
if (!Array.isArray(orbits) || orbits.length === 0)
|
|
29
35
|
throw bad(id, "the group needs at least one orbit; the list is empty");
|
|
36
|
+
const measured = orbits.some((orbit) => orbit?.meanAnomalyDeg !== undefined);
|
|
30
37
|
const seen = new Set();
|
|
31
38
|
for (const orbit of orbits) {
|
|
32
39
|
if (typeof orbit?.id !== "string" || orbit.id === "")
|
|
@@ -34,7 +41,20 @@ function checkOrbits(id, orbits) {
|
|
|
34
41
|
if (seen.has(orbit.id))
|
|
35
42
|
throw bad(id, `orbit "${orbit.id}" appears twice`);
|
|
36
43
|
seen.add(orbit.id);
|
|
44
|
+
const m = orbit.meanAnomalyDeg;
|
|
45
|
+
if (m === undefined) {
|
|
46
|
+
if (measured)
|
|
47
|
+
throw bad(id, `orbit "${orbit.id}" gives no meanAnomalyDeg while others do; give it for every orbit (measured positions) or for none (illustrative positions)`);
|
|
48
|
+
}
|
|
49
|
+
else if (!(typeof m === "number" && Number.isFinite(m))) {
|
|
50
|
+
throw bad(id, `orbit "${orbit.id}" meanAnomalyDeg must be a finite number of degrees, got ${String(m)}`);
|
|
51
|
+
}
|
|
37
52
|
}
|
|
53
|
+
return measured;
|
|
54
|
+
}
|
|
55
|
+
/** Whether every orbit of a (planned) group gives its mean anomaly: measured positions. */
|
|
56
|
+
function isMeasured(input) {
|
|
57
|
+
return input.orbits[0]?.meanAnomalyDeg !== undefined;
|
|
38
58
|
}
|
|
39
59
|
const positive = (value) => value === undefined || (Number.isFinite(value) && value > 0);
|
|
40
60
|
function checkLook(id, input) {
|
|
@@ -70,6 +90,7 @@ function checkClump(id, clump, catalogue) {
|
|
|
70
90
|
if (!(clump.widthDeg > 0 && clump.widthDeg <= 180))
|
|
71
91
|
throw bad(id, `clump.widthDeg must be above 0 and at most 180, got ${String(clump.widthDeg)}`);
|
|
72
92
|
}
|
|
93
|
+
const MEASURED_PLACEMENT_LIMIT = "Each dot's position comes from its record's mean anomaly by unperturbed two-body motion from the record's epoch; perturbations are ignored, so a dot drifts from the true position the further the time is from that epoch.";
|
|
73
94
|
const PLACEMENT_LIMIT = "The position of each dot along its orbit is illustrative: the list gives the orbit's shape and orientation, and the dots are spread evenly along them.";
|
|
74
95
|
const MOTION_LIMIT = "Motion is unperturbed two-body motion about the centre.";
|
|
75
96
|
const CLUMP_LIMIT = (catalogue, near, fraction) => `${Math.round(fraction * 100)}% of the dots are drawn near ${catalogue.get(near).definition.label}'s position along its orbit. That clump is a model, not a measurement.`;
|
|
@@ -78,18 +99,18 @@ const AS_SUPPLIED = createProvenance({ sourceType: "illustrative", sources: ["Su
|
|
|
78
99
|
function groupSource(input) {
|
|
79
100
|
return input.provenance ?? AS_SUPPLIED;
|
|
80
101
|
}
|
|
81
|
-
/** The provenance a group's card shows (`Scene.groups`): the
|
|
102
|
+
/** The provenance a group's card shows (`Scene.groups`): the caller's source with the engine's placement statement (measured or illustrative). */
|
|
82
103
|
export function groupCardProvenance(input) {
|
|
83
|
-
return listedGroupProvenance(groupSource(input), input.clump !== undefined);
|
|
104
|
+
return listedGroupProvenance(groupSource(input), input.clump !== undefined, isMeasured(input));
|
|
84
105
|
}
|
|
85
106
|
/** The words on a group's card: the caller's, else a sentence stating the count. */
|
|
86
107
|
export function groupDescription(input, count) {
|
|
87
108
|
return input.description ?? `${count} listed orbit${count === 1 ? "" : "s"}, each drawn as one dot. One item stands for the whole group; its focus point is the centroid of the dots.`;
|
|
88
109
|
}
|
|
89
|
-
/** The known limits on a group's card: the caller's, then the engine's own about placement, the clump and motion. */
|
|
110
|
+
/** The known limits on a group's card: the caller's, then the engine's own about placement (measured or illustrative), the clump and motion. */
|
|
90
111
|
export function groupLimitations(input, catalogue) {
|
|
91
112
|
const clump = input.clump;
|
|
92
|
-
return [...(input.knownLimitations ?? []), PLACEMENT_LIMIT, ...(clump === undefined ? [] : [CLUMP_LIMIT(catalogue, clump.near, clump.fraction)]), MOTION_LIMIT];
|
|
113
|
+
return [...(input.knownLimitations ?? []), isMeasured(input) ? MEASURED_PLACEMENT_LIMIT : PLACEMENT_LIMIT, ...(clump === undefined ? [] : [CLUMP_LIMIT(catalogue, clump.near, clump.fraction)]), MOTION_LIMIT];
|
|
93
114
|
}
|
|
94
115
|
/** Builds the draw layer: the listed-orbit group and its one shell item. `center` and `openUtcMs` come from the finished scene; a group error from the engine is renamed `bad-group`. */
|
|
95
116
|
export function buildGroupLayer(plan, catalogue, center, openUtcMs, window) {
|
|
@@ -99,6 +120,7 @@ export function buildGroupLayer(plan, catalogue, center, openUtcMs, window) {
|
|
|
99
120
|
recordId: orbit.id,
|
|
100
121
|
epochUtcMs: orbit.time === undefined ? referenceUtcMs : toUtcMs(orbit.time, `addGroup("${id}") orbit "${orbit.id}" time`),
|
|
101
122
|
elements: { semiMajorAxisKm: orbit.semiMajorAxisKm, eccentricity: orbit.eccentricity, inclinationDeg: orbit.inclinationDeg, raanDeg: orbit.raanDeg, argumentOfPeriapsisDeg: orbit.argumentOfPeriapsisDeg },
|
|
123
|
+
...(orbit.meanAnomalyDeg === undefined ? {} : { meanAnomalyDeg: orbit.meanAnomalyDeg }),
|
|
102
124
|
}));
|
|
103
125
|
const clump = input.clump;
|
|
104
126
|
try {
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
/** What `handle.setGroupLook` takes; a field left out keeps its value. */
|
|
2
|
+
export interface GroupLookInput {
|
|
3
|
+
/** A hex colour, as `addGroup` takes it. */
|
|
4
|
+
readonly color?: string;
|
|
5
|
+
/** Screen pixels, above 0. */
|
|
6
|
+
readonly dotSizePx?: number;
|
|
7
|
+
}
|
|
8
|
+
/** What `handle.groupLook` reads. */
|
|
9
|
+
export interface GroupLookRead {
|
|
10
|
+
/** The dots' colour. */
|
|
11
|
+
readonly color: string;
|
|
12
|
+
/** Screen pixels. */
|
|
13
|
+
readonly dotSizePx: number;
|
|
14
|
+
}
|
|
15
|
+
/**
|
|
16
|
+
* Checks a `setGroupLook` call and fills the fields left out from `current` (the look in force); throws `bad-group` naming the id when it is not a group
|
|
17
|
+
* (`current` undefined), or naming the field when a value is wrong.
|
|
18
|
+
*/
|
|
19
|
+
export declare function checkedGroupLook(id: unknown, look: unknown, current: GroupLookRead | undefined, groups: readonly string[]): GroupLookRead;
|
|
@@ -0,0 +1,26 @@
|
|
|
1
|
+
import { SceneError } from "./errors.js";
|
|
2
|
+
import { HEX } from "./group.js";
|
|
3
|
+
import { isPlainObject } from "./plainObject.js";
|
|
4
|
+
const FIELDS = ["color", "dotSizePx"];
|
|
5
|
+
const bad = (id, message) => new SceneError("bad-group", `setGroupLook("${String(id)}"): ${message}`);
|
|
6
|
+
/**
|
|
7
|
+
* Checks a `setGroupLook` call and fills the fields left out from `current` (the look in force); throws `bad-group` naming the id when it is not a group
|
|
8
|
+
* (`current` undefined), or naming the field when a value is wrong.
|
|
9
|
+
*/
|
|
10
|
+
export function checkedGroupLook(id, look, current, groups) {
|
|
11
|
+
if (typeof id !== "string" || current === undefined) {
|
|
12
|
+
throw bad(id, `"${String(id)}" is not a group this viewer draws (${groups.length === 0 ? "the scene added none; add them with addGroup" : groups.join(", ")})`);
|
|
13
|
+
}
|
|
14
|
+
if (!isPlainObject(look))
|
|
15
|
+
throw bad(id, `expected { color?, dotSizePx? }, got ${String(look)}`);
|
|
16
|
+
const given = look;
|
|
17
|
+
for (const key of Object.keys(given))
|
|
18
|
+
if (!FIELDS.includes(key))
|
|
19
|
+
throw bad(id, `"${key}" is not a group look field (${FIELDS.join(", ")})`);
|
|
20
|
+
const { color = current.color, dotSizePx = current.dotSizePx } = given;
|
|
21
|
+
if (typeof color !== "string" || !HEX.test(color))
|
|
22
|
+
throw bad(id, `color "${String(color)}" is not a hex colour such as "#9de3a8"`);
|
|
23
|
+
if (typeof dotSizePx !== "number" || !Number.isFinite(dotSizePx) || dotSizePx <= 0)
|
|
24
|
+
throw bad(id, `dotSizePx must be a finite number above 0, got ${String(dotSizePx)}`);
|
|
25
|
+
return { color, dotSizePx };
|
|
26
|
+
}
|
package/src/api/index.d.ts
CHANGED
|
@@ -2,6 +2,7 @@ export { Scene, type SceneCamera, type AddBodyOptions, type CardFactInput, type
|
|
|
2
2
|
export type { MoonPanelInput, MoonPanelFamilyInput, MoonPanelMoonInput, PlacesInput, PlaceInput, PlaceCategoryInput } from "./moonPanelInput.js";
|
|
3
3
|
export type { SkyFigureInput, SkyFigureEnd } from "./skyFigureInput.js";
|
|
4
4
|
export type { SkyClearOptions, SkyTraceOptions } from "./skyTraceInput.js";
|
|
5
|
+
export type { GroupLookInput, GroupLookRead } from "./groupLookInput.js";
|
|
5
6
|
export type { PickerInput, PickerOptionInput, PickChange } from "./pickerInput.js";
|
|
6
7
|
export type { BodySetInput, BodySetFamilyInput, BodySetMemberInput, BodySetElementsInput, BodySetBodyInput, BodySetBalanceInput } from "./bodySetInput.js";
|
|
7
8
|
export { type EventInput, type AddEventsOptions, type TimelineInput, type PacingInput, type StoryPanelAt, type StoryPanelInput, type StoryPanelPlaybackInput } from "./story.js";
|
package/src/api/lookInput.js
CHANGED
|
@@ -1,11 +1,12 @@
|
|
|
1
1
|
import { isCssColour, isFontFamily, isTimeZone } from "../core/lookValues.js";
|
|
2
2
|
import { LOOK_FIELDS, lookName, lookValue, lookWith } from "../app/look.js";
|
|
3
3
|
import { SceneError } from "./errors.js";
|
|
4
|
+
import { isPlainObject } from "./plainObject.js";
|
|
4
5
|
const TOP_LEVEL = [...new Set(LOOK_FIELDS.map(({ path }) => path[0]))];
|
|
5
6
|
/** Checks a `setLook` argument: an object of known looks, each a finite number in its range, a boolean, a CSS colour, a font-family text, a time zone or one of a few names as its field says. Returns a frozen copy (the scene keeps no reference to the caller's object). */
|
|
6
7
|
export function checkedLook(input) {
|
|
7
8
|
const bad = (message) => new SceneError("bad-look", `setLook: ${message}`);
|
|
8
|
-
const isObject =
|
|
9
|
+
const isObject = isPlainObject;
|
|
9
10
|
if (!isObject(input))
|
|
10
11
|
throw bad(`give an object such as { starBrightness: 1.4 } (looks: ${TOP_LEVEL.join(", ")})`);
|
|
11
12
|
for (const [key, value] of Object.entries(input)) {
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether `value` is a plain object, as an options or look argument must be: made by a literal, `Object.create(null)` or JSON, from any realm.
|
|
3
|
+
* Arrays, a `Map`, a `Date`, a class instance and every other object with its own prototype chain are not (I-183: a `Map` read as `{}` used to pass as an empty look).
|
|
4
|
+
*/
|
|
5
|
+
export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
|
|
@@ -0,0 +1,10 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Whether `value` is a plain object, as an options or look argument must be: made by a literal, `Object.create(null)` or JSON, from any realm.
|
|
3
|
+
* Arrays, a `Map`, a `Date`, a class instance and every other object with its own prototype chain are not (I-183: a `Map` read as `{}` used to pass as an empty look).
|
|
4
|
+
*/
|
|
5
|
+
export function isPlainObject(value) {
|
|
6
|
+
if (typeof value !== "object" || value === null)
|
|
7
|
+
return false;
|
|
8
|
+
const proto = Object.getPrototypeOf(value);
|
|
9
|
+
return proto === null || Object.getPrototypeOf(proto) === null;
|
|
10
|
+
}
|
package/src/api/sceneReads.d.ts
CHANGED
|
@@ -47,7 +47,7 @@ export interface SceneGroupRead {
|
|
|
47
47
|
readonly center: BodyId;
|
|
48
48
|
/** The plane the elements are given in. */
|
|
49
49
|
readonly plane: "ecliptic-j2000" | "EQJ";
|
|
50
|
-
/** The provenance its card shows:
|
|
50
|
+
/** The provenance its card shows: the source's own type when every orbit gives `meanAnomalyDeg` (measured positions); otherwise illustrative, with the source's own type kept in the accuracy line. */
|
|
51
51
|
readonly provenance: Provenance;
|
|
52
52
|
/** The words on its info card: those given to `addGroup`, else a sentence stating the count. */
|
|
53
53
|
readonly description: string;
|
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { LookInput, LookRead } from "./look.js";
|
|
2
|
+
import type { GroupLookInput, GroupLookRead } from "./groupLookInput.js";
|
|
2
3
|
import type { PickChange } from "./pickerInput.js";
|
|
3
4
|
import type { TimeInput } from "./time.js";
|
|
4
5
|
import type { SceneSkyFigureRead } from "./sceneReads.js";
|
|
@@ -65,6 +66,10 @@ export interface ViewerHandle {
|
|
|
65
66
|
readonly look: LookRead | undefined;
|
|
66
67
|
/** Sets the whole look, checked as `Scene.setLook` checks it (a look not named takes its default; a bad one throws `bad-look`); before `ready` or after `unmount` throws `not-mounted`. It wins over the same look in the page address, which only starts the viewer. Presentation only. `onChange` hears it with `cause: "host"`. */
|
|
67
68
|
setLook(look: LookInput): void;
|
|
69
|
+
/** The colour and dot size the group `id` is drawn with now; undefined until `ready`, after `unmount`, and for a non-group id. */
|
|
70
|
+
groupLook(id: string): GroupLookRead | undefined;
|
|
71
|
+
/** Changes a group's dot colour and size (and its label's colour) from the next frame without a rebuild; fields left out keep their value. Presentation only; `Scene.groups` is unchanged. A bad id or value throws `bad-group`; before `ready` or after `unmount`, `not-mounted`. */
|
|
72
|
+
setGroupLook(id: string, look: GroupLookInput): void;
|
|
68
73
|
/** The id of the scale showing; undefined until `ready` has resolved and after `unmount`. */
|
|
69
74
|
readonly scale: string | undefined;
|
|
70
75
|
/** Switches to one of the scales the viewer offers (`Scene.scales`); any other id throws `bad-scale`; before `ready` or after `unmount`, `not-mounted`. `onChange` hears it with `cause: "host"`. */
|
package/src/api/viewerHandle.js
CHANGED
|
@@ -17,6 +17,8 @@ export function viewerHandleOf(link) {
|
|
|
17
17
|
setPick: (value) => link.setPick(value),
|
|
18
18
|
onPick: (listener) => link.onPick(listener),
|
|
19
19
|
setLook: (look) => link.setLook(look),
|
|
20
|
+
groupLook: (id) => link.groupLook(id),
|
|
21
|
+
setGroupLook: (id, look) => link.setGroupLook(id, look),
|
|
20
22
|
setScale: (id) => link.setScale(id),
|
|
21
23
|
setSwitch: (id, on) => link.setSwitch(id, on),
|
|
22
24
|
traceSkyFigure: (id, options) => link.traceSkyFigure(id, options),
|
package/src/api/viewerLink.d.ts
CHANGED
|
@@ -1,6 +1,7 @@
|
|
|
1
1
|
import type { ViewerChangeCause, ViewerPort, ViewerState } from "../app/viewerPort.js";
|
|
2
2
|
import type { ViewerControl } from "../app/viewerPort.js";
|
|
3
3
|
import type { LookInput, LookRead } from "./look.js";
|
|
4
|
+
import type { GroupLookInput, GroupLookRead } from "./groupLookInput.js";
|
|
4
5
|
import { type SelectionChange } from "./viewerSelection.js";
|
|
5
6
|
import { type PanelChange } from "./viewerPanels.js";
|
|
6
7
|
import type { PickChange } from "./pickerInput.js";
|
|
@@ -138,6 +139,9 @@ export declare class ViewerLink implements ViewerPort {
|
|
|
138
139
|
setLook(look: LookInput): void;
|
|
139
140
|
setScale(id: string): void;
|
|
140
141
|
setSwitch(id: string, on: boolean): void;
|
|
142
|
+
groupLook(id: string): GroupLookRead | undefined;
|
|
143
|
+
/** Presentation only: moves no clock, view or selection, so nothing is published. */
|
|
144
|
+
setGroupLook(id: string, look: GroupLookInput): void;
|
|
141
145
|
setSelected(id: string | undefined): void;
|
|
142
146
|
setPanel(id: string | undefined): void;
|
|
143
147
|
onPanel(listener: (change: PanelChange) => void): () => void;
|
package/src/api/viewerLink.js
CHANGED
|
@@ -118,6 +118,9 @@ export class ViewerLink {
|
|
|
118
118
|
setLook(look) { this.#looks.setLook(look); this.#afterHost(); }
|
|
119
119
|
setScale(id) { this.#looks.setScale(id); this.#afterHost(); }
|
|
120
120
|
setSwitch(id, on) { this.#looks.setSwitch(id, on); this.#afterHost(); }
|
|
121
|
+
groupLook(id) { return this.#looks.groupLook(id); }
|
|
122
|
+
/** Presentation only: moves no clock, view or selection, so nothing is published. */
|
|
123
|
+
setGroupLook(id, look) { this.#looks.setGroupLook(id, look); }
|
|
121
124
|
setSelected(id) { this.#selection.setSelected(id); this.#afterHost(); }
|
|
122
125
|
setPanel(id) { this.#panels.setPanel(id); this.#afterHost(); }
|
|
123
126
|
onPanel(listener) { return this.#panels.onPanel(listener); }
|
package/src/api/viewerLooks.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { LookInput, LookRead } from "./look.js";
|
|
2
|
+
import { type GroupLookInput, type GroupLookRead } from "./groupLookInput.js";
|
|
2
3
|
import type { LinkAccess } from "./viewerLink.js";
|
|
3
4
|
/** The host link's presentation: the looks, the scale and the display switches, their reads and their setters. */
|
|
4
5
|
export declare class ViewerLooks {
|
|
@@ -14,6 +15,10 @@ export declare class ViewerLooks {
|
|
|
14
15
|
setLook(look: LookInput): void;
|
|
15
16
|
/** Switches to one of the scales the viewer offers (`Scene.scales`); any other id throws `bad-scale`. */
|
|
16
17
|
setScale(id: string): void;
|
|
18
|
+
/** The colour and dot size the group `id` is drawn with now; undefined before the viewer is drawn, after it is gone, and for an id that is not a group. */
|
|
19
|
+
groupLook(id: string): GroupLookRead | undefined;
|
|
20
|
+
/** Changes a group's colour and dot size, the fields left out kept (`bad-group` for a non-group id or a bad value); the dots take it at the next frame. */
|
|
21
|
+
setGroupLook(id: string, look: GroupLookInput): void;
|
|
17
22
|
/** Turns a display switch the scene placed on or off; an id it did not place, or a non-boolean, throws `bad-switch`. */
|
|
18
23
|
setSwitch(id: string, on: boolean): void;
|
|
19
24
|
}
|
package/src/api/viewerLooks.js
CHANGED
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import { SceneError } from "./errors.js";
|
|
2
2
|
import { checkedLook } from "./lookInput.js";
|
|
3
|
+
import { checkedGroupLook } from "./groupLookInput.js";
|
|
3
4
|
/** The host link's presentation: the looks, the scale and the display switches, their reads and their setters. */
|
|
4
5
|
export class ViewerLooks {
|
|
5
6
|
access;
|
|
@@ -24,6 +25,17 @@ export class ViewerLooks {
|
|
|
24
25
|
throw new SceneError("bad-scale", `setScale: "${String(id)}" is not one of the scales this viewer offers (${control.scales.join(", ")})`);
|
|
25
26
|
control.setScale(id);
|
|
26
27
|
}
|
|
28
|
+
/** The colour and dot size the group `id` is drawn with now; undefined before the viewer is drawn, after it is gone, and for an id that is not a group. */
|
|
29
|
+
groupLook(id) {
|
|
30
|
+
const look = this.access.control()?.groupLook?.(id);
|
|
31
|
+
return look === undefined ? undefined : { color: look.color, dotSizePx: look.dotSizePx };
|
|
32
|
+
}
|
|
33
|
+
/** Changes a group's colour and dot size, the fields left out kept (`bad-group` for a non-group id or a bad value); the dots take it at the next frame. */
|
|
34
|
+
setGroupLook(id, look) {
|
|
35
|
+
const control = this.access.open("setGroupLook");
|
|
36
|
+
const checked = checkedGroupLook(id, look, typeof id === "string" ? control.groupLook?.(id) : undefined, control.groups ?? []);
|
|
37
|
+
control.setGroupLook?.(id, checked);
|
|
38
|
+
}
|
|
27
39
|
/** Turns a display switch the scene placed on or off; an id it did not place, or a non-boolean, throws `bad-switch`. */
|
|
28
40
|
setSwitch(id, on) {
|
|
29
41
|
const control = this.access.open("setSwitch");
|
package/src/app/App.js
CHANGED
|
@@ -42,6 +42,7 @@ import { cameraIdsOf } from "../core/storyPanels.js";
|
|
|
42
42
|
import { baseGlowOf, glowLookOf, markerSettingsOf } from "./bodyDraw.js";
|
|
43
43
|
import { resolveLook } from "./look.js";
|
|
44
44
|
import { applyLook, desktopPicturesOf, lookReadOf, presentationOf, skySettingsOf } from "./liveLook.js";
|
|
45
|
+
import { DEFAULT_POINT_SIZE_PX } from "./PointsView.js";
|
|
45
46
|
/** Frames-per-second readings kept for the graph: one per 250 ms poll, so about 15 seconds. */
|
|
46
47
|
const FPS_HISTORY = 60;
|
|
47
48
|
/** The labels switched off at the start: objects that set `showLabel: false`, then `?labels=<id>:on|off,...` over them. */
|
|
@@ -491,6 +492,14 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
|
|
|
491
492
|
const hostClearSkyTrace = useCallback((id, seconds) => { controls.current.skyTraces.push({ id, seconds, reduced: prefersReducedMotion() }); }, []);
|
|
492
493
|
const hostTraceSkyFigure = useCallback((id, seconds, after) => { controls.current.skyTraces.push({ id, seconds, after, reduced: prefersReducedMotion() }); }, []);
|
|
493
494
|
const hostSetSwitch = useCallback((id, on) => live.current?.setSwitch(id, on), []);
|
|
495
|
+
// The host's group looks belong to this scene's groups: a viewer rebuilt with a new scene starts from that scene's own colours and sizes.
|
|
496
|
+
const groupLooks = useMemo(() => new Map(), [runtime]);
|
|
497
|
+
const groupIds = useMemo(() => runtime.groups.map((layer) => layer.object.id), [runtime]);
|
|
498
|
+
const hostGroupLook = useCallback((id) => {
|
|
499
|
+
const layer = runtime.groups.find((candidate) => candidate.object.id === id);
|
|
500
|
+
return layer === undefined ? undefined : groupLooks.get(id) ?? { color: layer.color, dotSizePx: layer.pointSizePx ?? DEFAULT_POINT_SIZE_PX };
|
|
501
|
+
}, [runtime, groupLooks]);
|
|
502
|
+
const hostSetGroupLook = useCallback((id, look) => { groupLooks.set(id, { color: look.color, dotSizePx: look.dotSizePx }); }, [groupLooks]);
|
|
494
503
|
/** The figure the open story panel traced when it opened; it is cleared (default fade) when the panel is left. */
|
|
495
504
|
const panelTrace = useRef(null);
|
|
496
505
|
/** The panel whose actions were last applied (a host `setPanel` shows its panel at once, so `openStoryPanelId` cannot say whether the shell has opened it yet). */
|
|
@@ -533,9 +542,10 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
|
|
|
533
542
|
return undefined;
|
|
534
543
|
hostAttached.current = true;
|
|
535
544
|
shownKey.current = null; // the presentation is read afresh after each attach
|
|
536
|
-
|
|
545
|
+
controls.current.groupLooks = groupLooks;
|
|
546
|
+
host.attach({ ...(definition.picker === undefined ? {} : { picker: { id: definition.picker.id, values: definition.picker.options.map((option) => option.value), start: definition.picker.value } }), window: runtime.loopWindow, skyFigures: skyFigureReads(runtime.skyFigures, experience.skyFigures), events: experience.events, rates: definition.experience.rates, paced: runtime.pacing !== undefined, read: stateNow, seek: hostSeekTo, setRate: changeRate, playable: definition.experience.hideTimeline !== true, setPlaying: hostSetPlaying, views: viewIds, setView: chooseView, cameraTargets, readCamera, setCamera, setSelected: hostSetSelected, panels: panelIds, setPanel: hostSetPanel, scales: hostScales, setScale: hostSetScale, setLook: hostSetLook, setSwitch: hostSetSwitch, traceSkyFigure: hostTraceSkyFigure, clearSkyTrace: hostClearSkyTrace, groups: groupIds, groupLook: hostGroupLook, setGroupLook: hostSetGroupLook });
|
|
537
547
|
return () => { hostAttached.current = false; host.detach(); };
|
|
538
|
-
}, [host, runtime, definition, hostSeekTo, changeRate, viewIds, chooseView, cameraTargets, readCamera, setCamera, hostSetSelected, panelIds, hostSetPanel, experience, hostSetPlaying, hostScales, hostSetScale, hostSetLook, hostSetSwitch, hostTraceSkyFigure, hostClearSkyTrace]);
|
|
548
|
+
}, [host, runtime, definition, hostSeekTo, changeRate, viewIds, chooseView, cameraTargets, readCamera, setCamera, hostSetSelected, panelIds, hostSetPanel, experience, hostSetPlaying, hostScales, hostSetScale, hostSetLook, hostSetSwitch, hostTraceSkyFigure, hostClearSkyTrace, groupLooks, groupIds, hostGroupLook, hostSetGroupLook]);
|
|
539
549
|
useEffect(() => {
|
|
540
550
|
if (!developerMode)
|
|
541
551
|
return undefined;
|
package/src/app/App.node.js
CHANGED
|
@@ -42,6 +42,7 @@ import { cameraIdsOf } from "../core/storyPanels.js";
|
|
|
42
42
|
import { baseGlowOf, glowLookOf, markerSettingsOf } from "./bodyDraw.js";
|
|
43
43
|
import { resolveLook } from "./look.js";
|
|
44
44
|
import { applyLook, desktopPicturesOf, lookReadOf, presentationOf, skySettingsOf } from "./liveLook.js";
|
|
45
|
+
import { DEFAULT_POINT_SIZE_PX } from "./PointsView.js";
|
|
45
46
|
/** Frames-per-second readings kept for the graph: one per 250 ms poll, so about 15 seconds. */
|
|
46
47
|
const FPS_HISTORY = 60;
|
|
47
48
|
/** The labels switched off at the start: objects that set `showLabel: false`, then `?labels=<id>:on|off,...` over them. */
|
|
@@ -491,6 +492,14 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
|
|
|
491
492
|
const hostClearSkyTrace = useCallback((id, seconds) => { controls.current.skyTraces.push({ id, seconds, reduced: prefersReducedMotion() }); }, []);
|
|
492
493
|
const hostTraceSkyFigure = useCallback((id, seconds, after) => { controls.current.skyTraces.push({ id, seconds, after, reduced: prefersReducedMotion() }); }, []);
|
|
493
494
|
const hostSetSwitch = useCallback((id, on) => live.current?.setSwitch(id, on), []);
|
|
495
|
+
// The host's group looks belong to this scene's groups: a viewer rebuilt with a new scene starts from that scene's own colours and sizes.
|
|
496
|
+
const groupLooks = useMemo(() => new Map(), [runtime]);
|
|
497
|
+
const groupIds = useMemo(() => runtime.groups.map((layer) => layer.object.id), [runtime]);
|
|
498
|
+
const hostGroupLook = useCallback((id) => {
|
|
499
|
+
const layer = runtime.groups.find((candidate) => candidate.object.id === id);
|
|
500
|
+
return layer === undefined ? undefined : groupLooks.get(id) ?? { color: layer.color, dotSizePx: layer.pointSizePx ?? DEFAULT_POINT_SIZE_PX };
|
|
501
|
+
}, [runtime, groupLooks]);
|
|
502
|
+
const hostSetGroupLook = useCallback((id, look) => { groupLooks.set(id, { color: look.color, dotSizePx: look.dotSizePx }); }, [groupLooks]);
|
|
494
503
|
/** The figure the open story panel traced when it opened; it is cleared (default fade) when the panel is left. */
|
|
495
504
|
const panelTrace = useRef(null);
|
|
496
505
|
/** The panel whose actions were last applied (a host `setPanel` shows its panel at once, so `openStoryPanelId` cannot say whether the shell has opened it yet). */
|
|
@@ -533,9 +542,10 @@ export function App({ definition, writeTitle = true, address, developerTools, ho
|
|
|
533
542
|
return undefined;
|
|
534
543
|
hostAttached.current = true;
|
|
535
544
|
shownKey.current = null; // the presentation is read afresh after each attach
|
|
536
|
-
|
|
545
|
+
controls.current.groupLooks = groupLooks;
|
|
546
|
+
host.attach({ ...(definition.picker === undefined ? {} : { picker: { id: definition.picker.id, values: definition.picker.options.map((option) => option.value), start: definition.picker.value } }), window: runtime.loopWindow, skyFigures: skyFigureReads(runtime.skyFigures, experience.skyFigures), events: experience.events, rates: definition.experience.rates, paced: runtime.pacing !== undefined, read: stateNow, seek: hostSeekTo, setRate: changeRate, playable: definition.experience.hideTimeline !== true, setPlaying: hostSetPlaying, views: viewIds, setView: chooseView, cameraTargets, readCamera, setCamera, setSelected: hostSetSelected, panels: panelIds, setPanel: hostSetPanel, scales: hostScales, setScale: hostSetScale, setLook: hostSetLook, setSwitch: hostSetSwitch, traceSkyFigure: hostTraceSkyFigure, clearSkyTrace: hostClearSkyTrace, groups: groupIds, groupLook: hostGroupLook, setGroupLook: hostSetGroupLook });
|
|
537
547
|
return () => { hostAttached.current = false; host.detach(); };
|
|
538
|
-
}, [host, runtime, definition, hostSeekTo, changeRate, viewIds, chooseView, cameraTargets, readCamera, setCamera, hostSetSelected, panelIds, hostSetPanel, experience, hostSetPlaying, hostScales, hostSetScale, hostSetLook, hostSetSwitch, hostTraceSkyFigure, hostClearSkyTrace]);
|
|
548
|
+
}, [host, runtime, definition, hostSeekTo, changeRate, viewIds, chooseView, cameraTargets, readCamera, setCamera, hostSetSelected, panelIds, hostSetPanel, experience, hostSetPlaying, hostScales, hostSetScale, hostSetLook, hostSetSwitch, hostTraceSkyFigure, hostClearSkyTrace, groupLooks, groupIds, hostGroupLook, hostSetGroupLook]);
|
|
539
549
|
useEffect(() => {
|
|
540
550
|
if (!developerMode)
|
|
541
551
|
return undefined;
|
|
@@ -20,6 +20,7 @@ import type { GroupFill } from "./FrameRateSection.js";
|
|
|
20
20
|
import { type BodySetLayer, type BodySetLook } from "./bodySet.js";
|
|
21
21
|
import type { LabelStyle } from "./labelStyle.js";
|
|
22
22
|
import type { TimeLook } from "./timeLook.js";
|
|
23
|
+
import type { GroupDotLook } from "./PointsView.js";
|
|
23
24
|
import type { SkyColours, SkyClearRequest, SkyFigureLayer, SkyLineSwitches, SkyTraceRequest } from "./skyFigures.js";
|
|
24
25
|
import type { RingLook } from "../assets/rings.js";
|
|
25
26
|
import type { Pictures } from "../assets/pictures.js";
|
|
@@ -93,6 +94,8 @@ export interface SceneControls {
|
|
|
93
94
|
skyColours: SkyColours;
|
|
94
95
|
/** Traces the host asked for, not yet started: the frame's `advanceSkyTraces` stage takes them in call order (the host link pushes, the frame empties it). */
|
|
95
96
|
skyTraces: (SkyTraceRequest | SkyClearRequest)[];
|
|
97
|
+
/** Presentation only: the colour and dot size per point group id the host set (`setGroupLook`), over the group's own; the frame applies them to the dots and the group's label. Absent, or an id not in it: the group's own. */
|
|
98
|
+
groupLooks?: Map<string, GroupDotLook>;
|
|
96
99
|
/** Presentation only: how long sky lines and their names fade in when they appear, in seconds (the look `skyFadeInSeconds`; live). */
|
|
97
100
|
skyFadeInSeconds: number;
|
|
98
101
|
/** Presentation only: the label font and size (the look `labels`; live). The viewer root carries it to every label as CSS variables. */
|
package/src/app/PointsView.d.ts
CHANGED
|
@@ -5,6 +5,13 @@ import type { FloatingOrigin } from "./floatingOrigin.js";
|
|
|
5
5
|
import { type RenderVector } from "./renderCoordinates.js";
|
|
6
6
|
import { type ScenePlacement } from "./sceneLayout.js";
|
|
7
7
|
export declare const DEFAULT_REFILL_AFTER_MS = 300000;
|
|
8
|
+
/** A group's dot size in screen pixels when its layer gives none. */
|
|
9
|
+
export declare const DEFAULT_POINT_SIZE_PX = 2.5;
|
|
10
|
+
/** A group's dot colour and size as drawn (presentation only). */
|
|
11
|
+
export interface GroupDotLook {
|
|
12
|
+
readonly color: string;
|
|
13
|
+
readonly dotSizePx: number;
|
|
14
|
+
}
|
|
8
15
|
/**
|
|
9
16
|
* Milliseconds of each frame the points layer may spend computing the next fill ahead of time (see `refillSliceMs`).
|
|
10
17
|
* About 8 ms leaves most of a 30 fps frame for drawing; 0 turns the look-ahead off and every fill happens in one frame.
|
|
@@ -70,6 +77,13 @@ export declare class PointsView {
|
|
|
70
77
|
/** Number of batch fills so far; lets tests and diagnostics see that no fill happens outside bounds. */
|
|
71
78
|
fillCount: number;
|
|
72
79
|
constructor(layer: GroupLayer, now?: () => number);
|
|
80
|
+
/** The dot colour and size in force: the layer's own until `setLook` changes them. */
|
|
81
|
+
get look(): GroupDotLook;
|
|
82
|
+
/**
|
|
83
|
+
* Gives the dots a new colour and size on both ways of drawing (the blend material and, when present, the shader-placed one), so a later switch
|
|
84
|
+
* between them keeps it. Only material values change: no geometry, fill or shader rebuild, and the dots stay where they are. Returns whether anything changed.
|
|
85
|
+
*/
|
|
86
|
+
setLook(look: GroupDotLook): boolean;
|
|
73
87
|
/** Whether the graphics chip places the dots at the last `sync`, rather than the blend of exact fills. */
|
|
74
88
|
get placedByShader(): boolean;
|
|
75
89
|
/** How many times the shader's phase epoch has been moved; 0 when the dots are not placed by the shader. */
|
package/src/app/PointsView.js
CHANGED
|
@@ -8,7 +8,8 @@ import { TRACK_LAYER } from "./TrackedBodyView.js";
|
|
|
8
8
|
// Measured in T-030 for 10^4 members: a 5-minute span blends to within about 8 km of the exact position on a ring 26,000 km
|
|
9
9
|
// across, and costs one ~12 ms slide per span; shorter spans slide more often, longer ones drift further from exact.
|
|
10
10
|
export const DEFAULT_REFILL_AFTER_MS = 300_000;
|
|
11
|
-
|
|
11
|
+
/** A group's dot size in screen pixels when its layer gives none. */
|
|
12
|
+
export const DEFAULT_POINT_SIZE_PX = 2.5;
|
|
12
13
|
/**
|
|
13
14
|
* Milliseconds of each frame the points layer may spend computing the next fill ahead of time (see `refillSliceMs`).
|
|
14
15
|
* About 8 ms leaves most of a 30 fps frame for drawing; 0 turns the look-ahead off and every fill happens in one frame.
|
|
@@ -84,6 +85,7 @@ export class PointsView {
|
|
|
84
85
|
#holdKm = null;
|
|
85
86
|
#mappedFor = "";
|
|
86
87
|
#drawn = false;
|
|
88
|
+
#look;
|
|
87
89
|
constructor(layer, now = () => performance.now()) {
|
|
88
90
|
this.layer = layer;
|
|
89
91
|
const count = layer.group.count;
|
|
@@ -98,14 +100,15 @@ export class PointsView {
|
|
|
98
100
|
}
|
|
99
101
|
this.#before = this.#emptyFill();
|
|
100
102
|
this.#after = this.#emptyFill();
|
|
103
|
+
this.#look = { color: layer.color, dotSizePx: layer.pointSizePx ?? DEFAULT_POINT_SIZE_PX };
|
|
101
104
|
const geometry = new BufferGeometry();
|
|
102
105
|
this.#from = new BufferAttribute(new Float32Array(3 * count), 3);
|
|
103
106
|
this.#to = new BufferAttribute(new Float32Array(3 * count), 3);
|
|
104
107
|
geometry.setAttribute("position", this.#from);
|
|
105
108
|
geometry.setAttribute("positionTo", this.#to);
|
|
106
109
|
this.#material = dotMaterial({
|
|
107
|
-
color:
|
|
108
|
-
size:
|
|
110
|
+
color: this.#look.color,
|
|
111
|
+
size: this.#look.dotSizePx,
|
|
109
112
|
sizeAttenuation: false,
|
|
110
113
|
transparent: true,
|
|
111
114
|
opacity: 0.9,
|
|
@@ -119,10 +122,28 @@ export class PointsView {
|
|
|
119
122
|
this.#points.visible = false;
|
|
120
123
|
this.group.add(this.#points);
|
|
121
124
|
const elements = count > SLICE_CHUNK_MEMBERS ? layer.group.keplerElements?.() : undefined;
|
|
122
|
-
this.#kepler = elements === undefined ? null : new KeplerPoints(elements,
|
|
125
|
+
this.#kepler = elements === undefined ? null : new KeplerPoints(elements, this.#look.color, this.#look.dotSizePx);
|
|
123
126
|
if (this.#kepler !== null)
|
|
124
127
|
this.group.add(this.#kepler.points);
|
|
125
128
|
}
|
|
129
|
+
/** The dot colour and size in force: the layer's own until `setLook` changes them. */
|
|
130
|
+
get look() {
|
|
131
|
+
return this.#look;
|
|
132
|
+
}
|
|
133
|
+
/**
|
|
134
|
+
* Gives the dots a new colour and size on both ways of drawing (the blend material and, when present, the shader-placed one), so a later switch
|
|
135
|
+
* between them keeps it. Only material values change: no geometry, fill or shader rebuild, and the dots stay where they are. Returns whether anything changed.
|
|
136
|
+
*/
|
|
137
|
+
setLook(look) {
|
|
138
|
+
if (look.color === this.#look.color && look.dotSizePx === this.#look.dotSizePx)
|
|
139
|
+
return false;
|
|
140
|
+
this.#look = { color: look.color, dotSizePx: look.dotSizePx };
|
|
141
|
+
for (const material of this.#kepler === null ? [this.#material] : [this.#material, this.#kepler.material]) {
|
|
142
|
+
material.color.set(look.color);
|
|
143
|
+
material.size = look.dotSizePx;
|
|
144
|
+
}
|
|
145
|
+
return true;
|
|
146
|
+
}
|
|
126
147
|
/** Whether the graphics chip places the dots at the last `sync`, rather than the blend of exact fills. */
|
|
127
148
|
get placedByShader() {
|
|
128
149
|
return this.#gpu;
|
package/src/app/SceneLabels.d.ts
CHANGED
|
@@ -40,6 +40,8 @@ export interface SkyLabelFrame {
|
|
|
40
40
|
export declare class SceneLabelLayer {
|
|
41
41
|
#private;
|
|
42
42
|
constructor(host: HTMLElement, objects: readonly ExperienceObject[], skyLabels?: readonly SkyLabelSpec[]);
|
|
43
|
+
/** Gives the object label `id` the colour `colour` (a group's live colour, `setGroupLook`); an id with no object label, or the colour it already has, changes nothing. */
|
|
44
|
+
setColor(id: string, colour: string): void;
|
|
43
45
|
/** The page rectangles of the labels shown after the latest update, by object id: the targets a tap on a name can hit. */
|
|
44
46
|
get shownRects(): ReadonlyMap<string, Rect>;
|
|
45
47
|
/** Brightens the name of the hovered object by `gain` (1 leaves it alone); null clears it. */
|
package/src/app/SceneLabels.js
CHANGED
|
@@ -19,6 +19,7 @@ const skyOpacity = (spec, sky) => (spec === undefined ? 1 : sky?.opacity?.(spec.
|
|
|
19
19
|
export class SceneLabelLayer {
|
|
20
20
|
#root = document.createElement("div");
|
|
21
21
|
#entries;
|
|
22
|
+
#byId;
|
|
22
23
|
#local = new Vector3();
|
|
23
24
|
#direction = new Vector3();
|
|
24
25
|
#shown = new Map();
|
|
@@ -45,8 +46,16 @@ export class SceneLabelLayer {
|
|
|
45
46
|
this.#root.appendChild(element);
|
|
46
47
|
return { object, element };
|
|
47
48
|
});
|
|
49
|
+
this.#byId = new Map(this.#entries.map((entry) => [entry.object.id, entry]));
|
|
48
50
|
host.appendChild(this.#root);
|
|
49
51
|
}
|
|
52
|
+
/** Gives the object label `id` the colour `colour` (a group's live colour, `setGroupLook`); an id with no object label, or the colour it already has, changes nothing. */
|
|
53
|
+
setColor(id, colour) {
|
|
54
|
+
const entry = this.#byId.get(id);
|
|
55
|
+
if (entry === undefined || this.#sky.has(id) || entry.element.style.getPropertyValue("--label-color") === colour)
|
|
56
|
+
return;
|
|
57
|
+
entry.element.style.setProperty("--label-color", colour);
|
|
58
|
+
}
|
|
50
59
|
/** The page rectangles of the labels shown after the latest update, by object id: the targets a tap on a name can hit. */
|
|
51
60
|
get shownRects() {
|
|
52
61
|
return this.#shown;
|
package/src/app/sceneFrame.d.ts
CHANGED
|
@@ -150,6 +150,8 @@ export declare function publishCanvasReadouts(ctx: FrameContext): void;
|
|
|
150
150
|
export declare function placeSkyFigures(ctx: FrameContext): void;
|
|
151
151
|
/** Stage 4c: starts the traces and removes the ones the host asked for since the last frame (in call order) and moves every trace on by this frame's real time; a moving trace wakes the draw rule. Wall time only (CODE-02, ARCH-02). */
|
|
152
152
|
export declare function advanceSkyTraces(ctx: FrameContext): void;
|
|
153
|
+
/** Stage 5a: gives each point group the colour and dot size the host set (`setGroupLook`) and its label the colour; a change wakes the draw rule, so a paused viewer draws it. Presentation only (ARCH-02): no fill, geometry or State is touched. */
|
|
154
|
+
export declare function applyGroupLooks(ctx: Pick<FrameContext, "controls" | "views" | "state" | "layers">): void;
|
|
153
155
|
/** Stage 5: places every view about the floating origin and publishes the views' readouts. Returns the hover brightness gain. */
|
|
154
156
|
export declare function placeViews(ctx: FrameContext, t: number, placed: PlacedScene, setLook: BodySetLook): number;
|
|
155
157
|
/** What this frame hides: the view's hidden ids, the objects not shown at clock time `t` (`shownDuring`; none when `t` is not given), and the body the camera stands inside while looking out (the one hidden-set path, read by the visibility, label and tap stages). */
|
package/src/app/sceneFrame.js
CHANGED
|
@@ -172,12 +172,28 @@ export function advanceSkyTraces(ctx) {
|
|
|
172
172
|
if (views.skyFiguresView.advanceFadeIn(delta, prefersReducedMotion() ? 0 : controls.skyFadeInSeconds, controls.skyLines))
|
|
173
173
|
state.wakes += 1;
|
|
174
174
|
}
|
|
175
|
+
/** Stage 5a: gives each point group the colour and dot size the host set (`setGroupLook`) and its label the colour; a change wakes the draw rule, so a paused viewer draws it. Presentation only (ARCH-02): no fill, geometry or State is touched. */
|
|
176
|
+
export function applyGroupLooks(ctx) {
|
|
177
|
+
const looks = ctx.controls.groupLooks;
|
|
178
|
+
if (looks === undefined || looks.size === 0)
|
|
179
|
+
return;
|
|
180
|
+
for (const view of ctx.views.groupViews) {
|
|
181
|
+
const look = looks.get(view.id);
|
|
182
|
+
if (look !== undefined && view.setLook(look))
|
|
183
|
+
ctx.state.wakes += 1;
|
|
184
|
+
}
|
|
185
|
+
const labels = ctx.layers.sceneLabels.current;
|
|
186
|
+
if (labels !== null)
|
|
187
|
+
for (const [id, look] of looks)
|
|
188
|
+
labels.setColor(id, look.color);
|
|
189
|
+
}
|
|
175
190
|
/** Stage 5: places every view about the floating origin and publishes the views' readouts. Returns the hover brightness gain. */
|
|
176
191
|
export function placeViews(ctx, t, placed, setLook) {
|
|
177
192
|
const { controls, camera, canvas, size, views, origin } = ctx;
|
|
178
193
|
const policy = controls.policy;
|
|
179
194
|
for (const view of views.trackedViews)
|
|
180
195
|
view.update(t, policy, origin, camera, ctx.placement);
|
|
196
|
+
applyGroupLooks(ctx);
|
|
181
197
|
for (const view of views.groupViews)
|
|
182
198
|
view.place(origin);
|
|
183
199
|
for (const view of views.sunCentredViews)
|
package/src/app/viewerPort.d.ts
CHANGED
|
@@ -76,6 +76,18 @@ export interface ViewerControl {
|
|
|
76
76
|
traceSkyFigure(id: string, seconds: number, after: SkyTraceAfter): void;
|
|
77
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
78
|
clearSkyTrace(id: string, seconds: number): void;
|
|
79
|
+
/** The ids of the point groups the scene added (`addGroup`), in order; empty when it added none. */
|
|
80
|
+
readonly groups?: readonly string[];
|
|
81
|
+
/** The colour and dot size the point group `id` (one added with `addGroup`) is drawn with now: the host's last `setGroupLook`, else the group's own; undefined for an id that is not a group. */
|
|
82
|
+
groupLook?(id: string): {
|
|
83
|
+
readonly color: string;
|
|
84
|
+
readonly dotSizePx: number;
|
|
85
|
+
} | undefined;
|
|
86
|
+
/** Gives the point group `id` (already checked) this colour and dot size, both filled in; `groupLook` reads it at once and the dots and the group's label take it at the next frame. */
|
|
87
|
+
setGroupLook?(id: string, look: {
|
|
88
|
+
readonly color: string;
|
|
89
|
+
readonly dotSizePx: number;
|
|
90
|
+
}): void;
|
|
79
91
|
/** The host's picker (`Scene.setPicker`): its id, the option values and the one pressed at the start; absent without a picker. */
|
|
80
92
|
readonly picker?: {
|
|
81
93
|
readonly id: string;
|
|
@@ -12,12 +12,17 @@ export interface ListedElements {
|
|
|
12
12
|
readonly raanDeg: number;
|
|
13
13
|
readonly argumentOfPeriapsisDeg: number;
|
|
14
14
|
}
|
|
15
|
-
/** One record of a measured list: its own source id, the time its elements were measured, and the
|
|
15
|
+
/** One record of a measured list: its own source id, the time its elements were measured, the elements, and optionally its position along the orbit. */
|
|
16
16
|
export interface ListedMember {
|
|
17
17
|
readonly recordId: string;
|
|
18
|
-
/** The record's own time.
|
|
18
|
+
/** The record's own time (its epoch). With `meanAnomalyDeg` it fixes where the dot is; without, it is kept with the record and does not place the dot (see ListedPhase). */
|
|
19
19
|
readonly epochUtcMs: number;
|
|
20
20
|
readonly elements: ListedElements;
|
|
21
|
+
/**
|
|
22
|
+
* The record's mean anomaly in degrees at `epochUtcMs`; finite, any value (it wraps to 0 to 360). All members give it or none do:
|
|
23
|
+
* with it the group is measured-phase (each dot at its record's position, advanced by two-body motion); without it the phase is a drawing choice.
|
|
24
|
+
*/
|
|
25
|
+
readonly meanAnomalyDeg?: number;
|
|
21
26
|
}
|
|
22
27
|
/** A stated share of the members drawn near a reference body's position along its orbit. A model, not a measurement. */
|
|
23
28
|
export interface ListedConcentration {
|
|
@@ -29,10 +34,14 @@ export interface ListedConcentration {
|
|
|
29
34
|
readonly widthDeg: number;
|
|
30
35
|
}
|
|
31
36
|
export interface ListedPhase {
|
|
32
|
-
/**
|
|
37
|
+
/**
|
|
38
|
+
* The instant from which members move by two-body motion. For an illustrative group, each member's mean anomaly here is the drawing choice below;
|
|
39
|
+
* for a measured-phase group (every member gives `meanAnomalyDeg`), it is the record's mean anomaly advanced from its epoch to this instant.
|
|
40
|
+
*/
|
|
33
41
|
readonly referenceUtcMs: number;
|
|
34
|
-
/** Unsigned 32-bit integer picking which member takes which slot; defaults to 0. */
|
|
42
|
+
/** Unsigned 32-bit integer picking which member takes which slot; defaults to 0. Illustrative groups only: a measured-phase group with a seed throws. */
|
|
35
43
|
readonly seed?: number;
|
|
44
|
+
/** Illustrative groups only: a measured-phase group with a concentration throws. */
|
|
36
45
|
readonly concentration?: ListedConcentration;
|
|
37
46
|
}
|
|
38
47
|
export interface ListedOrbitGroupInput {
|
|
@@ -43,13 +52,13 @@ export interface ListedOrbitGroupInput {
|
|
|
43
52
|
readonly members: readonly ListedMember[];
|
|
44
53
|
readonly phase: ListedPhase;
|
|
45
54
|
readonly bounds?: TimeBounds;
|
|
46
|
-
/** Where the elements came from.
|
|
55
|
+
/** Where the elements came from. An illustrative group restates the position along each orbit as illustrative; a measured-phase group keeps this `sourceType`. */
|
|
47
56
|
readonly provenance: Provenance;
|
|
48
57
|
}
|
|
49
58
|
export interface ListedOrbitGroup extends PointGroup {
|
|
50
59
|
/** The source record id of member `index`; also the suffix of that member's State body id. */
|
|
51
60
|
recordIdAt(index: number): string;
|
|
52
|
-
/** Member `index`'s mean anomaly (degrees, 0 to 360) at the reference time: the drawing choice. */
|
|
61
|
+
/** Member `index`'s mean anomaly (degrees, 0 to 360) at the reference time: the record's own, advanced from its epoch, for a measured-phase group; the drawing choice otherwise. */
|
|
53
62
|
meanAnomalyDegAt(index: number): number;
|
|
54
63
|
}
|
|
55
64
|
/** Solves Kepler's equation M = E - e sin E for E (Newton; bound orbits only). */
|
|
@@ -57,10 +66,15 @@ export declare function eccentricAnomalyRad(meanAnomalyRad: number, e: number):
|
|
|
57
66
|
export declare function trueAnomalyFromMeanRad(meanAnomalyRad: number, e: number): number;
|
|
58
67
|
/** Mean anomaly (radians, 0 to 2π) of a body with the given position and velocity about a centre of gravitational parameter `mu`. */
|
|
59
68
|
export declare function meanAnomalyFromStateRad(r: ArrayLike<number>, v: ArrayLike<number>, mu: number): number;
|
|
60
|
-
/** The provenance a group's own card carries: always illustrative, since the position along each orbit is a drawing choice; the source's type stays in the accuracy line. */
|
|
61
|
-
export declare function listedGroupProvenance(source: Provenance, concentrated: boolean): Provenance;
|
|
62
69
|
/**
|
|
63
|
-
*
|
|
64
|
-
*
|
|
70
|
+
* The provenance a group's own card carries. Illustrative (the default): `sourceType` "illustrative", since the position along each orbit is a drawing
|
|
71
|
+
* choice; the source's type stays in the accuracy line. Measured-phase: the source's `sourceType`, `sources` and `accuracy` as given, with a note that
|
|
72
|
+
* each position comes from its record's mean anomaly.
|
|
73
|
+
*/
|
|
74
|
+
export declare function listedGroupProvenance(source: Provenance, concentrated: boolean, measured?: boolean): Provenance;
|
|
75
|
+
/**
|
|
76
|
+
* A group drawn from a list of measured orbits: each member has its own elements, record time and source record id. The position along
|
|
77
|
+
* each orbit is the record's own when every member gives `meanAnomalyDeg` (measured-phase), else chosen here (see ListedPhase); every
|
|
78
|
+
* member then moves on its own ellipse by two-body motion.
|
|
65
79
|
*/
|
|
66
80
|
export declare function createListedOrbitGroup(input: ListedOrbitGroupInput, adapter: TwoBodyAdapter): ListedOrbitGroup;
|
|
@@ -11,10 +11,14 @@ const VELOCITY_STEP_MS = 1000;
|
|
|
11
11
|
function describe(member, index) {
|
|
12
12
|
return `member ${index} (record "${String(member.recordId)}")`;
|
|
13
13
|
}
|
|
14
|
-
/**
|
|
14
|
+
/**
|
|
15
|
+
* The rejection rule: a record must give a finite, bound orbit; unbound records are for the loader to drop. Mean anomalies are all or none.
|
|
16
|
+
* Returns whether the group is measured-phase (every member gives `meanAnomalyDeg`).
|
|
17
|
+
*/
|
|
15
18
|
function assertMembers(members) {
|
|
16
19
|
if (members.length === 0)
|
|
17
20
|
throw new GroupCountError("a listed group needs at least one member; the list is empty");
|
|
21
|
+
const measured = members[0]?.meanAnomalyDeg !== undefined;
|
|
18
22
|
const seen = new Set();
|
|
19
23
|
members.forEach((member, index) => {
|
|
20
24
|
const who = describe(member, index);
|
|
@@ -43,10 +47,22 @@ function assertMembers(members) {
|
|
|
43
47
|
if (!(e.inclinationDeg >= 0 && e.inclinationDeg <= 180)) {
|
|
44
48
|
throw new GroupElementsError(`${who}: inclinationDeg must be from 0 to 180, got ${e.inclinationDeg}`);
|
|
45
49
|
}
|
|
50
|
+
const m = member.meanAnomalyDeg;
|
|
51
|
+
if (m !== undefined && !(typeof m === "number" && Number.isFinite(m)))
|
|
52
|
+
throw new GroupElementsError(`${who}: meanAnomalyDeg must be finite, got ${String(m)}`);
|
|
53
|
+
if ((m !== undefined) !== measured) {
|
|
54
|
+
const missing = measured ? who : describe(members[0], 0);
|
|
55
|
+
throw new GroupElementsError(`${missing} gives no meanAnomalyDeg: give it for every member (measured positions) or for none (illustrative positions)`);
|
|
56
|
+
}
|
|
46
57
|
});
|
|
58
|
+
return measured;
|
|
47
59
|
}
|
|
48
|
-
function assertPhase(phase) {
|
|
60
|
+
function assertPhase(phase, measured) {
|
|
49
61
|
assertUtcUnixMs(phase.referenceUtcMs);
|
|
62
|
+
if (measured && phase.seed !== undefined)
|
|
63
|
+
throw new GroupElementsError("a seed only shuffles illustrative positions; the members give meanAnomalyDeg, so their positions are measured: drop the seed");
|
|
64
|
+
if (measured && phase.concentration !== undefined)
|
|
65
|
+
throw new GroupElementsError("a concentration only shapes illustrative positions; the members give meanAnomalyDeg, so their positions are measured: drop the concentration");
|
|
50
66
|
const seed = phase.seed ?? 0;
|
|
51
67
|
if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff)
|
|
52
68
|
throw new GroupElementsError("phase seed must be an unsigned 32-bit integer");
|
|
@@ -144,11 +160,40 @@ function assignMeanAnomaliesDeg(count, phase, referenceDeg) {
|
|
|
144
160
|
}
|
|
145
161
|
return result;
|
|
146
162
|
}
|
|
163
|
+
/**
|
|
164
|
+
* Mean anomalies in degrees (0 to 360) at the reference time, one per member, from each record's own mean anomaly at its epoch:
|
|
165
|
+
* M = M_epoch + n·Δt with n = √(μ / a³), the same μ the group propagates with, so placement and later motion agree.
|
|
166
|
+
*/
|
|
167
|
+
function measuredMeanAnomaliesDeg(members, referenceUtcMs, mu) {
|
|
168
|
+
const result = new Float64Array(members.length);
|
|
169
|
+
for (let i = 0; i < members.length; i++) {
|
|
170
|
+
const member = members[i];
|
|
171
|
+
const a = member.elements.semiMajorAxisKm;
|
|
172
|
+
const epochDeg = ((member.meanAnomalyDeg % 360) + 360) % 360;
|
|
173
|
+
const m = epochDeg * RADIANS + Math.sqrt(mu / (a * a * a)) * ((referenceUtcMs - member.epochUtcMs) / 1000);
|
|
174
|
+
const wrapped = ((m % TWO_PI) + TWO_PI) % TWO_PI;
|
|
175
|
+
result[i] = wrapped / RADIANS;
|
|
176
|
+
}
|
|
177
|
+
return result;
|
|
178
|
+
}
|
|
147
179
|
const PHASE_NOTE = "Each orbit's shape and orientation come from its record, but the records give no position along the orbit: "
|
|
148
180
|
+ "that position is an even spread of mean anomaly at the reference time, a drawing choice (illustrative), advanced by unperturbed two-body motion about the centre.";
|
|
181
|
+
const MEASURED_PHASE_NOTE = "Each dot's position along its orbit comes from its record's mean anomaly at the record's epoch, advanced by unperturbed two-body motion about the centre.";
|
|
149
182
|
const CONCENTRATION_NOTE = "A stated share of the dots is placed near the reference body's position along the orbit: a model, not a measurement. No orbit is added.";
|
|
150
|
-
/**
|
|
151
|
-
|
|
183
|
+
/**
|
|
184
|
+
* The provenance a group's own card carries. Illustrative (the default): `sourceType` "illustrative", since the position along each orbit is a drawing
|
|
185
|
+
* choice; the source's type stays in the accuracy line. Measured-phase: the source's `sourceType`, `sources` and `accuracy` as given, with a note that
|
|
186
|
+
* each position comes from its record's mean anomaly.
|
|
187
|
+
*/
|
|
188
|
+
export function listedGroupProvenance(source, concentrated, measured = false) {
|
|
189
|
+
if (measured) {
|
|
190
|
+
return createProvenance({
|
|
191
|
+
sourceType: source.sourceType,
|
|
192
|
+
sources: source.sources,
|
|
193
|
+
accuracy: source.accuracy,
|
|
194
|
+
notes: `${source.notes} ${MEASURED_PHASE_NOTE}`.trim(),
|
|
195
|
+
});
|
|
196
|
+
}
|
|
152
197
|
return createProvenance({
|
|
153
198
|
sourceType: "illustrative",
|
|
154
199
|
sources: source.sources,
|
|
@@ -157,20 +202,27 @@ export function listedGroupProvenance(source, concentrated) {
|
|
|
157
202
|
});
|
|
158
203
|
}
|
|
159
204
|
/**
|
|
160
|
-
* A group drawn from a list of measured orbits: each member has its own elements, record time and source record id.
|
|
161
|
-
*
|
|
205
|
+
* A group drawn from a list of measured orbits: each member has its own elements, record time and source record id. The position along
|
|
206
|
+
* each orbit is the record's own when every member gives `meanAnomalyDeg` (measured-phase), else chosen here (see ListedPhase); every
|
|
207
|
+
* member then moves on its own ellipse by two-body motion.
|
|
162
208
|
*/
|
|
163
209
|
export function createListedOrbitGroup(input, adapter) {
|
|
164
|
-
assertMembers(input.members);
|
|
165
|
-
assertPhase(input.phase);
|
|
210
|
+
const measured = assertMembers(input.members);
|
|
211
|
+
assertPhase(input.phase, measured);
|
|
166
212
|
const count = input.members.length;
|
|
167
213
|
assertGroupCount(count);
|
|
168
214
|
const { center, bounds } = input;
|
|
169
215
|
const { referenceUtcMs, concentration } = input.phase;
|
|
170
|
-
|
|
171
|
-
|
|
172
|
-
|
|
173
|
-
|
|
216
|
+
let anomaliesDeg;
|
|
217
|
+
if (measured) {
|
|
218
|
+
anomaliesDeg = measuredMeanAnomaliesDeg(input.members, referenceUtcMs, gravitationalParameterOf(adapter, center));
|
|
219
|
+
}
|
|
220
|
+
else {
|
|
221
|
+
const referenceDeg = concentration === undefined
|
|
222
|
+
? null
|
|
223
|
+
: referenceMeanAnomalyRad(concentration.around, center, referenceUtcMs, adapter) / RADIANS;
|
|
224
|
+
anomaliesDeg = assignMeanAnomaliesDeg(count, input.phase, referenceDeg);
|
|
225
|
+
}
|
|
174
226
|
const states = memberStatesOf(input.members.map(({ elements }, member) => ({
|
|
175
227
|
semiMajorAxisKm: elements.semiMajorAxisKm,
|
|
176
228
|
eccentricity: elements.eccentricity,
|
|
@@ -180,7 +232,7 @@ export function createListedOrbitGroup(input, adapter) {
|
|
|
180
232
|
trueAnomalyRad: trueAnomalyFromMeanRad(anomaliesDeg[member] * RADIANS, elements.eccentricity),
|
|
181
233
|
})), input.plane, center, adapter);
|
|
182
234
|
const recordIds = input.members.map((member) => member.recordId);
|
|
183
|
-
const provenance = listedGroupProvenance(input.provenance, concentration !== undefined);
|
|
235
|
+
const provenance = listedGroupProvenance(input.provenance, concentration !== undefined, measured);
|
|
184
236
|
let kepler = null;
|
|
185
237
|
const group = {
|
|
186
238
|
id: input.id,
|