astraeus 0.4.0 → 0.5.1
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +33 -0
- package/README.md +65 -11
- package/data/ephemerides/planets/planets.json +1 -1
- package/package.json +1 -1
- package/src/api/AstraeusScene.d.ts +9 -1
- package/src/api/AstraeusScene.js +26 -4
- package/src/api/AstraeusScene.node.js +26 -4
- package/src/api/data.js +11 -1
- package/src/api/errors.d.ts +1 -1
- package/src/api/index.d.ts +2 -1
- package/src/api/mount.d.ts +16 -0
- package/src/api/mount.js +13 -1
- package/src/api/mount.node.js +13 -1
- package/src/api/pathProvenance.d.ts +10 -0
- package/src/api/pathProvenance.js +34 -0
- package/src/api/scene.d.ts +7 -1
- package/src/api/scene.js +122 -26
- package/src/api/story.d.ts +45 -1
- package/src/api/story.js +73 -2
- package/src/api/sunOrbit.d.ts +3 -3
- package/src/api/sunOrbit.js +92 -24
- package/src/api/viewerLink.d.ts +40 -0
- package/src/api/viewerLink.js +86 -0
- package/src/app/App.d.ts +4 -1
- package/src/app/App.js +42 -6
- package/src/app/App.node.js +42 -6
- package/src/app/AstraeusScene.d.ts +7 -0
- package/src/app/AstraeusScene.js +3 -1
- package/src/app/BodySetView.js +3 -2
- package/src/app/KeplerPoints.d.ts +1 -1
- package/src/app/KeplerPoints.js +3 -2
- package/src/app/LayeredRender.js +1 -0
- package/src/app/OrbitSetView.js +5 -0
- package/src/app/PointsView.js +3 -2
- package/src/app/SceneLabels.d.ts +8 -0
- package/src/app/SceneLabels.js +15 -1
- package/src/app/SkyView.js +2 -0
- package/src/app/TrackedBodyView.js +3 -2
- package/src/app/bodyDraw.js +3 -2
- package/src/app/dotMaterial.d.ts +11 -0
- package/src/app/dotMaterial.js +38 -0
- package/src/app/experienceDefinition.d.ts +12 -0
- package/src/app/mission.d.ts +1 -1
- package/src/app/mission.js +1 -1
- package/src/app/openClock.d.ts +1 -1
- package/src/app/openClock.js +3 -0
- package/src/app/sceneContentsHooks.js +2 -1
- package/src/app/sceneFrame.d.ts +2 -2
- package/src/app/sceneFrame.js +6 -1
- package/src/app/sceneFraming.d.ts +1 -1
- package/src/app/sceneFraming.js +9 -3
- package/src/app/viewerPort.d.ts +33 -0
- package/src/app/viewerPort.js +1 -0
- package/src/assets/bodies/jupiter.js +2 -0
- package/src/assets/bodies/outerPlanetCatalogues.d.ts +1 -5
- package/src/assets/bodies/outerPlanetCatalogues.js +2 -6
- package/src/assets/bodies/outerPlanetRings.d.ts +5 -0
- package/src/assets/bodies/outerPlanetRings.js +6 -0
- package/src/assets/bodies/planetSystemMaps.js +6 -3
- package/src/assets/compositions.js +2 -1
- package/src/assets/visual.d.ts +1 -1
- package/src/core/bodies/io.js +2 -1
- package/src/core/bodies/jupiterMoons.d.ts +1 -1
- package/src/core/bodies/jupiterMoons.js +7 -6
- package/src/core/bodies/moon.d.ts +2 -0
- package/src/core/bodies/moon.js +4 -0
- package/src/core/bodies/moonSystem.d.ts +17 -1
- package/src/core/bodies/moonSystem.js +59 -7
- package/src/core/bodies/outerPlanetData.d.ts +0 -3
- package/src/core/bodies/outerPlanetData.js +1 -7
- package/src/core/bodies/outerPlanetRingData.d.ts +3 -0
- package/src/core/bodies/outerPlanetRingData.js +10 -0
- package/src/core/bodies/outerPlanets.js +1 -1
- package/src/core/bodies/planetMoons.js +12 -11
- package/src/core/body.d.ts +4 -0
- package/src/core/chebyshevEphemeris.d.ts +7 -1
- package/src/core/chebyshevEphemeris.js +24 -7
- package/src/core/clock.d.ts +8 -0
- package/src/core/clock.js +14 -0
- package/src/core/events.d.ts +2 -0
- package/src/core/pacing.d.ts +24 -0
- package/src/core/pacing.js +35 -0
- package/src/core/planetModels.d.ts +4 -1
- package/src/core/planetModels.js +6 -1
- package/src/core/planetSeries.d.ts +3 -0
- package/src/core/planetSeries.js +8 -1
- package/src/core/satelliteMeanElements.d.ts +2 -8
- package/src/core/satelliteMeanElements.js +2 -15
- package/src/core/siderealPeriod.d.ts +27 -0
- package/src/core/siderealPeriod.js +18 -0
- package/src/core/timeWindow.d.ts +2 -0
- package/src/core/timeWindow.js +4 -3
- package/src/shell/AstraeusShell.d.ts +6 -2
- package/src/shell/AstraeusShell.js +9 -5
- package/src/shell/AstraeusShell.node.js +9 -5
- package/src/shell/TimelineBar.d.ts +4 -2
- package/src/shell/TimelineBar.js +15 -6
- package/src/shell/TimelineBar.node.js +15 -6
- package/src/shell/experience.d.ts +3 -1
- package/src/shell/infoModel.js +5 -4
- package/src/shell/timelineModel.d.ts +2 -3
- package/src/shell/timelineModel.js +3 -11
- package/src/synthetic/syntheticJourneyScene.d.ts +9 -0
- package/src/synthetic/syntheticJourneyScene.js +76 -0
package/CHANGELOG.md
CHANGED
|
@@ -2,6 +2,39 @@
|
|
|
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.5.1 (2026-10-31)
|
|
6
|
+
|
|
7
|
+
First download of the packed example (`npm run measure:example`): 1,618,563 bytes raw, 461,100 bytes gzip (code and styles loaded on first open).
|
|
8
|
+
|
|
9
|
+
Near planets stay visible and ringed planets show their rings (O-048, G-014), from a second round of findings sent back by the outside interplanetary probe app built on 0.5.0.
|
|
10
|
+
|
|
11
|
+
- A planet or moon near the camera now stays visible however far the camera has zoomed out (O-048 T-204, I-117). The renderer uses a logarithmic depth buffer, so a Sun-centred scene whose far plane reaches a 170 AU path no longer loses Saturn at 0.01 AU to depth precision. Every custom shader in the engine carries the log-depth chunks, and a test fails for one that does not.
|
|
12
|
+
- Jupiter, Saturn, Uranus and Neptune now carry their rings in their one catalogue definition (O-048 T-205, I-118), so a scene that adds the planet through the public API draws the rings with their NSSDC fact-sheet source; the ring bands and the ring look sliders are unchanged. The planets demo no longer attaches rings itself. First download of the packed example (`npm run measure:example`) grows from 1,608,313 to 1,617,005 bytes raw and from 457,901 to 460,652 bytes gzip (the ring data now ships with the engine).
|
|
13
|
+
- `addBody(moon, { orbit: true })` draws the orbit line of any catalogued moon, not only the Moon and Io (O-048 T-206, I-119). One rule: one lap of the period the moon's catalogue definition carries (`orbitPeriodDays`, read once from its mean-element record), drawn about its planet; the Moon and Io draw as before, and a moon with no period (Phobos, Deimos) throws `no-orbit`. First download grows by 786 bytes raw, 243 bytes gzip (1,617,005 to 1,617,791 raw; 460,652 to 460,895 gzip).
|
|
14
|
+
- `addEvents` takes an optional `object` (a body or trajectory id) per event (O-048 T-207, I-120): the timeline's Go to, Previous and Next seek to the event and frame that object as `camera.lookAt` does; an event without one seeks as before, and an `object` the scene lacks throws `bad-event` naming the event and the id. Only code already in the first download changed; size is not re-measured.
|
|
15
|
+
- Overlapping labels no longer flicker at fast playback (O-048 T-208, I-121). One rule for every label: a label hidden by an overlap needs 14 px more clearance than the plain 6 px gap before it shows again, so two labels crossing swap winner once per crossing; the selected object's label still always wins and labels switched off stay hidden. Layout only; no State change and no new files in the package.
|
|
16
|
+
|
|
17
|
+
## 0.5.0 (2026-10-31)
|
|
18
|
+
|
|
19
|
+
First download of the packed example (`npm run measure:example`): 1,608,131 bytes raw, 457,845 bytes gzip (code and styles loaded on first open).
|
|
20
|
+
|
|
21
|
+
A historical probe journey can be told end to end (O-047, G-014), from findings sent back by an outside interplanetary probe app built on 0.4.0.
|
|
22
|
+
|
|
23
|
+
- Far-away markers and group dots are drawn round instead of square (one shared `dotMaterial`; size and colour unchanged).
|
|
24
|
+
- A path reaching past the planets can be zoomed out to whole (O-047 T-203, I-114). In a Sun-centred scene with a path about the Sun and no `camera.setReach` or `camera.fitOrbit`, the farthest zoom-out and the far plane now widen to cover twice the path's farthest distance from the Sun for the canvas shape (it never narrows the old default, and a declared reach still wins); proved with a path to 170 AU on a desktop and a phone shape. Before, the default stopped near the planets and the far plane (5,000 Earth radii) cut the path off.
|
|
25
|
+
- Fixed: a moon's orbit ring is centred on the clock, so at the last instant of the timeline it asked for positions the page had not loaded (a chunk error every frame). The loader now also fetches the year after the timeline's end for each moon where the data package ships it.
|
|
26
|
+
- Changed: playback in a scene with a timeline bar that does not loop now stops on the end (or start, at a negative speed) of the timeline instead of running past it. Before, the clock kept going and moons were asked for positions the page had not loaded, an error every frame.
|
|
27
|
+
- A path can carry different provenance along its length (O-047 T-198, I-113). `addTrajectory` takes `provenanceSpans`: a sorted, non-overlapping `{ start, end, provenance }` list inside the path (the shape of an activity's `provenance`), and the info card shows the span the clock is in; a gap, or no list, shows `provenance` (or the illustrative default) as before. Faults throw `bad-trajectory` naming the index.
|
|
28
|
+
- Playback can slow down for encounters and speed up for cruise (O-047 T-201, I-112). `setTimeline` takes `pacing`: spans `{ from, to, rate }` and event rules `{ near: { type, within }, rate }`, with optional `ramp` seconds; the speed eases between pieces (log-space smoothstep, a pure function of the time, so loops and seeks land right). The speed menu gains **Auto** in a scene with pacing; a speed a visitor or the host picks wins until Auto or `setRate("auto")` (new on the `mount` handle and the `AstraeusScene` `rate` prop; `bad-timeline` without pacing). Where pieces meet (a span and an event rule, or two event rules, either containing the other) the slowest speed applies, whatever order they are listed in. Overlapping spans and a rule whose event type has no events throw `bad-timeline` naming the field. New exported type `PacingInput`.
|
|
29
|
+
- A host page can read and set the viewer's time and speed (O-047 T-197, I-099). The `mount` handle gains `time`, `rate`, `setTime(time)`, `setRate(rate)` and `onChange(listener)`, and `mount` takes `onChange`; `AstraeusScene` gains `time`, `rate` and `onChange` props. `onChange` hears `{ time, rate, playing, cause }` for playback, a visitor's use of the timeline and the host's own calls. `setTime` outside the timeline throws `bad-time`; `setRate` takes only a speed the timeline offers, else `bad-timeline`; setting before `ready` throws `missing-data`. New exported types `ViewerChange` and `RateSource`.
|
|
30
|
+
- Changed: the speed menu shows exactly the `rates` a scene gives (I-106). Before, 1x, 1 hour, 1 day and 1 week per second were always added. A scene that gives no `rates` still offers 1 minute, 1 hour and 1 day per second. A scene that relied on the added speeds must now list them.
|
|
31
|
+
- Orbit lines and `camera.fitOrbit` now work for every planet (O-047 T-196, I-111). One rule, chosen by data coverage and never by name: one full turn of the body's own positions where they cover a whole turn from the opening time (the turn search now reaches Saturn's 29.5 years), else the two-body ellipse osculating at the opening time (Uranus, Neptune), whose info card says so and that perturbations are not drawn. The farthest distance for `fitOrbit` is worked out once in setup (at `toDefinition`, or at `prepare` once the planet series are in), so a failure reaches the host once through `ready`, not per frame.
|
|
32
|
+
- A body's positions can cover its own years (O-047 T-195, I-110 engine half). A moon-fit `index.json` may give each body a `span: { fromUtc, toUtc }` (optional; an index without one reads as before, the six shipped data packages are unchanged), and the engine answers each body only inside its own span and its centre's. The importer `tools/import/horizons-moons.mjs --only ... --from ... --to ...` merges a longer-span rebuild of chosen bodies into an existing index.
|
|
33
|
+
- New `SceneError` code `out-of-span`. A scene whose timeline reaches outside the years a loaded moon's data (or the built-in planet series, 1950 to 2045) covers now fails once, as `ready` rejecting at mount, naming the body, the data package and the span, instead of throwing on every frame.
|
|
34
|
+
- The main moons and each planet's system fitted back to 1950 (O-047 T-200, I-110 data half). `astraeus-data-jupiter` (Io, Europa, Ganymede, Callisto), `-saturn` (Mimas, Enceladus, Tethys, Dione, Rhea, Titan, Hyperion, Iapetus, Phoebe), `-uranus` (Miranda, Ariel, Umbriel, Titania, Oberon) and `-neptune` (Triton, Nereid) now answer from 1950-01-01, each with its planet; every other moon keeps 2010 to 2030. Worst fit error 0.59 m or less per moon, 0.05 m or less per planet; moon about planet through the provider against Horizons 0.53 m or less. The packages grew: Jupiter 22.9 to 30.9 MB packed, Saturn 40.0 to 53.5 MB, Uranus 32.6 to 40.6 MB, Neptune 17.8 to 18.5 MB (a page still downloads only the years it shows). The built-in planet series (`planets.json`) now runs 1950 to 2045 (was 1969), 329 kB to 432 kB raw (220 to 279 kB gzip); the example's first download is 1,608,131 bytes raw, 457,845 gzip (was 1,594,919 and 453,695). A mapped moon's `accuracy.validUtc` and its position note follow the span of its own data.
|
|
35
|
+
- Fixed: the fitted moons' time-scale table before 1972 followed monthly samples, so a Jupiter- or Saturn-centred position in 1961 to 1972 could be 1 to 7 km off in time terms; it is now sampled daily with a piece per step and per straight stretch (within 10 microseconds), and the end-to-end check back to 1950 is within 0.6 m.
|
|
36
|
+
- Fixed: asking the ephemeris for a body's bounds threw for Pluto's data, whose last chunk ends a day past its time-scale table.
|
|
37
|
+
|
|
5
38
|
## 0.4.0 (2026-10-31)
|
|
6
39
|
|
|
7
40
|
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).
|
package/README.md
CHANGED
|
@@ -67,7 +67,7 @@ scene.camera.fitOrbit(mars);
|
|
|
67
67
|
mount(document.getElementById("app"), scene);
|
|
68
68
|
```
|
|
69
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`.
|
|
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`, and a made-up 1977-to-170-AU journey past Jupiter and Saturn (moons at their dates, paced playback, provenance by stretch) at `?experience=synthetic-journey`.
|
|
71
71
|
|
|
72
72
|
## The public API
|
|
73
73
|
|
|
@@ -76,25 +76,25 @@ The full reference, generated from the types and doc comments, is at <https://as
|
|
|
76
76
|
| Call | What it does |
|
|
77
77
|
|---|---|
|
|
78
78
|
| `new Scene()` | An empty scene. Every method below returns the scene, so calls chain. |
|
|
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`
|
|
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. |
|
|
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: any catalogued moon with a period in its data (`moon`, `io`, `europa`, `ganymede`, `callisto`, `mimas`, `enceladus`, `tethys`, `dione`, `rhea`, `titan`, `iapetus`, `triton`, `charon`) about its planet, one lap of that period (the planet must be in the scene; `phobos` and `deimos` have no period in the catalogue and throw `no-orbit`), or, with `sun` in the scene, one turn round the Sun of any body that circles it (the planets, Earth's year, a body from `addBodyFromElements`), from the opening time: one full turn of the body's own positions where they cover a whole turn, else (Uranus and Neptune, whose turn outlasts the planet series) the two-body ellipse osculating at the opening time, which the info card says; anything else throws `no-orbit`. `camera.fitOrbit` follows the same rule. `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`. Jupiter, Saturn, Uranus and Neptune are drawn with their rings (bands at the NASA NSSDC ring fact sheet radii) whenever you add them; Mercury, Venus, Earth, Mars and Pluto have none. |
|
|
80
|
+
| `scene.addTrajectory({ id, label?, color?, center?, plane?, lineFixedTo?, labelReach?, samples, provenance?, provenanceSpans?, 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. `provenanceSpans` (a list of `{ start, end, provenance }`, sorted, not overlapping, inside the path) gives each stretch its own provenance, shown with the path as time moves (as an activity's `provenance`); where no span covers the time, `provenance` (or the illustrative default) shows; a fault throws `bad-trajectory` naming the index. |
|
|
81
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`. |
|
|
82
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`. |
|
|
83
83
|
| `scene.setTime(time)` | The moment the scene opens at. |
|
|
84
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`. |
|
|
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. |
|
|
85
|
+
| `scene.addEvents(events, { provenance? })` | Timed events on the timeline: `[{ id, label, time, type?, provenance?, object? }]`, ids unique. `object` is the id of a body or trajectory in the scene the event is about: the timeline's Go to (and Previous/Next) seeks to the event and frames that object as `camera.lookAt` does (it is selected and Focus shows pressed); an event without one only seeks. An `object` the scene lacks throws `bad-event` naming the event and the id when the scene is built. `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. |
|
|
86
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. |
|
|
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`. |
|
|
87
|
+
| `scene.setTimeline({ start, end, rates?, rate?, loop?, pacing? })` | 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`. The speed menu shows exactly the `rates` you give (ascending), and no others; without `rates` it offers 1 minute, 1 hour and 1 day per second. `pacing` slows playback for encounters and speeds it up for cruise, see "Paced playback" below. With a timeline bar and no `loop`, playback stops on the timeline's end instead of running past it. |
|
|
88
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`. |
|
|
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. |
|
|
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`. Without `setReach` or `fitOrbit`, a Sun-centred scene with a path about the Sun widens its farthest zoom-out to fit that path whole (twice its farthest Sun distance, for the live canvas shape), so a path out to 170 AU can be seen entire. 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. |
|
|
90
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")` |
|
|
91
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`. |
|
|
92
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;` |
|
|
93
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. |
|
|
94
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. |
|
|
95
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. |
|
|
96
|
-
| `mount(element, scene, { data? })` | Draws the scene with the full viewer. Returns `{ ready, unmount() }`. `data` is a list of data packages (below). |
|
|
97
|
-
| `<AstraeusScene scene data? onReady? onError? />` | The same viewer as a React component (below). |
|
|
96
|
+
| `mount(element, scene, { data?, onChange? })` | Draws the scene with the full viewer. Returns `{ ready, unmount(), time, rate, setTime(t), setRate(r), onChange(fn) }`. `data` is a list of data packages (below); the time and speed members are described under "Reading and setting the time". |
|
|
97
|
+
| `<AstraeusScene scene data? onReady? onError? time? rate? onChange? />` | The same viewer as a React component (below). |
|
|
98
98
|
| `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. |
|
|
99
99
|
|
|
100
100
|
Checking accuracy and records without a scene: the class limits are root exports (`APPROXIMATE_LIMIT_FRACTION`, `INDICATIVE_LIMIT_FRACTION`), `classifyPositionError(maxFraction)` returns `"approximate"`, `"indicative"` or `null` (neither) for a measured largest error fraction, and `parseElementsBodyRecord(record)` validates an elements record (the same check `addBodyFromElements` makes, throwing `bad-element` naming the field):
|
|
@@ -125,6 +125,58 @@ export const App = () => (
|
|
|
125
125
|
|
|
126
126
|
Props: `scene`, `data` (as for `mount`), `onReady`, `onError` (a bad scene or failed data load), `className` and `style` for the wrapper. Build the `Scene` once (outside the component or in `useMemo`): a new `Scene` object rebuilds the viewer. It needs React 19 and the peer dependencies (`react`, `react-dom`, `@react-three/fiber`, `three`). See `examples/hello-react` in the repository.
|
|
127
127
|
|
|
128
|
+
## Reading and setting the time
|
|
129
|
+
|
|
130
|
+
The viewer has one clock. A host page reads it, moves it and hears about changes, from the `mount` handle or from `AstraeusScene` props. Time is Unix milliseconds UTC; speed is simulated seconds per real second.
|
|
131
|
+
|
|
132
|
+
| Name | What it does |
|
|
133
|
+
|------|--------------|
|
|
134
|
+
| `handle.time`, `handle.rate` | The clock now. `undefined` until `ready` has resolved and after `unmount`. |
|
|
135
|
+
| `handle.setTime(time)` | Moves the viewer to `time` (ISO text, a `Date` or milliseconds). Outside the timeline throws `bad-time`. Before `ready` or after `unmount` throws `missing-data`. |
|
|
136
|
+
| `handle.setRate(rate)` | Sets the speed to one the timeline offers (`setTimeline({ rates })`). Any other number throws `bad-timeline`: the speed menu always shows what is running, so a custom speed is refused, not added. `handle.setRate("auto")` hands the speed back to the scene's pacing (below); without pacing it throws `bad-timeline`. |
|
|
137
|
+
| `handle.onChange(fn)` or `mount(..., { onChange })` | `fn({ time, rate, playing, cause })` on every change; returns a function that stops it. `cause` is `playback` (the clock ran on; about ten calls a second while playing), `visitor` (someone used the timeline) or `host` (your own `setTime` or `setRate`). Nothing arrives after `unmount`. |
|
|
138
|
+
| `<AstraeusScene time rate onChange />` | `time` and `rate` are applied once the viewer is drawn and again whenever their value changes (a new `Date` of the same moment does not seek again); they are not controlled values, so read the live time from `onChange`. A bad one goes to `onError`. |
|
|
139
|
+
|
|
140
|
+
```ts
|
|
141
|
+
const mounted = mount(el, scene);
|
|
142
|
+
await mounted.ready;
|
|
143
|
+
mounted.setTime("2026-08-12T21:00:00Z"); // jump to the flyby
|
|
144
|
+
mounted.setRate(3600); // one hour per second (must be in setTimeline's rates)
|
|
145
|
+
const stop = mounted.onChange(({ time, cause }) => {
|
|
146
|
+
if (cause !== "host") console.log(new Date(time).toISOString());
|
|
147
|
+
});
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
The speed menu shows exactly the `rates` the scene gives (`setTimeline({ rates })`) and no others.
|
|
151
|
+
|
|
152
|
+
### Paced playback
|
|
153
|
+
|
|
154
|
+
A long journey wants fast cruising and slow encounters. `setTimeline` takes `pacing`, a list of pieces; outside every piece playback runs at the timeline's `rate`.
|
|
155
|
+
|
|
156
|
+
| Piece | Meaning |
|
|
157
|
+
|-------|---------|
|
|
158
|
+
| `{ from, to, rate, ramp? }` | Plays at `rate` between the two moments. |
|
|
159
|
+
| `{ near: { type, within }, rate, ramp? }` | Plays at `rate` within `within` seconds (simulated) of every event whose `type` matches (`addEvents`). |
|
|
160
|
+
|
|
161
|
+
Speeds ease between pieces in log space over `ramp` simulated seconds (default: `within` for an event rule, a tenth of the span for a span; `ramp: 0` steps), so a jump from cruise to encounter is smooth both ways. The paced speed depends only on the time, so seeking or looping lands on the right speed at once. Spans may not overlap (touching is fine); where an event rule meets a span or another rule, the slowest speed wins, whichever contains the other and in whatever order they are listed. A piece's `rate` is any positive number and need not be in `rates`. Mistakes throw `bad-timeline` naming the field (`pacing[1].rate`); an event `type` that matches no event is refused too, since a typo would otherwise slow nothing.
|
|
162
|
+
|
|
163
|
+
With pacing the speed menu gains an **Auto** choice, selected from the start. Picking a speed (menu, or `setRate(number)`) takes over until the visitor chooses Auto or the host calls `setRate("auto")`. `onChange` reports the speed pacing runs at (`cause: "playback"`), and `handle.rate` reads it.
|
|
164
|
+
|
|
165
|
+
```ts
|
|
166
|
+
const scene = new Scene()
|
|
167
|
+
.addBody(earth)
|
|
168
|
+
.addEvents([{ id: "jupiter", label: "Jupiter flyby", time: "2030-06-01", type: "flyby" }])
|
|
169
|
+
.setTimeline({
|
|
170
|
+
start: "2030-01-01", end: "2031-01-01", rate: 86_400, rates: [3_600, 86_400, 604_800],
|
|
171
|
+
pacing: [
|
|
172
|
+
{ from: "2030-02-01", to: "2030-04-01", rate: 604_800 }, // a week per second through the long coast
|
|
173
|
+
{ near: { type: "flyby", within: 3 * 86_400 }, rate: 600 }, // ten minutes per second within 3 days of each flyby
|
|
174
|
+
],
|
|
175
|
+
});
|
|
176
|
+
mounted.setRate(3_600); // the visitor's choice wins ...
|
|
177
|
+
mounted.setRate("auto"); // ... until it is released
|
|
178
|
+
```
|
|
179
|
+
|
|
128
180
|
## Inside someone else's page
|
|
129
181
|
|
|
130
182
|
The viewer is built to sit in a host page without taking it over. It never changes `document.title`. It isolates its own layers (`isolation: isolate` on the element given to `mount` and on the `AstraeusScene` wrapper), so its `z-index` values (0 to 9) stay inside the viewer and cannot cover or sit under your page's layers; `mount` does not restore the element's old `isolation` on `unmount`. Its Escape handlers (story panel, phone drawer, switch panel) ignore a keydown your page already stopped with `preventDefault()`. It honours `prefers-reduced-motion`: the viewer's own animations and transitions are switched off.
|
|
@@ -145,16 +197,18 @@ window.addEventListener("vite:preloadError", () => window.location.reload());
|
|
|
145
197
|
|
|
146
198
|
For tests, the package has a `node` export condition: Node and Vitest's Node environment import a copy of the package without the stylesheet import, so `new Scene()...toDefinition()` works with no `test.server.deps.inline` setting. The jsdom and happy-dom Vitest environments also take the `node` condition, so the viewer's CSS is not loaded there; this does not matter for tests that check scene definitions or behaviour. Bundlers do not use the `node` condition and load the normal build.
|
|
147
199
|
|
|
148
|
-
First download: the packed `examples/hello-scene` loads 1,
|
|
200
|
+
First download: the packed `examples/hello-scene` loads 1,618,563 bytes (461,100 gzip) of code and styles, measured at this commit on first open (`npm run measure:example`; pictures and data files are not counted).
|
|
149
201
|
|
|
150
202
|
## What `astraeus-data` adds
|
|
151
203
|
|
|
152
|
-
The engine alone draws the Sun, Earth, Moon and the eight planets with their pictures and positions for
|
|
204
|
+
The engine alone draws the Sun, Earth, Moon and the eight planets with their pictures and positions for 1950 to 2045. Everything heavier is a separate, optional package you import and hand to `mount`, so you only download what you use. A moon-position package is thousands of small files; your build copies them as separate files and the page fetches only the ones for the time window on screen (each chunk URL ends `?no-inline`, so Vite does not paste them into your script):
|
|
153
205
|
|
|
154
206
|
| Package | Adds | Download |
|
|
155
207
|
|---|---|---|
|
|
156
208
|
| `astraeus-data` | Moon pictures (Io to Charon), the 8k Venus map, the Milky Way | about 39 MB |
|
|
157
|
-
| `astraeus-data-jupiter`, `-saturn`, `-uranus`, `-neptune`, `-mars`, `-pluto` | Moon positions for that planet's system |
|
|
209
|
+
| `astraeus-data-jupiter`, `-saturn`, `-uranus`, `-neptune`, `-mars`, `-pluto` | Moon positions for that planet's system | 1.5 to 53 MB each (Saturn 53, Uranus 41, Jupiter 31, Neptune 19, Mars 5, Pluto 1.5) |
|
|
210
|
+
|
|
211
|
+
Years each package covers: the main moons and the planet reach back to 1950 in `astraeus-data-jupiter` (Io, Europa, Ganymede, Callisto), `-saturn` (Mimas, Enceladus, Tethys, Dione, Rhea, Titan, Hyperion, Iapetus, Phoebe), `-uranus` (Miranda, Ariel, Umbriel, Titania, Oberon) and `-neptune` (Triton, Nereid), 1950 to 2030; every other moon, and all of `-mars` and `-pluto`, covers 2010 to 2030. A scene whose timeline reaches outside a body's years fails once at mount with `SceneError` code `out-of-span`.
|
|
158
212
|
|
|
159
213
|
```js
|
|
160
214
|
import { Scene, jupiter, io, mount } from "astraeus";
|