astraeus 0.3.0 → 0.4.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +16 -0
- package/README.md +32 -5
- package/package.json +1 -1
- package/src/api/activity.d.ts +1 -1
- package/src/api/activity.js +1 -1
- package/src/api/bodies.d.ts +2 -0
- package/src/api/bodies.js +2 -0
- package/src/api/index.d.ts +1 -1
- package/src/api/index.js +1 -1
- package/src/api/index.node.js +1 -1
- package/src/api/scene.d.ts +19 -4
- package/src/api/scene.js +95 -31
- package/src/app/SceneLabels.d.ts +2 -0
- package/src/app/SceneLabels.js +5 -1
- package/src/app/TrackedBodyView.d.ts +9 -3
- package/src/app/TrackedBodyView.js +52 -13
- package/src/app/mission.d.ts +2 -0
- package/src/app/pathRules.d.ts +7 -3
- package/src/app/pathRules.js +9 -5
- package/src/app/sceneDebug.d.ts +4 -2
- package/src/app/sceneFrame.js +1 -1
- package/src/core/scalePolicy.d.ts +2 -0
- package/src/core/scalePolicy.js +2 -0
- package/src/synthetic/syntheticProbeDefinition.d.ts +5 -0
- package/src/synthetic/syntheticProbeDefinition.js +38 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,22 @@
|
|
|
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.4.0 (2026-10-31)
|
|
6
|
+
|
|
7
|
+
First download of the packed example (`npm run measure:example`): 1,594,919 bytes raw, 453,695 bytes gzip (code and styles loaded on first open).
|
|
8
|
+
|
|
9
|
+
A recorded path can now cross the solar system (O-046, G-013), from findings sent back by an outside Voyager app built on 0.3.0.
|
|
10
|
+
|
|
11
|
+
- `addTrajectory` says which frame its positions use (I-097): equatorial J2000 (EQJ) about `center`, as before. A new `plane: "ecliptic-j2000"` option takes ecliptic vectors as JPL Horizons publishes them and rotates them to EQJ once on the way in (samples and provider states), so drawing, `stateOf` and readouts agree. A bad `plane` throws `bad-trajectory`.
|
|
12
|
+
- A path can cross the solar system (O-046). `addTrajectory` is now accepted in a Sun-centred scene (it threw `bad-trajectory`), and a new `lineFixedTo` option names the body the path's line is drawn against at each sample's own time (default the scene centre; `"sun"` for a probe). A `lineFixedTo` body the finished scene does not hold throws `bad-trajectory`. Paths in Earth-centred scenes draw as before.
|
|
13
|
+
- Behaviour change (O-046): `addTrajectory`'s `center` now defaults to the scene's centre (its first body) instead of always `"earth"`. Scenes whose first body is Earth (Apollo 11, the hello example) are unchanged; a scene whose first body is neither Earth nor the Sun now reads its paths' positions from that body, so add `center: "earth"` to keep the old reading. A path added before any body follows the first body added; with no catalogued first body the default stays Earth. Found when a made-up probe given from the Sun missed Earth by a wide margin in a Sun-first scene.
|
|
14
|
+
- `solarSystemScale` is exported beside `trueScale` and `readableScale`, and `setScale` accepts it (I-098), so a Sun-centred scene with an enlarged body can open on the Solar system view. In any other scene `toDefinition` throws `bad-scale`.
|
|
15
|
+
- Example and check (O-046 T-193): the README shows a made-up Sun-centred probe path ("A probe across the solar system"); the repository's dev site opens a fuller made-up one at `?experience=synthetic-probe` (not in public builds). A provider path's `orientation` is not rotated by `plane` (documented limit).
|
|
16
|
+
- A path's own name shows (I-100). Its label was limited to 4 scaled units from the camera, so it never showed at a normal view; it now has the same reach as a body's label (none in a Sun-centred or fitted scene, otherwise the camera reach, at least 500) and follows the `labels` switch. In Earth-centred scenes a path's label now shows as far out as a body's; give it `labelReach` to keep a shorter reach (Apollo 11 keeps 4).
|
|
17
|
+
- New `labelReach` option on `addBody` and `addTrajectory`: a positive number (the camera's `distance` units) that limits how far from the camera that label shows, replacing the shared rule for that item; a bad value throws `bad-body` / `bad-trajectory`. Apollo 11 sets `labelReach: 4` on its paths so they behave as before.
|
|
18
|
+
- Wording only (O-046): the `addActivity` error for a missing unit now suggests `"events per hour"` instead of `"meteors per hour"` (the engine names no shower, ARCH-06); the doc comment's example changed the same way.
|
|
19
|
+
- Labels (I-108): as before, the label of the selected object (the one `camera.follow` or `camera.lookAt` opens on) always wins a collision with another label, so follow a path to keep its name shown on a small screen; other labels keep their priority order (bodies before paths). A scene's labels also stay hidden until the first layout places them, so none shows unplaced for a moment after load.
|
|
20
|
+
|
|
5
21
|
## 0.3.0 (2026-10-29)
|
|
6
22
|
|
|
7
23
|
First download of the packed example (`npm run measure:example`): 1,592,336 bytes raw, 453,513 bytes gzip (code and styles loaded on first open).
|
package/README.md
CHANGED
|
@@ -42,6 +42,33 @@ mount(document.getElementById("app"), scene);
|
|
|
42
42
|
|
|
43
43
|
The element needs a size (for example `height: 100%` all the way up). The probe's circle and the Moon's own orbit (tilted to it, because the circle lies in the reference frame's x-y plane) are both drawn. The finished app, grown into a small made-up story with every call below, is in the repository at `examples/hello-scene`.
|
|
44
44
|
|
|
45
|
+
### A probe across the solar system
|
|
46
|
+
|
|
47
|
+
A recorded path can cross the solar system beside enlarged planets. This one is made up (an invented straight line that starts 0.6 AU from the Sun, inside Earth's orbit, and ends about 1.49 AU out, given in ecliptic axes; it is not aimed at any planet); the same calls take positions you downloaded from JPL Horizons.
|
|
48
|
+
|
|
49
|
+
```js
|
|
50
|
+
import { Scene, earth, mars, mount, solarSystemScale, sun } from "astraeus";
|
|
51
|
+
|
|
52
|
+
const start = Date.parse("2026-01-01T00:00:00Z");
|
|
53
|
+
const DAY = 86_400_000;
|
|
54
|
+
const AU = 149_597_870.7;
|
|
55
|
+
// Ecliptic J2000 positions from the Sun, in km: a straight line from 0.6 AU to about 1.49 AU from the Sun over 200 days (x runs 0.6 to 1.1 AU, y 0 to 1.0 AU).
|
|
56
|
+
const samples = Array.from({ length: 11 }, (_, i) => ({ time: start + i * 20 * DAY, positionKm: [AU * (0.6 + 0.05 * i), AU * 0.1 * i, 0] }));
|
|
57
|
+
|
|
58
|
+
const scene = new Scene()
|
|
59
|
+
.addBody(sun)
|
|
60
|
+
.addBody(earth, { enlarge: 60 })
|
|
61
|
+
.addBody(mars, { enlarge: 60 })
|
|
62
|
+
.addTrajectory({ id: "probe", label: "Made-up probe", samples, plane: "ecliptic-j2000", lineFixedTo: "sun" })
|
|
63
|
+
.setTime(start)
|
|
64
|
+
.setScale(solarSystemScale);
|
|
65
|
+
scene.camera.fitOrbit(mars);
|
|
66
|
+
|
|
67
|
+
mount(document.getElementById("app"), scene);
|
|
68
|
+
```
|
|
69
|
+
|
|
70
|
+
Positions are about the scene centre (here the Sun, the first body) unless `center` says otherwise. `lineFixedTo: "sun"` keeps the line still against the Sun while the planets move; `plane` turns the ecliptic vectors into the engine's equatorial frame once; `solarSystemScale` keeps the distances true and draws the named bodies larger; the probe's name shows at any distance in a Sun-centred scene. The repository's dev site opens a fuller version at `?experience=synthetic-probe`.
|
|
71
|
+
|
|
45
72
|
## The public API
|
|
46
73
|
|
|
47
74
|
The full reference, generated from the types and doc comments, is at <https://astraeus.anipatke.com/api/>. The table below is the short form.
|
|
@@ -49,20 +76,20 @@ The full reference, generated from the types and doc comments, is at <https://as
|
|
|
49
76
|
| Call | What it does |
|
|
50
77
|
|---|---|
|
|
51
78
|
| `new Scene()` | An empty scene. Every method below returns the scene, so calls chain. |
|
|
52
|
-
| `scene.addBody(body, { orbit?, enlarge?, showLabel?, description?, color?, knownLimitations? })` | Adds a catalogued body: a ready-made one (`sun`, `mercury`, `venus`, `earth`, `moon`, `mars`, `jupiter`, `saturn`, `uranus`, `neptune`, `pluto`, and the moons `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`, `phobos`, `deimos`) or its id. The first body added is the scene's centre. `{ orbit: true }` also draws its orbit line: `moon` about Earth and `io` about Jupiter (the parent must be in the scene), or, with `sun` in the scene, one full turn round the Sun of any body that circles it (the planets, Earth's year, a body from `addBodyFromElements`), from the opening time; anything else throws `no-orbit`. `enlarge` (a number of at least 1) draws the body that many times larger than life (in a Sun-centred scene the viewer then offers its "Solar system" scale, true distances with the named bodies enlarged, as the second scale in place of Readable); `showLabel: false` starts its label off. A scene whose first body is the Sun sets no label reach, so labels stay when zoomed out, and it
|
|
53
|
-
| `scene.addTrajectory({ id, label?, color?, center?, samples, provenance?, description?, knownLimitations?, anchors?, readouts? })` | A recorded path. Each sample is `{ time, positionKm, velocityKmS? }` measured from `center` (default `"
|
|
79
|
+
| `scene.addBody(body, { orbit?, enlarge?, showLabel?, labelReach?, description?, color?, knownLimitations? })` | Adds a catalogued body: a ready-made one (`sun`, `mercury`, `venus`, `earth`, `moon`, `mars`, `jupiter`, `saturn`, `uranus`, `neptune`, `pluto`, and the moons `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`, `phobos`, `deimos`) or its id. The first body added is the scene's centre. `{ orbit: true }` also draws its orbit line: `moon` about Earth and `io` about Jupiter (the parent must be in the scene), or, with `sun` in the scene, one full turn round the Sun of any body that circles it (the planets, Earth's year, a body from `addBodyFromElements`), from the opening time; anything else throws `no-orbit`. `enlarge` (a number of at least 1) draws the body that many times larger than life (in a Sun-centred scene the viewer then offers its "Solar system" scale, true distances with the named bodies enlarged, as the second scale in place of Readable); `showLabel: false` starts its label off; `labelReach` (a positive number, in the camera's distance units) shows its label only within that distance of the camera, in place of the scene's shared rule. A scene whose first body is the Sun sets no label reach, so labels stay when zoomed out, and it can hold a path (`addTrajectory`, drawn with `lineFixedTo: "sun"`). `color` (a hex colour such as `"#9fd8ff"`) sets the colour on its info card and label; `knownLimitations` (a list of non-empty texts) replaces the catalogue's limits shown with its provenance; a bad value throws `bad-body`. |
|
|
80
|
+
| `scene.addTrajectory({ id, label?, color?, center?, plane?, lineFixedTo?, labelReach?, samples, provenance?, description?, knownLimitations?, anchors?, readouts? })` | A recorded path. Each sample is `{ time, positionKm, velocityKmS? }` measured from `center` (default: the scene's centre, its first body, so a Sun-first scene reads them from the Sun and an Earth-first one from Earth; Earth if no body is added) in equatorial J2000 (EQJ) axes; `plane: "ecliptic-j2000"` instead takes ecliptic J2000 vectors as JPL Horizons publishes them and rotates them to EQJ once on the way in (positions and velocities, from samples or a provider; a provider's `orientation` quaternion passes through unrotated, a known limit; any other `plane` throws `bad-trajectory`); `lineFixedTo` names the body the line is drawn against (default the scene centre): each sample is placed from that body at the sample's own time, then the line is carried to that body's place from the scene centre at the clock time, so `"sun"` fixes a probe's line to the Sun in any scene, Sun-centred ones included, and a body the scene does not hold throws `bad-trajectory`; `labelReach` (a positive number, in the camera's distance units) limits how far from the camera its name shows, in place of the scene's shared rule; a bad value throws `bad-trajectory`; `time` is ISO text, a `Date` or Unix milliseconds. Instead of `samples` you may give `provider` (an object with `stateAt(timeUtcMs)`) and `bounds: { start, end }`. `description` and `knownLimitations` (a list of sentences) go on its info card with `provenance`. `anchors: [{ id, time }]` draw labelled dots where the source published a point (the time must fall within the path). `readouts` are bars on the card, in order: `{ kind: "range", marker? }` (distance from the centre; `marker` names a body to mark), `{ kind: "speed" }`, `{ kind: "distance", to }` and `{ kind: "altitude", above }`; a named body must be in the scene. |
|
|
54
81
|
| `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? }, frame: "ecliptic-j2000", source: { name, url, solution, accessed }, radius?, accuracy: { classification, statement, validFromUtc, validToUtc, limitations }, marker?: { color, sizePx } }`. Drawn as a marker on unperturbed two-body motion about the Sun; the source, accuracy and limits show on its info card, with a live "Distance from Sun" row. `options` are `addBody`'s (`{ 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`. |
|
|
55
82
|
| `scene.addGroup({ id, orbits, label?, center?, plane?, 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` (`"ecliptic-j2000"` default, or `"EQJ"`). 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. The 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`. |
|
|
56
83
|
| `scene.setTime(time)` | The moment the scene opens at. |
|
|
57
|
-
| `scene.setScale(trueScale \| readableScale, { only? })` | The opening scale; the viewer can switch to the other unless `{ only: true }` offers that scale alone. |
|
|
84
|
+
| `scene.setScale(trueScale \| readableScale \| solarSystemScale, { only? })` | The opening scale; the viewer can switch to the other unless `{ only: true }` offers that scale alone. `solarSystemScale` (true distances, enlarged bodies drawn larger) needs a Sun-centred scene with an enlarged body, else `bad-scale`; such a scene offers it second in place of `readableScale`. |
|
|
58
85
|
| `scene.addEvents(events, { provenance? })` | Timed events on the timeline: `[{ id, label, time, type?, provenance? }]`, ids unique. `provenance` says where the times come from; an event's own `provenance` wins over the batch's. A provenance `sourceType` is `ephemeris`, `observed`, `reconstructed`, `modelled` or `illustrative`; `modelled` is shown as "Modelled". Batch and per-event provenance are checked: a malformed one throws `bad-event`. May be called more than once. |
|
|
59
86
|
| `scene.addStoryPanels({ pauseSeconds?, autoOpen?, panels })` | Story panels that open as playback reaches them: `{ id, at: { utc } \| { event } \| { anchor }, title, body, details?, badge, sources, object? }`. `badge` is `observed`, `modelled` or `illustrative`; `sources` is never empty. A mistake throws `bad-panels` naming the panel and field. |
|
|
60
87
|
| `scene.setTimeline({ start, end, rates?, rate? })` | The timeline's span, the playback speeds offered (simulated seconds per real second) and the one it opens at. `{ none: true, at?, rate? }` draws no timeline bar: time is frozen at `at`, or runs on at `rate`. |
|
|
61
88
|
| `scene.addActivity({ id, label, unit, start, end, samples, peak?, provenance?, type?, peakLabel? })` | A period of activity on the timeline: a rate curve `samples: [{ time, value }]` (at least two, sorted, inside `start` to `end`; straight lines between) that the timeline glows by, with an optional `peak` mark and `provenance: [{ start, end, provenance }]` for where each stretch comes from. A group's `readouts: [{ kind: "rate", activity? }]` shows the live rate (unavailable outside the period) against the peak on its card. Without `setTimeline` the timeline spans the activities. A repeated id or a bad curve, peak or source throws `bad-activity`; a rate readout with no activity is `bad-readout`. |
|
|
62
|
-
| `scene.camera.setReach(distance)` | How far the viewer can zoom out, in Earth radii; labels reach as far. A bad value throws `bad-camera`. `camera.follow` and `camera.lookAt` take `up: "ecliptic"` (default `"equatorial"`) to orbit about the ecliptic's pole; any other value throws `bad-camera`. `setTimeline` takes `loop: true` so playback wraps from the end to the start. |
|
|
89
|
+
| `scene.camera.setReach(distance)` | How far the viewer can zoom out, in Earth radii; labels reach as far, a path's own name (at its marker, switched by `labels`) included. A bad value throws `bad-camera`. The object the scene opens on (`camera.follow` or `camera.lookAt`) is selected, and a selected object's label wins every label collision: it is never the one hidden because it overlaps another. Other labels keep their priority order. `camera.follow` and `camera.lookAt` take `up: "ecliptic"` (default `"equatorial"`) to orbit about the ecliptic's pole; any other value throws `bad-camera`. `setTimeline` takes `loop: true` so playback wraps from the end to the start. |
|
|
63
90
|
| `scene.camera.fitOrbit(body)` | Sets the farthest zoom-out so the whole orbit of a body that circles the Sun (a planet, the built-in comet, or one from `addBodyFromElements`, already added) fits the canvas from any view direction: 1.1 times its farthest Sun distance over the sine of the narrower half field of view. The fit follows the live canvas shape (a phone turning, a window resizing) and the far plane is 2.5 times the reach. The opening view is not moved, except that it is clamped to the limit like any other. Labels are not limited in a fitted scene. It and `setReach` set the same limit; the later call wins. A body that does not circle the Sun throws `bad-camera`; one not in the scene, `unknown-body`. `scene.camera.fitOrbit("c-2025-a1")` |
|
|
64
91
|
| `scene.setSwitches({ orbitLines?, labels?, milkyWay? })` | Where each display switch shows: `{ place: "top-bar" \| "panel" \| "developer", on? }`. A top-bar switch is a button in the bar, a panel switch is a row in one switch panel opened from the bar, and a developer switch is only in the Developer drawer (where every switch stays). `orbitLines` is the orbit ring, trailing arc and moon orbits; `labels` is body and anchor labels; `milkyWay` is the sky picture. `on` is the starting state (default on). Nothing placed: the bar is as before. A bad name, place or `on` throws `bad-switch`. |
|
|
65
|
-
| `scene.stateOf(id, time)` | The state of any body in the scene at a moment, for figures a story quotes. `positionKm` is always there; `velocityKmS` (km/s) only where the body's source gives one, so check it before use: a path from `addTrajectory` whose samples or provider carry velocities, and a moon from fitted data (Io); planets, Earth, the Sun, built-in Swift-Tuttle and elements bodies give position only. Bodies: a path from `addTrajectory` (about its centre), or a ready-made body, moon or elements body (about its parent). Ready-made and elements bodies answer at any date; only a moment outside an `addTrajectory` path throws `bad-time`. A planet's data lives in the planet series, so it answers only once they are loaded (at `mount`), else `missing-data`. `const au = Math.hypot(...scene.stateOf("earth", "2026-08-12T00:00:00Z").positionKm) / 149597870.7;` |
|
|
92
|
+
| `scene.stateOf(id, time)` | The state of any body in the scene at a moment, for figures a story quotes. `positionKm` is always there; `velocityKmS` (km/s) only where the body's source gives one, so check it before use: a path from `addTrajectory` whose samples or provider carry velocities, and a moon from fitted data (Io); planets, Earth, the Sun, built-in Swift-Tuttle and elements bodies give position only. Bodies: a path from `addTrajectory` (about its centre, in EQJ axes whatever `plane` it was given in), or a ready-made body, moon or elements body (about its parent). Ready-made and elements bodies answer at any date; only a moment outside an `addTrajectory` path throws `bad-time`. A planet's data lives in the planet series, so it answers only once they are loaded (at `mount`), else `missing-data`. `const au = Math.hypot(...scene.stateOf("earth", "2026-08-12T00:00:00Z").positionKm) / 149597870.7;` |
|
|
66
93
|
| `scene.provenanceOf(id)` | Where a body's position comes from, as its info card shows it. Where a comparison with an independent ephemeris exists it carries `accuracyClass` and `maxErrorFraction`. For built-in Swift-Tuttle that fraction is measured (0.00857). For a body from `addBodyFromElements` it is the limit of its class (0.01 `approximate`, 0.05 `indicative`): an upper bound, not a measured figure. Other bodies carry neither field. |
|
|
67
94
|
| `scene.camera.follow(id, { azimuthDeg?, elevationDeg?, distance? })` | Opens framed on a body or trajectory already added, and already following it. `distance` is in Earth radii. |
|
|
68
95
|
| `scene.camera.lookAt(id, { azimuthDeg?, elevationDeg?, distance? })` | The same opening view without following. The last of `follow` and `lookAt` wins. The viewer's camera menu gets a Focus and a Follow entry for every body and path. |
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "astraeus",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.4.0",
|
|
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/activity.d.ts
CHANGED
|
@@ -22,7 +22,7 @@ export interface ActivityInput {
|
|
|
22
22
|
readonly id: string;
|
|
23
23
|
/** Name shown on the timeline and with the rate bar. */
|
|
24
24
|
readonly label: string;
|
|
25
|
-
/** What the rate counts, per unit of time, such as "
|
|
25
|
+
/** What the rate counts, per unit of time, such as "events per hour". */
|
|
26
26
|
readonly unit: string;
|
|
27
27
|
/** The first and last moment of the activity. The curve's samples lie inside it, and the rate is unavailable outside it. */
|
|
28
28
|
readonly start: TimeInput;
|
package/src/api/activity.js
CHANGED
|
@@ -12,7 +12,7 @@ function checkFields(input) {
|
|
|
12
12
|
if (!isText(input.label))
|
|
13
13
|
throw bad(id, "the activity needs a non-empty label");
|
|
14
14
|
if (!isText(input.unit))
|
|
15
|
-
throw bad(id, "the activity needs a unit such as \"
|
|
15
|
+
throw bad(id, "the activity needs a unit such as \"events per hour\"");
|
|
16
16
|
if (!Array.isArray(input.samples) || input.samples.length < 2)
|
|
17
17
|
throw bad(id, "the curve needs at least two samples");
|
|
18
18
|
if (input.peakLabel !== undefined && !isText(input.peakLabel))
|
package/src/api/bodies.d.ts
CHANGED
|
@@ -15,6 +15,8 @@ export declare const venus: BodyRef;
|
|
|
15
15
|
export declare const earth: BodyRef;
|
|
16
16
|
/** Moon. */
|
|
17
17
|
export declare const moon: BodyRef;
|
|
18
|
+
/** The scene centre when a path is added before any body: Earth, the documented default (the only place the fallback is named; ARCH-06). */
|
|
19
|
+
export declare const FALLBACK_SCENE_CENTRE: BodyId;
|
|
18
20
|
/** Mars. */
|
|
19
21
|
export declare const mars: BodyRef;
|
|
20
22
|
/** Jupiter. */
|
package/src/api/bodies.js
CHANGED
|
@@ -9,6 +9,8 @@ export const venus = ref("venus", "Venus");
|
|
|
9
9
|
export const earth = ref("earth", "Earth");
|
|
10
10
|
/** Moon. */
|
|
11
11
|
export const moon = ref("moon", "Moon");
|
|
12
|
+
/** The scene centre when a path is added before any body: Earth, the documented default (the only place the fallback is named; ARCH-06). */
|
|
13
|
+
export const FALLBACK_SCENE_CENTRE = earth.id;
|
|
12
14
|
/** Mars. */
|
|
13
15
|
export const mars = ref("mars", "Mars");
|
|
14
16
|
/** Jupiter. */
|
package/src/api/index.d.ts
CHANGED
|
@@ -5,7 +5,7 @@ export { mount, type MountOptions, type MountedScene } from "./mount.js";
|
|
|
5
5
|
export { AstraeusScene, type AstraeusSceneProps } from "./AstraeusScene.js";
|
|
6
6
|
export { SceneError, type SceneErrorCode } from "./errors.js";
|
|
7
7
|
export { sun, mercury, venus, earth, moon, mars, jupiter, saturn, uranus, neptune, pluto, io, europa, ganymede, callisto, mimas, enceladus, tethys, dione, rhea, titan, iapetus, triton, charon, phobos, deimos, type BodyRef } from "./bodies.js";
|
|
8
|
-
export { trueScale, readableScale, type ScalePolicy } from "../core/scalePolicy.js";
|
|
8
|
+
export { trueScale, readableScale, solarSystemScale, type ScalePolicy } from "../core/scalePolicy.js";
|
|
9
9
|
export type { State } from "../core/state.js";
|
|
10
10
|
export type { Provenance, ProvenanceSourceType } from "../core/provenance.js";
|
|
11
11
|
export type { Pictures } from "../assets/pictures.js";
|
package/src/api/index.js
CHANGED
|
@@ -4,5 +4,5 @@ export { mount } from "./mount.js";
|
|
|
4
4
|
export { AstraeusScene } from "./AstraeusScene.js";
|
|
5
5
|
export { SceneError } from "./errors.js";
|
|
6
6
|
export { sun, mercury, venus, earth, moon, mars, jupiter, saturn, uranus, neptune, pluto, io, europa, ganymede, callisto, mimas, enceladus, tethys, dione, rhea, titan, iapetus, triton, charon, phobos, deimos } from "./bodies.js";
|
|
7
|
-
export { trueScale, readableScale } from "../core/scalePolicy.js";
|
|
7
|
+
export { trueScale, readableScale, solarSystemScale } from "../core/scalePolicy.js";
|
|
8
8
|
export { APPROXIMATE_LIMIT_FRACTION, INDICATIVE_LIMIT_FRACTION, classifyPositionError, parseElementsBodyRecord } from "../core/elementsBody.js";
|
package/src/api/index.node.js
CHANGED
|
@@ -4,5 +4,5 @@ export { mount } from "./mount.node.js";
|
|
|
4
4
|
export { AstraeusScene } from "./AstraeusScene.node.js";
|
|
5
5
|
export { SceneError } from "./errors.js";
|
|
6
6
|
export { sun, mercury, venus, earth, moon, mars, jupiter, saturn, uranus, neptune, pluto, io, europa, ganymede, callisto, mimas, enceladus, tethys, dione, rhea, titan, iapetus, triton, charon, phobos, deimos } from "./bodies.js";
|
|
7
|
-
export { trueScale, readableScale } from "../core/scalePolicy.js";
|
|
7
|
+
export { trueScale, readableScale, solarSystemScale } from "../core/scalePolicy.js";
|
|
8
8
|
export { APPROXIMATE_LIMIT_FRACTION, INDICATIVE_LIMIT_FRACTION, classifyPositionError, parseElementsBodyRecord } from "../core/elementsBody.js";
|
package/src/api/scene.d.ts
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
import type { BodyId } from "../core/body.js";
|
|
2
2
|
import { type Provenance } from "../core/provenance.js";
|
|
3
3
|
import { type ScalePolicy } from "../core/scalePolicy.js";
|
|
4
|
-
import type
|
|
4
|
+
import { type State } from "../core/state.js";
|
|
5
5
|
import { type ElementsBodyRecord } from "../core/elementsBody.js";
|
|
6
6
|
import type { ExperienceDefinition } from "../app/experienceDefinition.js";
|
|
7
7
|
import { type BodyRef } from "./bodies.js";
|
|
@@ -27,6 +27,8 @@ export interface AddBodyOptions {
|
|
|
27
27
|
readonly enlarge?: number;
|
|
28
28
|
/** False starts the body's label off (the body stays in the menu and selectable; the viewer's labels switch can turn it on). Default true. */
|
|
29
29
|
readonly showLabel?: boolean;
|
|
30
|
+
/** How far from the camera the body's label shows, in the camera's `distance` units (as `camera.setReach`); a positive finite number. When absent the scene's shared rule applies: no limit in a Sun-centred or fitted scene, else the camera reach (at least 500). */
|
|
31
|
+
readonly labelReach?: number;
|
|
30
32
|
/** One or two plain sentences for the body's info card. */
|
|
31
33
|
readonly description?: string;
|
|
32
34
|
/** The body's colour on its info card and label, as a CSS hex colour such as "#9fd8ff"; the catalogue's own when absent. A bad value throws `bad-body`. */
|
|
@@ -56,7 +58,7 @@ export type ReadoutInput = {
|
|
|
56
58
|
readonly kind: "altitude";
|
|
57
59
|
readonly above: BodyId;
|
|
58
60
|
};
|
|
59
|
-
/** One sample of a recorded path: position in km (and optionally velocity in km/s) about the trajectory's centre
|
|
61
|
+
/** One sample of a recorded path: position in km (and optionally velocity in km/s) about the trajectory's centre, in equatorial J2000 (EQJ) axes unless the path says `plane: "ecliptic-j2000"`. */
|
|
60
62
|
export interface TrajectorySampleInput {
|
|
61
63
|
readonly time: TimeInput;
|
|
62
64
|
readonly positionKm: ArrayLike<number>;
|
|
@@ -66,8 +68,21 @@ interface TrajectoryBase {
|
|
|
66
68
|
readonly id: string;
|
|
67
69
|
readonly label?: string;
|
|
68
70
|
readonly color?: string;
|
|
69
|
-
/** The body the positions are measured from; defaults to "earth". */
|
|
71
|
+
/** The body the positions are measured from; defaults to the scene's centre (its first body, whichever you add first; "earth" if none is a catalogued body). */
|
|
70
72
|
readonly center?: BodyId;
|
|
73
|
+
/**
|
|
74
|
+
* The body the path's line is drawn against: each sample is placed from this body at the sample's own time, then the line is carried to
|
|
75
|
+
* this body's place from the scene centre at the clock time. Defaults to the scene centre; name the Sun for a probe crossing a Sun-centred scene.
|
|
76
|
+
* Throws `bad-trajectory` at build if the scene does not hold the body.
|
|
77
|
+
*/
|
|
78
|
+
readonly lineFixedTo?: BodyId;
|
|
79
|
+
/**
|
|
80
|
+
* The frame the positions and velocities are given in, about `center`: "EQJ" (equatorial J2000, the default) or "ecliptic-j2000" (the vectors JPL Horizons
|
|
81
|
+
* publishes by default). Ecliptic input is rotated to EQJ once, as it is read, so drawing, `stateOf` and readouts all see EQJ. Any other value throws `bad-trajectory`.
|
|
82
|
+
*/
|
|
83
|
+
readonly plane?: "EQJ" | "ecliptic-j2000";
|
|
84
|
+
/** How far from the camera the path's label shows, in the camera's `distance` units (as `camera.setReach`); a positive finite number. When absent the scene's shared rule applies: no limit in a Sun-centred or fitted scene, else the camera reach (at least 500). */
|
|
85
|
+
readonly labelReach?: number;
|
|
71
86
|
readonly provenance?: Provenance;
|
|
72
87
|
/** One or two plain sentences for the path's info card. */
|
|
73
88
|
readonly description?: string;
|
|
@@ -175,7 +190,7 @@ export declare class Scene {
|
|
|
175
190
|
addActivity(input: ActivityInput): this;
|
|
176
191
|
/** Sets the moment the scene opens at. */
|
|
177
192
|
setTime(time: TimeInput): this;
|
|
178
|
-
/** Chooses the opening scale: `trueScale` or `
|
|
193
|
+
/** Chooses the opening scale: `trueScale`, `readableScale` or `solarSystemScale` (true distances, the enlarged bodies drawn larger; it needs a Sun-centred scene with an enlarged body, else the scene throws `bad-scale`); the viewer can switch to the other (in a Sun-centred scene with an enlarged body, the second choice is the Solar system scale instead of the readable one), unless `{ only: true }` offers this scale alone. */
|
|
179
194
|
setScale(scale: ScalePolicy, options?: {
|
|
180
195
|
readonly only?: boolean;
|
|
181
196
|
}): this;
|
package/src/api/scene.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { createProvenance } from "../core/provenance.js";
|
|
2
2
|
import { SampledTrajectory } from "../core/sampledTrajectory.js";
|
|
3
|
-
import { readableScale, trueScale } from "../core/scalePolicy.js";
|
|
3
|
+
import { readableScale, solarSystemScale, trueScale } from "../core/scalePolicy.js";
|
|
4
|
+
import { createState } from "../core/state.js";
|
|
5
|
+
import { createOrbTwoBodyAdapter } from "../core/twoBodyAdapter.js";
|
|
4
6
|
import { createStateResolver } from "../core/stateResolver.js";
|
|
5
7
|
import { createOrbAstronomyAdapter } from "../core/astronomyAdapter.js";
|
|
6
8
|
import { loadPlanetSeries, planetSeriesLoaded } from "../core/planetSeries.js";
|
|
@@ -13,7 +15,7 @@ import { needsPlanetSeries } from "../app/planetNeeds.js";
|
|
|
13
15
|
import { catalogueItem } from "../app/catalogueItem.js";
|
|
14
16
|
import { createReadoutMetrics } from "../app/trackedMetrics.js";
|
|
15
17
|
import { circlesTheSun, farthestSunDistanceKm, sunOrbitIdOf, sunOrbitLayer } from "./sunOrbit.js";
|
|
16
|
-
import { readyMade } from "./bodies.js";
|
|
18
|
+
import { FALLBACK_SCENE_CENTRE, readyMade } from "./bodies.js";
|
|
17
19
|
import { installData } from "./data.js";
|
|
18
20
|
import { planActivity, rateMetricOf } from "./activity.js";
|
|
19
21
|
import { buildGroupLayer, planGroup } from "./group.js";
|
|
@@ -22,15 +24,15 @@ import { toUtcMs } from "./time.js";
|
|
|
22
24
|
import { switchesOf } from "./switches.js";
|
|
23
25
|
import { eventProvenanceOf, eventsOf, panelsOf, timelineOf } from "./story.js";
|
|
24
26
|
export { toUtcMs } from "./time.js";
|
|
25
|
-
/** The orbits the engine can draw: the parent the line is measured from
|
|
27
|
+
/** The orbits the engine can draw: the span one lap covers (the parent the line is measured from is the body's catalogue parent). */
|
|
26
28
|
const ORBITS = {
|
|
27
|
-
moon: {
|
|
28
|
-
io: {
|
|
29
|
+
moon: { path: { spanMs: SIDEREAL_MONTH_MS } },
|
|
30
|
+
io: { path: { spanMs: IO_PERIOD_DAYS * 86_400_000, look: { endFadeOn: false } } },
|
|
29
31
|
};
|
|
30
32
|
const DEFAULT_COLOR = "#ffd27a";
|
|
31
33
|
const DAY_MS = 86_400_000;
|
|
32
34
|
const PROVIDER_PATH_SAMPLES = 128;
|
|
33
|
-
const SCALES = [trueScale, readableScale];
|
|
35
|
+
const SCALES = [trueScale, readableScale, solarSystemScale];
|
|
34
36
|
/** The scene's camera: what it opens on. */
|
|
35
37
|
export class SceneCamera {
|
|
36
38
|
#target;
|
|
@@ -117,10 +119,13 @@ export class Scene {
|
|
|
117
119
|
camera;
|
|
118
120
|
#bodies = new Map();
|
|
119
121
|
#tracked = new Map();
|
|
122
|
+
/** Paths added without a `center`: they follow the scene's first body, so one added before any body is rebuilt when the first body arrives. */
|
|
123
|
+
#defaulted = new Map();
|
|
120
124
|
#groups = new Map();
|
|
121
125
|
#activities = new Map();
|
|
122
126
|
#orbits = new Set();
|
|
123
127
|
#own = new Map();
|
|
128
|
+
#labelReaches = new Map();
|
|
124
129
|
#shape = new Map();
|
|
125
130
|
#catalogue = builtInCatalogue;
|
|
126
131
|
#notes = new Map();
|
|
@@ -177,6 +182,8 @@ export class Scene {
|
|
|
177
182
|
if (this.#taken(id))
|
|
178
183
|
throw new SceneError("duplicate-id", `${call}("${id}"): already in the scene`);
|
|
179
184
|
checkBodyLook(id, options);
|
|
185
|
+
if (options.labelReach !== undefined)
|
|
186
|
+
this.#labelReaches.set(id, options.labelReach);
|
|
180
187
|
if (options.orbit === true)
|
|
181
188
|
this.#orbits.add(id);
|
|
182
189
|
if (options.color !== undefined || options.knownLimitations !== undefined)
|
|
@@ -186,6 +193,9 @@ export class Scene {
|
|
|
186
193
|
if (options.description !== undefined)
|
|
187
194
|
this.#notes.set(id, options.description);
|
|
188
195
|
this.#bodies.set(id, ref);
|
|
196
|
+
if (this.#bodies.size === 1 && builtInCatalogue.has(id))
|
|
197
|
+
for (const input of this.#defaulted.values())
|
|
198
|
+
this.#buildTracked(input, id);
|
|
189
199
|
}
|
|
190
200
|
/** Adds a path to follow and draw, from sampled states or a provider with `stateAt(time)`. */
|
|
191
201
|
addTrajectory(input) {
|
|
@@ -194,15 +204,33 @@ export class Scene {
|
|
|
194
204
|
throw new SceneError("bad-trajectory", "addTrajectory: the trajectory needs a non-empty id");
|
|
195
205
|
if (this.#taken(id))
|
|
196
206
|
throw new SceneError("duplicate-id", `addTrajectory("${id}"): that id is already in the scene`);
|
|
197
|
-
|
|
207
|
+
this.#buildTracked(input, input.center ?? this.#sceneCentre());
|
|
208
|
+
if (input.center === undefined)
|
|
209
|
+
this.#defaulted.set(id, input);
|
|
210
|
+
return this;
|
|
211
|
+
}
|
|
212
|
+
/** The scene's centre: its first body when that is a built-in one, else Earth (the default of a path added before any body; `#register` re-reads it when the first body arrives). */
|
|
213
|
+
#sceneCentre() {
|
|
214
|
+
const first = this.#bodies.keys().next();
|
|
215
|
+
return first.done === true || !builtInCatalogue.has(first.value) ? FALLBACK_SCENE_CENTRE : first.value;
|
|
216
|
+
}
|
|
217
|
+
/** Validates and stores one path about `center`. */
|
|
218
|
+
#buildTracked(input, center) {
|
|
219
|
+
const id = input.id;
|
|
198
220
|
if (!builtInCatalogue.has(center))
|
|
199
221
|
throw new SceneError("unknown-body", `addTrajectory("${id}"): centre "${center}" is not a catalogued body`);
|
|
200
222
|
const provenance = input.provenance ?? createProvenance({ sourceType: "illustrative", sources: ["Supplied by the caller"], accuracy: "As supplied; the engine makes no claim.", notes: "Positions were passed to addTrajectory." });
|
|
201
|
-
const common = { id, label: input.label ?? id, color: input.color ?? DEFAULT_COLOR, anchorTimesUtcMs: [], provenance };
|
|
223
|
+
const common = { id, label: input.label ?? id, color: input.color ?? DEFAULT_COLOR, anchorTimesUtcMs: [], provenance, ...(input.lineFixedTo === undefined ? {} : { lineFixedTo: input.lineFixedTo }) };
|
|
202
224
|
const readouts = readoutsOf(id, input.readouts);
|
|
203
|
-
|
|
225
|
+
if (input.labelReach !== undefined) {
|
|
226
|
+
checkLabelReach(input.labelReach, new SceneError("bad-trajectory", `addTrajectory("${id}"): labelReach ${String(input.labelReach)} must be a positive finite number`));
|
|
227
|
+
this.#labelReaches.set(id, input.labelReach);
|
|
228
|
+
}
|
|
229
|
+
if (input.plane !== undefined && input.plane !== "EQJ" && input.plane !== "ecliptic-j2000")
|
|
230
|
+
throw new SceneError("bad-trajectory", `addTrajectory("${id}"): plane "${String(input.plane)}" must be "EQJ" or "ecliptic-j2000"`);
|
|
231
|
+
const toEqj = input.plane === "ecliptic-j2000" ? createOrbTwoBodyAdapter().eclipticJ2000ToEqjMatrix() : null;
|
|
232
|
+
const body = "samples" in input ? sampledBody(common, input, center, toEqj) : providerBody(common, input, toEqj);
|
|
204
233
|
this.#tracked.set(id, { center, body: withAnchors(body, input.anchors), readouts, ...(input.description === undefined ? {} : { description: input.description }), ...(input.knownLimitations === undefined ? {} : { knownLimitations: input.knownLimitations }) });
|
|
205
|
-
return this;
|
|
206
234
|
}
|
|
207
235
|
/** Whether a body, path or group already has this id. */
|
|
208
236
|
#taken(id) {
|
|
@@ -239,10 +267,10 @@ export class Scene {
|
|
|
239
267
|
this.#timeUtcMs = toUtcMs(time, "setTime");
|
|
240
268
|
return this;
|
|
241
269
|
}
|
|
242
|
-
/** Chooses the opening scale: `trueScale` or `
|
|
270
|
+
/** Chooses the opening scale: `trueScale`, `readableScale` or `solarSystemScale` (true distances, the enlarged bodies drawn larger; it needs a Sun-centred scene with an enlarged body, else the scene throws `bad-scale`); the viewer can switch to the other (in a Sun-centred scene with an enlarged body, the second choice is the Solar system scale instead of the readable one), unless `{ only: true }` offers this scale alone. */
|
|
243
271
|
setScale(scale, options = {}) {
|
|
244
272
|
if (!SCALES.some((known) => known.id === scale?.id))
|
|
245
|
-
throw new SceneError("bad-scale", `setScale: "${String(scale?.id)}" is not a scale; use trueScale or
|
|
273
|
+
throw new SceneError("bad-scale", `setScale: "${String(scale?.id)}" is not a scale; use trueScale, readableScale or solarSystemScale`);
|
|
246
274
|
this.#scale = scale;
|
|
247
275
|
this.#scaleOnly = options.only === true;
|
|
248
276
|
return this;
|
|
@@ -365,6 +393,10 @@ export class Scene {
|
|
|
365
393
|
#earlySunPaths(orbitIds, openUtcMs) {
|
|
366
394
|
return planetSeriesLoaded() ? orbitIds.map((id) => this.#sunPath(id, openUtcMs)) : [];
|
|
367
395
|
}
|
|
396
|
+
#checkSolarSystemScale(sunCentred) {
|
|
397
|
+
if (this.#scale.id === solarSystemScale.id && !this.#enlargedInSun(sunCentred))
|
|
398
|
+
throw new SceneError("bad-scale", "setScale: the Solar system scale needs a Sun-centred scene with an enlarged body (addBody(x, { enlarge }))");
|
|
399
|
+
}
|
|
368
400
|
/** Whether a Sun-centred scene enlarges a body, which the viewer's solar-system scale draws. */
|
|
369
401
|
#enlargedInSun(sunCentred) {
|
|
370
402
|
return sunCentred && [...this.#shape.values()].some((shape) => shape.enlarge !== undefined);
|
|
@@ -402,21 +434,26 @@ export class Scene {
|
|
|
402
434
|
#moonPaths() {
|
|
403
435
|
return [...this.#orbits].filter((id) => ORBITS[id] !== undefined).map((id) => {
|
|
404
436
|
const orbit = ORBITS[id];
|
|
405
|
-
|
|
406
|
-
|
|
437
|
+
const parent = this.#catalogue.get(id).definition.parentId;
|
|
438
|
+
if (parent === undefined || !this.#bodies.has(parent))
|
|
439
|
+
throw new SceneError("no-orbit", `addBody("${id}", { orbit: true }): the orbit is drawn about ${parent}, which has not been added to the scene`);
|
|
407
440
|
return { body: id, ...orbit.path };
|
|
408
441
|
});
|
|
409
442
|
}
|
|
410
|
-
/** Whether the scene is centred on the Sun
|
|
443
|
+
/** Whether the scene is centred on the Sun. */
|
|
411
444
|
#checkSunCentred(ids) {
|
|
412
|
-
|
|
413
|
-
|
|
414
|
-
|
|
415
|
-
|
|
445
|
+
return ids[0] === rootBodyId(this.#catalogue);
|
|
446
|
+
}
|
|
447
|
+
/** How far a label shows, for bodies and paths alike: the item's own `labelReach` if given, else the shared rule: a Sun-centred scene, or one that fits the zoom-out to an orbit (`fitOrbit`, whose limit changes with the canvas), sets no limit; otherwise the camera reach, at least 500. */
|
|
448
|
+
#labelReach(id, sunCentred) {
|
|
449
|
+
const own = this.#labelReaches.get(id);
|
|
450
|
+
if (own !== undefined)
|
|
451
|
+
return { labelMaxDistance: own };
|
|
452
|
+
return sunCentred || this.camera.fitted !== undefined ? {} : { labelMaxDistance: Math.max(500, this.camera.reach ?? 0) };
|
|
416
453
|
}
|
|
417
|
-
/** The shell item of a body: from the catalogue, with the scene's own words, look and label setting.
|
|
454
|
+
/** The shell item of a body: from the catalogue, with the scene's own words, look and label setting. Label reach is `#labelReach`. */
|
|
418
455
|
#bodyObject(body, ids, sunCentred) {
|
|
419
|
-
const own = { labelPriority: 100 - ids.indexOf(body.id), ...(
|
|
456
|
+
const own = { labelPriority: 100 - ids.indexOf(body.id), ...this.#labelReach(body.id, sunCentred), ...(this.#shape.get(body.id)?.showLabel === undefined ? {} : { showLabel: this.#shape.get(body.id).showLabel }), ...(this.#notes.has(body.id) ? { description: this.#notes.get(body.id) } : {}), ...this.#looks.get(body.id) };
|
|
420
457
|
return { ...catalogueItem(body.id, own, this.#catalogue), label: body.label };
|
|
421
458
|
}
|
|
422
459
|
/** The event provenance entries of the experience: the batch's, and each event's own. */
|
|
@@ -451,8 +488,11 @@ export class Scene {
|
|
|
451
488
|
throw new SceneError("no-orbit", `addBody("${id}", { orbit: true }): "${id}" completes no turn within a dozen years and the catalogue does not know its period; add it with addBodyFromElements to draw its whole orbit`);
|
|
452
489
|
return layer;
|
|
453
490
|
}
|
|
454
|
-
/** A readout
|
|
491
|
+
/** A readout, or the body the line is fixed to, names a body the scene must hold. */
|
|
455
492
|
#checkReadouts(entry, ids) {
|
|
493
|
+
const fixed = entry.body.lineFixedTo;
|
|
494
|
+
if (fixed !== undefined && !ids.includes(fixed))
|
|
495
|
+
throw new SceneError("bad-trajectory", `addTrajectory("${entry.body.id}"): lineFixedTo names "${fixed}", which has not been added to the scene`);
|
|
456
496
|
for (const spec of entry.readouts) {
|
|
457
497
|
const named = readoutBody(spec);
|
|
458
498
|
if (named !== undefined && !ids.includes(named))
|
|
@@ -474,6 +514,7 @@ export class Scene {
|
|
|
474
514
|
const ids = [...this.#bodies.keys()];
|
|
475
515
|
const paths = this.#moonPaths();
|
|
476
516
|
const sunCentred = this.#checkSunCentred(ids);
|
|
517
|
+
this.#checkSolarSystemScale(sunCentred);
|
|
477
518
|
for (const entry of this.#tracked.values())
|
|
478
519
|
this.#checkReadouts(entry, ids);
|
|
479
520
|
const tracked = [...this.#tracked.values()].map((entry) => entry.body);
|
|
@@ -496,7 +537,7 @@ export class Scene {
|
|
|
496
537
|
experience: {
|
|
497
538
|
objects: [
|
|
498
539
|
...[...this.#bodies.values()].map((body) => this.#bodyObject(body, ids, sunCentred)),
|
|
499
|
-
...[...this.#tracked.values()].map(({ body, description, knownLimitations }) => ({ id: body.id, label: body.label, color: body.color, availability: body.trajectory.bounds, labelPriority: 80,
|
|
540
|
+
...[...this.#tracked.values()].map(({ body, description, knownLimitations }) => ({ id: body.id, label: body.label, color: body.color, availability: body.trajectory.bounds, labelPriority: 80, ...this.#labelReach(body.id, sunCentred), provenance: body.provenance, ...(description === undefined ? {} : { description }), ...(knownLimitations === undefined ? {} : { knownLimitations }) })),
|
|
500
541
|
],
|
|
501
542
|
cameraPresets: cameraPresetsOf(labelled),
|
|
502
543
|
...(target === undefined ? {} : { startCameraPresetId: `${this.camera.following ? "follow" : "focus"}-${target}` }),
|
|
@@ -598,14 +639,24 @@ function clockOf(timeline, startUtcMs) {
|
|
|
598
639
|
}
|
|
599
640
|
/**
|
|
600
641
|
* The scale choices offered: the opening one first, then the other unless the caller offered one alone. A Sun-centred scene with an enlarged body (`addBody(x, { enlarge })`)
|
|
601
|
-
* offers
|
|
642
|
+
* offers `solarSystemScale` (true distances, the named bodies enlarged) in place of the readable scale it would offer second, since the readable scale does not enlarge.
|
|
602
643
|
*/
|
|
603
644
|
function scaleChoicesOf(scale, only, enlarged) {
|
|
604
|
-
const
|
|
605
|
-
|
|
645
|
+
const offered = [trueScale, enlarged ? solarSystemScale : readableScale];
|
|
646
|
+
const second = scale.id === readableScale.id ? [trueScale] : offered.filter((other) => other.id !== scale.id);
|
|
647
|
+
return only ? [scale.id] : [scale.id, ...second.map((other) => other.id)];
|
|
648
|
+
}
|
|
649
|
+
/** Rotates a vector by a row-major 3x3 matrix; a missing matrix leaves it as it is. Input that is not three numbers passes through for the State checks to refuse. */
|
|
650
|
+
function rotated(matrix, v) {
|
|
651
|
+
if (matrix === null || v === undefined || v.length !== 3)
|
|
652
|
+
return v;
|
|
653
|
+
return [0, 1, 2].map((row) => matrix[3 * row] * v[0] + matrix[3 * row + 1] * v[1] + matrix[3 * row + 2] * v[2]);
|
|
606
654
|
}
|
|
607
|
-
function sampledBody(common, input, center) {
|
|
608
|
-
const samples = input.samples.map((sample, index) =>
|
|
655
|
+
function sampledBody(common, input, center, toEqj) {
|
|
656
|
+
const samples = input.samples.map((sample, index) => {
|
|
657
|
+
const velocityKmS = rotated(toEqj, sample.velocityKmS);
|
|
658
|
+
return { positionKm: rotated(toEqj, sample.positionKm), ...(velocityKmS === undefined ? {} : { velocityKmS }), timeUtcMs: toUtcMs(sample.time, `addTrajectory("${common.id}") sample ${index} time`) };
|
|
659
|
+
});
|
|
609
660
|
try {
|
|
610
661
|
const trajectory = new SampledTrajectory({ body: common.id, center, samples });
|
|
611
662
|
return { ...common, trajectory, pathTimesUtcMs: samples.map((sample) => sample.timeUtcMs) };
|
|
@@ -616,16 +667,22 @@ function sampledBody(common, input, center) {
|
|
|
616
667
|
throw new SceneError("bad-trajectory", `addTrajectory("${common.id}"): ${error instanceof Error ? error.message : String(error)}`);
|
|
617
668
|
}
|
|
618
669
|
}
|
|
619
|
-
function providerBody(common, input) {
|
|
670
|
+
function providerBody(common, input, toEqj) {
|
|
620
671
|
if (typeof input.provider?.stateAt !== "function")
|
|
621
672
|
throw new SceneError("bad-trajectory", `addTrajectory("${common.id}"): provider needs a stateAt(time) function`);
|
|
622
673
|
const bounds = { startUtcMs: toUtcMs(input.bounds?.start, `addTrajectory("${common.id}") bounds.start`), endUtcMs: toUtcMs(input.bounds?.end, `addTrajectory("${common.id}") bounds.end`) };
|
|
623
674
|
if (bounds.endUtcMs <= bounds.startUtcMs)
|
|
624
675
|
throw new SceneError("bad-trajectory", `addTrajectory("${common.id}"): bounds must end after they start`);
|
|
625
|
-
const trajectory = { body: common.id, bounds, stateAt: (timeUtcMs, center) => input.provider.stateAt(timeUtcMs, center) };
|
|
676
|
+
const trajectory = { body: common.id, bounds, stateAt: (timeUtcMs, center) => rotatedState(toEqj, input.provider.stateAt(timeUtcMs, center)) };
|
|
626
677
|
const step = (bounds.endUtcMs - bounds.startUtcMs) / (PROVIDER_PATH_SAMPLES - 1);
|
|
627
678
|
return { ...common, trajectory, pathTimesUtcMs: Array.from({ length: PROVIDER_PATH_SAMPLES }, (_, index) => bounds.startUtcMs + index * step) };
|
|
628
679
|
}
|
|
680
|
+
/** A provider's State with its position and velocity rotated into EQJ; unchanged for EQJ input. */
|
|
681
|
+
function rotatedState(matrix, state) {
|
|
682
|
+
if (matrix === null)
|
|
683
|
+
return state;
|
|
684
|
+
return createState({ body: state.body, center: state.center, timeUtcMs: state.timeUtcMs, positionKm: rotated(matrix, state.positionKm), ...(state.velocityKmS === undefined ? {} : { velocityKmS: rotated(matrix, state.velocityKmS) }), orientation: state.orientation });
|
|
685
|
+
}
|
|
629
686
|
/** The timeline span: the union of the trajectories' and activities' spans, else a month about the chosen time (or about now). */
|
|
630
687
|
function windowOf(tracked, timeUtcMs) {
|
|
631
688
|
if (tracked.length > 0) {
|
|
@@ -637,8 +694,15 @@ function windowOf(tracked, timeUtcMs) {
|
|
|
637
694
|
const centre = timeUtcMs ?? Date.now();
|
|
638
695
|
return { startUtcMs: centre - 15 * DAY_MS, endUtcMs: centre + 15 * DAY_MS };
|
|
639
696
|
}
|
|
640
|
-
/**
|
|
697
|
+
/** Throws `error` unless `reach` is a positive finite number. */
|
|
698
|
+
function checkLabelReach(reach, error) {
|
|
699
|
+
if (!(typeof reach === "number" && Number.isFinite(reach) && reach > 0))
|
|
700
|
+
throw error;
|
|
701
|
+
}
|
|
702
|
+
/** Checks the colour, known limits and label reach given to `addBody`. */
|
|
641
703
|
function checkBodyLook(id, options) {
|
|
704
|
+
if (options.labelReach !== undefined)
|
|
705
|
+
checkLabelReach(options.labelReach, new SceneError("bad-body", `addBody("${id}"): labelReach ${String(options.labelReach)} must be a positive finite number`));
|
|
642
706
|
if (options.enlarge !== undefined && !(typeof options.enlarge === "number" && Number.isFinite(options.enlarge) && options.enlarge >= 1))
|
|
643
707
|
throw new SceneError("bad-body", `addBody("${id}"): enlarge ${String(options.enlarge)} must be a number of at least 1`);
|
|
644
708
|
if (options.showLabel !== undefined && typeof options.showLabel !== "boolean")
|
package/src/app/SceneLabels.d.ts
CHANGED
|
@@ -8,6 +8,8 @@ interface Rect {
|
|
|
8
8
|
readonly right: number;
|
|
9
9
|
readonly bottom: number;
|
|
10
10
|
}
|
|
11
|
+
/** Added to the selected object's label priority; larger than any labelPriority, so it is never the label hidden by an overlap. */
|
|
12
|
+
export declare const SELECTED_PRIORITY = 1000;
|
|
11
13
|
/** App adapter that places configured labels; the label presentation itself stays generic. */
|
|
12
14
|
export declare class SceneLabelLayer {
|
|
13
15
|
#private;
|
package/src/app/SceneLabels.js
CHANGED
|
@@ -1,6 +1,8 @@
|
|
|
1
1
|
import { Vector3 } from "three";
|
|
2
2
|
import { createLabelElement } from "../shell/Label.js";
|
|
3
3
|
import { projectToScreen } from "./AnchorLabels.js";
|
|
4
|
+
/** Added to the selected object's label priority; larger than any labelPriority, so it is never the label hidden by an overlap. */
|
|
5
|
+
export const SELECTED_PRIORITY = 1_000;
|
|
4
6
|
/** App adapter that places configured labels; the label presentation itself stays generic. */
|
|
5
7
|
export class SceneLabelLayer {
|
|
6
8
|
#root = document.createElement("div");
|
|
@@ -12,6 +14,7 @@ export class SceneLabelLayer {
|
|
|
12
14
|
this.#entries = objects.map((object) => {
|
|
13
15
|
const element = createLabelElement(object.label, object.color, "scene-object-label");
|
|
14
16
|
element.dataset.labelId = object.id;
|
|
17
|
+
element.hidden = true; // not shown until the first layout places it (I-108: unplaced labels all showed for a moment, so a reader could see a label the settled layout then hides)
|
|
15
18
|
this.#root.appendChild(element);
|
|
16
19
|
return { object, element };
|
|
17
20
|
});
|
|
@@ -46,7 +49,8 @@ export class SceneLabelLayer {
|
|
|
46
49
|
entry.element.hidden = true;
|
|
47
50
|
return [];
|
|
48
51
|
}
|
|
49
|
-
|
|
52
|
+
// The selected (and so followed) object's label wins every collision: the bonus outranks any labelPriority (I-108).
|
|
53
|
+
const selectedPriority = entry.object.id === selectedObjectId ? SELECTED_PRIORITY : 0;
|
|
50
54
|
return [{ ...entry, screen, priority: (entry.object.labelPriority ?? 0) + selectedPriority }];
|
|
51
55
|
}).sort((a, b) => b.priority - a.priority || a.object.id.localeCompare(b.object.id));
|
|
52
56
|
const occupied = [];
|
|
@@ -1,9 +1,10 @@
|
|
|
1
|
-
import { DataTexture, Group,
|
|
1
|
+
import { DataTexture, Group, Vector3, type Camera } from "three";
|
|
2
2
|
import type { ScalePolicy } from "../core/scalePolicy.js";
|
|
3
3
|
import type { FloatingOrigin } from "./floatingOrigin.js";
|
|
4
|
+
import type { PathScreenReadout } from "./PathView.js";
|
|
4
5
|
import { type TrackedBody } from "./mission.js";
|
|
5
|
-
import type { PathRule } from "./experienceDefinition.js";
|
|
6
6
|
import { type RenderVector } from "./renderCoordinates.js";
|
|
7
|
+
import type { PathRule } from "./experienceDefinition.js";
|
|
7
8
|
import { type ScenePlacement } from "./sceneLayout.js";
|
|
8
9
|
/** Drawn after Earth and Moon so overlays are never swallowed by a body in a compressed scale. */
|
|
9
10
|
export declare const TRACK_LAYER = 3;
|
|
@@ -22,7 +23,7 @@ export declare function releaseAnchorSprite(): void;
|
|
|
22
23
|
export declare class TrackedBodyView {
|
|
23
24
|
#private;
|
|
24
25
|
readonly body: TrackedBody;
|
|
25
|
-
/**
|
|
26
|
+
/** Every tracked body's path is one rule, a relative trail (`pathRules.ts`); the body it is drawn against is the path's own `lineFixedTo`, default the scene centre. */
|
|
26
27
|
static readonly pathRule: PathRule;
|
|
27
28
|
readonly group: Group<import("three").Object3DEventMap>;
|
|
28
29
|
/** Anchor labels in anchor order, or null when the body has none. */
|
|
@@ -31,6 +32,11 @@ export declare class TrackedBodyView {
|
|
|
31
32
|
/** Scaled absolute target for the camera; holds the nearest bound outside the trajectory. */
|
|
32
33
|
absolute(timeUtcMs: number, policy: ScalePolicy, placement: ScenePlacement): RenderVector;
|
|
33
34
|
update(timeUtcMs: number, policy: ScalePolicy, origin: FloatingOrigin, camera: Camera, placement: ScenePlacement): void;
|
|
35
|
+
/**
|
|
36
|
+
* Diagnostic for the browser checks (`data-paths`, O-046 T-193): whether the path is drawn, the vertices of its two lines (travelled and future) in front of the camera and inside the view, and the box they cover
|
|
37
|
+
* as shares of the view. Both lines together are the whole path, so a line fixed to the Sun reads the same at any time. The line box repeats the vertex box.
|
|
38
|
+
*/
|
|
39
|
+
screenReadout(camera: Camera): PathScreenReadout;
|
|
34
40
|
/** Local (floating-origin) render position of anchor `index` as last drawn. */
|
|
35
41
|
anchorLocalPosition(index: number, out: Vector3): Vector3;
|
|
36
42
|
}
|
|
@@ -1,8 +1,8 @@
|
|
|
1
|
-
import { BufferAttribute, BufferGeometry, DataTexture, Group, Line, LineBasicMaterial, Mesh, MeshBasicMaterial, Points, PointsMaterial, RGBAFormat, SphereGeometry, } from "three";
|
|
1
|
+
import { BufferAttribute, BufferGeometry, DataTexture, Group, Line, LineBasicMaterial, Mesh, MeshBasicMaterial, Points, PointsMaterial, RGBAFormat, SphereGeometry, Vector3, } from "three";
|
|
2
2
|
import { anchorLabelsOf, markerRadiusUnits, sampleTrackedPositions, stateClampedToBounds, stateIfInBounds, travelledCount } from "./mission.js";
|
|
3
|
-
import { mapPathKm, relativeTrailKm } from "./pathRules.js";
|
|
3
|
+
import { mapPathKm, relativeTrailKm, shiftedBy } from "./pathRules.js";
|
|
4
4
|
import { eqjToRenderVector } from "./renderCoordinates.js";
|
|
5
|
-
import { trackedAbsolute } from "./sceneLayout.js";
|
|
5
|
+
import { sceneOffsetKm, trackedAbsolute } from "./sceneLayout.js";
|
|
6
6
|
/** Drawn after Earth and Moon so overlays are never swallowed by a body in a compressed scale. */
|
|
7
7
|
export const TRACK_LAYER = 3;
|
|
8
8
|
function lineWithCapacity(count, color, opacity) {
|
|
@@ -54,7 +54,7 @@ export function releaseAnchorSprite() {
|
|
|
54
54
|
*/
|
|
55
55
|
export class TrackedBodyView {
|
|
56
56
|
body;
|
|
57
|
-
/**
|
|
57
|
+
/** Every tracked body's path is one rule, a relative trail (`pathRules.ts`); the body it is drawn against is the path's own `lineFixedTo`, default the scene centre. */
|
|
58
58
|
static pathRule = Object.freeze({ kind: "trail", frame: "relative" });
|
|
59
59
|
group = new Group();
|
|
60
60
|
#marker;
|
|
@@ -64,6 +64,7 @@ export class TrackedBodyView {
|
|
|
64
64
|
#samples;
|
|
65
65
|
#anchorKm;
|
|
66
66
|
#mappedFor = "";
|
|
67
|
+
#mappedAt = 0;
|
|
67
68
|
#placedFor = null;
|
|
68
69
|
#mappedPath = new Float64Array(0);
|
|
69
70
|
#mappedAnchors = new Float64Array(0);
|
|
@@ -103,7 +104,7 @@ export class TrackedBodyView {
|
|
|
103
104
|
return trackedAbsolute(stateClampedToBounds(this.body, timeUtcMs), policy, placement);
|
|
104
105
|
}
|
|
105
106
|
update(timeUtcMs, policy, origin, camera, placement) {
|
|
106
|
-
this.#remap(policy, placement);
|
|
107
|
+
this.#remap(policy, placement, timeUtcMs);
|
|
107
108
|
// Mapped positions are not consistent with body radii in ReadableScale, so only TrueScale occludes.
|
|
108
109
|
const occlude = policy.id === "true-scale";
|
|
109
110
|
for (const material of this.#materials)
|
|
@@ -123,22 +124,31 @@ export class TrackedBodyView {
|
|
|
123
124
|
}
|
|
124
125
|
}
|
|
125
126
|
/**
|
|
126
|
-
* A relative trail: each sample is the body's position from the scene centre at that sample's own time
|
|
127
|
-
* scene
|
|
127
|
+
* A relative trail (`pathRules.ts`): each sample is the body's position from `lineFixedTo` (default the scene centre) at that sample's own time.
|
|
128
|
+
* A line fixed to a body other than the scene centre is carried to where that body is from the centre at the display time, so it
|
|
129
|
+
* is remapped as the clock moves; a line against the scene centre depends on the centre and scale alone.
|
|
128
130
|
*/
|
|
129
|
-
#remap(policy, placement) {
|
|
131
|
+
#remap(policy, placement, timeUtcMs) {
|
|
130
132
|
const placed = placement.center;
|
|
131
|
-
|
|
133
|
+
const moves = this.#against(placement) !== placed;
|
|
134
|
+
if (this.#mappedFor === policy.id && this.#placedFor === placed && (!moves || this.#mappedAt === timeUtcMs))
|
|
132
135
|
return;
|
|
133
|
-
this.#mappedPath = mapPathKm(this.#relative(this.#samples, placement), policy);
|
|
134
|
-
this.#mappedAnchors = mapPathKm(this.#relative({ timesUtcMs: this.body.anchorTimesUtcMs, positionsKm: this.#anchorKm }, placement), policy);
|
|
136
|
+
this.#mappedPath = mapPathKm(this.#relative(this.#samples, placement, timeUtcMs), policy);
|
|
137
|
+
this.#mappedAnchors = mapPathKm(this.#relative({ timesUtcMs: this.body.anchorTimesUtcMs, positionsKm: this.#anchorKm }, placement, timeUtcMs), policy);
|
|
135
138
|
this.#mappedFor = policy.id;
|
|
136
139
|
this.#placedFor = placed;
|
|
140
|
+
this.#mappedAt = timeUtcMs;
|
|
137
141
|
}
|
|
138
|
-
#
|
|
142
|
+
#against(placement) {
|
|
143
|
+
return this.body.lineFixedTo ?? placement.center;
|
|
144
|
+
}
|
|
145
|
+
#relative(samples, placement, timeUtcMs) {
|
|
139
146
|
if (samples.timesUtcMs.length === 0)
|
|
140
147
|
return samples.positionsKm;
|
|
141
|
-
|
|
148
|
+
const against = this.#against(placement);
|
|
149
|
+
const drawn = relativeTrailKm(samples, this.body.trajectory.stateAt(samples.timesUtcMs[0]).center, placement, against);
|
|
150
|
+
const carry = sceneOffsetKm(placement, against, timeUtcMs);
|
|
151
|
+
return carry === null ? drawn : shiftedBy(drawn, carry);
|
|
142
152
|
}
|
|
143
153
|
/** Writes [leading?] samples [from, to) [trailing?] into the line and sets how much of it is drawn. */
|
|
144
154
|
#fillPath(line, from, to, leading, trailing, origin) {
|
|
@@ -159,6 +169,35 @@ export class TrackedBodyView {
|
|
|
159
169
|
positions.needsUpdate = true;
|
|
160
170
|
line.geometry.setDrawRange(0, written >= 2 ? written : 0);
|
|
161
171
|
}
|
|
172
|
+
/**
|
|
173
|
+
* Diagnostic for the browser checks (`data-paths`, O-046 T-193): whether the path is drawn, the vertices of its two lines (travelled and future) in front of the camera and inside the view, and the box they cover
|
|
174
|
+
* as shares of the view. Both lines together are the whole path, so a line fixed to the Sun reads the same at any time. The line box repeats the vertex box.
|
|
175
|
+
*/
|
|
176
|
+
screenReadout(camera) {
|
|
177
|
+
camera.updateMatrixWorld();
|
|
178
|
+
const point = new Vector3();
|
|
179
|
+
let [vertices, inView, minX, maxX, minY, maxY] = [0, 0, 1, 0, 1, 0];
|
|
180
|
+
for (const line of [this.#travelled, this.#future]) {
|
|
181
|
+
const positions = line.geometry.getAttribute("position");
|
|
182
|
+
const drawn = line.geometry.drawRange.count;
|
|
183
|
+
vertices += drawn;
|
|
184
|
+
for (let i = 0; i < drawn; i += 1) {
|
|
185
|
+
point.fromBufferAttribute(positions, i).applyMatrix4(camera.matrixWorldInverse);
|
|
186
|
+
if (point.z >= 0)
|
|
187
|
+
continue;
|
|
188
|
+
point.applyMatrix4(camera.projectionMatrix);
|
|
189
|
+
if (Math.abs(point.x) > 1 || Math.abs(point.y) > 1)
|
|
190
|
+
continue;
|
|
191
|
+
const [x, y] = [(point.x + 1) / 2, (1 - point.y) / 2];
|
|
192
|
+
inView += 1;
|
|
193
|
+
minX = Math.min(minX, x);
|
|
194
|
+
maxX = Math.max(maxX, x);
|
|
195
|
+
minY = Math.min(minY, y);
|
|
196
|
+
maxY = Math.max(maxY, y);
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
return { id: this.body.id, visible: this.group.visible && vertices > 0, vertices, inView, minX, maxX, minY, maxY, lineMinX: minX, lineMaxX: maxX, lineMinY: minY, lineMaxY: maxY, axisDeg: 0, aspect: camera.aspect ?? 1, look: null };
|
|
200
|
+
}
|
|
162
201
|
/** Local (floating-origin) render position of anchor `index` as last drawn. */
|
|
163
202
|
anchorLocalPosition(index, out) {
|
|
164
203
|
return out.fromBufferAttribute(this.#anchors.geometry.getAttribute("position"), index);
|
package/src/app/mission.d.ts
CHANGED
|
@@ -20,6 +20,8 @@ export interface TrackedBody {
|
|
|
20
20
|
readonly anchorLabels?: readonly string[];
|
|
21
21
|
/** Published position discrepancy per reconstruction segment, in time order. */
|
|
22
22
|
readonly positionDiscrepancies?: readonly PositionDiscrepancy[];
|
|
23
|
+
/** The body the line is drawn against, at each sample's own time; absent: the scene centre. */
|
|
24
|
+
readonly lineFixedTo?: string;
|
|
23
25
|
/** The trajectory's own Provenance, passed through unchanged. */
|
|
24
26
|
readonly provenance?: Provenance;
|
|
25
27
|
}
|
package/src/app/pathRules.d.ts
CHANGED
|
@@ -13,13 +13,17 @@ export declare function mapPathKm(positionsKm: Float64Array, policy: ScalePolicy
|
|
|
13
13
|
* offsets, so a source need not be catalogued: it only has to say which catalogued body it is measured from.
|
|
14
14
|
*
|
|
15
15
|
* - orbit: every sample about its centre, the whole line carried to the centre's place from the scene centre at the clock time.
|
|
16
|
-
* - relative trail: each sample from the scene centre at that sample's own time
|
|
16
|
+
* - relative trail: each sample from `against` (default the scene centre) at that sample's own time; against another body it is then carried to the scene centre at the display time.
|
|
17
17
|
* - inertial trail: each sample in the common root frame at its own time, then from the scene centre at the display time.
|
|
18
18
|
*/
|
|
19
19
|
/** Orbit: the samples (about `center`) plus the one vector from the scene centre to `center` at the clock time. Returns the input when that vector is zero. */
|
|
20
20
|
export declare function orbitKm(samplesKm: Float64Array, center: CenterId, placement: ScenePlacement, clockUtcMs: number): Float64Array;
|
|
21
|
-
/**
|
|
22
|
-
|
|
21
|
+
/**
|
|
22
|
+
* Relative trail: sample i plus the offset from `native` to `against` at time i, so the line is drawn against `against` (default the scene
|
|
23
|
+
* centre: what an observer riding the centre saw). Returns the input when `native` is `against`. Fixing the line to another body leaves it
|
|
24
|
+
* about that body; `sceneOffsetKm(placement, against, displayUtcMs)` then carries it to the scene centre at the display time.
|
|
25
|
+
*/
|
|
26
|
+
export declare function relativeTrailKm(samples: PathSamples, native: CenterId, placement: ScenePlacement, against?: CenterId): Float64Array;
|
|
23
27
|
/** Inertial trail, first half: each sample in the root frame at its own time. Does not depend on the scene centre or the clock, so it is computed once. */
|
|
24
28
|
export declare function rootFrameKm(samples: PathSamples, native: CenterId, placement: ScenePlacement): Float64Array;
|
|
25
29
|
/** Inertial trail, second half: root-frame samples as seen from the scene centre at the display time. */
|
package/src/app/pathRules.js
CHANGED
|
@@ -12,7 +12,7 @@ export function mapPathKm(positionsKm, policy) {
|
|
|
12
12
|
* offsets, so a source need not be catalogued: it only has to say which catalogued body it is measured from.
|
|
13
13
|
*
|
|
14
14
|
* - orbit: every sample about its centre, the whole line carried to the centre's place from the scene centre at the clock time.
|
|
15
|
-
* - relative trail: each sample from the scene centre at that sample's own time
|
|
15
|
+
* - relative trail: each sample from `against` (default the scene centre) at that sample's own time; against another body it is then carried to the scene centre at the display time.
|
|
16
16
|
* - inertial trail: each sample in the common root frame at its own time, then from the scene centre at the display time.
|
|
17
17
|
*/
|
|
18
18
|
/** Orbit: the samples (about `center`) plus the one vector from the scene centre to `center` at the clock time. Returns the input when that vector is zero. */
|
|
@@ -20,13 +20,17 @@ export function orbitKm(samplesKm, center, placement, clockUtcMs) {
|
|
|
20
20
|
const offset = sceneOffsetKm(placement, center, clockUtcMs);
|
|
21
21
|
return offset === null ? samplesKm : shiftedBy(samplesKm, offset);
|
|
22
22
|
}
|
|
23
|
-
/**
|
|
24
|
-
|
|
25
|
-
|
|
23
|
+
/**
|
|
24
|
+
* Relative trail: sample i plus the offset from `native` to `against` at time i, so the line is drawn against `against` (default the scene
|
|
25
|
+
* centre: what an observer riding the centre saw). Returns the input when `native` is `against`. Fixing the line to another body leaves it
|
|
26
|
+
* about that body; `sceneOffsetKm(placement, against, displayUtcMs)` then carries it to the scene centre at the display time.
|
|
27
|
+
*/
|
|
28
|
+
export function relativeTrailKm(samples, native, placement, against = placement.center) {
|
|
29
|
+
if (samples.timesUtcMs.length === 0 || native === against)
|
|
26
30
|
return samples.positionsKm;
|
|
27
31
|
const out = Float64Array.from(samples.positionsKm);
|
|
28
32
|
samples.timesUtcMs.forEach((time, index) => {
|
|
29
|
-
const offset = placement.resolver.offsetKm(native,
|
|
33
|
+
const offset = placement.resolver.offsetKm(native, against, time);
|
|
30
34
|
for (let k = 0; k < 3; k += 1)
|
|
31
35
|
out[index * 3 + k] += offset[k];
|
|
32
36
|
});
|
package/src/app/sceneDebug.d.ts
CHANGED
|
@@ -3,7 +3,7 @@ import type { SimulationClock } from "../core/clock.js";
|
|
|
3
3
|
import type { ScalePolicy } from "../core/scalePolicy.js";
|
|
4
4
|
import type { StateResolver } from "../core/stateResolver.js";
|
|
5
5
|
import type { Camera } from "three";
|
|
6
|
-
import type {
|
|
6
|
+
import type { PathScreenReadout } from "./PathView.js";
|
|
7
7
|
import type { BodyScreenReadout } from "./sceneBodies.js";
|
|
8
8
|
import { type DebugReadout } from "./debugReadout.js";
|
|
9
9
|
import type { FloatingOrigin } from "./floatingOrigin.js";
|
|
@@ -23,7 +23,9 @@ export declare function publishSceneData(canvas: HTMLElement, state: {
|
|
|
23
23
|
* What the browser scripts read back about every drawn path line (`data-paths`, JSON): per path its id, whether it is drawn, its vertex count, how many
|
|
24
24
|
* vertices are in view and the share of the view they span (with the box's edges, the major axis angle on screen and the view's aspect), and for an orbit its look in force. This is the line itself, so a check that a path is drawn never depends on its label.
|
|
25
25
|
*/
|
|
26
|
-
export declare function publishPathData(canvas: HTMLElement, views: readonly
|
|
26
|
+
export declare function publishPathData(canvas: HTMLElement, views: readonly {
|
|
27
|
+
screenReadout(camera: Camera): PathScreenReadout;
|
|
28
|
+
}[], camera: Camera): void;
|
|
27
29
|
/**
|
|
28
30
|
* What the browser scripts read back about every point group (`data-points`, JSON): per group its id, whether it is drawn, its member count, how many members
|
|
29
31
|
* are in view (an even sample scaled up) and the share of the view they span. This is the dots themselves, so a check that a stream is drawn never depends on pixels.
|
package/src/app/sceneFrame.js
CHANGED
|
@@ -147,7 +147,7 @@ export function placeViews(ctx, t, placed, setLook) {
|
|
|
147
147
|
for (const layer of ctx.layers.bodySetLabels.current)
|
|
148
148
|
layer.update(setLook, hoverGain);
|
|
149
149
|
publishBodySets(canvas, views.bodySetViews, views.orbitSetViews, setLook, camera, size.width, size.height);
|
|
150
|
-
publishPathData(canvas, [...views.sunCentredViews, ...views.compositionPaths], camera);
|
|
150
|
+
publishPathData(canvas, [...views.sunCentredViews, ...views.compositionPaths, ...views.trackedViews], camera);
|
|
151
151
|
publishPointsData(canvas, views.groupViews, camera, views.bodySetViews);
|
|
152
152
|
return hoverGain;
|
|
153
153
|
}
|
|
@@ -44,4 +44,6 @@ export interface SolarSystemScalePolicy extends ScalePolicy {
|
|
|
44
44
|
readonly explanation: string;
|
|
45
45
|
}
|
|
46
46
|
export declare function createSolarSystemScale(options: SolarSystemScaleOptions): SolarSystemScalePolicy;
|
|
47
|
+
/** The Solar system scale: true distances with bodies enlarged. This one enlarges nothing itself; a viewer builds the working policy from the scene's declared factors, and `Scene.setScale` accepts it for a Sun-centred scene with an enlarged body. */
|
|
48
|
+
export declare const solarSystemScale: SolarSystemScalePolicy;
|
|
47
49
|
export {};
|
package/src/core/scalePolicy.js
CHANGED
|
@@ -58,3 +58,5 @@ export function createSolarSystemScale(options) {
|
|
|
58
58
|
mapRadius: (radiusKm, bodyId) => trueScale.mapRadius(radiusKm) * factorFor(bodyId),
|
|
59
59
|
});
|
|
60
60
|
}
|
|
61
|
+
/** The Solar system scale: true distances with bodies enlarged. This one enlarges nothing itself; a viewer builds the working policy from the scene's declared factors, and `Scene.setScale` accepts it for a Sun-centred scene with an enlarged body. */
|
|
62
|
+
export const solarSystemScale = createSolarSystemScale({ exaggeration: {}, defaultExaggeration: 1 });
|
|
@@ -0,0 +1,5 @@
|
|
|
1
|
+
import type { ExperienceDefinition } from "../app/experienceDefinition.js";
|
|
2
|
+
export declare const PROBE_START_UTC_MS: number;
|
|
3
|
+
/** The moment the made-up probe is at Earth. */
|
|
4
|
+
export declare const PROBE_FLYBY_UTC_MS: number;
|
|
5
|
+
export declare const syntheticProbeDefinition: ExperienceDefinition;
|
|
@@ -0,0 +1,38 @@
|
|
|
1
|
+
import { earth, mars, sun, venus } from "../api/bodies.js";
|
|
2
|
+
import { Scene } from "../api/scene.js";
|
|
3
|
+
import { solarSystemScale } from "../core/scalePolicy.js";
|
|
4
|
+
import { createOrbTwoBodyAdapter } from "../core/twoBodyAdapter.js";
|
|
5
|
+
export const PROBE_START_UTC_MS = Date.parse("2026-01-01T00:00:00Z");
|
|
6
|
+
const DAY_MS = 86_400_000;
|
|
7
|
+
/** The moment the made-up probe is at Earth. */
|
|
8
|
+
export const PROBE_FLYBY_UTC_MS = PROBE_START_UTC_MS + 200 * DAY_MS;
|
|
9
|
+
/** The engine's own ecliptic-to-equator rotation (row-major 3x3); its transpose turns equator vectors back to the ecliptic (STYLE-07: no second obliquity constant). */
|
|
10
|
+
const ECLIPTIC_TO_EQJ = createOrbTwoBodyAdapter().eclipticJ2000ToEqjMatrix();
|
|
11
|
+
const scene = new Scene().addBody(sun).addBody(venus, { enlarge: 60, orbit: true }).addBody(earth, { enlarge: 60, orbit: true }).addBody(mars, { enlarge: 60, orbit: true }).setTime(PROBE_START_UTC_MS);
|
|
12
|
+
/** A planet's place from the Sun at `timeUtcMs`, turned from the equator frame the scene answers in to the ecliptic frame the path is given in (km). */
|
|
13
|
+
function eclipticPlace(id, timeUtcMs) {
|
|
14
|
+
const [x, y, z] = scene.stateOf(id, timeUtcMs).positionKm;
|
|
15
|
+
const m = ECLIPTIC_TO_EQJ;
|
|
16
|
+
return [m[0] * x + m[3] * y + m[6] * z, m[1] * x + m[4] * y + m[7] * z, m[2] * x + m[5] * y + m[8] * z];
|
|
17
|
+
}
|
|
18
|
+
// A straight leg from a point 0.6 of the way from the Sun to Earth's place at the start, to Earth's place at the flyby, ten samples, then on along the same line for five more.
|
|
19
|
+
const from = eclipticPlace("earth", PROBE_START_UTC_MS).map((v) => v * 0.6);
|
|
20
|
+
const to = eclipticPlace("earth", PROBE_FLYBY_UTC_MS);
|
|
21
|
+
const samples = Array.from({ length: 16 }, (_, i) => ({ time: PROBE_START_UTC_MS + i * 20 * DAY_MS, positionKm: from.map((v, k) => v + ((to[k] - v) * i) / 10) }));
|
|
22
|
+
scene.addTrajectory({
|
|
23
|
+
id: "probe",
|
|
24
|
+
label: "Made-up probe",
|
|
25
|
+
samples,
|
|
26
|
+
center: "sun",
|
|
27
|
+
plane: "ecliptic-j2000",
|
|
28
|
+
lineFixedTo: "sun",
|
|
29
|
+
provenance: { sourceType: "illustrative", sources: ["Made up for the Sun-centred path test; not a real spacecraft"], accuracy: "None claimed. A straight line ending at Earth's place on day 200.", notes: "Exists to prove a recorded path can be drawn fixed to the Sun beside enlarged planets." },
|
|
30
|
+
description: "An invented probe that starts inside Earth's orbit and is at Earth on day 200.",
|
|
31
|
+
knownLimitations: ["Made up; not a real spacecraft.", "A straight line: it ignores the Sun's gravity."],
|
|
32
|
+
anchors: [{ id: "probe-flyby", time: PROBE_FLYBY_UTC_MS }],
|
|
33
|
+
});
|
|
34
|
+
scene.addEvents([{ id: "probe-flyby", label: "Made-up flyby of Earth", time: PROBE_FLYBY_UTC_MS }], { provenance: { sourceType: "illustrative", sources: ["Made up"], accuracy: "None claimed.", notes: "Not a real flyby." } });
|
|
35
|
+
scene.setScale(solarSystemScale);
|
|
36
|
+
scene.camera.follow("probe", { distance: 70_000 });
|
|
37
|
+
scene.camera.fitOrbit(mars);
|
|
38
|
+
export const syntheticProbeDefinition = scene.toDefinition();
|