docs(sky): shorten the sky comments and README, fix three stale ones

The far-plane comment said z = w (the code puts z just under w), the Milky
Way constant is a brightness, not an opacity, and the CDS acknowledgement
lives in the Data attribution popover, not DATA_SOURCES.md.

Co-Authored-By: Claude Opus 5.5 <[email protected]>

changelog.d/1243-starfield-sky.md

@@ -1,5 +1,5 @@
 - Replace the blocky JPEG sky around the globe with the 9,096 stars of the
-  Yale Bright Star Catalogue, drawn as sharp points at their catalogue
+  Yale Bright Star Catalogue, drawn as sharp points where they are at the
-  positions for the scene clock, over a soft Milky Way built from ESO/S.
+  scene time, over a soft Milky Way from ESO/S. Brunier (CC BY 4.0). The Sun
-  Brunier's panorama (CC BY 4.0). The Sun and Moon stay, the anime style fades
+  and Moon stay; the anime style hides the Milky Way. Assets: 296 kB (gekh,
-  the Milky Way out, and the new assets weigh 296 kB (gekh, #1243).
+  #1243).

scripts/build-bright-stars.mjs

@@ -8,7 +8,7 @@
  * Format:   fixed-width ASCII, 197 bytes per record, byte layout in
  *           https://cdsarc.cds.unistra.fr/ftp/V/50/ReadMe
  * License:  public domain (Yale University Observatory / NASA ADC); CDS asks
- *           for an acknowledgement, which DATA_SOURCES.md carries.
+ *           for an acknowledgement, which the Data attribution popover carries.
  *
  * Transform (deterministic):
  *   1. J2000 RA/Dec (bytes 76-90), V magnitude (103-107) and B−V (110-114).

scripts/build-milky-way.mjs

@@ -14,27 +14,16 @@
  *              Centre, galactic longitude increasing to the left.
  *
  * Transform (deterministic):
- *   1. Resample to WORK_WIDTH×WORK_WIDTH/2 and convert sRGB to linear light.
+ *   1. Resample to WORK_WIDTH×WORK_WIDTH/2, sRGB to linear light.
- *   2. Remove stars with a morphological opening (minimum, then maximum, over
+ *   2. Remove stars with a morphological opening: the renderer draws
- *      a (2·OPEN_RADIUS+1)² window): anything smaller than the window — every
+ *      catalogue stars itself, sharp and in the right place.
- *      star — drops to the surrounding sky; the renderer draws catalogue stars
+ *   3. Paint out the planets the 2008–2010 exposures caught (PLANETS).
- *      itself, sharp and in the right place.
+ *   4. Blur, round on the sphere: σ = BLUR_DEG, widening to FAINT_BLUR_DEG
- *   3. Paint out the planets the 2008–2010 exposures caught (PLANETS): they
+ *      in the faint glow so unresolved stars leave no clumps.
- *      sit where today's sky has nothing and are far brighter than any star.
+ *   5. Resample into six WebGL cube faces (uploaded without flipY) with the
- *   4. Blur with a three-pass box approximation of a Gaussian, σ = BLUR_DEG on
+ *      ICRF axes: +X to the March equinox, +Z to the north celestial pole.
- *      the sky: rows wrap in longitude and widen by 1/cos(latitude) so the
+ *   6. Median sky to black with a soft knee, brightest 0.01 % to ~97 %
- *      blur stays round towards the poles. Faint glow blends to a second,
+ *      white, on luminance to keep the hue; gamma 1/2.2, dither, WebP.
- *      FAINT_BLUR_DEG blur, so it carries no clumps of unresolved stars.
- *   5. Resample into six FACE_SIZE² cube faces in the standard WebGL face
- *      orientation (the renderer uploads them without flipY), with the ICRF
- *      axes as the cube axes — +X to the March equinox, +Z to the north
- *      celestial pole — rotating each direction into galactic coordinates
- *      with the IAU J2000 matrix.
- *   6. Map the median sky to black, easing in with a soft knee, and the
- *      brightest 0.01 % to about 97 % white, the knee's offset there (both
- *      levels taken before the faint-glow blend; on luminance, keeping each
- *      pixel's hue),
- *      encode with gamma 1/2.2 and ±0.5 LSB dither against banding; WebP.
  *
  * Usage:
  *   node scripts/build-milky-way.mjs <eso0932a.tif>
@@ -46,19 +35,16 @@ import { fileURLToPath } from 'node:url';
 
 export const FACE_SIZE = 1024;
 export const BLUR_DEG = 0.4;
-// Faint glow takes a much wider blur: there the panorama is grain of
+// Faint glow is grain of unresolved stars and needs the wide blur; bright
-// unresolved stars, which a 0.4° blur leaves as clumps. Bright parts keep the
+// parts keep the fine one and their dust lanes. FAINT_RANGE (fraction of
-// fine blur and their dust lanes; FAINT_RANGE (fraction of black-to-white)
+// black-to-white) is where the two blend.
-// is where the two blend.
 export const FAINT_BLUR_DEG = 2;
 const FAINT_RANGE = [0.005, 0.08];
 const WORK_WIDTH = 4096;
 const OPEN_RADIUS = 3;
 const WEBP_QUALITY = 96;
-// The median sky is the black level: away from the galactic plane the
+// The median sky is black: above it the glow away from the plane reads as
-// panorama carries a mottled glow of unresolved stars and dust that reads as
+// grey blotches. SOFT_KNEE eases the cut in so it draws no edges.
-// grey blotches around the globe. A hard cut there draws edges of its own, so
-// the level eases in over SOFT_KNEE (a fraction of the black-to-white range).
 const BLACK_PERCENTILE = 0.5;
 const SOFT_KNEE = 0.03;
 const WHITE_PERCENTILE = 0.9999;

src/app/viewer.js

@@ -118,9 +118,8 @@ export function applicationViewerOptions(creditContainer) {
     selectionIndicator: false,
     infoBox: false,
     baseLayer: false,
-    // Instead of the default Tycho-2 cube map, whose JPEG blocks show around
+    // Replaces the blocky Tycho-2 default. An option, not `skyBox: false`,
-    // the whole globe. Passed here, not assigned later: `skyBox: false` would
+    // which would also stop CesiumWidget from creating the Sun and Moon.
-    // also stop CesiumWidget from creating the Sun and the Moon.
     skyBox: new StarrySky(),
     creditContainer,
     msaaSamples: 4,

src/data/local_data/sky/README.md

@@ -1,9 +1,7 @@
 # Sky background
 
-The space behind the globe (`src/sky/starrySky.js`): catalogue stars drawn as
+Catalogue stars over a soft Milky Way, drawn by `src/sky/starrySky.js` in
-sharp point sprites over a soft Milky Way cube map. It replaces Cesium's
+place of Cesium's blocky Tycho-2 sky box.
-default Tycho-2 sky box, whose six 1024² JPEGs stretch 3–6× around the
-whole-globe view and show compression blocks.
 
 | File | Content | Size |
 | ---- | ------- | ---- |
@@ -12,57 +10,42 @@ whole-globe view and show compression blocks.
 
 ## Stars — Yale Bright Star Catalogue
 
-**Source:** Yale Bright Star Catalogue, 5th Revised Edition (Hoffleit &
+**Source:** 5th Revised Edition (Hoffleit & Warren 1991), CDS catalogue
-Warren 1991), CDS VizieR catalogue
 [V/50](https://cdsarc.cds.unistra.fr/viz-bin/cat/V/50), file
 `https://cdsarc.cds.unistra.fr/ftp/V/50/catalog.gz` (sha256
 `3dc44b1e90be8fbe5bcc7656032560f51275f985c7e3f783c9028e1838ec7bed`, fetched
 2026-10-19).
 
-**License:** public domain (Yale University Observatory / NASA Astronomical
+**License:** public domain. CDS asks for an acknowledgement; the "Data
-Data Center). CDS asks for an acknowledgement; the in-app "Data attribution"
+attribution" popover carries it.
-popover carries it.
 
-**Build:** `node scripts/build-bright-stars.mjs [catalog.gz]` — every record
+**Build:** `node scripts/build-bright-stars.mjs [catalog.gz]`. Drops the 14
-with a J2000 position (14 novae and non-stellar entries dropped), RA/Dec
+records without a J2000 position; rounds RA/Dec to 0.001° and magnitudes to
-rounded to 0.001°, magnitudes to 0.01. The renderer maps magnitude to sprite
+0.01.
-width and opacity and B−V to a desaturated black-body colour
-(`src/sky/stars.js`).
 
 ## Milky Way — ESO/S. Brunier
 
-**Source:** "The Milky Way panorama", ESO image
+**Source:** ESO image [eso0932a](https://www.eso.org/public/images/eso0932a/),
-[eso0932a](https://www.eso.org/public/images/eso0932a/), full-size original
 `https://cdn.eso.org/images/original/eso0932a.tif` (6000×3000 sRGB TIFF, sha256
 `10f209ab83e1fd89e7fa1ed70277ffc6ed19c43549f04ec637c6806d98aff035`, fetched
-2026-10-19). Plate carrée in galactic coordinates, centred on the Galactic
+2026-10-19).
-Centre.
 
-**License:** [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/)
+**License:** [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/).
-(<https://www.eso.org/public/outreach/copyright/>). **Credit: ESO/S. Brunier.**
+**Credit: ESO/S. Brunier.**
 
-**Changes made** (CC BY 4.0 asks for them to be stated): resampled to
+**Changes made** (CC BY 4.0 asks for them): resampled to 4096×2048; stars
-4096×2048, stars removed with a 7×7 morphological opening, two planets
+removed; two images of Jupiter painted over; blurred (0.4°, 2° in the faint
-(Jupiter, by position) painted over with the median of the surrounding sky,
+glow); reprojected to ICRF cube faces; black level at the median sky; saved as
-blurred (σ = 0.4°, blending to σ = 2° in the faint glow so unresolved
+WebP. Build: `node scripts/build-milky-way.mjs <eso0932a.tif>`.
-stars leave no clumps), reprojected from galactic coordinates to ICRF cube faces,
-black level set at the median sky with a soft knee (the faint glow away
-from the galactic plane fades to black), gamma-encoded and saved as
-WebP. Build:
-`node scripts/build-milky-way.mjs <eso0932a.tif>`.
 
-The panorama is a photographic mosaic, not an astrometric map: bright stars
+The panorama's stars sit up to ~2° off; that is invisible in the blurred glow,
-sit up to ~2° from their catalogue positions. That is invisible in a glow
+and every sharp star comes from the catalogue.
-blurred this much, and every sharp star on screen comes from the catalogue.
 
-The NASA SVS "Deep Star Maps 2020" Milky Way layer was considered and not
+NASA SVS "Deep Star Maps 2020" was not used: it derives from Gaia DR2, which
-used: it is derived from Gaia DR2, which ESA distributes under CC BY-NC 3.0
+ESA licenses CC BY-NC 3.0 IGO.
-IGO with prior authorization required for commercial use.
 
 ## Frame
 
-Both layers are in ICRF/J2000. The cube faces use the standard WebGL face
+Both layers are in ICRF/J2000. The cube faces use the WebGL face layout, +X
-layout with +X towards the March equinox and +Z towards the north celestial
+to the March equinox and +Z to the north celestial pole, uploaded without
-pole, uploaded without `flipY`. At runtime one rotation —
+`flipY`.
-`Transforms.computeIcrfToFixedMatrix` at the scene clock — turns both into
-Earth-fixed coordinates.

src/sky/starrySky.js

@@ -12,7 +12,7 @@ import { buildStarVertices, STAR_VERTEX_FLOATS } from './stars.js';
  */
 export const STARRY_SKY_CESIUM_VERSION = '1.138.0';
 
-/** Opacity of the Milky Way glow over black; the stars carry the sky. */
+/** Brightness of the Milky Way glow; the stars carry the sky. */
 export const MILKY_WAY_INTENSITY = 0.4;
 /** Clock change, in seconds, below which the sky rotation is reused. */
 export const SKY_ROTATION_EPSILON_SECONDS = 1;
@@ -48,8 +48,8 @@ const MILKY_WAY_FACE_URLS = Object.freeze({
   ),
 });
 
-// Directions, not points: w = 0 drops the camera translation, and z = w puts
+// Directions, not points: w = 0 drops the camera translation, and z just
-// every fragment on the far plane, inside the clip volume at any frustum.
+// under w keeps every fragment at the far plane, inside any frustum.
 const SKY_DIRECTION_GLSL = `
 uniform mat3 u_icrfToFixed;
 vec4 skyClipPosition(vec3 icrfDirection)

src/sky/stars.js

@@ -3,17 +3,13 @@
  *
  * Pure functions, no Cesium. The pack is `local_data/sky/bright_stars.json`
  * (Yale Bright Star Catalogue, built by scripts/build-bright-stars.mjs): a
- * flat `[raDeg, decDeg, vmag, bv, …]` array in ICRF/J2000.
+ * flat `[raDeg, decDeg, vmag, bv, …]` array in ICRF/J2000. Each star is a
- *
+ * small Gaussian sprite, sized in CSS pixels so it stays a crisp dot at any DPR.
- * Every star is drawn as a point sprite holding a small Gaussian. Its width
- * is set in CSS pixels and scaled by the device pixel ratio in the shader, so
- * a star covers the same screen area at any DPR and stays a crisp dot rather
- * than a texel stretched across several pixels.
  *
  * @module sky/stars
  */
 
-/** Faintest magnitude drawn distinctly (fainter catalogue stars look like it); the brightness reference. */
+/** Brightness reference; fainter catalogue stars are drawn like it. */
 export const STAR_LIMIT_MAGNITUDE = 6.5;
 /** Gaussian σ of the faintest star, CSS pixels. */
 export const STAR_MIN_SIGMA_PX = 0.55;

src/tooling/skyAssets.test.mjs

@@ -93,7 +93,7 @@ test('plate carrée is centred on longitude 0, growing to the left, north up', (
 });
 
 test('the galactic rotation puts the Galactic Centre and pole where the IAU does', () => {
-  // Sgr A*-adjacent origin l = b = 0 at RA 266.405°, Dec −28.936° (J2000).
+  // Galactic origin l = b = 0 at RA 266.405°, Dec −28.936° (J2000).
   const centre = icrfToGalactic(raDecToUnitVector(266.40499, -28.93617));
   close(centre[0], 1, 1e-6);
   // North galactic pole at RA 192.85948°, Dec +27.12825°.

src/ui/visualEffects.js

@@ -112,10 +112,8 @@ export class VisualEffects {
     if (this.stopped || !stage) return;
     stage.uniforms.intensity = value;
     stage.enabled = value > 0.001;
-    // Anime's four luminance bands turn the faint Milky Way into blotches, and
+    // Anime's bands turn the faint Milky Way into blotches, and depth cannot
-    // a post-process cannot tell the sky from far geometry reliably (near
+    // tell the sky from far geometry, so the glow fades with the style.
-    // plane clamps, keyless terrain above the ellipsoid horizon): fade the
-    // glow out with the style instead. Bright stars survive as banded points.
     if (stage === this.stages.anime)
       this.viewer.scene.skyBox.milkyWayVisibility = 1 - value;
     if (stage.enabled && stage.uniforms.time !== undefined)