Draw the satellites layer through the renderer ports

The satellite dots, the tracked satellite's dot and the orbit rings now go
through the draw port instead of a raw point collection, an entity and
primitives, so the layer's rendering no longer drives Cesium and leaves the
Cesium allow-list.

- Dots are one points set, patched in place and sent once per frame.
- The tracked dot is its own set, drawn at the sample the follow camera
  framed (or after the frame's own sample when no camera read it).
- Rings are geodesic lines with a behind-the-globe colour, turned about the
  pole by the sidereal angle in the layer each second, since the port has no
  inertial frame. The orbit frame matrix is a plain 16-number array, and
  the launches layer now receives plain ECEF orbit positions.
- Clicks match the draw hit against the layer's own sets.
- The focus pass projects every dot in one batched call.
- Depth-fail lines in the Cesium draw port honour pickable: false.
This commit is contained in:
Sameh Khamis committed 2026-11-08 13:06:52 -08:00
1 parent 1bff078097
commit d513034f3d
17 files changed
+845 -415

No files matched your search

+6
View File
@@ -1072,6 +1072,12 @@ a fresh winning record. Dense removal clears only its own provenance, and a
fresh core rebuild or lifecycle reset replaces the corresponding ownership.
Source adapters retain the existing CelesTrak and Launch Library
endpoints; standalone entries provide scene services and the satellite dependency.
The satellites layer draws through the renderer's draw port and no longer
reaches Cesium: the dots are one point set moved in a single write a frame, the
tracked satellite's dot a set of its own drawn where the follow camera framed
it, and the orbit rings a line set dimmed behind the globe and turned with the
Earth each second. A caller handing it a Cesium viewer, with no
renderer bound, loads the `./render/cesium/unbound` export once first.
The mission factory separates paths, replay, camera, panel, overlays and placement.
Launch Library pad coordinates retain unknown values: missing fields use the
reported location coordinates when available, and launches without a known pad
+4 -4
View File
@@ -114,10 +114,10 @@ assertResumeGate('CCTV', () => {
assertResumeGate('satellite', () => {
const point = {
position: { x: 1, y: 2, z: 3 },
pos: { x: 1, y: 2, z: 3 },
show: true,
pixelSize: 6,
color: color(),
color: [1, 1, 1, 1],
};
return {
pass: ({ nowMs, target: focusTarget, previousActiveCount }) =>
@@ -129,9 +129,9 @@ assertResumeGate('satellite', () => {
nowMs,
screenPositionFor: () => ({ x: 50, y: 50 }),
cameraDistanceFor: () => 1200,
baseColorFor: () => color(),
baseColorFor: () => [1, 1, 1, 1],
params,
}),
readAlpha: () => point.color.alpha,
readAlpha: () => point.color[3],
};
});
+3 -3
View File
@@ -96,7 +96,7 @@ test('satellite getAnalystRecords: disabled or empty catalog returns []', () =>
test('satellite getAnalystRecords: core rows beat dense extras under the cap', () => {
const satrec = twoline2satrec(ISS_L1, ISS_L2);
const point = {
position: Cesium.Cartesian3.fromDegrees(-97.7, 30.2, 420_000),
pos: Cesium.Cartesian3.fromDegrees(-97.7, 30.2, 420_000),
};
_setTrackedSatelliteRefreshStateForTest({
noradId: ISS_NORAD,
@@ -112,7 +112,7 @@ test('satellite getAnalystRecords: core rows beat dense extras under the cap', (
name: 'STARLINK-TEST',
satrec,
group: 'dense',
point: { position: Cesium.Cartesian3.fromDegrees(-90, 20, 550_000) },
point: { pos: Cesium.Cartesian3.fromDegrees(-90, 20, 550_000) },
},
{
noradId: 24876,
@@ -120,7 +120,7 @@ test('satellite getAnalystRecords: core rows beat dense extras under the cap', (
satrec,
group: 'gps-ops',
point: {
position: Cesium.Cartesian3.fromDegrees(-100, 10, 20_200_000),
pos: Cesium.Cartesian3.fromDegrees(-100, 10, 20_200_000),
},
},
],
+29 -40
View File
@@ -18,6 +18,7 @@ import {
} from './satellites.js';
import { followedOf } from './followed.js';
import { bindRenderer } from '../render/rendererOf.js';
import { fakeDrawPort } from '../testSupport/fakeDrawPort.mjs';
import satellitesLayer from './satellites.js';
import { createTrackedOverlayEntry } from './trackedReadout.js';
import { readEntityRecord, withEntityRecord } from './entityRecords.js';
@@ -110,23 +111,17 @@ test('satellite first update aborts every parallel catalog request', async () =>
test('selected satellite params survive delayed arrival and yield to newer explicit intent', (t) => {
const point = {
position: Cesium.Cartesian3.fromDegrees(-97.7, 30.2, 420_000),
pos: Cesium.Cartesian3.fromDegrees(-97.7, 30.2, 420_000),
show: true,
pixelSize: 12,
color: Cesium.Color.RED,
outlineColor: Cesium.Color.WHITE,
color: [1, 0, 0, 1],
outlineColor: [1, 1, 1, 1],
outlineWidth: 2,
disableDepthTestDistance: 0,
disableDepthTest: 0,
};
const viewer = {
entities: new Cesium.EntityCollection(),
trackedEntity: undefined,
scene: {
frameState: { frameNumber: 1 },
primitives: { remove() {} },
},
};
t.after(bindRenderer(viewer, { camera: followingPort() }));
const viewer = {};
const draw = fakeDrawPort();
t.after(bindRenderer(viewer, { camera: followingPort(), draw }));
_setSatelliteLabelLifecycleStateForTest({
viewer,
satrec: twoline2satrec(L1, L2),
@@ -215,13 +210,13 @@ test('a tracked docked cluster consolidates its companions onto one card', () =>
// consolidate them as secondary info on that card, and suppress only those
// members — never unrelated satellites that merely happen to be nearby.
const entity = withEntityRecord({}, { labelModel: { title: 'OLD', details: ['? km'] } });
const point = { position: new Cesium.Cartesian3() };
const point = { pos: new Cesium.Cartesian3() };
const viewer = { camera: null, scene: { frameState: { frameNumber: 1 } } };
let nowMs = Date.UTC(2008, 8, 20, 12, 30);
// The tracked satellite moves ~7.6 km/s, so neighbours are defined RELATIVE to
// wherever it is at scan time rather than pinned to a stale sample.
const near = (metres) => ({
get position() {
get pos() {
const tracked = _trackedFrameCartesianForTest();
return new Cesium.Cartesian3(tracked.x + metres, tracked.y, tracked.z);
},
@@ -246,7 +241,6 @@ test('a tracked docked cluster consolidates its companions onto one card', () =>
// The cluster scan is throttled, so advance past its interval before the frame
// that must observe the cluster.
nowMs += 2000;
viewer.scene.frameState.frameNumber = 2;
_runSatellitePreRenderForTest();
const details = readEntityRecord(entity)?.labelModel.details;
@@ -273,7 +267,7 @@ test('a tracked docked cluster consolidates its companions onto one card', () =>
});
test('satellite pre-render refreshes the tracked altitude on each propagated frame', () => {
const entity = withEntityRecord({}, { labelModel: { title: 'OLD', details: ['? km'] } });
const point = { position: new Cesium.Cartesian3() };
const point = { pos: new Cesium.Cartesian3() };
const viewer = {
camera: null,
scene: { frameState: { frameNumber: 1 } },
@@ -297,7 +291,6 @@ test('satellite pre-render refreshes the tracked altitude on each propagated fra
assert.equal(readEntityRecord(entity)?.labelModel.details[1], '353\u00a0km · NORAD 25544');
epochIndex = 1;
viewer.scene.frameState.frameNumber = 2;
_runSatellitePreRenderForTest();
assert.equal(readEntityRecord(entity)?.labelModel.details[1], '366\u00a0km · NORAD 25544');
assert.equal(
@@ -315,23 +308,17 @@ test('ISS ambient and tracked lifecycle uses cached host entries with no native
clearSource: (...args) => calls.push(['clear', ...args]),
};
const point = {
position: Cesium.Cartesian3.fromDegrees(-97.7, 30.2, 420_000),
pos: Cesium.Cartesian3.fromDegrees(-97.7, 30.2, 420_000),
show: true,
pixelSize: 12,
color: Cesium.Color.RED,
outlineColor: Cesium.Color.WHITE,
color: [1, 0, 0, 1],
outlineColor: [1, 1, 1, 1],
outlineWidth: 2,
disableDepthTestDistance: 0,
disableDepthTest: 0,
};
const viewer = {
entities: new Cesium.EntityCollection(),
trackedEntity: undefined,
scene: {
frameState: { frameNumber: 1 },
primitives: { remove() {} },
},
};
t.after(bindRenderer(viewer, { camera: followingPort() }));
const viewer = {};
const draw = fakeDrawPort();
t.after(bindRenderer(viewer, { camera: followingPort(), draw }));
let cleaned = false;
_setSatelliteLabelLifecycleStateForTest({
viewer,
@@ -348,7 +335,7 @@ test('ISS ambient and tracked lifecycle uses cached host entries with no native
assert.equal(ambient.title, 'ISS');
assert.equal(
ambient.position(),
point.position,
point.pos,
'ISS getter reads the existing point cache',
);
assert.equal(
@@ -359,16 +346,17 @@ test('ISS ambient and tracked lifecycle uses cached host entries with no native
const trackedEntity = _trackIssForTest();
assert.ok(trackedEntity);
const tracked = [...draw.sets.values()].find(
(set) => !set.disposed && /^satellites:\d+:tracked$/.test(set.spec.id),
);
assert.ok(tracked, 'the tracked dot has a set of its own');
_runSatellitePreRenderForTest();
assert.equal(
viewer.entities.values.length,
1,
'runtime guard requires a real tracked entity',
tracked.items.get('25544')?.pixelSize,
14,
'the tracked dot draws, as the follow camera frames it',
);
assert.equal(trackedEntity.label, undefined);
assert.ok(
trackedEntity.point,
'tracked dot remains on the entity for camera framing',
);
const trackedEntry = createTrackedOverlayEntry(trackedEntity);
assert.ok(trackedEntry);
assert.equal(trackedEntry.id, 'satellites:25544');
@@ -393,7 +381,8 @@ test('ISS ambient and tracked lifecycle uses cached host entries with no native
_clearSatelliteLabelLifecycleForTest();
cleaned = true;
assert.equal(viewer.entities.values.length, 0);
assert.equal(tracked.items.size, 0);
assert.ok(tracked.disposed);
assert.equal(
calls.filter(
([type, sourceId]) =>
+2 -3
View File
@@ -18,11 +18,11 @@ const L2 =
function run(locale) {
setLocale(locale);
const entity = withEntityRecord({}, { labelModel: { title: 'OLD', details: ['? km'] } });
const point = { position: new Cesium.Cartesian3() };
const point = { pos: new Cesium.Cartesian3() };
const viewer = { camera: null, scene: { frameState: { frameNumber: 1 } } };
let nowMs = Date.UTC(2008, 8, 20, 12, 30);
const near = (metres) => ({
get position() {
get pos() {
const tracked = _trackedFrameCartesianForTest();
return new Cesium.Cartesian3(tracked.x + metres, tracked.y, tracked.z);
},
@@ -42,7 +42,6 @@ function run(locale) {
});
_runSatellitePreRenderForTest();
nowMs += 2000;
viewer.scene.frameState.frameNumber = 2;
_runSatellitePreRenderForTest();
const details = readEntityRecord(entity)?.labelModel.details;
setLocale('en');
+10 -11
View File
@@ -21,7 +21,7 @@ export function createInteraction({
// Cross-layer untrack (H2, mirror of flights): if ANOTHER layer (flights,
// military, …) grabs the follow-camera, drop our tracking so the orbit ring /
// tracked entity don't orphan — without touching viewer.trackedEntity (the
// tracked dot don't orphan — without touching viewer.trackedEntity (the
// new owner controls it). Guarded so our OWN switch (viewer.trackedEntity
// briefly undefined mid-_trackSatellite) doesn't self-clear.
if (!layerState._trackedEntityChangedRemove) {
@@ -46,18 +46,17 @@ export function createInteraction({
layerState._clickSubscription = inputFor(viewer).onClick((event) => {
if (!layerState._enabled) return;
const picked = event.pick;
const hit = event.drawHit;
if (picked) {
// Clicking tracked entity itself — ignore
if (parts.rendering._pickIsTrackedEntity(picked)) return;
// Clicking the tracked satellite's own dot — ignore
if (parts.rendering._hitIsTracked(hit)) return;
// Check if it's a satellite point (id is NORAD catalog number)
const noradId = parts.rendering._pickedPointId(picked);
if (noradId !== null && layerState._catalog.has(noradId)) {
parts.tracking._cancelPendingTrackingRestore();
parts.tracking._trackSatellite(noradId, { origin: 'user' });
return;
}
// A satellite dot (its item id is the NORAD catalog number)
const noradId = parts.rendering._hitPointId(hit);
if (noradId !== null && layerState._catalog.has(noradId)) {
parts.tracking._cancelPendingTrackingRestore();
parts.tracking._trackSatellite(noradId, { origin: 'user' });
return;
}
// A pick that belongs to a sibling layer (plane, vessel, station, CCTV
+3 -3
View File
@@ -13,7 +13,7 @@ export function createLifecycle({
/** Run the shared per-frame tick before each frame draws. */
function onEachFrame(frame) {
return frame.on('preRender', () => parts.rendering._preRenderTick());
return frame.on('preRender', (t) => parts.rendering._preRenderTick(t));
}
const methods = {
@@ -54,7 +54,7 @@ export function createLifecycle({
layerState._denseError = null;
layerState._catalogRevision++;
// The collection the satellite dots draw in
// The sets the satellite dots, the tracked dot and the rings draw in
parts.rendering._attach(viewer);
parts.interaction._installClickHandler(viewer);
@@ -141,7 +141,7 @@ export function createLifecycle({
}
layerState._overlayHost.clearSource(ISS_OVERLAY_SOURCE_ID);
layerState._overlayHost.setVisible(ISS_OVERLAY_SOURCE_ID, false);
// The dots' collection and the orbit rings go (and are destroyed)
// The dots', tracked dot's and rings' sets are disposed of
parts.rendering._detach(viewer);
layerState._points.clear();
layerState._detectionObjects.clear();
+246 -62
View File
@@ -13,6 +13,9 @@ import {
TRACKED_ORBIT_COLOR,
} from './policy.js';
import { createRendering } from './rendering.js';
import { bindFakeDraw } from '../../testSupport/fakeDrawPort.mjs';
import { gstime } from 'satellite.js';
import * as focusDeemphasis from '../../data/focusDeemphasis.js';
const rgba = (color) => [color.red, color.green, color.blue, color.alpha];
@@ -44,9 +47,9 @@ test('point styles keep the colours the dots were drawn in', () => {
test('positions read back from the drawn dots match the Cesium geodetic conversion', () => {
const position = Cesium.Cartesian3.fromDegrees(-97.7, 30.2, 420_000);
const point = { position, show: true };
const point = { pos: position, show: true };
_setSatelliteLabelLifecycleStateForTest({
viewer: { scene: { frameState: { frameNumber: 1 } } },
viewer: {},
satrec: null,
point,
overlayHost: { setEntries() {}, setVisible() {}, clearSource() {} },
@@ -68,7 +71,7 @@ test('positions read back from the drawn dots match the Cesium geodetic conversi
}
});
test('only the rendering part drives Cesium', () => {
test('no part of the layer drives Cesium', () => {
const offList = [
'catalog',
'controls',
@@ -114,6 +117,13 @@ test('only the rendering part drives Cesium', () => {
for (const pattern of forbidden)
assert.doesNotMatch(source, pattern, `${name}.js: ${pattern}`);
}
// The rendering part owns the handles, and draws through the draw port.
const rendering = readFileSync(
new URL('./rendering.js', import.meta.url),
'utf8',
);
for (const pattern of forbidden.slice(0, 7))
assert.doesNotMatch(rendering, pattern, `rendering.js: ${pattern}`);
// The patterns themselves still catch what they are for.
const caught = [
'layerState._trackedEntity.position.setValue(p)',
@@ -161,64 +171,238 @@ test('only the rendering part drives Cesium', () => {
);
});
test('the rendering part draws the dots and rings in Cesium colours', () => {
const added = [];
const state = {
_points: new Map(),
_orbitPaths: new Map(),
_catalog: new Map([[25544, { satrec: {} }]]),
_pointCollection: { add: (options) => ({ ...options }) },
_viewer: { scene: { primitives: { add: (p) => added.push(p) } } },
};
const path = [
{ x: 7e6, y: 0, z: 0 },
{ x: 0, y: 7e6, z: 0 },
{ x: -7e6, y: 0, z: 0 },
];
const rendering = createRendering({
state,
services: { focus: {} },
parts: { orbits: { computeOrbitPath: () => path } },
});
rendering._addPoint(25544, { x: 1, y: 2, z: 3 }, POINT_STYLES.iss);
const point = state._points.get(25544);
assert.ok(point.position instanceof Cesium.Cartesian3);
assert.deepEqual(
[point.position.x, point.position.y, point.position.z],
[1, 2, 3],
);
assert.ok(point.color instanceof Cesium.Color);
assert.deepEqual(
rgba(point.color),
rgba(Cesium.Color.fromCssColorString('#ff4444')),
);
assert.deepEqual(
rgba(point.outlineColor),
rgba(Cesium.Color.WHITE.withAlpha(0.3)),
);
assert.equal(point.pixelSize, 12);
assert.equal(point.outlineWidth, 2);
assert.equal(point.id, 25544);
assert.ok(
Cesium.NearFarScalar.equals(
point.scaleByDistance,
new Cesium.NearFarScalar(1e6, 1.5, 2e7, 0.6),
),
);
test('the rendering part draws the dots, the tracked dot and the rings through the draw port', () => {
const viewer = {};
const { draw, unbind } = bindFakeDraw(viewer);
try {
const state = {
_points: new Map(),
_orbitPaths: new Map(),
_catalog: new Map([[25544, { satrec: {} }]]),
_viewer: viewer,
_trackedNorad: null,
_enabled: false,
};
const path = [
{ x: 7e6, y: 0, z: 0 },
{ x: 0, y: 7e6, z: 0 },
{ x: -7e6, y: 0, z: 0 },
];
const rendering = createRendering({
state,
services: {
focus: {
focusNowMs: (ms) => ms,
getFocusTarget: () => null,
focusPassIsNeeded: () => false,
},
},
parts: {
orbits: { computeOrbitPath: () => path },
tracking: { _getTrackedFramePosition: () => sampleFrame() },
},
});
// The frame's own sample, taken after the tick's first part.
let sampleFrame = () => null;
rendering._attach(viewer);
const points = draw.find('satellites:').spec.id;
assert.match(points, /^satellites:\d+:points$/);
rendering._addPoint(25544, { x: 1, y: 2, z: 3 }, POINT_STYLES.iss);
const point = state._points.get(25544);
assert.deepEqual(point.pos, { x: 1, y: 2, z: 3 });
assert.equal(draw.set(points).items.size, 0, 'sent with the frame');
rendering._preRenderTick({ frame: 1 });
const drawn = draw.set(points).items.get('25544');
assert.equal(drawn, point);
assert.deepEqual(
[...drawn.color],
rgba(Cesium.Color.fromCssColorString('#ff4444')),
);
assert.deepEqual(
[...drawn.outlineColor],
rgba(Cesium.Color.WHITE.withAlpha(0.3)),
);
assert.equal(drawn.pixelSize, 12);
assert.equal(drawn.outlineWidth, 2);
assert.deepEqual(drawn.meta, { noradId: 25544 });
assert.deepEqual(
{ ...drawn.scaleByDistance },
{ near: 1e6, nearValue: 1.5, far: 2e7, farValue: 0.6 },
);
// Moves go out in one upsert a frame.
const writes = draw.set(points).writes;
rendering._movePoint(25544, { x: 4, y: 5, z: 6 });
rendering._movePoint(25544, { x: 7, y: 8, z: 9 });
rendering._preRenderTick({ frame: 2 });
assert.equal(draw.set(points).writes, writes + 1);
assert.deepEqual(draw.set(points).items.get('25544').pos, {
x: 7,
y: 8,
z: 9,
});
// A pick on a dot names its satellite; one on another set does not.
assert.equal(rendering._hitPointId({ set: points, id: '25544' }), 25544);
assert.equal(rendering._hitPointId({ set: 'other:1', id: '25544' }), null);
rendering._showOrbitPath(25544, TRACKED_ORBIT_COLOR);
assert.equal(added.length, 1);
const instance = added[0].geometryInstances;
assert.deepEqual(
[...instance.attributes.color.value],
[255, 255, 0, Cesium.Color.floatToByte(0.6)],
);
assert.ok(
instance.geometry._positions.every((p) => p instanceof Cesium.Cartesian3),
);
assert.ok(
rendering
._rendererPositions(path)
.every((p, i) => p instanceof Cesium.Cartesian3 && p.x === path[i].x),
);
rendering._showOrbitPath(25544, TRACKED_ORBIT_COLOR);
const rings = draw.sets.get(points.replace(':points', ':rings'));
assert.equal(rings.spec.pickable, false, 'ring clicks fall through');
const ring = rings.items.get('25544');
assert.deepEqual(ring.style, { kind: 'solid', color: [1, 1, 0, 0.6] });
assert.deepEqual(ring.depthFailColor, [1, 1, 0, 0.35]);
assert.equal(ring.widthPx, 2.5, 'the ISS ring is wider');
assert.equal(ring.mode, 'geodesic');
assert.deepEqual([...ring.positions.slice(0, 3)], [7e6, 0, 0]);
// Turned with the Earth: by minus the GMST elapsed since its bake.
const path0 = state._orbitPaths.get(25544);
const later = new Date(Date.now() + 600_000);
rendering._updateOrbitPathRotations(later);
const angle = -(gstime(later) - path0.gmstAtBake);
const turned = rings.items.get('25544').positions;
assert.ok(Math.abs(turned[0] - 7e6 * Math.cos(angle)) < 1e-3);
assert.ok(Math.abs(turned[1] - 7e6 * Math.sin(angle)) < 1e-3);
rendering._hideOrbitPath(25544);
assert.equal(rings.items.size, 0);
// The tracked dot draws at the tracker's position, from the next frame.
state._trackedNorad = 25544;
state._enabled = true;
state._params = { showPoints: false, showOrbits: false };
let at = { x: 10, y: 20, z: 30 };
const carrier = rendering._addTrackedEntity({ position: () => at });
assert.deepEqual(carrier, { noradId: 25544 });
const tracked = draw.set(points.replace(':points', ':tracked'));
assert.equal(tracked.items.size, 0);
rendering._preRenderTick({ frame: 3 });
assert.deepEqual(tracked.items.get('25544').pos, at);
assert.equal(tracked.items.get('25544').pixelSize, 14);
assert.equal(tracked.items.get('25544').disableDepthTest, Infinity);
at = { x: 11, y: 21, z: 31 };
rendering._preRenderTick({ frame: 4 });
assert.deepEqual(tracked.items.get('25544').pos, at);
// When the follow camera has already sampled this frame's key, the dot
// draws at that sample, before the frame's own sample moves it on.
const framed = { x: 12, y: 22, z: 32 };
at = framed;
state._trackedFrameGeo = {};
state._trackedFrameNumber = 4;
sampleFrame = () => {
at = { x: 13, y: 23, z: 33 };
return at;
};
rendering._preRenderTick({ frame: 5 });
assert.deepEqual(tracked.items.get('25544').pos, framed);
// With no sample under the frame's key, it draws after the frame's own.
state._trackedFrameNumber = 3;
at = framed;
rendering._preRenderTick({ frame: 6 });
assert.deepEqual(tracked.items.get('25544').pos, { x: 13, y: 23, z: 33 });
assert.equal(
rendering._hitIsTracked({ set: tracked.spec.id, id: '25544' }),
true,
);
rendering._removeTrackedEntity(carrier);
assert.equal(tracked.items.size, 0);
rendering._detach(viewer);
assert.ok([...draw.sets.values()].every((set) => set.disposed));
} finally {
unbind();
}
});
test('the orbit frame matrix turns ECEF about Z by minus the GMST elapsed', () => {
const rendering = createRendering({
state: {},
services: { focus: {} },
parts: {},
});
const bake = new Date('2026-07-20T10:00:00Z');
const now = new Date('2026-07-20T10:10:00Z');
const m = rendering.orbitFrameModelMatrix(gstime(bake), now);
const angle = -(gstime(now) - gstime(bake));
assert.equal(m.length, 16);
assert.ok(Math.abs(m[0] - Math.cos(angle)) < 1e-12);
assert.ok(Math.abs(m[1] - Math.sin(angle)) < 1e-12);
assert.ok(Math.abs(m[4] + Math.sin(angle)) < 1e-12);
assert.equal(m[10], 1);
assert.equal(m[15], 1);
// Written in place into a matrix it is handed.
const into = new Cesium.Matrix4();
assert.equal(rendering.orbitFrameModelMatrix(gstime(bake), now, into), into);
assert.ok(Math.abs(into[0] - Math.cos(angle)) < 1e-12);
});
test('the focus pass projects every dot in one call and dims the dot under the focus', () => {
const viewer = {};
const calls = [];
const { unbind } = bindFakeDraw(viewer, {
camera: { pose: () => ({ position: { x: 0, y: 0, z: 0 } }) },
query: {
// Screen x, y are the point's own x, y.
projectMany(source, out) {
calls.push(source.length / 3);
for (let i = 0, j = 0; i + 2 < source.length; i += 3, j += 2) {
out[j] = source[i];
out[j + 1] = source[i + 1];
}
},
project: () => {
throw new Error('the pass projects in one batch');
},
},
});
try {
const target = {
screenRect: { left: 90, right: 110, top: 90, bottom: 110 },
cameraDistance: 1,
};
const state = {
_points: new Map(),
_orbitPaths: new Map(),
_catalog: new Map(),
_viewer: viewer,
_trackedNorad: null,
_enabled: true,
_params: { showPoints: true, showOrbits: false },
_activeFocusCount: 0,
_lastFocusUpdate: -Infinity,
};
const rendering = createRendering({
state,
services: {
focus: {
...focusDeemphasis,
focusNowMs: (ms) => ms,
getFocusTarget: () => target,
focusPassIsNeeded: () => true,
},
},
parts: {
controls: { _pointStyleFor: () => ({ color: [1, 1, 1, 1] }) },
tracking: { _getTrackedFramePosition: () => null },
},
});
rendering._attach(viewer);
const style = { ...POINT_STYLES.iss, color: [1, 1, 1, 1] };
rendering._addPoint(1, { x: 100, y: 100, z: 0 }, style);
rendering._addPoint(2, { x: 100, y: 100, z: 0 }, style);
rendering._addPoint(3, { x: 500, y: 500, z: 0 }, style);
rendering._addPoint(4, { x: 100, y: 100, z: 0 }, style);
state._points.get(2).show = false;
state._trackedNorad = 4;
for (let now = 0; now <= 5000; now += 100) rendering._updatePointFocus(now);
assert.ok(calls.length > 0);
assert.ok(
calls.every((n) => n === 4),
'one call over every dot',
);
const alpha = (id) => state._points.get(id).color[3];
assert.ok(alpha(1) < 1, 'the dot under the focus dims');
assert.equal(alpha(2), 1, 'a hidden dot is not dimmed');
assert.equal(alpha(3), 1, 'a dot away from the focus is not dimmed');
assert.equal(alpha(4), 1, 'the tracked dot is not dimmed');
rendering._detach(viewer);
} finally {
unbind();
}
});
+416 -251
View File
@@ -1,39 +1,55 @@
import * as Cesium from 'cesium';
// The camera and frame ports over a viewer with no renderer bound, for the
// tracking and lifecycle parts that follow and tick through them.
import '../../render/cesium/camera.js';
import '../../render/cesium/frame.js';
import { toCartesian } from '../../render/cesium/common.js';
import { toColor as cesiumColor } from '../../render/cesium/draw.js';
import { drawOf, findCamera, findQuery } from '../../render/rendererOf.js';
import { fromDegreesInto } from '../../geo/ellipsoid.js';
import { distance } from '../../geo/vector.js';
import { gstime } from 'satellite.js';
import { ISS_NORAD, POSITION_UPDATE_MS, RING_ROTATION_MS } from './policy.js';
/**
* The satellites layer's Cesium side: the point collection and its point
* primitives, the baked orbit-ring primitives, the tracked entity the follow
* camera and the tracked card read, and the per-frame tick that moves them.
* The other parts hand it render-contract values (ECEF `{x, y, z}`, colours
* as `[r, g, b, a]`) and never touch these objects themselves.
* The satellites layer's drawing, through the renderer contract's draw port:
* a points set of the satellite dots, a points set of the tracked
* satellite's dot, and a lines set of the orbit rings, with the per-frame
* tick that moves them. The other parts hand it render-contract values
* (ECEF `{x, y, z}`, colours as `[r, g, b, a]`).
*
* `layerState._points` keeps each satellite's dot as the point item it is
* drawn from (NORAD id → item): its `pos` is moved in place, so a reader
* holding it sees where the dot is now, as one holding a point primitive's
* position did. Writes are kept and sent to the set once per frame, at the
* end of the tick, so a catalog of thousands moves in one upsert.
*/
/** Points shrink with distance as they always have. */
const POINT_SCALE_BY_DISTANCE = new Cesium.NearFarScalar(1e6, 1.5, 2e7, 0.6);
const POINT_SCALE_BY_DISTANCE = Object.freeze({
near: 1e6,
nearValue: 1.5,
far: 2e7,
farValue: 0.6,
});
/** Each policy style once in Cesium's colours (styles are module constants). */
const cesiumStyles = new WeakMap();
function cesiumStyleOf(style) {
let converted = cesiumStyles.get(style);
if (!converted) {
converted = {
pixelSize: style.pixelSize,
color: cesiumColor(style.color),
outlineColor: cesiumColor(style.outlineColor),
outlineWidth: style.outlineWidth,
};
cesiumStyles.set(style, converted);
}
return converted;
}
/**
* The tracked satellite's dot: 14 px yellow with a white outline, drawn
* over everything.
*/
const TRACKED_DOT = Object.freeze({
pixelSize: 14,
color: Object.freeze([1, 1, 0, 1]),
outlineColor: Object.freeze([1, 1, 1, 1]),
outlineWidth: 2,
disableDepthTest: Number.POSITIVE_INFINITY,
});
/** An orbit ring's colour when none is given (cyan). */
const DEFAULT_RING_COLOR = Object.freeze([0, 1, 1, 1]);
/** Rings: this alpha in front of the globe, the dimmer one behind it. */
const RING_ALPHA = 0.6;
const RING_BEHIND_ALPHA = 0.35;
/** An RGBA colour with another alpha. */
const withAlpha = (color, alpha) => [color[0], color[1], color[2], alpha];
/** Layer instances so far: set ids unique to each. */
let instances = 0;
export function createRendering({
state: layerState,
@@ -51,96 +67,182 @@ export function createRendering({
publishFocusTargetAt,
} = services.focus;
const scratchFocusScreen = new Cesium.Cartesian2();
const scratchRingRotation = new Cesium.Matrix3();
// The tracked satellite's per-frame ECEF sample (WS-D2), shared with the
// tracked entity, the follow camera and the tracked card. Tracking writes
// its x/y/z; it stays one Cesium value for the readers that take it.
layerState._trackedFrameCartesian = new Cesium.Cartesian3();
// tracked dot, the follow camera and the tracked card. Tracking writes its
// x/y/z in place.
layerState._trackedFrameCartesian = { x: 0, y: 0, z: 0 };
/** The draw sets, while attached: `{points, tracked, rings}`. */
let sets = null;
/** Dots changed since the last write to the set, by NORAD id. */
const dirty = new Set();
/** Dots removed since the last write to the set, by NORAD id. */
const gone = new Set();
/** Whether every dot was removed since the last write. */
let cleared = false;
/** Whether the satellite dots are shown. */
let pointsShown = true;
/**
* The tracked dot: its item and how its position is read (the tracker's
* callback, read as the follow camera reads it).
*/
let trackedDot = null;
let trackedDrawnThisTick = false;
/** The frame the tick last ran in: the tracked sample's cache key. */
let renderedFrame = -1;
/**
* Build the rigid ECEF transform that keeps an orbit path baked at one GMST
* aligned with live SGP4 positions propagated at another epoch.
* aligned with live SGP4 positions propagated at another epoch: a column-
* major 4×4 rotation about Z.
* @param {number} gmstAtBake GMST used when the path positions were baked.
* @param {Date} nowDate Epoch whose rotating-Earth frame should be displayed.
* @param {Cesium.Matrix4} [result] Optional matrix to update in place.
* @returns {Cesium.Matrix4} Z-rotation from bake-time ECEF to current ECEF.
* @param {ArrayLike<number>} [result] A 16-element matrix to update in place.
* @returns {ArrayLike<number>} Z-rotation from bake-time ECEF to current ECEF.
*/
function orbitFrameModelMatrix(
gmstAtBake,
nowDate,
result = new Cesium.Matrix4(),
) {
const deltaGmst = gstime(nowDate) - gmstAtBake;
const rotation = Cesium.Matrix3.fromRotationZ(
-deltaGmst,
scratchRingRotation,
);
return Cesium.Matrix4.fromRotationTranslation(
rotation,
Cesium.Cartesian3.ZERO,
result,
);
function orbitFrameModelMatrix(gmstAtBake, nowDate, result = new Array(16)) {
const angle = -(gstime(nowDate) - gmstAtBake);
const c = Math.cos(angle);
const s = Math.sin(angle);
result[0] = c;
result[1] = s;
result[2] = 0;
result[3] = 0;
result[4] = -s;
result[5] = c;
result[6] = 0;
result[7] = 0;
result[8] = 0;
result[9] = 0;
result[10] = 1;
result[11] = 0;
result[12] = 0;
result[13] = 0;
result[14] = 0;
result[15] = 1;
return result;
}
/** ECEF `{x, y, z}` positions as the renderer's own. */
/** ECEF `{x, y, z}` positions as the renderer's own: plain copies. */
function _rendererPositions(positions) {
return positions.map(toCartesian);
return positions.map((p) => ({ x: p.x, y: p.y, z: p.z }));
}
/** The scene's rendered-frame number, the tracked sample's cache key. */
/** The frame the tick last ran in, the tracked sample's cache key. */
function _drawnFrameNumber() {
return layerState._viewer?.scene?.frameState?.frameNumber ?? -1;
return renderedFrame;
}
/** Add the point collection the satellite dots draw in. */
/** Make the sets the dots, the tracked dot and the rings draw in. */
function _attach(viewer) {
layerState._pointCollection = new Cesium.PointPrimitiveCollection();
viewer.scene.primitives.add(layerState._pointCollection);
_attachTo(drawOf(viewer));
}
/** Remove the point collection and every orbit ring from `viewer`. */
/** Make the layer's sets on `draw`, a draw port. */
function _attachTo(draw) {
if (sets) _detach();
const prefix = `satellites:${++instances}`;
pointsShown = true;
sets = {
points: draw.points({ id: `${prefix}:points`, show: pointsShown }),
tracked: draw.points({ id: `${prefix}:tracked` }),
// Ring clicks fall through to the satellites and the deselect.
rings: draw.lines({ id: `${prefix}:rings`, pickable: false }),
};
layerState._sets = sets;
dirty.clear();
gone.clear();
cleared = false;
// Dots kept while detached draw once attached.
for (const noradId of layerState._points.keys()) dirty.add(noradId);
}
/** Dispose of the sets; the dots and rings go with them. */
function _detach(viewer) {
if (layerState._pointCollection) {
viewer.scene.primitives.remove(layerState._pointCollection);
layerState._pointCollection = null;
}
// Orbit ring primitives are removed (and destroyed) here
for (const path of layerState._orbitPaths.values()) {
viewer.scene.primitives.remove(path.primitive);
}
if (!sets) return;
sets.points.dispose();
sets.tracked.dispose();
sets.rings.dispose();
sets = null;
layerState._sets = null;
trackedDot = null;
dirty.clear();
gone.clear();
cleared = false;
}
/** Whether there is a point collection to draw satellites in. */
/** Whether there is a set to draw satellites in. */
function _hasPointCollection() {
return Boolean(layerState._pointCollection);
return Boolean(sets);
}
/** Whether the satellite dots are shown. */
function _pointsShown() {
return Boolean(layerState._pointCollection?.show);
return Boolean(sets) && pointsShown;
}
function _setPointsShown(show) {
if (layerState._pointCollection) layerState._pointCollection.show = show;
if (!sets) return;
pointsShown = show;
sets.points.show = show;
}
/** Show or hide every ring. */
function _setOrbitPathsShown(show) {
for (const path of layerState._orbitPaths.values())
path.primitive.show = show;
const changed = [];
for (const path of layerState._orbitPaths.values()) {
path.item.show = show;
changed.push(path.item);
}
if (sets && changed.length) sets.rings.upsert(changed);
}
function _setOrbitPathShown(noradId, show) {
const path = layerState._orbitPaths.get(noradId);
if (path) path.primitive.show = show;
if (!path) return;
path.item.show = show;
sets?.rings.upsert([path.item]);
}
/** Remove every orbit ring from `viewer`'s scene. */
function _clearOrbitPaths(viewer) {
for (const path of layerState._orbitPaths.values())
viewer.scene.primitives.remove(path.primitive);
/** Remove every orbit ring. */
function _clearOrbitPaths() {
const ids = [...layerState._orbitPaths.values()].map(
(path) => path.item.id,
);
layerState._orbitPaths.clear();
if (sets && ids.length) sets.rings.remove(ids);
}
/** Note a dot's change, sent at the end of the frame's tick. */
function _markDirty(noradId) {
gone.delete(noradId);
dirty.add(noradId);
}
/** Send the dots changed since the last frame to the points set. */
function _flushPoints() {
if (!sets) return;
if (cleared) {
cleared = false;
gone.clear();
dirty.clear();
sets.points.set([...layerState._points.values()]);
return;
}
if (gone.size) {
sets.points.remove([...gone].map(String));
gone.clear();
}
if (dirty.size) {
const items = [];
for (const noradId of dirty) {
const item = layerState._points.get(noradId);
if (item) items.push(item);
}
dirty.clear();
if (items.length) sets.points.upsert(items);
}
}
/**
@@ -150,104 +252,125 @@ export function createRendering({
* @param {object} style A `POINT_STYLES` entry.
*/
function _addPoint(noradId, position, style) {
const look = cesiumStyleOf(style);
const point = layerState._pointCollection.add({
position: toCartesian(position),
pixelSize: look.pixelSize,
color: look.color,
outlineColor: look.outlineColor,
outlineWidth: look.outlineWidth,
layerState._points.set(noradId, {
id: String(noradId),
pos: { x: position.x, y: position.y, z: position.z },
pixelSize: style.pixelSize,
color: style.color,
outlineColor: style.outlineColor,
outlineWidth: style.outlineWidth,
scaleByDistance: POINT_SCALE_BY_DISTANCE,
id: noradId,
disableDepthTest: 0,
show: true,
meta: { noradId },
});
layerState._points.set(noradId, point);
_markDirty(noradId);
}
/** Move a drawn dot to ECEF `position`; false when it has none. */
function _movePoint(noradId, position) {
const point = layerState._points.get(noradId);
if (!point) return false;
point.position = position; // primitive setter clones
point.pos.x = position.x;
point.pos.y = position.y;
point.pos.z = position.z;
_markDirty(noradId);
return true;
}
function _removePoint(noradId) {
const point = layerState._points.get(noradId);
if (point && layerState._pointCollection)
layerState._pointCollection.remove(point);
layerState._points.delete(noradId);
if (!layerState._points.delete(noradId)) return;
dirty.delete(noradId);
if (!cleared) gone.add(noradId);
}
/** Remove every dot. */
function _clearPoints() {
layerState._pointCollection.removeAll();
layerState._points.clear();
dirty.clear();
gone.clear();
cleared = true;
}
/** Where a dot is drawn (ECEF), or null. */
function _pointPosition(noradId) {
return layerState._points.get(noradId)?.position || null;
return layerState._points.get(noradId)?.pos || null;
}
/** Hide a dot while the tracked entity draws it. */
/** Hide a dot while the tracked dot draws it. */
function _hidePoint(noradId) {
const point = layerState._points.get(noradId);
if (point) point.show = false;
if (!point) return;
point.show = false;
_markDirty(noradId);
}
/** Show a dot again in its group's style (WS-D3). */
function _restorePoint(noradId, style) {
const point = layerState._points.get(noradId);
if (!point) return;
const look = cesiumStyleOf(style);
point.show = true;
point.pixelSize = look.pixelSize;
point.color = look.color;
point.outlineColor = look.outlineColor;
point.outlineWidth = look.outlineWidth;
point.disableDepthTestDistance = 0;
point.pixelSize = style.pixelSize;
point.color = style.color;
point.outlineColor = style.outlineColor;
point.outlineWidth = style.outlineWidth;
point.disableDepthTest = 0;
_markDirty(noradId);
}
/**
* Add the tracked satellite's entity: it owns a point graphic so the
* follow camera can resolve a bounding sphere (a label-only entity left
* the camera stranded), and the tracked card reads its entity record.
* Draw the tracked satellite's dot and make the carrier the follow target
* and the tracked card read (its entity record holds the card).
* @param {{position: () => object, viewFrom: {x: number, y: number,
* z: number}}} options `position` is evaluated every time it is read.
* @returns {object} The entity.
* z: number}}} options `position` is read as the follow camera reads
* it, once each frame before the tick moves the sample on.
* @returns {object} The carrier.
*/
function _addTrackedEntity({ position, viewFrom }) {
return layerState._viewer.entities.add({
position: new Cesium.CallbackProperty(position, false),
viewFrom: toCartesian(viewFrom),
point: {
pixelSize: 14,
color: Cesium.Color.YELLOW,
outlineColor: Cesium.Color.WHITE,
outlineWidth: 2,
disableDepthTestDistance: Number.POSITIVE_INFINITY,
function _addTrackedEntity({ position }) {
const noradId = layerState._trackedNorad;
const carrier = { noradId };
trackedDot = {
position,
item: {
id: String(noradId),
pos: { x: 0, y: 0, z: 0 },
...TRACKED_DOT,
meta: { noradId },
},
});
drawn: false,
};
// Drawn from the next frame's tick on, as the camera first frames it.
return carrier;
}
function _removeTrackedEntity(entity) {
layerState._viewer.entities.remove(entity);
function _removeTrackedEntity() {
if (trackedDot?.drawn) sets?.tracked.clear();
trackedDot = null;
}
/** Whether a scene pick is the tracked satellite's entity. */
function _pickIsTrackedEntity(picked) {
return picked?.id === layerState._trackedEntity;
/** Put the tracked dot where the tracker says it is now. */
function _drawTrackedDot() {
if (!trackedDot || !sets) return;
const at = trackedDot.position();
if (!at) return;
const pos = trackedDot.item.pos;
pos.x = at.x;
pos.y = at.y;
pos.z = at.z;
sets.tracked.upsert([trackedDot.item]);
trackedDot.drawn = true;
}
/**
* The NORAD id a scene pick's point primitive carries, or null. Any
* primitive with a numeric id answers; the caller checks the catalog.
*/
function _pickedPointId(picked) {
const prim = picked?.primitive;
if (!prim || prim.id == null) return null;
const noradId = Number(prim.id);
return isNaN(noradId) ? null : noradId;
/** Whether a click's draw hit is the tracked satellite's dot. */
function _hitIsTracked(hit) {
return Boolean(sets) && hit?.set === sets.tracked.id;
}
/** The NORAD id of the satellite dot a click's draw hit is on, or null. */
function _hitPointId(hit) {
if (!sets || hit?.set !== sets.points.id) return null;
const noradId = Number(hit.id);
return Number.isFinite(noradId) ? noradId : null;
}
/** Publish the tracked satellite's focus rectangle from its cached position. */
@@ -255,23 +378,27 @@ export function createRendering({
publishFocusTargetAt({ ...target, viewer: layerState._viewer });
}
/** A ring's positions rotated from its bake-time frame to `gmst`'s. */
function _ringPositions(path, gmst) {
const angle = -(gmst - path.gmstAtBake);
const c = Math.cos(angle);
const s = Math.sin(angle);
const base = path.base;
const out = new Float64Array(base.length * 3);
for (let i = 0; i < base.length; i++) {
const p = base[i];
out[i * 3] = c * p.x - s * p.y;
out[i * 3 + 1] = s * p.x + c * p.y;
out[i * 3 + 2] = p.z;
}
return out;
}
/**
* Show orbital path for a satellite.
*
* RING FLICKER FIX: this is a one-instance Cesium.Primitive built
* synchronously ONCE (asynchronous: false), then re-aligned to current GMST
* each tick via its modelMatrix. The previous Entity-polyline approach
* rebuilt geometry ASYNCHRONOUSLY on every positions assignment, which made
* both the selected ring and the ISS ring blink once per second while the
* rebuild was in flight. A rigid Z-rotation needs no rebuild at all.
*
* Why not a CallbackProperty entity (dynamic mode)? Verified in Cesium
* 1.138 source: the dynamic polyline updater renders through a shared
* PolylineCollection and applies only the fill material —
* `depthFailMaterial` is silently dropped, losing the dimmed behind-Earth
* segment. The Primitive keeps it via depthFailAppearance + the per-instance
* depthFailColor attribute (same mechanism the entity STATIC batch uses):
* bright where above the horizon, dimmed where behind the globe.
* Show orbital path for a satellite: the ring over one orbit, baked once
* in ECEF at the current GMST, bright in front of the globe and dimmed
* behind it (`depthFailColor`), and turned with the Earth each
* `RING_ROTATION_MS` (`_updateOrbitPathRotations`).
*/
function _showOrbitPath(noradId, color) {
@@ -281,86 +408,64 @@ export function createRendering({
if (!sat || !layerState._viewer) return;
const bakeDate = new Date();
const basePositions = _rendererPositions(
parts.orbits.computeOrbitPath(sat.satrec, bakeDate),
);
if (basePositions.length < 2) return;
const base = parts.orbits.computeOrbitPath(sat.satrec, bakeDate);
if (base.length < 2) return;
const pathColor = color ? cesiumColor(color) : Cesium.Color.CYAN;
const primitive = new Cesium.Primitive({
geometryInstances: new Cesium.GeometryInstance({
geometry: new Cesium.PolylineGeometry({
positions: basePositions,
width: noradId === ISS_NORAD ? 2.5 : 2.0,
vertexFormat: Cesium.PolylineColorAppearance.VERTEX_FORMAT,
}),
attributes: {
color: Cesium.ColorGeometryInstanceAttribute.fromColor(
pathColor.withAlpha(0.6),
),
depthFailColor: Cesium.ColorGeometryInstanceAttribute.fromColor(
pathColor.withAlpha(0.35),
),
},
}),
appearance: new Cesium.PolylineColorAppearance({ translucent: true }),
depthFailAppearance: new Cesium.PolylineColorAppearance({
translucent: true,
}),
asynchronous: false, // build this frame — no async-rebuild blink window
allowPicking: false, // ring clicks fall through to satellites/deselect
});
layerState._viewer.scene.primitives.add(primitive);
layerState._orbitPaths.set(noradId, {
primitive,
const pathColor = color || DEFAULT_RING_COLOR;
const path = {
base,
// Same Date object as computeOrbitPath's internal fixedGmst → identical
// GMST value (gstime is pure), so delta starts at exactly 0 and the
// initial identity modelMatrix is correct until the first ring tick.
// GMST value (gstime is pure), so the ring starts unturned.
gmstAtBake: gstime(bakeDate),
});
item: null,
};
path.item = {
id: String(noradId),
positions: _ringPositions(path, path.gmstAtBake),
widthPx: noradId === ISS_NORAD ? 2.5 : 2.0,
// Along the ellipsoid between samples, as the ring always ran.
mode: 'geodesic',
style: { kind: 'solid', color: withAlpha(pathColor, RING_ALPHA) },
depthFailColor: withAlpha(pathColor, RING_BEHIND_ALPHA),
show: true,
};
layerState._orbitPaths.set(noradId, path);
sets?.rings.upsert([path.item]);
}
/**
* Rotate every baked orbit ring from its bake-time ECEF snapshot to current
* Turn every baked orbit ring from its bake-time ECEF snapshot to current
* GMST (WS-D1). The baked ring is an inertial-frame snapshot frozen at
* gmstAtBake; the live dot lives in true rotating-frame ECEF, so without this
* the dot slides west off the ring at Earth-rotation rate (~0.25°/min).
*
* Sign derivation: a point fixed in inertial space keeps its right ascension
* α, so its ECEF longitude λ = α − gmst DECREASES by ΔGMST as time advances
* (it drifts WEST). Cesium.Matrix3.fromRotationZ(θ) rotates +X toward +Y,
* i.e. INCREASES longitude by θ — so we rotate the baked points by −ΔGMST.
* Mental check: ISS baked over Austin at t0; 10 min later Austin has rotated
* east under the (inertial) ring, so the ring must sit further WEST in ECEF.
* (it drifts WEST). A rotation about Z by θ INCREASES longitude by θ — so
* the baked points are rotated by −ΔGMST. Mental check: ISS baked over
* Austin at t0; 10 min later Austin has rotated east under the (inertial)
* ring, so the ring must sit further WEST in ECEF.
*
* Wraparound: gstime returns radians in [0, 2π), so the raw difference can be
* off from the continuous ΔGMST — but only by exact multiples of 2π, which a
* rotation cannot distinguish. Tiny negative deltas right after bake are
* likewise harmless. No unwrapping needed.
*
* No SGP4 here — the rotation is applied as the ring primitive's modelMatrix
* (exact compensation; WGS84 is rotationally symmetric about Z, so rotating
* the baked curve rigidly equals rebaking from rotated points). modelMatrix
* updates are synchronous uniforms — no geometry rebuild, no flicker. Post-
* creation modelMatrix changes are supported for one-instance primitives in
* 3D mode, which these rings are. In-place mutation is safe: Primitive.update
* diffs modelMatrix against an internal clone.
* No SGP4 here: WGS84 is rotationally symmetric about Z, so rotating the
* baked curve rigidly equals rebaking from rotated points. A ring with a
* `depthFailColor` is built at once where it now runs, so it never blinks.
* @param {Date} nowDate Epoch used for current GMST.
*/
function _updateOrbitPathRotations(nowDate) {
if (layerState._orbitPaths.size === 0) return;
const gmst = gstime(nowDate);
const changed = [];
for (const path of layerState._orbitPaths.values()) {
if (!path.primitive) continue;
orbitFrameModelMatrix(
path.gmstAtBake,
nowDate,
path.primitive.modelMatrix,
);
path.item.positions = _ringPositions(path, gmst);
changed.push(path.item);
}
sets?.rings.upsert(changed);
}
/**
@@ -369,15 +474,13 @@ export function createRendering({
function _hideOrbitPath(noradId) {
const path = layerState._orbitPaths.get(noradId);
if (path) {
if (layerState._viewer)
layerState._viewer.scene.primitives.remove(path.primitive); // remove() destroys
layerState._orbitPaths.delete(noradId);
}
if (!path) return;
layerState._orbitPaths.delete(noradId);
sets?.rings.remove([path.item.id]);
}
/**
* Propagate all CORE satellite positions and update point primitives.
* Propagate all CORE satellite positions and update their dots.
* (~840 sats ≈ 1.6 ms/pass — fine at the 1s/200ms cadence.) Dense extras are
* excluded: they refresh on the round-robin budget in _propagateDenseChunk.
*/
@@ -391,14 +494,10 @@ export function createRendering({
const pos = parts.orbits.propagatePosition(sat.satrec, now);
if (!pos) continue;
const cartesian = Cesium.Cartesian3.fromDegrees(
pos.longitude,
pos.latitude,
pos.altitude,
);
const point = layerState._points.get(noradId);
if (point) {
point.position = cartesian;
fromDegreesInto(pos.longitude, pos.latitude, pos.altitude, point.pos);
_markDirty(noradId);
updated++;
}
}
@@ -407,15 +506,43 @@ export function createRendering({
}
/**
* Shared scene.preRender tick (single definition for init + enable):
* Shared preRender tick (single definition for init + enable):
* - the tracked dot where the follow camera put it this frame,
* - core fleet propagation at 200ms-tracked / 1s-idle cadence,
* - dense extras on a per-frame round-robin budget,
* - tracked satellite's point primitive per frame (WS-D2),
* - orbit ring GMST re-alignment every ~1s (WS-D1).
* - tracked satellite's dot sample per frame (WS-D2),
* - orbit ring GMST re-alignment every ~1s (WS-D1),
* - the frame's dot changes sent to the points set.
* @param {{frame: number}} [t] The frame port's tick.
*/
function _preRenderTick() {
if (!layerState._enabled) return;
function _preRenderTick(t) {
if (layerState._enabled) _tick();
// The frame's sample is taken from here on (the tracked dot above was
// drawn from the last one, as the camera framed it).
renderedFrame = Number.isFinite(t?.frame) ? t.frame : renderedFrame + 1;
if (layerState._enabled) _tickAfterFrame();
_flushPoints();
}
/** The tick's part read before the frame's own sample is taken. */
function _tick() {
// The tracked dot draws at the sample the follow camera framed this frame.
// With no camera reading it this frame, it is drawn after the frame's own
// sample instead, so the tracked satellite is propagated once a frame.
trackedDrawnThisTick = false;
if (
layerState._trackedNorad !== null &&
layerState._trackedFrameGeo !== null &&
layerState._trackedFrameNumber === renderedFrame
) {
_drawTrackedDot();
trackedDrawnThisTick = true;
}
}
/** The tick's part that takes the frame's own sample. */
function _tickAfterFrame() {
const now = focusNowMs(Date.now());
const interval = layerState._trackedNorad ? 200 : POSITION_UPDATE_MS;
@@ -433,20 +560,20 @@ export function createRendering({
if (layerState._params.showPoints) parts.catalog._propagateDenseChunk();
// Keep the tracked dot on the per-frame epoch shared with label + camera —
// runs after _propagateAll so the per-frame sample wins over the 200ms one.
// Keep the tracked satellite's (hidden) dot on the per-frame epoch shared
// with label + camera — runs after _propagateAll so the per-frame sample
// wins over the 200ms one.
if (layerState._trackedNorad !== null) {
const pos = parts.tracking._getTrackedFramePosition();
const point = layerState._points.get(layerState._trackedNorad);
if (pos && point) {
point.position = layerState._trackedFrameCartesian; // primitive setter clones
}
if (pos && layerState._points.has(layerState._trackedNorad))
_movePoint(layerState._trackedNorad, layerState._trackedFrameCartesian);
if (!trackedDrawnThisTick) _drawTrackedDot();
}
_updatePointFocus(now);
// Hidden standalone orbit primitives do not need GMST matrix writes while
// Space Missions draws the selected mission orbit itself.
// Hidden standalone orbit rings do not need turning while Space Missions
// draws the selected mission orbit itself.
if (
layerState._params.showOrbits &&
now - layerState._lastRingRotation >= RING_ROTATION_MS
@@ -458,6 +585,12 @@ export function createRendering({
/** Focus alpha for satellite points, inside the existing shared preRender tick. */
// The focus pass projects every dot in one call, into buffers kept between
// passes, so a pass over thousands of dots allocates nothing per dot.
let focusSource = new Float64Array(0);
let focusScreen = new Float32Array(0);
const focusOrder = [];
const focusScreenXY = { x: 0, y: 0 };
function _updatePointFocus(nowMs) {
const target = getFocusTarget();
if (
@@ -467,28 +600,55 @@ export function createRendering({
return;
if (nowMs - layerState._lastFocusUpdate < 80) return;
layerState._lastFocusUpdate = nowMs;
const scene = layerState._viewer.scene;
const camera = layerState._viewer.camera;
const query = findQuery(layerState._viewer);
const eye = findCamera(layerState._viewer)?.pose()?.position;
if (!query || !eye) return;
const count = layerState._points.size;
if (focusSource.length < count * 3) {
focusSource = new Float64Array(count * 3);
focusScreen = new Float32Array(count * 2);
}
focusOrder.length = 0;
for (const point of layerState._points.values()) {
const pos = point?.pos;
const i = focusOrder.length * 3;
focusSource[i] = pos ? pos.x : NaN;
focusSource[i + 1] = pos ? pos.y : NaN;
focusSource[i + 2] = pos ? pos.z : NaN;
focusOrder.push(pos);
}
query.projectMany(
focusSource.subarray(0, focusOrder.length * 3),
focusScreen,
);
// The pass asks in the points' own order, skipping some: a cursor finds
// each asked position in one sweep.
let cursor = 0;
const result = applySatellitePointFocusDeemphasis({
points: layerState._points,
trackedId: layerState._trackedNorad,
target,
previousActiveCount: layerState._activeFocusCount,
nowMs,
screenPositionFor: (position) =>
Cesium.SceneTransforms.worldToWindowCoordinates(
scene,
position,
scratchFocusScreen,
),
cameraDistanceFor: (position) =>
Cesium.Cartesian3.distance(camera.positionWC, position),
screenPositionFor: (position) => {
while (cursor < focusOrder.length && focusOrder[cursor] !== position)
cursor++;
if (cursor >= focusOrder.length) {
cursor = 0;
return query.project(position);
}
const x = focusScreen[cursor * 2];
const y = focusScreen[cursor * 2 + 1];
if (Number.isNaN(x) || Number.isNaN(y)) return null;
focusScreenXY.x = x;
focusScreenXY.y = y;
return focusScreenXY;
},
cameraDistanceFor: (position) => distance(eye, position),
baseColorFor: (noradId) =>
cesiumStyleOf(
parts.controls._pointStyleFor(
noradId,
layerState._catalog.get(noradId)?.group,
),
parts.controls._pointStyleFor(
noradId,
layerState._catalog.get(noradId)?.group,
).color,
});
layerState._activeFocusCount = result.activeCount;
@@ -497,6 +657,8 @@ export function createRendering({
/**
* Apply the gated satellite-point focus pass through the production color path.
* @param {object} input
* @param {Map<number, object>} input.points Point items by NORAD id; a
* written colour is sent to the set with the frame's other changes.
* @returns {{writes:number,transitioning:boolean,activeCount:number,ran:boolean}}
*/
@@ -518,8 +680,8 @@ export function createRendering({
let transitioning = false;
let activeCount = 0;
for (const [noradId, point] of points || []) {
if (noradId === trackedId || !point?.position) continue;
const cameraDistance = cameraDistanceFor(point.position);
if (noradId === trackedId || !point?.pos) continue;
const cameraDistance = cameraDistanceFor(point.pos);
const distanceScale = nearFarScalarValueAtDistance(
point.scaleByDistance,
cameraDistance,
@@ -529,7 +691,7 @@ export function createRendering({
// Hidden points still release toward identity, preventing stale dim
// alpha if a catalog/presentation toggle later makes them visible.
screenPosition:
point.show === false ? null : screenPositionFor(point.position),
point.show === false ? null : screenPositionFor(point.pos),
cameraDistance,
nowMs,
target,
@@ -540,11 +702,12 @@ export function createRendering({
transitioning ||= focus.transitioning;
if (focus.active) activeCount += 1;
const base = baseColorFor(noradId);
const alpha = base.alpha * focus.factor;
if (focusAlphaNeedsWrite(point.color?.alpha, alpha, params)) {
const alpha = base[3] * focus.factor;
if (focusAlphaNeedsWrite(point.color?.[3], alpha, params)) {
// Point stays continuously present at the non-zero emphasis floor; its
// own alpha yields around the tracked target, independent of draw order.
point.color = base.withAlpha(alpha);
point.color = withAlpha(base, alpha);
if (points === layerState._points) _markDirty(noradId);
writes += 1;
}
}
@@ -555,6 +718,7 @@ export function createRendering({
_rendererPositions,
_drawnFrameNumber,
_attach,
_attachTo,
_detach,
_hasPointCollection,
_pointsShown,
@@ -572,8 +736,8 @@ export function createRendering({
_addTrackedEntity,
_removeTrackedEntity,
_publishTrackedFocus,
_pickIsTrackedEntity,
_pickedPointId,
_hitIsTracked,
_hitPointId,
_showOrbitPath,
_updateOrbitPathRotations,
_hideOrbitPath,
@@ -581,5 +745,6 @@ export function createRendering({
_preRenderTick,
_updatePointFocus,
applySatellitePointFocusDeemphasis,
_flushPoints,
};
}
+7 -3
View File
@@ -12,6 +12,7 @@ import { createTracking } from './tracking.js';
import { createRendering } from './rendering.js';
import { bindRenderer } from '../../render/rendererOf.js';
import { fakeSceneFrame } from '../../testSupport/fakeCesiumScene.mjs';
import { fakeDrawPort } from '../../testSupport/fakeDrawPort.mjs';
import { createCatalog } from './catalog.js';
import { createLifecycle } from './lifecycle.js';
import { createInteraction } from './interaction.js';
@@ -66,7 +67,7 @@ async function fixture(t) {
fetchImpl: (path, options) =>
fetch(`http://127.0.0.1:${server.address().port}${path}`, options),
});
// Application host services and native EventTargets; actual Cesium collections,
// Application host services and native EventTargets; a fake draw port,
// input handler, events, SGP4, ingestion and lifecycle run without a WebGL scene.
const noop = () => {};
const services = {
@@ -117,11 +118,14 @@ async function fixture(t) {
},
trackedEntityChanged: new Cesium.Event(),
};
const unbind = bindRenderer(viewer, { frame: fakeSceneFrame(viewer) });
const unbind = bindRenderer(viewer, {
frame: fakeSceneFrame(viewer),
draw: fakeDrawPort(),
});
await parts.lifecycle.methods.init(viewer);
t.after(async () => {
unbind();
if (state._pointCollection) parts.lifecycle.methods.destroy(viewer);
if (state._sets) parts.lifecycle.methods.destroy(viewer);
viewer.scene.primitives.destroy();
if (previousDocument === undefined) delete globalThis.document;
else globalThis.document = previousDocument;
+6 -6
View File
@@ -15,18 +15,18 @@ export function createState({ services }) {
state._catalog = new Map();
state._pointCollection = null;
/** The draw sets (`{points, tracked, rings}`), owned by the rendering part. */
state._sets = null;
state._points = new Map();
// noradId → point primitive
// noradId → the point item its dot is drawn from (the rendering part's)
/** Stable lightweight records reused by the detection overlay between updates. */
state._detectionObjects = new Map();
// noradId → { primitive, gmstAtBake }, owned by the rendering part:
// primitive is a one-instance primitive holding the ring baked in ECEF
// at gmstAtBake; the preRender tick re-aligns it to current GMST by updating
// its modelMatrix (rigid Z-rotation — no geometry rebuild, WS-D1).
// noradId → { base, gmstAtBake, item }, owned by the rendering part: base
// is the ring baked in ECEF at gmstAtBake; the preRender tick turns it to
// current GMST (rigid Z-rotation, WS-D1) into the line item drawn.
state._orbitPaths = new Map();
+35 -17
View File
@@ -1,5 +1,23 @@
import { rendererOf } from '../../render/rendererOf.js';
import { ISS_NORAD, ISS_OVERLAY_SOURCE_ID } from './policy.js';
/** A draw port that draws nothing, for seams that need sets but no renderer. */
const NO_DRAW = (() => {
const set = (spec) => ({
id: spec.id,
show: spec.show !== false,
set() {},
upsert() {},
remove() {},
clear() {},
setOptions() {},
size: () => 0,
on: () => () => {},
dispose() {},
});
return { points: set, lines: set, icons: set, shapes: set };
})();
export function createTesting({ state: layerState, services, parts, source }) {
/**
* Seed a single tracked satellite so tests can invoke the exact production
@@ -8,8 +26,8 @@ export function createTesting({ state: layerState, services, parts, source }) {
* @param {number} state.noradId
* @param {string} state.name
* @param {object} state.satrec
* @param {object} state.entity
* @param {object} state.point
* @param {object} state.entity The tracked carrier.
* @param {object} state.point The satellite's point item (`pos` ECEF).
* @param {object} state.viewer
* @param {() => (number|Date)} state.now
*/
@@ -97,9 +115,7 @@ export function createTesting({ state: layerState, services, parts, source }) {
catalog = 'core',
showPoints = true,
} = {}) {
layerState._viewer = {
scene: { primitives: { add: (p) => p, remove() {} } },
};
layerState._viewer = {};
// Neutralize the shared world-overlay host: these tests exercise catalog and
// row-control logic, not the ISS callout.
layerState._overlayHost = {
@@ -107,12 +123,7 @@ export function createTesting({ state: layerState, services, parts, source }) {
setVisible() {},
clearSource() {},
};
layerState._pointCollection = {
show: true,
add: (opts) => ({ ...opts }),
remove() {},
removeAll() {},
};
parts.rendering._attachTo(NO_DRAW);
layerState._catalog = new Map();
layerState._points = new Map();
layerState._detectionObjects = new Map();
@@ -136,7 +147,7 @@ export function createTesting({ state: layerState, services, parts, source }) {
layerState._overlayHost = layerState.DEFAULT_OVERLAY_HOST;
layerState._orbitPaths = new Map();
layerState._viewer = null;
layerState._pointCollection = null;
parts.rendering._detach();
layerState._catalog = new Map();
layerState._points = new Map();
layerState._denseIds = [];
@@ -176,17 +187,23 @@ export function createTesting({ state: layerState, services, parts, source }) {
[
ISS_NORAD,
{
// A stand-in ring: shown, at the identity 4x4 (column-major).
primitive: {
show: true,
modelMatrix: [1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1, 0, 0, 0, 0, 1],
},
// A stand-in ring: shown, baked with no points.
base: [],
gmstAtBake: 0,
item: {
id: String(ISS_NORAD),
positions: new Float64Array(0),
show: true,
},
},
],
]);
layerState._trackedNorad = null;
layerState._trackedEntity = null;
// Drawn through the viewer's renderer when it has one bound.
parts.rendering._detach();
const draw = rendererOf(viewer)?.draw;
if (draw) parts.rendering._attachTo(draw);
if (!preservePending) parts.tracking._cancelPendingTrackingRestore();
layerState._trackedFrameNumber = -1;
layerState._trackedFrameGeo = null;
@@ -231,6 +248,7 @@ export function createTesting({ state: layerState, services, parts, source }) {
function _clearSatelliteLabelLifecycleForTest() {
parts.tracking._clearTracking();
parts.rendering._detach();
layerState._enabled = false;
layerState._overlayHost.clearSource(ISS_OVERLAY_SOURCE_ID);
layerState._overlayHost.setVisible(ISS_OVERLAY_SOURCE_ID, false);
+9 -11
View File
@@ -90,7 +90,7 @@ export function createTracking({ state: layerState, services, parts, source }) {
const clearedNorad = layerState._trackedNorad;
clearFocusTarget('satellites', layerState._trackedNorad);
// Re-show the dot (hidden while the tracked entity rendered it) and
// Re-show the dot (hidden while the tracked dot drew it) and
// restore the original group palette from the shared style table (WS-D3)
parts.rendering._restorePoint(
layerState._trackedNorad,
@@ -104,7 +104,7 @@ export function createTracking({ state: layerState, services, parts, source }) {
layerState._trackedFrameNumber = -1;
layerState._trackedFrameGeo = null;
// Remove tracked entity and orbit path (unless ISS — keep its path)
// Remove the tracked dot and orbit path (unless ISS — keep its path)
if (layerState._trackedNorad !== ISS_NORAD) {
parts.rendering._hideOrbitPath(layerState._trackedNorad);
}
@@ -128,8 +128,8 @@ export function createTracking({ state: layerState, services, parts, source }) {
/**
* Get the tracked satellite's geodetic position, propagated at most once per
* rendered frame (WS-D2). All tracked-satellite consumers (entity position
* callback → camera, host model, point primitive, getTrackedInfo) share this
* rendered frame (WS-D2). All tracked-satellite consumers (the tracked dot
* and follow camera, host model, the hidden dot, getTrackedInfo) share this
* single `new Date()` epoch per frame, so they can never diverge by the old
* 200ms throttle. The matching ECEF position is left in
* `_trackedFrameCartesian`. SGP4 for one satellite per frame is cheap.
@@ -405,16 +405,13 @@ export function createTracking({ state: layerState, services, parts, source }) {
layerState._trackedFrameGeo = null;
parts.labels._syncIssOverlay();
// Hide the dot — the tracked ENTITY renders it below. The entity must
// own a point graphic so the tracking camera can resolve a bounding
// sphere and engage viewFrom (a label-only entity left the camera
// stranded; this mirrors the proven flights pattern).
// Hide the dot — the tracked dot draws it, larger and over everything.
parts.rendering._hidePoint(noradId);
// Show orbital path
parts.rendering._showOrbitPath(noradId, TRACKED_ORBIT_COLOR);
// Tracked entity position propagates per evaluation through the per-frame
// The tracked position propagates per evaluation through the per-frame
// cache (WS-D2) — dot, host readout, and camera share one SGP4 epoch per frame.
// Falls back to the dot's 1s-throttled position if SGP4 fails.
const trackedPosition = () => {
@@ -457,8 +454,9 @@ export function createTracking({ state: layerState, services, parts, source }) {
selectTrackedSubjectContext(_contextSubjectMetadata(noradId, initialPos));
layerState._contextRefreshedAtMs = Date.now();
// The renderer's own frame for a fast mover (autodetect), as the tracked entity
// had; no close-range rules at orbital distances.
// The renderer's own frame for a fast mover (autodetect), as the tracked
// entity had; no close-range rules at orbital distances. The carrier is
// what the tracked card reads (its entity record).
layerState._followTarget = entityFollowTarget(layerState._trackedEntity, {
position: trackedPosition,
frame: 'autodetect',
+2
View File
@@ -1572,6 +1572,8 @@ export function createCesiumDraw({
}),
show: item.show !== false,
asynchronous: false,
// A set that never picks keeps these out of the pick pass too.
allowPicking: record.spec.pickable !== false,
});
}
+64
View File
@@ -1889,6 +1889,70 @@ test('the installations layer draws its site dots, outlines and selected dot on
assert.equal(scene.added.length, 0, 'gone with the layer');
});
test('the satellites layer draws its dots as one point collection and its rings as depth-fail primitives out of picks', async () => {
const { createRendering } =
await import('../../layers/satellites/rendering.js');
const { POINT_STYLES, TRACKED_ORBIT_COLOR } =
await import('../../layers/satellites/policy.js');
const scene = fakeScene();
const viewer = { scene };
const state = {
_points: new Map(),
_orbitPaths: new Map(),
_catalog: new Map([[25544, { satrec: {} }]]),
_viewer: viewer,
_trackedNorad: null,
_enabled: false,
};
const ring = [
{ x: 7e6, y: 0, z: 0 },
{ x: 0, y: 7e6, z: 0 },
{ x: -7e6, y: 0, z: 0 },
];
const rendering = createRendering({
state,
services: { focus: {} },
parts: { orbits: { computeOrbitPath: () => ring } },
});
rendering._attach(viewer);
rendering._addPoint(25544, { x: 7e6, y: 0, z: 0 }, POINT_STYLES.iss);
rendering._addPoint(5, { x: 0, y: 7e6, z: 0 }, POINT_STYLES.visual);
rendering._preRenderTick({ frame: 1 });
const points = scene.added.find(
(host) => host instanceof Cesium.PointPrimitiveCollection,
);
assert.equal(points.length, 2);
const iss = points.get(0);
assert.equal(iss.id.id, '25544');
assert.deepEqual(iss.id.meta, { noradId: 25544 });
assert.equal(iss.pixelSize, 12);
assert.equal(iss.scaleByDistance.nearValue, 1.5);
assert.equal(iss.scaleByDistance.far, 2e7);
// Moved in place, both in one write.
rendering._movePoint(25544, { x: 6.9e6, y: 0, z: 0 });
rendering._movePoint(5, { x: 0, y: 6.9e6, z: 0 });
rendering._preRenderTick({ frame: 2 });
assert.equal(points.get(0), iss);
assert.equal(iss.position.x, 6.9e6);
withImageClasses(() =>
rendering._showOrbitPath(25544, TRACKED_ORBIT_COLOR),
);
const all = (host) =>
host instanceof Cesium.PrimitiveCollection
? Array.from({ length: host.length }, (_, i) => all(host.get(i))).flat()
: [host];
const primitive = scene.added
.flatMap(all)
.find(
(host) => host instanceof Cesium.Primitive && host.depthFailAppearance,
);
assert.ok(primitive, 'a ring with a dimmed part behind the globe');
assert.equal(primitive.allowPicking, false, 'ring clicks fall through');
rendering._detach(viewer);
assert.equal(scene.added.length, 0, 'gone with the layer');
});
test('the ALPR layer draws its badges as icons that follow the ground, restyled in place', async () => {
const { alprMarkers, createAlprMarkerSet } =
await import('../../layers/alpr/markerState.js');
-1
View File
@@ -15,7 +15,6 @@
"src/layers/launches/orbitRendering.js",
"src/layers/launches/rendering.js",
"src/layers/recentImagery/rendering.js",
"src/layers/satellites/rendering.js",
"src/layers/traffic/rendering.js",
"src/layers/transit/rendering.js",
"src/layers/weather/shellRendering.js",
+3
View File
@@ -98,6 +98,9 @@ const DRAW_FROM_CALLER = new Set([
// Its site dots, outlines and selected fill draw through `drawOf`; it
// follows a site and reads the globe through the camera and globe ports.
'./layers/installations',
// Its dots, tracked dot and orbit rings draw through `drawOf`; it follows,
// ticks, projects and reads the eye through the ports.
'./layers/satellites',
// Its data packs draw through `drawOf`; its flights ask `cameraOf`, which
// throws until then too.
'./scenes',