Widen the star catalogue, and separate what is drawn from what is known

The map held 8750 stars within 50 pc and rendered 371 systems. Both were
lower than they needed to be, for different reasons.

The star catalogue was capped by its own encoding as much as by the
cutoff: one JSON object per star, eight key names repeated each time, 157
bytes a star. At the range HYG actually reaches that is 17 MB to download
and parse before the first frame. So the numbers move into two binary
column stores — positions in stars.bin, which the GPU is handed verbatim,
and id/magnitude/colour/spectral index in stars-meta.bin — and the JSON
keeps only the strings, with 2600 distinct spectral classifications
collapsed to a dictionary. The layout is defined once, in star-catalog.ts,
and the ETL and the app both use it, so the writer and the reader cannot
drift.

The cutoff then goes to 250 pc: 68388 stars, 7.8x as many for 1.7x the
bytes. That is where HYG's measurements stop rather than a round number —
98.6% of its rows are Hipparcos, whose parallaxes are good to about a
milliarcsecond, so beyond 250 pc it would be plotting noise.

Drawing all of them is a separate question from knowing them, and it is
answered separately. The field draws a budget: every star inside 25 pc,
because the nearest are faint red dwarfs and Proxima Centauri is magnitude
11, then the brightest of everything beyond. Search, navigation and the
planet cross-reference still see the whole catalogue. A real GPU would
draw all 68388 without noticing; the budget is for the machines that would
not, and it is one constant.

Systems were limited by something else entirely. The archive data already
shipped named 4735 host stars and only 388 resolved, because the rest lay
outside a 50 pc catalogue — and the cross-reference kept only its own
result, so redoing it meant re-downloading an archive that is not
reachable from here. Host coordinates are now stored with each planet, and
the match is re-resolved at build time against whatever catalogue the run
produced. Even name matching alone, which needs no coordinates and so
works on the records already shipped, rescues 335 planets across 238
systems: 371 renderable systems become 609.

Two selection rules were tuned for a 50 pc bubble and no longer fit.
Tethers followed the Sun's nearest neighbours, which are a speck at this
range, and now follow the brightest; labels were ranked by proximity,
which named whatever sat nearest the middle of the screen, and are now
ranked by brightness — so the view names Canopus, Achernar and Spica
rather than a clump of catalogue designations.

Co-Authored-By: Claude Opus 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WaySiNst4HhDXBHnMy8p5G

src/app/features/galaxy-system/galaxy-system-scene.component.spec.ts

@@ -215,7 +215,9 @@ describe('GalaxySystemSceneComponent camera-flight transitions', () => {
     // far the camera has pulled back, so what identifies it is the far plane it settles on
     // (5000 pc) versus the AU-space one (20000 AU), not a fixed near plane.
     expect(engine.getCamera().far).toBeCloseTo(5000, 6);
-    expect(engine.getCamera().near).toBeLessThan(0.1);
+    // The near plane tracks how far back the camera is rather than sitting at a constant, so
+    // what identifies galaxy space is that it is a small fraction of that far plane.
+    expect(engine.getCamera().near).toBeLessThan(engine.getCamera().far / 1000);
     expect(navigationStore.viewLevel()).toBe('galaxy');
   });
 

src/app/features/galaxy-system/galaxy-system-scene.component.ts

@@ -30,8 +30,14 @@ const SOL_STAR_ID = 0;
 /** Stars drawn from a colour rather than a photograph get a more restrained halo. */
 const DIM_STAR_GLOW_SCALE = 0.6;
 
-/** Stars closer than this to the camera get a name label (always includes the selection). */
-const LABEL_MAX_DISTANCE_PC = 20;
+/**
+ * How far from what the camera is looking at a star can be and still be named, as a fraction of
+ * how far back the camera is — so the net widens as the view pulls out and closes as it dives
+ * in, instead of naming the same handful of stars at every scale. Bounded at both ends.
+ */
+const LABEL_RADIUS_TO_ORBIT_DISTANCE = 0.35;
+const MIN_LABEL_RADIUS_PC = 4;
+const MAX_LABEL_RADIUS_PC = 400;
 /** Caps how many labels are shown at once, to keep the DOM light. */
 const LABEL_MAX_COUNT = 15;
 /**
@@ -57,7 +63,7 @@ const CLICK_DRAG_SLOP_PX = 5;
  * arbitrary equatorial direction gives — the plane is tilted 63 degrees to the equator.
  */
 const GALAXY_OVERVIEW_POSITION = (() => {
-  const view = galacticToEquatorial({ x: -21, y: -46, z: 35 });
+  const view = galacticToEquatorial({ x: -105, y: -230, z: 175 });
   return new THREE.Vector3(view.x, view.y, view.z);
 })();
 const GALAXY_OVERVIEW_TARGET = new THREE.Vector3(0, 0, 0);
@@ -80,15 +86,22 @@ const GALACTIC_NEAR_PC = 5;
 const GALACTIC_FAR_PC = 250000;
 
 /** Rings for the local grid (parsecs from the Sun), with the catalogue's edge called out. */
-const LOCAL_GRID_RINGS_PC = [10, 20, 30, 40, 50];
+const LOCAL_GRID_RINGS_PC = [50, 100, 150, 200, 250];
 const LOCAL_GRID_SPOKES = 12;
 /** Rings for the galactic grid (parsecs from the centre), with the Sun's orbit called out. */
 const GALACTIC_GRID_RINGS_PC = [2500, 5000, SUN_GALACTOCENTRIC_RADIUS_PC, 11000, 14000];
 const GALACTIC_GRID_SPOKES = 24;
 /** The local grid passes through the Sun, which is the origin, so tethers drop to height zero. */
 const LOCAL_PLANE_HEIGHT_PC = 0;
-/** How many of the Sun's nearest neighbours get a permanent drop line to the local grid. */
-const TETHERED_STAR_COUNT = 28;
+/**
+ * How many stars get a permanent drop line to the local grid, and which ones: the brightest in
+ * the catalogue rather than the Sun's nearest neighbours.
+ *
+ * Nearest-to-the-Sun was the right set when the catalogue stopped at 50 pc and the camera sat
+ * just outside it. Across 250 pc those same stars are a speck at the centre, while the brightest
+ * are spread through the whole volume — and are the ones the eye is already on.
+ */
+const TETHERED_STAR_COUNT = 60;
 
 /** Camera pose for the whole-Galaxy overview: above the disc, out past the Sun, looking in. */
 const GALACTIC_OVERVIEW_HEIGHT_PC = 26000;
@@ -344,13 +357,12 @@ export class GalaxySystemSceneComponent implements AfterViewInit, OnDestroy {
       spokeCount: LOCAL_GRID_SPOKES,
       emphasisRadii: [LOCAL_GRID_RINGS_PC[LOCAL_GRID_RINGS_PC.length - 1]]
     });
-    // Drop lines for the Sun's nearest neighbours. A fixed set rather than whatever is currently
-    // labelled: these are the stars the local view is about, they cluster where the grid is
-    // densest, and a tether that appears and vanishes as the camera drifts reads as a glitch.
+    // A fixed set rather than whatever is currently labelled: a tether that appears and vanishes
+    // as the camera drifts reads as a glitch.
     this.tethers = new TetherField(TETHERED_STAR_COUNT);
     this.tethers.setTargets(
       [...stars]
-        .sort((a, b) => Math.hypot(a.x, a.y, a.z) - Math.hypot(b.x, b.y, b.z))
+        .sort((a, b) => a.magnitude - b.magnitude)
         .slice(0, TETHERED_STAR_COUNT)
         .map((star) => new THREE.Vector3(star.x, star.y, star.z)),
       LOCAL_PLANE_HEIGHT_PC
@@ -461,8 +473,11 @@ export class GalaxySystemSceneComponent implements AfterViewInit, OnDestroy {
     // Measured from what the camera is looking at, not from where it is. Those differ by the
     // orbit distance, so a camera-relative rule names the stars closest to the near edge of the
     // view — a ring of labels around the outside of the thing the user is actually looking at.
-    const { x: cx, y: cy, z: cz } = this.controls?.target ?? GALAXY_OVERVIEW_TARGET;
-    const maxDistanceSq = LABEL_MAX_DISTANCE_PC * LABEL_MAX_DISTANCE_PC;
+    const target = this.controls?.target ?? GALAXY_OVERVIEW_TARGET;
+    const { x: cx, y: cy, z: cz } = target;
+    const orbitDistance = (this.controls ? camera.position.distanceTo(target) : GALAXY_OVERVIEW_POSITION.length()) * LABEL_RADIUS_TO_ORBIT_DISTANCE;
+    const labelRadius = THREE.MathUtils.clamp(orbitDistance, MIN_LABEL_RADIUS_PC, MAX_LABEL_RADIUS_PC);
+    const maxDistanceSq = labelRadius * labelRadius;
 
     const candidates: Array<{ star: StarRecord; distanceSq: number }> = [];
     for (const star of this.stars) {
@@ -475,7 +490,11 @@ export class GalaxySystemSceneComponent implements AfterViewInit, OnDestroy {
       }
     }
 
-    candidates.sort((a, b) => a.distanceSq - b.distanceSq);
+    // Brightest first, not nearest first. Proximity was the right ranking when the catalogue was
+    // a 50 pc bubble and everything in it was equally worth naming; across 250 pc it labels a
+    // clump of whatever happens to be closest to the middle of the screen and never names the
+    // stars that are actually prominent. Brightness is what makes a star worth a name.
+    candidates.sort((a, b) => a.star.magnitude - b.star.magnitude);
     // Individual star names mean nothing once the whole Galaxy is in frame — at that range the
     // entire catalogue is inside one pixel — so the labels hand over to the structural ones.
     const isGalactic = this.galacticStrength >= GALACTIC_LEVEL_THRESHOLD;
@@ -561,7 +580,9 @@ export class GalaxySystemSceneComponent implements AfterViewInit, OnDestroy {
     this.hudTitle.set('Local Stars');
     this.hudSubtitle.set('Hipparcos · Yale Bright Star · Gliese');
     this.hudReadouts.set([
-      { label: 'Stars', value: `${this.stars.length}` },
+      // Both numbers, because they differ: the catalogue is what the map knows and the first is
+      // what it draws. See `STAR_RENDER_BUDGET`.
+      { label: 'Stars', value: this.starField && this.starField.drawnCount < this.stars.length ? `${this.starField.drawnCount} / ${this.stars.length}` : `${this.stars.length}` },
       { label: 'Radius', value: `${LOCAL_GRID_RINGS_PC[LOCAL_GRID_RINGS_PC.length - 1]} pc` },
       { label: 'Exoplanets', value: `${this.exoplanets.length}` }
     ]);

src/app/features/galaxy-system/star-field-renderer.spec.ts

@@ -2,7 +2,7 @@ import * as THREE from 'three/webgpu';
 import { describe, expect, it } from 'vitest';
 
 import { StarRecord } from '../../shared/models/star.model';
-import { colorIndexToRgb, magnitudeToPointSize, StarFieldRenderer } from './star-field-renderer';
+import { colorIndexToRgb, magnitudeToPointSize, selectDrawnStars, StarFieldRenderer } from './star-field-renderer';
 
 function star(overrides: Partial<StarRecord> = {}): StarRecord {
   return {
@@ -223,3 +223,71 @@ describe('StarFieldRenderer', () => {
     });
   });
 });
+
+/** A star at a given distance along +X, with a given apparent magnitude. */
+function catalogueStar(id: number, distancePc: number, magnitude: number): StarRecord {
+  return { id, name: `star-${id}`, x: distancePc, y: 0, z: 0, magnitude, spectralType: 'G2V', colorIndex: 0.6 };
+}
+
+describe('selectDrawnStars', () => {
+  it('draws everything when the catalogue fits the budget', () => {
+    const catalogue = [catalogueStar(1, 10, 5), catalogueStar(2, 20, 6)];
+    expect(Array.from(selectDrawnStars(catalogue, 10))).toEqual([0, 1]);
+  });
+
+  it('never draws more than the budget', () => {
+    const catalogue = Array.from({ length: 500 }, (_, i) => catalogueStar(i, 200, i));
+    expect(selectDrawnStars(catalogue, 50)).toHaveLength(50);
+  });
+
+  it('keeps the whole solar neighbourhood, however faint', () => {
+    // The load-bearing case: the nearest stars are overwhelmingly faint red dwarfs, and Proxima
+    // Centauri is magnitude 11. A pure brightness cut would delete the part of the map that
+    // matters most and holds the nearby planets.
+    const proxima = catalogueStar(999, 1.3, 11.1);
+    const catalogue = [proxima, ...Array.from({ length: 200 }, (_, i) => catalogueStar(i, 240, 2))];
+    const drawn = selectDrawnStars(catalogue, 20);
+
+    expect(Array.from(drawn)).toContain(0);
+    expect(drawn).toHaveLength(20);
+  });
+
+  it('spends what is left on the brightest stars beyond the neighbourhood', () => {
+    const catalogue = [catalogueStar(0, 10, 12), catalogueStar(1, 200, 8), catalogueStar(2, 200, 2), catalogueStar(3, 200, 5)];
+    const drawn = Array.from(selectDrawnStars(catalogue, 3));
+
+    // The nearby faint one, then the two brightest distant ones — not the magnitude-8 straggler.
+    expect(drawn).toEqual([0, 2, 3]);
+  });
+
+  it('returns catalogue indices in order, so positions can be subset alongside', () => {
+    const catalogue = Array.from({ length: 100 }, (_, i) => catalogueStar(i, 150, 100 - i));
+    const drawn = Array.from(selectDrawnStars(catalogue, 10));
+    expect(drawn).toEqual([...drawn].sort((a, b) => a - b));
+  });
+});
+
+describe('StarFieldRenderer render budget', () => {
+  it('draws only the budget, and reports how many that was', () => {
+    const catalogue = Array.from({ length: 300 }, (_, i) => catalogueStar(i, 200, i));
+    const positions = new Float32Array(catalogue.flatMap((s) => [s.x, s.y, s.z]));
+    const renderer = new StarFieldRenderer(catalogue, positions, 40);
+
+    expect(renderer.drawnCount).toBe(40);
+    expect((renderer.object.geometry as THREE.InstancedBufferGeometry).instanceCount).toBe(40);
+    renderer.dispose();
+  });
+
+  it('keeps each drawn star with its own position after subsetting', () => {
+    // The subtle failure this guards: repacking positions for a subset while the colours and
+    // sizes follow a different order would give every star someone else's place in the sky.
+    const catalogue = [catalogueStar(0, 5, 9), catalogueStar(1, 200, 1), catalogueStar(2, 200, 7)];
+    const positions = new Float32Array(catalogue.flatMap((s) => [s.x, s.y, s.z]));
+    const renderer = new StarFieldRenderer(catalogue, positions, 2);
+
+    expect(renderer.drawnCount).toBe(2);
+    expect(renderer.starIdAt(0)).toBe(0);
+    expect(renderer.starIdAt(1)).toBe(1);
+    renderer.dispose();
+  });
+});

src/app/features/galaxy-system/star-field-renderer.ts

@@ -30,6 +30,36 @@ const PIXELS_TO_ANGULAR_SIZE =
  */
 const PICK_NDC_SLOP = 0.01;
 
+/**
+ * How many stars the field draws at once, however many the catalogue holds.
+ *
+ * The catalogue reaches as far as its parallaxes do — 68388 stars at 250 pc — but drawing all of
+ * them is a cost paid every frame by every machine, and most of that cost buys 1.5-pixel dots.
+ * So the *data* is the catalogue and the *drawing* is a budget, and the two are allowed to
+ * differ. Everything still exists for search, for flying to, and for hosting planets.
+ *
+ * The figure is set low deliberately. A real GPU would draw the whole catalogue without
+ * noticing — this is one instanced draw call — but the value that matters is what a weak one
+ * does, and the software rasterizer this was measured against costs a third of its frame rate
+ * per 12000 stars. Raise it freely on hardware that can take it; nothing else depends on it.
+ */
+export const STAR_RENDER_BUDGET = 12000;
+
+/**
+ * Radius (parsecs) inside which every star is drawn regardless of brightness.
+ *
+ * A pure brightness cut would be defensible — apparent magnitude is exactly "how visible this
+ * is" — but it would drop the solar neighbourhood, because the nearest stars are overwhelmingly
+ * faint red dwarfs. Proxima Centauri is magnitude 11. Those are the stars this map is most about
+ * and the ones that hold the nearby planets, so the neighbourhood is kept whole and the budget
+ * is spent on the brightest of everything beyond it.
+ *
+ * Kept deliberately small against the catalogue's 250 pc reach. The guaranteed core occupies a
+ * thousandth of that volume, so a generous radius spends most of the budget inside it and draws
+ * a dense knot surrounded by nothing — which is a worse picture than the smaller catalogue was.
+ */
+export const ALWAYS_DRAWN_RADIUS_PC = 25;
+
 const COLD_STAR_COLOR = new THREE.Color(0.65, 0.75, 1.0);
 const NEUTRAL_STAR_COLOR = new THREE.Color(1.0, 1.0, 1.0);
 const WARM_STAR_COLOR = new THREE.Color(1.0, 0.6, 0.35);
@@ -90,22 +120,58 @@ function createQuadGeometry(instanceCount: number): THREE.InstancedBufferGeometr
  * close the camera gets. That is deliberate and physically right: real stars are unresolvable
  * point sources, and their apparent size on screen is a function of brightness, not distance.
  */
+/**
+ * Chooses which stars to draw when the catalogue is larger than the budget: everything inside
+ * the neighbourhood radius, then the brightest of the rest until the budget is spent.
+ *
+ * Returns indices into the original list, so the caller can subset the positions that go with
+ * them. Returns them in catalogue order rather than in selection order, purely so the drawn set
+ * is stable and inspectable.
+ */
+export function selectDrawnStars(stars: readonly StarRecord[], budget = STAR_RENDER_BUDGET): Uint32Array {
+  if (stars.length <= budget) {
+    return Uint32Array.from(stars.keys());
+  }
+
+  const near: number[] = [];
+  const far: number[] = [];
+  stars.forEach((star, index) => {
+    (Math.hypot(star.x, star.y, star.z) <= ALWAYS_DRAWN_RADIUS_PC ? near : far).push(index);
+  });
+
+  far.sort((a, b) => stars[a].magnitude - stars[b].magnitude);
+  const selected = near.concat(far.slice(0, Math.max(0, budget - near.length)));
+  selected.sort((a, b) => a - b);
+  return Uint32Array.from(selected);
+}
+
 export class StarFieldRenderer {
   readonly object: THREE.Mesh;
+  /** How many of the catalogue's stars this field actually draws. */
+  readonly drawnCount: number;
 
   private readonly geometry: THREE.InstancedBufferGeometry;
   private readonly material: THREE.SpriteNodeMaterial;
-  /** Angular diameter per star, in the same order as `stars` — reused for picking. */
+  /** The subset of the catalogue that is drawn, and so the only set that can be clicked. */
+  private readonly stars: readonly StarRecord[];
+  /** Angular diameter per drawn star, in the same order as `stars` — reused for picking. */
   private readonly angularSizes: Float32Array;
 
-  constructor(
-    private readonly stars: readonly StarRecord[],
-    positions: Float32Array
-  ) {
+  constructor(catalogue: readonly StarRecord[], cataloguePositions: Float32Array, budget = STAR_RENDER_BUDGET) {
+    const drawn = selectDrawnStars(catalogue, budget);
+    this.stars = drawn.length === catalogue.length ? catalogue : Array.from(drawn, (index) => catalogue[index]);
+    this.drawnCount = this.stars.length;
+
+    const stars = this.stars;
     this.geometry = createQuadGeometry(stars.length);
 
     const colors = new Float32Array(stars.length * 3);
     this.angularSizes = new Float32Array(stars.length);
+    // Repacked only when the drawn set is a subset; otherwise the ETL's buffer is used as-is.
+    const positions =
+      drawn.length === catalogue.length
+        ? cataloguePositions
+        : Float32Array.from({ length: drawn.length * 3 }, (_, i) => cataloguePositions[drawn[(i / 3) | 0] * 3 + (i % 3)]);
 
     stars.forEach((star, index) => {
       const color = colorIndexToRgb(star.colorIndex, star.spectralType);
@@ -115,7 +181,6 @@ export class StarFieldRenderer {
       this.angularSizes[index] = magnitudeToPointSize(star.magnitude) * PIXELS_TO_ANGULAR_SIZE;
     });
 
-    // `positions` is the ETL's packed buffer, already in the same order as `stars`.
     const positionAttribute = new THREE.InstancedBufferAttribute(positions, 3);
     const colorAttribute = new THREE.InstancedBufferAttribute(colors, 3);
     const sizeAttribute = new THREE.InstancedBufferAttribute(this.angularSizes, 1);