feat(satellites): file satellites under six classes with a toggle each

The satellites layer now sorts every object into Stations, Imaging,
Telecom, Starlink, Probes or Debris, each with a chip and a live count on
the layer row. Stations and Imaging show by default; the Starlink chip is
the former DENSE catalog switch. Hidden classes keep their points, so a
toggle needs no reload, and they leave the detection overlay and the voice
position lists.

A class comes, strongest evidence first, from CelesTrak SATCAT (object type
and status, served by a new /api/celestrak-satcat/<group> proxy route and
cached for a day), the bundled UCS Satellite Database pack (operator, owner
country and purpose), name patterns for later launches, and the CelesTrak
group. The core catalog also reads the resource, weather, planet, sar and
science groups. Payloads with no evidence of life launched 20 or more years
ago are filed as debris. The UCS pack, its build script and its data credit
are added.
This commit is contained in:
Denis Groshev committed 2026-11-08 23:34:55 +01:00
1 parent 1b9bb844e6
commit c56f098d07
44 files changed
+2530 -362

No files matched your search

+115 -89
View File
@@ -5,9 +5,8 @@ import {
SATELLITE_CLASS_ORDER,
satelliteClassColor,
satelliteClassLabel,
satelliteClassLegend,
satelliteClassOf,
tallySatelliteClasses,
satelliteClassText,
} from './satelliteClass.js';
import satellitesLayer, {
_catalogGroupForTest,
@@ -35,13 +34,17 @@ const ISS_TLE = tleFor('25544', 'ISS (ZARYA)');
/** Poll the chip until the async dense load settles (or give up). */
async function settleChip(maxTicks = 50) {
for (let i = 0; i < maxTicks; i++) {
const chip = satellitesLayer.getRowControls().chips[0];
const chip = starlinkChip();
if (chip && !chip.busy) return chip;
await new Promise((resolve) => setTimeout(resolve, 1));
}
return satellitesLayer.getRowControls().chips[0];
return starlinkChip();
}
/** The STARLINK class chip: the dense catalog toggle (id `catalog`). */
const starlinkChip = () =>
satellitesLayer.getRowControls().chips.find((entry) => entry.id === 'catalog');
/** Every CelesTrak group the catalog ingests, plus the dense-mode tag. */
const INGESTED_GROUPS = ['stations', 'visual', 'gps-ops', 'glonass', 'galileo', 'geo', 'dense'];
@@ -146,69 +149,7 @@ test('the dense shell stays dimmer than the class it sits among', () => {
);
});
test('tallying groups counts by class, folding the GNSS constellations together', () => {
const counts = tallySatelliteClasses([
'gps-ops', 'gps-ops', 'glonass', 'galileo',
'geo', 'geo', 'geo',
'stations',
'visual',
'dense', 'dense',
]);
assert.equal(counts.nav, 4, 'all three GNSS groups fold into NAV');
assert.equal(counts.geo, 3);
assert.equal(counts.station, 1);
assert.equal(counts.visual, 1);
assert.equal(counts.comms, 2);
});
test('tallying tolerates an empty or missing input', () => {
assert.deepEqual({ ...tallySatelliteClasses([]) }, {});
assert.deepEqual({ ...tallySatelliteClasses(undefined) }, {});
});
test('the tally files the ISS under STATION even when a partial outage moved it', () => {
// The legend and the card must never disagree. With the stations feed down,
// the ISS is ingested as `visual`; counting it there would let STATION vanish
// from the legend while the tracked card still reads "STATION · ISS".
const outage = tallySatelliteClasses([
{ group: 'visual', isIss: true },
{ group: 'visual' },
{ group: 'visual' },
]);
assert.equal(outage.station, 1, 'the ISS is counted as a STATION');
assert.equal(outage.visual, 2, 'and is not double-counted under VISUAL');
const legend = satelliteClassLegend(outage);
assert.equal(legend.some((row) => row.klass === 'station'), true,
'STATION stays in the legend, matching the card');
// Bare group tags still work — the descriptor form is additive.
assert.deepEqual({ ...tallySatelliteClasses(['visual', 'visual']) }, { visual: 2 });
assert.equal(satelliteClassOf('visual', { isIss: true }).klass, 'station',
'one helper owns the rule for every consumer');
});
test('the legend lists present classes in order and omits absent ones', () => {
const legend = satelliteClassLegend(tallySatelliteClasses(['geo', 'gps-ops', 'stations']));
assert.deepEqual(legend.map((row) => row.klass), ['station', 'nav', 'geo'],
'legend follows SATELLITE_CLASS_ORDER, not input order');
// COMMS only exists in DENSE mode — the legend must not advertise a class
// that has nothing on screen.
assert.equal(legend.some((row) => row.klass === 'comms'), false);
const row = legend.find((entry) => entry.klass === 'nav');
assert.equal(row.label, 'NAV');
assert.equal(row.color, SATELLITE_CLASSES.nav.color);
assert.equal(row.count, 1);
assert.ok(row.blurb.length > 0, 'every legend row carries a plain-language gloss');
});
test('the legend drops zero and negative counts', () => {
assert.deepEqual(satelliteClassLegend({ nav: 0, geo: -1, station: 2 }).map((r) => r.klass), ['station']);
assert.deepEqual(satelliteClassLegend(null), []);
});
test('the DENSE row chip is stateless and declares the params to apply', () => {
test('the STARLINK row chip is stateless and declares the params to apply', () => {
// The chip never carries its own state: it declares the params to apply, so
// whatever else drives the catalog param (Space Missions capture/restore)
// stays authoritative. Whether it reads ACTIVE is decided by the dense LOAD,
@@ -217,7 +158,7 @@ test('the DENSE row chip is stateless and declares the params to apply', () => {
_setDenseCatalogStateForTest({});
const chip = satellitesLayer.getRowControls().chips.find((entry) => entry.id === 'catalog');
assert.equal(chip.id, 'catalog');
assert.equal(chip.label, 'DENSE');
assert.equal(chip.label, 'STARLINK');
assert.equal(chip.active, false);
assert.equal(chip.busy, false);
assert.equal(chip.state, 'idle');
@@ -236,7 +177,7 @@ test('an invalid catalog mode is rejected without disturbing the chip', () => {
assert.equal(chip.active, false);
});
test('DENSE reports loading, then ACTIVE only once the points exist', async () => {
test('STARLINK reports loading, then ACTIVE only once the points exist', async () => {
const originalFetch = globalThis.fetch;
const refreshes = [];
try {
@@ -247,7 +188,7 @@ test('DENSE reports loading, then ACTIVE only once the points exist', async () =
satellitesLayer.setParams({ catalog: 'dense' });
// The param flips synchronously, but the shell has not arrived yet — the
// chip must say BUSY, never ACTIVE.
const pending = satellitesLayer.getRowControls().chips[0];
const pending = starlinkChip();
assert.equal(pending.busy, true);
assert.equal(pending.disabled, true);
assert.equal(pending.active, false, 'never active before the points exist');
@@ -256,21 +197,21 @@ test('DENSE reports loading, then ACTIVE only once the points exist', async () =
const settled = await settleChip();
assert.equal(settled.active, true, 'active once the dense points are on screen');
assert.equal(settled.state, 'active');
assert.equal(settled.label, 'DENSE');
assert.equal(settled.label, 'STARLINK');
assert.deepEqual(settled.params, { catalog: 'core' }, 'a settled chip toggles back off');
// The completion pushed a refresh, and the legend gained COMMS with it —
// The completion pushed a refresh, and the legend gained STARLINK with it —
// without that push the row would keep the pre-load counts for 5 minutes.
assert.ok(refreshes.length >= 2, 'load start and load completion each pushed a refresh');
const legend = satellitesLayer.getRowControls().legend;
assert.equal(legend.some((row) => row.klass === 'comms'), true);
assert.equal(legend.some((row) => row.klass === 'starlink'), true);
} finally {
globalThis.fetch = originalFetch;
_clearDenseCatalogStateForTest();
}
});
test('a failed DENSE load reverts the mode rather than leaving an active chip', async () => {
test('a failed STARLINK load reverts the mode rather than leaving an active chip', async () => {
const originalFetch = globalThis.fetch;
const warn = console.warn;
console.warn = () => {};
@@ -285,14 +226,14 @@ test('a failed DENSE load reverts the mode rather than leaving an active chip',
assert.equal(settled.active, false, 'a 502 must never present as a live dense catalog');
assert.equal(settled.state, 'error');
assert.equal(settled.label, 'DENSE ✕');
assert.equal(settled.label, 'STARLINK ✕');
assert.match(settled.title, /502/, 'the chip explains why');
assert.equal(satellitesLayer.getParams().catalog, 'core', 'the mode reverts to reality');
assert.deepEqual(settled.params, { catalog: 'dense' }, 'clicking retries');
assert.equal(
satellitesLayer.getRowControls().legend.some((row) => row.klass === 'comms'),
satellitesLayer.getRowControls().legend.some((row) => row.klass === 'starlink'),
false,
'no COMMS class is advertised when nothing loaded',
'no STARLINK class is advertised when nothing loaded',
);
assert.ok(pushes >= 2, 'the failure pushed its own refresh');
@@ -365,9 +306,9 @@ test('an explicit return to core clears a failure the user never caused', async
// A no-op restore of the pre-mission snapshot.
satellitesLayer.setParams({ catalog: 'core', showPoints: true, showOrbits: true });
const restored = satellitesLayer.getRowControls().chips[0];
const restored = starlinkChip();
assert.equal(restored.state, 'idle', 'the error does not survive the restore');
assert.equal(restored.label, 'DENSE');
assert.equal(restored.label, 'STARLINK');
assert.doesNotMatch(restored.title, /502/);
} finally {
console.warn = warn;
@@ -376,7 +317,7 @@ test('an explicit return to core clears a failure the user never caused', async
}
});
test('a real stations-feed outage keeps STATION in the legend, matching the card', async () => {
test('a real stations-feed outage keeps the ISS under STATIONS in the legend', async () => {
// End-to-end version of the tally rule: drive a real rebuild in which only
// the `visual` group answers, so the ISS is genuinely ingested as `visual`.
// The legend must still file it under STATION or it disagrees with the card.
@@ -398,10 +339,9 @@ test('a real stations-feed outage keeps STATION in the legend, matching the card
'the outage really did ingest the ISS from the visual group');
const legend = satellitesLayer.getRowControls().legend;
assert.equal(legend.find((row) => row.klass === 'station')?.count, 1,
'STATION survives the outage because the ISS is counted there');
assert.equal(legend.some((row) => row.klass === 'visual'), false,
'and it is not also counted under VISUAL');
assert.equal(legend.find((row) => row.klass === 'stations')?.count, 1,
'STATIONS survives the outage because the ISS is counted there');
assert.equal(legend.length, 1, 'and it is not also counted under another class');
assert.equal(satelliteClassLabel('visual', { isIss: true }), 'STATION · ISS',
'the card says the same thing the legend does');
} finally {
@@ -431,15 +371,21 @@ test('a catalog rebuild refreshes the detection overlay class strings', async ()
text: async () => (String(url).endsWith(`/${homeGroup}`) ? ALT_TLE : ''),
});
// Every class on: the seeded satellite's class must not hide it.
satellitesLayer.setParams({
classes: { telecom: true, probes: true, debris: true },
});
await satellitesLayer.update(viewer);
const first = satellitesLayer.getDetectableObjects().find((o) => o.sourceId === 33333);
assert.ok(first, 'the seeded satellite is collectable');
assert.equal(first.klass, 'GEO');
// A payload with no SATCAT record and no recognisable name takes its
// group's class (src/layers/satellites/classes.js).
assert.equal(first.klass, 'TELECOM');
homeGroup = 'visual';
homeGroup = 'resource';
await satellitesLayer.update(viewer);
const second = satellitesLayer.getDetectableObjects().find((o) => o.sourceId === 33333);
assert.equal(second.klass, 'VISUAL', 'the cached record does not outlive its catalog');
assert.equal(second.klass, 'IMAGING', 'the cached record does not outlive its catalog');
} finally {
console.log = log;
console.warn = warn;
@@ -451,7 +397,7 @@ test('a catalog rebuild refreshes the detection overlay class strings', async ()
test('a dependency owner hiding the points surrenders the whole row', async () => {
try {
_setDenseCatalogStateForTest({});
assert.equal(satellitesLayer.getRowControls().chips.length, 1);
assert.equal(satellitesLayer.getRowControls().chips.length, 6);
// Space Missions borrows this layer for TLE lookup with showPoints:false.
satellitesLayer.setParams({ showPoints: false });
@@ -460,8 +406,88 @@ test('a dependency owner hiding the points surrenders the whole row', async () =
assert.deepEqual(owned.legend, [], 'no legend describing an empty sky');
satellitesLayer.setParams({ showPoints: true });
assert.equal(satellitesLayer.getRowControls().chips.length, 1, 'released on restore');
assert.equal(satellitesLayer.getRowControls().chips.length, 6, 'released on restore');
} finally {
_clearDenseCatalogStateForTest();
}
});
test('stations and imaging show by default; each class chip turns its class on and off', async () => {
const originalFetch = globalThis.fetch;
const log = console.log;
const warn = console.warn;
console.log = () => {};
console.warn = () => {};
const served = {
'/api/celestrak/stations': ISS_TLE,
'/api/celestrak/resource': tleFor('40002', 'SENTINEL-2A'),
'/api/celestrak/gps-ops': tleFor('40001', 'GPS BIII-1'),
'/api/celestrak/visual': tleFor('40003', 'SL-16 R/B'),
};
const shown = () => satellitesLayer.getAllPositions().map((row) => row.id).sort();
const chip = (id) =>
satellitesLayer.getRowControls().chips.find((entry) => entry.id === `class-${id}`);
try {
_setDenseCatalogStateForTest({});
globalThis.fetch = async (url) => ({
ok: true,
text: async () => served[String(url)] || '',
});
await satellitesLayer.update({ scene: { primitives: { add: (p) => p, remove() {} } } });
assert.deepEqual(shown(), [25544, 40002], 'stations and imaging only');
assert.deepEqual(
satellitesLayer.getRowControls().chips.map((entry) => entry.label),
['STATIONS', 'IMAGING', 'TELECOM', 'STARLINK', 'PROBES', 'DEBRIS'],
);
assert.equal(chip('imaging').active, true);
assert.equal(chip('telecom').active, false);
assert.deepEqual(chip('telecom').params, { classes: { telecom: true } });
assert.deepEqual(
satellitesLayer.getRowControls().legend.map((row) => row.klass),
['stations', 'imaging'],
'the legend keys only what is on screen',
);
satellitesLayer.setParams(chip('telecom').params);
satellitesLayer.setParams(chip('debris').params);
assert.deepEqual(shown(), [25544, 40001, 40002, 40003]);
assert.equal(chip('debris').active, true);
assert.deepEqual(satellitesLayer.getParams().classes, {
stations: true,
imaging: true,
telecom: true,
starlink: false,
probes: false,
debris: true,
});
satellitesLayer.setParams(chip('imaging').params);
assert.deepEqual(shown(), [25544, 40001, 40003], 'imaging off');
assert.equal(satellitesLayer.setParams({ classes: 'all' }), false, 'malformed request refused');
} finally {
console.log = log;
console.warn = warn;
globalThis.fetch = originalFetch;
_clearDenseCatalogStateForTest();
}
});
test('the shown class is the six-class one, with a subtype that says more', () => {
assert.equal(satelliteClassText('telecom', 'gps-ops'), 'TELECOM · GPS');
assert.equal(
satelliteClassText('stations', 'visual', { isIss: true }),
'STATIONS · ISS',
);
assert.equal(satelliteClassText('imaging', 'resource'), 'IMAGING');
assert.equal(satelliteClassText('imaging', 'visual'), 'IMAGING');
// A subtype that only repeats the class is dropped.
assert.equal(satelliteClassText('starlink', 'dense'), 'STARLINK');
// A dead geostationary comsat is debris, not GEO.
assert.equal(satelliteClassText('debris', 'geo'), 'DEBRIS');
// Without a class the group's label stands.
assert.equal(satelliteClassText(null, 'gps-ops'), 'NAV · GPS');
assert.equal(
satelliteClassText('telecom', 'gps-ops', { localize: false }),
'TELECOM · GPS',
);
});