astraeus 0.9.2 → 0.9.3

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 CHANGED
@@ -2,6 +2,12 @@
2
2
 
3
3
  Versions follow [semantic versioning](https://semver.org). While the version starts with `0.`, the public API (the names exported from `astraeus`) may still change between minor versions; each change is listed here.
4
4
 
5
+ ## 0.9.3 (2026-11-20)
6
+
7
+ First download of the packed example (`npm run measure:example`): 1,775,354 bytes raw, 510,719 bytes gzip (code and styles loaded on first open), against 1,773,029 raw and 510,085 gzip at 0.9.2 (+2,325 raw, +634 gzip). Additions only (G-021); every `astraeus-data*` package still peers on `>=0.9.0 <0.10.0`.
8
+
9
+ - Added: `GroupOrbitInput.meanAnomalyDeg`, an orbit's catalogue mean anomaly in degrees at its own `time` (its epoch); finite, wrapping to 0 to 360. When every orbit of an `addGroup` gives it, each dot sits at its record's real position, advanced from its epoch by unperturbed two-body motion about the centre with the same GM the group moves with, instead of the illustrative even spread. An orbit without `time` has its mean anomaly read at `referenceTime`; when every orbit gives `time`, `referenceTime` makes no difference. The card and `scene.groups[].provenance` keep the caller's `sourceType`, sources and accuracy, add the note "Each dot's position along its orbit comes from its record's mean anomaly at the record's epoch, advanced by unperturbed two-body motion about the centre.", and replace the illustrative placement limit with one on two-body drift from each epoch. A list where some orbits give it and some do not, a non-finite value, or `seed` or `clump` with it throws `bad-group` (no new error code). Groups without it are unchanged, card text included. 110,000 orbits in one group build in about 0.4 s and fill once in about 0.1 s in Node.
10
+
5
11
  ## 0.9.2 (2026-11-17)
6
12
 
7
13
  First download of the packed example (`npm run measure:example`): 1,773,029 bytes raw, 510,085 bytes gzip (code and styles loaded on first open), against 1,764,446 raw and 507,330 gzip at 0.9.1 (+8,583 raw, +2,755 gzip). Additions and fixes only (G-020); every `astraeus-data*` package still peers on `>=0.9.0 <0.10.0`.
package/README.md CHANGED
@@ -87,7 +87,7 @@ The full reference, generated from the types and doc comments, is at <https://as
87
87
  | `scene.addBodyFromElements(record, options?)` | Your own body that circles the Sun, from published orbit elements: `record` is `{ id, label, elements: { semiMajorAxisAu, eccentricity, inclinationDeg, ascendingNodeDeg, argumentOfPerihelionDeg, meanAnomalyDeg or perihelionJdTdb }, epoch: { jd, timeScale, ttMinusUtcSeconds? }, plane: "ecliptic-j2000", source: { name, url, solution, accessed }, radius?, accuracy: { classification, statement, valid: { start, end }, limitations }, marker?: { color, sizePx } }`; `accuracy.valid` is `{ start, end }`, each ISO text such as `2030-01-01T00:00:00Z` (a record is usually JSON), a `Date` or milliseconds. Drawn as a marker on unperturbed two-body motion about the Sun; colours: with a `color` option (`addBody`'s) the orbit line and the label take it and the dot takes `marker.color`, and without one all three take `marker.color` (default a pale blue); the source, accuracy and limits show on its info card, with a live "Distance from Sun" row. `options` are `addBody`'s, `shownDuring` included (`{ orbit: true }` draws its whole orbit from periapsis, smooth even for a sharp comet orbit). A bad record throws `bad-element` naming the field; a repeated id throws `duplicate-id`. |
88
88
  | `scene.addBodySet({ id, families, members, provenance, center?, bodies?, centerGmKm3S2?, balancePoint?, orbitHistoryMs? })` | Many small bodies about one centre as one batch of dots, each selectable with an info card, with orbit lines coloured by family. `families` is one to sixteen of `{ id, label, color?, brightness? }` (colour a CSS hex colour, default the palette in family order; `brightness` the orbit-line multiplier, default 1). A member is `{ id, family, label?, radiusKm?, elements?, description?, facts?, provenance?, knownLimitations?, listed? }`: with no `elements` it is a listed moon of `center` (`listedMoons(planet)`; its positions come through `data`, as for `addBody`, and its label and radius default to the list's); with `elements` (`semiMajorAxisKm`, `eccentricity`, `inclinationDeg`, `raanDeg`, `argumentOfPeriapsisDeg`, `trueAnomalyDeg`, `time?`, `plane?`) it is a made-up member on two-body motion and needs `label` and `radiusKm`. A set is one kind or the other. `center` is a body in the scene (default the scene's first); `centerGmKm3S2` sizes each orbit line to one lap (default the centre's moon system, else its catalogue record; neither is `bad-body-set`). `bodies` are bodies added with `addBody` that belong to a family: their orbit lines take its colour, and one with no `orbit` of its own, if it is a listed moon of `center`, gets its line in this batch. `balancePoint` (`{ body, gmKm3S2 }`, a member or such a body) draws the lines about the balance point of the centre and that body (default the centre's moon system's own when its body is drawn here). `orbitHistoryMs` loads positions that long before the window so a line can reach back (default 0). Members are not in the Object menu unless `listed: true`. `stateOf` and `provenanceOf` accept member ids; story panels may name them; a view cannot name a set or a member. A repeated id throws `duplicate-id`; a mistake throws `bad-body-set`. |
89
89
  | `scene.addPlaces(body, { categories, places, provenance, knownLimitations? })` | The tagged surface places of one body, drawn as markers on it and opened in the information panel. `categories` are `{ key, label, color }` (a CSS hex colour); `places` are `{ id, name, kind, category, latitudeDeg, longitudeDeg, description, details? }` (`id` unique within the body, `kind` shown as the place's kind such as "Crater", an unknown `category` draws white, longitude east-positive as the marker draws it, coordinates kept exactly as given, `details` card facts). `provenance` is shown with every place (PROV-01). The body must be in the scene when it is built; a second call for one body throws `duplicate-id`; a mistake throws `bad-places`. The place lists of 24 bodies ship as data in `astraeus-data` (`astraeus-data/bodies/<body>/{features,categories,map,overview}.json`, with `catalogue.json`); an app converts them to this input. |
90
- | `scene.addGroup({ id, orbits, plane, label?, center?, color?, dotSizePx?, referenceTime?, seed?, clump?, refillAfterMs?, refillSliceMs?, provenance?, description?, knownLimitations? })` | A list of orbits drawn as one group of dots: `orbits` is `[{ id, semiMajorAxisKm, eccentricity, inclinationDeg, raanDeg, argumentOfPeriapsisDeg, time? }]` (bound orbits, ids distinct), measured about `center` (default the scene's centre; it must be in the scene) in `plane`, which you must give (`"ecliptic-j2000"` or `"EQJ"`; a group without one throws `bad-group`). One colour (`color`, a hex colour), dot size (`dotSizePx`), menu item, info card, provenance and known limits. Where each dot sits along its orbit is a drawing choice, marked illustrative: an even spread shuffled by `seed`, fixed at `referenceTime` (default the opening time), then two-body motion. `clump: { near, fraction, widthDeg }` draws a share of the dots near a body's place along its orbit (a model; the body must be in the scene and not the centre; it may be one added with `addBodyFromElements` before the group). `refillAfterMs` is how often the dots are placed again; `refillSliceMs` (0 or more) is how much of a frame may go on computing the next fill ahead of time. 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`. |
90
+ | `scene.addGroup({ id, orbits, plane, label?, center?, color?, dotSizePx?, referenceTime?, seed?, clump?, refillAfterMs?, refillSliceMs?, provenance?, description?, knownLimitations? })` | A list of orbits drawn as one group of dots: `orbits` is `[{ id, semiMajorAxisKm, eccentricity, inclinationDeg, raanDeg, argumentOfPeriapsisDeg, time?, meanAnomalyDeg? }]` (bound orbits, ids distinct), measured about `center` (default the scene's centre; it must be in the scene) in `plane`, which you must give (`"ecliptic-j2000"` or `"EQJ"`; a group without one throws `bad-group`). One colour (`color`, a hex colour), dot size (`dotSizePx`), menu item, info card, provenance and known limits. Where each dot sits along its orbit is either measured or a drawing choice. Measured: when every orbit gives `meanAnomalyDeg` (its catalogue mean anomaly in degrees at its own `time`, the record's epoch; finite, wrapping to 0 to 360), each dot sits at that record's position, advanced by unperturbed two-body motion about the centre (mean motion `√(GM / a³)` from the centre's GM); an orbit without `time` has its mean anomaly read at `referenceTime`, so `referenceTime` makes no difference only when every orbit gives `time`; `seed` or `clump` with it throws `bad-group`, and so does a list where some orbits give it and some do not (naming the first without one). The dots drift from the true positions the further the time is from each epoch, since perturbations are ignored. Otherwise the placement is marked illustrative: an even spread shuffled by `seed`, fixed at `referenceTime` (default the opening time), then two-body motion. `clump: { near, fraction, widthDeg }` draws a share of the dots near a body's place along its orbit (a model; the body must be in the scene and not the centre; it may be one added with `addBodyFromElements` before the group). `refillAfterMs` is how often the dots are placed again; `refillSliceMs` (0 or more) is how much of a frame may go on computing the next fill ahead of time. A measured group's card keeps your `provenance` (its `sourceType`, sources and accuracy) and adds a note that each position comes from its record's mean anomaly, and a limit on two-body drift from each epoch; an illustrative group's card shows "illustrative" as its source type, with the elements' own type in the accuracy sentence. The id joins the camera menu (`focus-<id>`, `follow-<id>`) and may be a panel's `object`. A mistake throws `bad-group`. |
91
91
 
92
92
  ### Time, events and story
93
93
 
@@ -155,7 +155,7 @@ A sky-only viewer (Look out and its switches, no orbit-camera buttons): `scene.c
155
155
  | `scene.picker` | The picker as set (`{ id, label, options, value }`, frozen), or `undefined` before `setPicker`. |
156
156
  | `scene.places` | `{ body, count }` per `addPlaces`, in the order added; a fresh frozen list on every read. |
157
157
  | `scene.skyFigures` | `{ id, label, kind, listed, provenance, description?, facts? }` per `addSkyFigures` figure, in the order added; a fresh frozen list on every read. |
158
- | `scene.groups` | `{ id, label, count, center, plane, provenance, description, knownLimitations }` per `addGroup`: `provenance`, `description` and `knownLimitations` are what the group's card shows (always illustrative, with the engine's placement and motion limits). |
158
+ | `scene.groups` | `{ id, label, count, center, plane, provenance, description, knownLimitations }` per `addGroup`: `provenance`, `description` and `knownLimitations` are what the group's card shows (the caller's source type for measured positions, else illustrative; with the engine's placement and motion limits). |
159
159
  | `scene.activities` | `{ id, label, unit, windowStartUtcMs, windowEndUtcMs, peak: { label, value, timeUtcMs? }, samples: [{ timeUtcMs, value }], provenance?: [{ stretchStartUtcMs, stretchEndUtcMs, provenance }], type? }` per `addActivity`, in the order added; a fresh frozen copy. `peak.value` is the highest sample when no peak moment was given. |
160
160
  | `scene.events` | `{ id, label, timeUtcMs, type?, object?, withinSeconds?, provenance? }` per `addEvents`, sorted by time; `provenance` is the event's own, else the batch's. |
161
161
  | `scene.panels` | `{ id, timeUtcMs?, title, body, details, provenance, object? }` per `addStoryPanels` (the actions are not read): the moment panels sorted by time, the times resolved as `mount` resolves them, then the steps (no `timeUtcMs`) in the order added (a bad panel throws `bad-panels`). |
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "astraeus",
3
- "version": "0.9.2",
3
+ "version": "0.9.3",
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",
@@ -4,7 +4,7 @@ import type { TimeBounds } from "../core/trajectory.js";
4
4
  import { type BodyCatalogue } from "../assets/catalogue.js";
5
5
  import type { GroupLayer } from "../app/experienceDefinition.js";
6
6
  import { type TimeInput } from "./time.js";
7
- /** One listed orbit of a group: its own id (the record it came from) and its shape and orientation. Angles in degrees, length in km. The orbit carries no position along itself; the group chooses that. */
7
+ /** One listed orbit of a group: its own id (the record it came from), its shape and orientation, and optionally where along itself it is (`meanAnomalyDeg`). Angles in degrees, length in km. */
8
8
  export interface GroupOrbitInput {
9
9
  /** The orbit's own id, such as the record it was listed under; distinct within the group. */
10
10
  readonly id: string;
@@ -14,8 +14,10 @@ export interface GroupOrbitInput {
14
14
  readonly inclinationDeg: number;
15
15
  readonly raanDeg: number;
16
16
  readonly argumentOfPeriapsisDeg: number;
17
- /** The moment the record was measured, kept with the record; it does not place the dot. Defaults to the group's reference time. */
17
+ /** The moment the record was measured (its epoch); it places the dot only with `meanAnomalyDeg`. Defaults to the group's reference time. */
18
18
  readonly time?: TimeInput;
19
+ /** The mean anomaly in degrees at `time`, as a catalogue lists it (finite; wraps). Give it for every orbit or none: then each dot sits at its record's position. A mix throws `bad-group`. */
20
+ readonly meanAnomalyDeg?: number;
19
21
  }
20
22
  /** A stated share of the dots drawn near a body's position along its orbit: a model, not a measurement. */
21
23
  export interface GroupClumpInput {
@@ -34,8 +36,8 @@ export interface GroupReadoutInput {
34
36
  }
35
37
  /**
36
38
  * A group of listed orbits drawn as one set of dots: one dot per orbit, on its own ellipse, one colour and dot size, one menu item and one info card.
37
- * The group's id joins the camera menu (`focus-<id>`, `follow-<id>`) and may be named by story panels. The orbits' shapes are as listed; where each dot sits
38
- * along its orbit is a drawing choice (an even spread, shuffled by `seed`) and the info card says so.
39
+ * The group's id joins the camera menu (`focus-<id>`, `follow-<id>`) and may be named by story panels. The orbits' shapes are as listed. Where each dot sits
40
+ * along its orbit is measured when every orbit gives `meanAnomalyDeg`, else a drawing choice (an even spread, shuffled by `seed`); the card says which.
39
41
  */
40
42
  export interface GroupInput {
41
43
  /** The group's id: its menu item, camera target and panel `object`. Not shared with any body, path or other group. */
@@ -54,16 +56,17 @@ export interface GroupInput {
54
56
  readonly dotSizePx?: number;
55
57
  /** The moment each orbit's dot is placed from (then it moves by two-body motion); the scene's opening time when absent. */
56
58
  readonly referenceTime?: TimeInput;
57
- /** A whole number from 0 to 4294967295 that shuffles which orbit takes which place along its orbit; the same seed gives the same picture. Default 0. */
59
+ /** A whole number from 0 to 4294967295 that shuffles which orbit takes which place along its orbit; the same seed gives the same picture. Default 0. Not with `meanAnomalyDeg` (`bad-group`). */
58
60
  readonly seed?: number;
59
- /** Draws a share of the dots near a body's position along its orbit. */
61
+ /** Draws a share of the dots near a body's position along its orbit. Not with `meanAnomalyDeg` (`bad-group`). */
60
62
  readonly clump?: GroupClumpInput;
61
63
  /** How often, in simulated milliseconds, the dots are placed again exactly; between fills the picture blends the two nearest. Presentation only. Default five minutes. */
62
64
  readonly refillAfterMs?: number;
63
65
  /** Milliseconds of each frame the dots layer may spend computing the next fill ahead of time, so a large group does not hitch; 0 or a positive number. 0 makes every fill whole in one frame. Presentation only. Default 8. */
64
66
  readonly refillSliceMs?: number;
65
67
  /**
66
- * Where the orbit list came from. The group's own card always shows `sourceType` "illustrative", because the position along each orbit is a drawing choice;
68
+ * Where the orbit list came from. With `meanAnomalyDeg` the card keeps this, with a note that each position comes from its record's mean anomaly.
69
+ * Otherwise the group's own card shows `sourceType` "illustrative", because the position along each orbit is a drawing choice;
67
70
  * the orbits' `sourceType` here is kept in the accuracy line as "Orbit elements are as listed (<sourceType>); the position along each orbit is illustrative."
68
71
  * Your `sources` stay, and the group appends this note to your `notes`: "Each orbit's shape and orientation come from its record, but the records give no
69
72
  * position along the orbit: that position is an even spread of mean anomaly at the reference time, a drawing choice (illustrative), advanced by unperturbed
@@ -85,11 +88,11 @@ export interface PlannedGroup {
85
88
  }
86
89
  /** Checks what can be checked before the scene is complete; the centre, the clump body and the id clash with other things are checked at build. */
87
90
  export declare function planGroup(input: GroupInput, catalogue?: BodyCatalogue): PlannedGroup;
88
- /** The provenance a group's card shows (`Scene.groups`): the engine's illustrative statement over the caller's source. */
91
+ /** The provenance a group's card shows (`Scene.groups`): the caller's source with the engine's placement statement (measured or illustrative). */
89
92
  export declare function groupCardProvenance(input: GroupInput): Provenance;
90
93
  /** The words on a group's card: the caller's, else a sentence stating the count. */
91
94
  export declare function groupDescription(input: GroupInput, count: number): string;
92
- /** The known limits on a group's card: the caller's, then the engine's own about placement, the clump and motion. */
95
+ /** The known limits on a group's card: the caller's, then the engine's own about placement (measured or illustrative), the clump and motion. */
93
96
  export declare function groupLimitations(input: GroupInput, catalogue: BodyCatalogue): readonly string[];
94
97
  /** Builds the draw layer: the listed-orbit group and its one shell item. `center` and `openUtcMs` come from the finished scene; a group error from the engine is renamed `bad-group`. */
95
98
  export declare function buildGroupLayer(plan: PlannedGroup, catalogue: BodyCatalogue, center: BodyId, openUtcMs: number, window: TimeBounds): GroupLayer;
package/src/api/group.js CHANGED
@@ -15,7 +15,11 @@ export function planGroup(input, catalogue = builtInCatalogue) {
15
15
  throw bad(id, "the group needs a non-empty id");
16
16
  if (input.plane !== "ecliptic-j2000" && input.plane !== "EQJ")
17
17
  throw bad(id, `plane must be "ecliptic-j2000" or "EQJ", got ${input.plane === undefined ? "nothing" : JSON.stringify(input.plane)}; say which plane the elements are given in`);
18
- checkOrbits(id, input.orbits);
18
+ const measured = checkOrbits(id, input.orbits);
19
+ if (measured && input.seed !== undefined)
20
+ throw bad(id, "seed only shuffles illustrative positions; every orbit gives meanAnomalyDeg, so the positions are measured: drop seed");
21
+ if (measured && input.clump !== undefined)
22
+ throw bad(id, "clump only shapes illustrative positions; every orbit gives meanAnomalyDeg, so the positions are measured: drop clump");
19
23
  checkLook(id, input);
20
24
  if (input.clump !== undefined)
21
25
  checkClump(id, input.clump, catalogue);
@@ -24,9 +28,11 @@ export function planGroup(input, catalogue = builtInCatalogue) {
24
28
  throw new SceneError("unknown-body", `addGroup("${id}"): centre "${String(input.center)}" is not a catalogued body`);
25
29
  return { id, label: input.label ?? id, input };
26
30
  }
31
+ /** Checks ids and the all-or-none mean anomaly rule; returns whether the group has measured positions. */
27
32
  function checkOrbits(id, orbits) {
28
33
  if (!Array.isArray(orbits) || orbits.length === 0)
29
34
  throw bad(id, "the group needs at least one orbit; the list is empty");
35
+ const measured = orbits.some((orbit) => orbit?.meanAnomalyDeg !== undefined);
30
36
  const seen = new Set();
31
37
  for (const orbit of orbits) {
32
38
  if (typeof orbit?.id !== "string" || orbit.id === "")
@@ -34,7 +40,20 @@ function checkOrbits(id, orbits) {
34
40
  if (seen.has(orbit.id))
35
41
  throw bad(id, `orbit "${orbit.id}" appears twice`);
36
42
  seen.add(orbit.id);
43
+ const m = orbit.meanAnomalyDeg;
44
+ if (m === undefined) {
45
+ if (measured)
46
+ throw bad(id, `orbit "${orbit.id}" gives no meanAnomalyDeg while others do; give it for every orbit (measured positions) or for none (illustrative positions)`);
47
+ }
48
+ else if (!(typeof m === "number" && Number.isFinite(m))) {
49
+ throw bad(id, `orbit "${orbit.id}" meanAnomalyDeg must be a finite number of degrees, got ${String(m)}`);
50
+ }
37
51
  }
52
+ return measured;
53
+ }
54
+ /** Whether every orbit of a (planned) group gives its mean anomaly: measured positions. */
55
+ function isMeasured(input) {
56
+ return input.orbits[0]?.meanAnomalyDeg !== undefined;
38
57
  }
39
58
  const positive = (value) => value === undefined || (Number.isFinite(value) && value > 0);
40
59
  function checkLook(id, input) {
@@ -70,6 +89,7 @@ function checkClump(id, clump, catalogue) {
70
89
  if (!(clump.widthDeg > 0 && clump.widthDeg <= 180))
71
90
  throw bad(id, `clump.widthDeg must be above 0 and at most 180, got ${String(clump.widthDeg)}`);
72
91
  }
92
+ const MEASURED_PLACEMENT_LIMIT = "Each dot's position comes from its record's mean anomaly by unperturbed two-body motion from the record's epoch; perturbations are ignored, so a dot drifts from the true position the further the time is from that epoch.";
73
93
  const PLACEMENT_LIMIT = "The position of each dot along its orbit is illustrative: the list gives the orbit's shape and orientation, and the dots are spread evenly along them.";
74
94
  const MOTION_LIMIT = "Motion is unperturbed two-body motion about the centre.";
75
95
  const CLUMP_LIMIT = (catalogue, near, fraction) => `${Math.round(fraction * 100)}% of the dots are drawn near ${catalogue.get(near).definition.label}'s position along its orbit. That clump is a model, not a measurement.`;
@@ -78,18 +98,18 @@ const AS_SUPPLIED = createProvenance({ sourceType: "illustrative", sources: ["Su
78
98
  function groupSource(input) {
79
99
  return input.provenance ?? AS_SUPPLIED;
80
100
  }
81
- /** The provenance a group's card shows (`Scene.groups`): the engine's illustrative statement over the caller's source. */
101
+ /** The provenance a group's card shows (`Scene.groups`): the caller's source with the engine's placement statement (measured or illustrative). */
82
102
  export function groupCardProvenance(input) {
83
- return listedGroupProvenance(groupSource(input), input.clump !== undefined);
103
+ return listedGroupProvenance(groupSource(input), input.clump !== undefined, isMeasured(input));
84
104
  }
85
105
  /** The words on a group's card: the caller's, else a sentence stating the count. */
86
106
  export function groupDescription(input, count) {
87
107
  return input.description ?? `${count} listed orbit${count === 1 ? "" : "s"}, each drawn as one dot. One item stands for the whole group; its focus point is the centroid of the dots.`;
88
108
  }
89
- /** The known limits on a group's card: the caller's, then the engine's own about placement, the clump and motion. */
109
+ /** The known limits on a group's card: the caller's, then the engine's own about placement (measured or illustrative), the clump and motion. */
90
110
  export function groupLimitations(input, catalogue) {
91
111
  const clump = input.clump;
92
- return [...(input.knownLimitations ?? []), PLACEMENT_LIMIT, ...(clump === undefined ? [] : [CLUMP_LIMIT(catalogue, clump.near, clump.fraction)]), MOTION_LIMIT];
112
+ return [...(input.knownLimitations ?? []), isMeasured(input) ? MEASURED_PLACEMENT_LIMIT : PLACEMENT_LIMIT, ...(clump === undefined ? [] : [CLUMP_LIMIT(catalogue, clump.near, clump.fraction)]), MOTION_LIMIT];
93
113
  }
94
114
  /** Builds the draw layer: the listed-orbit group and its one shell item. `center` and `openUtcMs` come from the finished scene; a group error from the engine is renamed `bad-group`. */
95
115
  export function buildGroupLayer(plan, catalogue, center, openUtcMs, window) {
@@ -99,6 +119,7 @@ export function buildGroupLayer(plan, catalogue, center, openUtcMs, window) {
99
119
  recordId: orbit.id,
100
120
  epochUtcMs: orbit.time === undefined ? referenceUtcMs : toUtcMs(orbit.time, `addGroup("${id}") orbit "${orbit.id}" time`),
101
121
  elements: { semiMajorAxisKm: orbit.semiMajorAxisKm, eccentricity: orbit.eccentricity, inclinationDeg: orbit.inclinationDeg, raanDeg: orbit.raanDeg, argumentOfPeriapsisDeg: orbit.argumentOfPeriapsisDeg },
122
+ ...(orbit.meanAnomalyDeg === undefined ? {} : { meanAnomalyDeg: orbit.meanAnomalyDeg }),
102
123
  }));
103
124
  const clump = input.clump;
104
125
  try {
@@ -47,7 +47,7 @@ export interface SceneGroupRead {
47
47
  readonly center: BodyId;
48
48
  /** The plane the elements are given in. */
49
49
  readonly plane: "ecliptic-j2000" | "EQJ";
50
- /** The provenance its card shows: always illustrative, with the source's own type kept in the accuracy line. */
50
+ /** The provenance its card shows: the source's own type when every orbit gives `meanAnomalyDeg` (measured positions); otherwise illustrative, with the source's own type kept in the accuracy line. */
51
51
  readonly provenance: Provenance;
52
52
  /** The words on its info card: those given to `addGroup`, else a sentence stating the count. */
53
53
  readonly description: string;
@@ -12,12 +12,17 @@ export interface ListedElements {
12
12
  readonly raanDeg: number;
13
13
  readonly argumentOfPeriapsisDeg: number;
14
14
  }
15
- /** One record of a measured list: its own source id, the time its elements were measured, and the elements. */
15
+ /** One record of a measured list: its own source id, the time its elements were measured, the elements, and optionally its position along the orbit. */
16
16
  export interface ListedMember {
17
17
  readonly recordId: string;
18
- /** The record's own time. Kept with the record; it does not place the dot (see ListedPhase). */
18
+ /** The record's own time (its epoch). With `meanAnomalyDeg` it fixes where the dot is; without, it is kept with the record and does not place the dot (see ListedPhase). */
19
19
  readonly epochUtcMs: number;
20
20
  readonly elements: ListedElements;
21
+ /**
22
+ * The record's mean anomaly in degrees at `epochUtcMs`; finite, any value (it wraps to 0 to 360). All members give it or none do:
23
+ * with it the group is measured-phase (each dot at its record's position, advanced by two-body motion); without it the phase is a drawing choice.
24
+ */
25
+ readonly meanAnomalyDeg?: number;
21
26
  }
22
27
  /** A stated share of the members drawn near a reference body's position along its orbit. A model, not a measurement. */
23
28
  export interface ListedConcentration {
@@ -29,10 +34,14 @@ export interface ListedConcentration {
29
34
  readonly widthDeg: number;
30
35
  }
31
36
  export interface ListedPhase {
32
- /** The instant at which each member's mean anomaly is the drawing choice below; members then move by two-body motion. */
37
+ /**
38
+ * The instant from which members move by two-body motion. For an illustrative group, each member's mean anomaly here is the drawing choice below;
39
+ * for a measured-phase group (every member gives `meanAnomalyDeg`), it is the record's mean anomaly advanced from its epoch to this instant.
40
+ */
33
41
  readonly referenceUtcMs: number;
34
- /** Unsigned 32-bit integer picking which member takes which slot; defaults to 0. */
42
+ /** Unsigned 32-bit integer picking which member takes which slot; defaults to 0. Illustrative groups only: a measured-phase group with a seed throws. */
35
43
  readonly seed?: number;
44
+ /** Illustrative groups only: a measured-phase group with a concentration throws. */
36
45
  readonly concentration?: ListedConcentration;
37
46
  }
38
47
  export interface ListedOrbitGroupInput {
@@ -43,13 +52,13 @@ export interface ListedOrbitGroupInput {
43
52
  readonly members: readonly ListedMember[];
44
53
  readonly phase: ListedPhase;
45
54
  readonly bounds?: TimeBounds;
46
- /** Where the elements came from. The group restates the position along each orbit as illustrative. */
55
+ /** Where the elements came from. An illustrative group restates the position along each orbit as illustrative; a measured-phase group keeps this `sourceType`. */
47
56
  readonly provenance: Provenance;
48
57
  }
49
58
  export interface ListedOrbitGroup extends PointGroup {
50
59
  /** The source record id of member `index`; also the suffix of that member's State body id. */
51
60
  recordIdAt(index: number): string;
52
- /** Member `index`'s mean anomaly (degrees, 0 to 360) at the reference time: the drawing choice. */
61
+ /** Member `index`'s mean anomaly (degrees, 0 to 360) at the reference time: the record's own, advanced from its epoch, for a measured-phase group; the drawing choice otherwise. */
53
62
  meanAnomalyDegAt(index: number): number;
54
63
  }
55
64
  /** Solves Kepler's equation M = E - e sin E for E (Newton; bound orbits only). */
@@ -57,10 +66,15 @@ export declare function eccentricAnomalyRad(meanAnomalyRad: number, e: number):
57
66
  export declare function trueAnomalyFromMeanRad(meanAnomalyRad: number, e: number): number;
58
67
  /** Mean anomaly (radians, 0 to 2π) of a body with the given position and velocity about a centre of gravitational parameter `mu`. */
59
68
  export declare function meanAnomalyFromStateRad(r: ArrayLike<number>, v: ArrayLike<number>, mu: number): number;
60
- /** The provenance a group's own card carries: always illustrative, since the position along each orbit is a drawing choice; the source's type stays in the accuracy line. */
61
- export declare function listedGroupProvenance(source: Provenance, concentrated: boolean): Provenance;
62
69
  /**
63
- * A group drawn from a list of measured orbits: each member has its own elements, record time and source record id. Only the
64
- * position along each orbit is chosen here (see ListedPhase); every member then moves on its own ellipse by two-body motion.
70
+ * The provenance a group's own card carries. Illustrative (the default): `sourceType` "illustrative", since the position along each orbit is a drawing
71
+ * choice; the source's type stays in the accuracy line. Measured-phase: the source's `sourceType`, `sources` and `accuracy` as given, with a note that
72
+ * each position comes from its record's mean anomaly.
73
+ */
74
+ export declare function listedGroupProvenance(source: Provenance, concentrated: boolean, measured?: boolean): Provenance;
75
+ /**
76
+ * A group drawn from a list of measured orbits: each member has its own elements, record time and source record id. The position along
77
+ * each orbit is the record's own when every member gives `meanAnomalyDeg` (measured-phase), else chosen here (see ListedPhase); every
78
+ * member then moves on its own ellipse by two-body motion.
65
79
  */
66
80
  export declare function createListedOrbitGroup(input: ListedOrbitGroupInput, adapter: TwoBodyAdapter): ListedOrbitGroup;
@@ -11,10 +11,14 @@ const VELOCITY_STEP_MS = 1000;
11
11
  function describe(member, index) {
12
12
  return `member ${index} (record "${String(member.recordId)}")`;
13
13
  }
14
- /** The rejection rule: a record must give a finite, bound orbit; unbound records are for the loader to drop. */
14
+ /**
15
+ * The rejection rule: a record must give a finite, bound orbit; unbound records are for the loader to drop. Mean anomalies are all or none.
16
+ * Returns whether the group is measured-phase (every member gives `meanAnomalyDeg`).
17
+ */
15
18
  function assertMembers(members) {
16
19
  if (members.length === 0)
17
20
  throw new GroupCountError("a listed group needs at least one member; the list is empty");
21
+ const measured = members[0]?.meanAnomalyDeg !== undefined;
18
22
  const seen = new Set();
19
23
  members.forEach((member, index) => {
20
24
  const who = describe(member, index);
@@ -43,10 +47,22 @@ function assertMembers(members) {
43
47
  if (!(e.inclinationDeg >= 0 && e.inclinationDeg <= 180)) {
44
48
  throw new GroupElementsError(`${who}: inclinationDeg must be from 0 to 180, got ${e.inclinationDeg}`);
45
49
  }
50
+ const m = member.meanAnomalyDeg;
51
+ if (m !== undefined && !(typeof m === "number" && Number.isFinite(m)))
52
+ throw new GroupElementsError(`${who}: meanAnomalyDeg must be finite, got ${String(m)}`);
53
+ if ((m !== undefined) !== measured) {
54
+ const missing = measured ? who : describe(members[0], 0);
55
+ throw new GroupElementsError(`${missing} gives no meanAnomalyDeg: give it for every member (measured positions) or for none (illustrative positions)`);
56
+ }
46
57
  });
58
+ return measured;
47
59
  }
48
- function assertPhase(phase) {
60
+ function assertPhase(phase, measured) {
49
61
  assertUtcUnixMs(phase.referenceUtcMs);
62
+ if (measured && phase.seed !== undefined)
63
+ throw new GroupElementsError("a seed only shuffles illustrative positions; the members give meanAnomalyDeg, so their positions are measured: drop the seed");
64
+ if (measured && phase.concentration !== undefined)
65
+ throw new GroupElementsError("a concentration only shapes illustrative positions; the members give meanAnomalyDeg, so their positions are measured: drop the concentration");
50
66
  const seed = phase.seed ?? 0;
51
67
  if (!Number.isInteger(seed) || seed < 0 || seed > 0xffffffff)
52
68
  throw new GroupElementsError("phase seed must be an unsigned 32-bit integer");
@@ -144,11 +160,40 @@ function assignMeanAnomaliesDeg(count, phase, referenceDeg) {
144
160
  }
145
161
  return result;
146
162
  }
163
+ /**
164
+ * Mean anomalies in degrees (0 to 360) at the reference time, one per member, from each record's own mean anomaly at its epoch:
165
+ * M = M_epoch + n·Δt with n = √(μ / a³), the same μ the group propagates with, so placement and later motion agree.
166
+ */
167
+ function measuredMeanAnomaliesDeg(members, referenceUtcMs, mu) {
168
+ const result = new Float64Array(members.length);
169
+ for (let i = 0; i < members.length; i++) {
170
+ const member = members[i];
171
+ const a = member.elements.semiMajorAxisKm;
172
+ const epochDeg = ((member.meanAnomalyDeg % 360) + 360) % 360;
173
+ const m = epochDeg * RADIANS + Math.sqrt(mu / (a * a * a)) * ((referenceUtcMs - member.epochUtcMs) / 1000);
174
+ const wrapped = ((m % TWO_PI) + TWO_PI) % TWO_PI;
175
+ result[i] = wrapped / RADIANS;
176
+ }
177
+ return result;
178
+ }
147
179
  const PHASE_NOTE = "Each orbit's shape and orientation come from its record, but the records give no position along the orbit: "
148
180
  + "that position is an even spread of mean anomaly at the reference time, a drawing choice (illustrative), advanced by unperturbed two-body motion about the centre.";
181
+ const MEASURED_PHASE_NOTE = "Each dot's position along its orbit comes from its record's mean anomaly at the record's epoch, advanced by unperturbed two-body motion about the centre.";
149
182
  const CONCENTRATION_NOTE = "A stated share of the dots is placed near the reference body's position along the orbit: a model, not a measurement. No orbit is added.";
150
- /** The provenance a group's own card carries: always illustrative, since the position along each orbit is a drawing choice; the source's type stays in the accuracy line. */
151
- export function listedGroupProvenance(source, concentrated) {
183
+ /**
184
+ * The provenance a group's own card carries. Illustrative (the default): `sourceType` "illustrative", since the position along each orbit is a drawing
185
+ * choice; the source's type stays in the accuracy line. Measured-phase: the source's `sourceType`, `sources` and `accuracy` as given, with a note that
186
+ * each position comes from its record's mean anomaly.
187
+ */
188
+ export function listedGroupProvenance(source, concentrated, measured = false) {
189
+ if (measured) {
190
+ return createProvenance({
191
+ sourceType: source.sourceType,
192
+ sources: source.sources,
193
+ accuracy: source.accuracy,
194
+ notes: `${source.notes} ${MEASURED_PHASE_NOTE}`.trim(),
195
+ });
196
+ }
152
197
  return createProvenance({
153
198
  sourceType: "illustrative",
154
199
  sources: source.sources,
@@ -157,20 +202,27 @@ export function listedGroupProvenance(source, concentrated) {
157
202
  });
158
203
  }
159
204
  /**
160
- * A group drawn from a list of measured orbits: each member has its own elements, record time and source record id. Only the
161
- * position along each orbit is chosen here (see ListedPhase); every member then moves on its own ellipse by two-body motion.
205
+ * A group drawn from a list of measured orbits: each member has its own elements, record time and source record id. The position along
206
+ * each orbit is the record's own when every member gives `meanAnomalyDeg` (measured-phase), else chosen here (see ListedPhase); every
207
+ * member then moves on its own ellipse by two-body motion.
162
208
  */
163
209
  export function createListedOrbitGroup(input, adapter) {
164
- assertMembers(input.members);
165
- assertPhase(input.phase);
210
+ const measured = assertMembers(input.members);
211
+ assertPhase(input.phase, measured);
166
212
  const count = input.members.length;
167
213
  assertGroupCount(count);
168
214
  const { center, bounds } = input;
169
215
  const { referenceUtcMs, concentration } = input.phase;
170
- const referenceDeg = concentration === undefined
171
- ? null
172
- : referenceMeanAnomalyRad(concentration.around, center, referenceUtcMs, adapter) / RADIANS;
173
- const anomaliesDeg = assignMeanAnomaliesDeg(count, input.phase, referenceDeg);
216
+ let anomaliesDeg;
217
+ if (measured) {
218
+ anomaliesDeg = measuredMeanAnomaliesDeg(input.members, referenceUtcMs, gravitationalParameterOf(adapter, center));
219
+ }
220
+ else {
221
+ const referenceDeg = concentration === undefined
222
+ ? null
223
+ : referenceMeanAnomalyRad(concentration.around, center, referenceUtcMs, adapter) / RADIANS;
224
+ anomaliesDeg = assignMeanAnomaliesDeg(count, input.phase, referenceDeg);
225
+ }
174
226
  const states = memberStatesOf(input.members.map(({ elements }, member) => ({
175
227
  semiMajorAxisKm: elements.semiMajorAxisKm,
176
228
  eccentricity: elements.eccentricity,
@@ -180,7 +232,7 @@ export function createListedOrbitGroup(input, adapter) {
180
232
  trueAnomalyRad: trueAnomalyFromMeanRad(anomaliesDeg[member] * RADIANS, elements.eccentricity),
181
233
  })), input.plane, center, adapter);
182
234
  const recordIds = input.members.map((member) => member.recordId);
183
- const provenance = listedGroupProvenance(input.provenance, concentration !== undefined);
235
+ const provenance = listedGroupProvenance(input.provenance, concentration !== undefined, measured);
184
236
  let kepler = null;
185
237
  const group = {
186
238
  id: input.id,