From 8c33c6f34953d6e2f73b8927ef762e94ce8d914e Mon Sep 17 00:00:00 2001 From: German Khokhlov Date: Tue, 20 Oct 2026 13:56:44 +0400 Subject: [PATCH] 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 --- changelog.d/1243-starfield-sky.md | 8 ++-- scripts/build-bright-stars.mjs | 2 +- scripts/build-milky-way.mjs | 44 ++++++++------------- src/app/viewer.js | 5 +-- src/data/local_data/sky/README.md | 63 +++++++++++-------------------- src/sky/starrySky.js | 6 +-- src/sky/stars.js | 10 ++--- src/tooling/skyAssets.test.mjs | 2 +- src/ui/visualEffects.js | 6 +-- 9 files changed, 54 insertions(+), 92 deletions(-) diff --git a/changelog.d/1243-starfield-sky.md b/changelog.d/1243-starfield-sky.md index d3ecbaf95..04d0cfbf8 100644 --- a/changelog.d/1243-starfield-sky.md +++ b/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 - positions for the scene clock, over a soft Milky Way built from ESO/S. - Brunier's panorama (CC BY 4.0). The Sun and Moon stay, the anime style fades - the Milky Way out, and the new assets weigh 296 kB (gekh, #1243). + Yale Bright Star Catalogue, drawn as sharp points where they are at the + scene time, over a soft Milky Way from ESO/S. Brunier (CC BY 4.0). The Sun + and Moon stay; the anime style hides the Milky Way. Assets: 296 kB (gekh, + #1243). diff --git a/scripts/build-bright-stars.mjs b/scripts/build-bright-stars.mjs index 45a6aaab3..95568935b 100644 --- a/scripts/build-bright-stars.mjs +++ b/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). diff --git a/scripts/build-milky-way.mjs b/scripts/build-milky-way.mjs index 55c7f8225..a6af99dec 100644 --- a/scripts/build-milky-way.mjs +++ b/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. - * 2. Remove stars with a morphological opening (minimum, then maximum, over - * a (2·OPEN_RADIUS+1)² window): anything smaller than the window — every - * star — drops to the surrounding sky; the renderer draws catalogue stars - * itself, sharp and in the right place. - * 3. Paint out the planets the 2008–2010 exposures caught (PLANETS): they - * sit where today's sky has nothing and are far brighter than any star. - * 4. Blur with a three-pass box approximation of a Gaussian, σ = BLUR_DEG on - * the sky: rows wrap in longitude and widen by 1/cos(latitude) so the - * blur stays round towards the poles. Faint glow blends to a second, - * 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. + * 1. Resample to WORK_WIDTH×WORK_WIDTH/2, sRGB to linear light. + * 2. Remove stars with a morphological opening: the renderer draws + * catalogue stars itself, sharp and in the right place. + * 3. Paint out the planets the 2008–2010 exposures caught (PLANETS). + * 4. Blur, round on the sphere: σ = BLUR_DEG, widening to FAINT_BLUR_DEG + * in the faint glow so unresolved stars leave no clumps. + * 5. Resample into six WebGL cube faces (uploaded without flipY) with the + * ICRF axes: +X to the March equinox, +Z to the north celestial pole. + * 6. Median sky to black with a soft knee, brightest 0.01 % to ~97 % + * white, on luminance to keep the hue; gamma 1/2.2, dither, WebP. * * Usage: * node scripts/build-milky-way.mjs @@ -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 -// unresolved stars, which a 0.4° blur leaves as clumps. Bright parts keep the -// fine blur and their dust lanes; FAINT_RANGE (fraction of black-to-white) -// is where the two blend. +// Faint glow is grain of unresolved stars and needs the wide blur; bright +// parts keep the fine one and their dust lanes. FAINT_RANGE (fraction of +// black-to-white) 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 -// panorama carries a mottled glow of unresolved stars and dust that reads as -// 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). +// The median sky is black: above it the glow away from the plane reads as +// grey blotches. SOFT_KNEE eases the cut in so it draws no edges. const BLACK_PERCENTILE = 0.5; const SOFT_KNEE = 0.03; const WHITE_PERCENTILE = 0.9999; diff --git a/src/app/viewer.js b/src/app/viewer.js index 633616fef..cedfbb020 100644 --- a/src/app/viewer.js +++ b/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 - // the whole globe. Passed here, not assigned later: `skyBox: false` would - // also stop CesiumWidget from creating the Sun and the Moon. + // Replaces the blocky Tycho-2 default. An option, not `skyBox: false`, + // which would also stop CesiumWidget from creating the Sun and Moon. skyBox: new StarrySky(), creditContainer, msaaSamples: 4, diff --git a/src/data/local_data/sky/README.md b/src/data/local_data/sky/README.md index e20b1fb77..9bf106d31 100644 --- a/src/data/local_data/sky/README.md +++ b/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 -sharp point sprites over a soft Milky Way cube map. It replaces Cesium's -default Tycho-2 sky box, whose six 1024² JPEGs stretch 3–6× around the -whole-globe view and show compression blocks. +Catalogue stars over a soft Milky Way, drawn by `src/sky/starrySky.js` in +place of Cesium's blocky Tycho-2 sky box. | 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 & -Warren 1991), CDS VizieR catalogue +**Source:** 5th Revised Edition (Hoffleit & Warren 1991), CDS 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 -Data Center). CDS asks for an acknowledgement; the in-app "Data attribution" -popover carries it. +**License:** public domain. CDS asks for an acknowledgement; the "Data +attribution" popover carries it. -**Build:** `node scripts/build-bright-stars.mjs [catalog.gz]` — every record -with a J2000 position (14 novae and non-stellar entries dropped), RA/Dec -rounded to 0.001°, magnitudes to 0.01. The renderer maps magnitude to sprite -width and opacity and B−V to a desaturated black-body colour -(`src/sky/stars.js`). +**Build:** `node scripts/build-bright-stars.mjs [catalog.gz]`. Drops the 14 +records without a J2000 position; rounds RA/Dec to 0.001° and magnitudes to +0.01. ## Milky Way — ESO/S. Brunier -**Source:** "The Milky Way panorama", ESO image -[eso0932a](https://www.eso.org/public/images/eso0932a/), full-size original +**Source:** ESO image [eso0932a](https://www.eso.org/public/images/eso0932a/), `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 -Centre. +2026-10-19). -**License:** [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/) -(). **Credit: ESO/S. Brunier.** +**License:** [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/). +**Credit: ESO/S. Brunier.** -**Changes made** (CC BY 4.0 asks for them to be stated): resampled to -4096×2048, stars removed with a 7×7 morphological opening, two planets -(Jupiter, by position) painted over with the median of the surrounding sky, -blurred (σ = 0.4°, blending to σ = 2° in the faint glow so unresolved -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 `. +**Changes made** (CC BY 4.0 asks for them): resampled to 4096×2048; stars +removed; two images of Jupiter painted over; blurred (0.4°, 2° in the faint +glow); reprojected to ICRF cube faces; black level at the median sky; saved as +WebP. Build: `node scripts/build-milky-way.mjs `. -The panorama is a photographic mosaic, not an astrometric map: bright stars -sit up to ~2° from their catalogue positions. That is invisible in a glow -blurred this much, and every sharp star on screen comes from the catalogue. +The panorama's stars sit up to ~2° off; that is invisible in the blurred glow, +and every sharp star comes from the catalogue. -The NASA SVS "Deep Star Maps 2020" Milky Way layer was considered and not -used: it is derived from Gaia DR2, which ESA distributes under CC BY-NC 3.0 -IGO with prior authorization required for commercial use. +NASA SVS "Deep Star Maps 2020" was not used: it derives from Gaia DR2, which +ESA licenses CC BY-NC 3.0 IGO. ## Frame -Both layers are in ICRF/J2000. The cube faces use the standard WebGL face -layout with +X towards the March equinox and +Z towards the north celestial -pole, uploaded without `flipY`. At runtime one rotation — -`Transforms.computeIcrfToFixedMatrix` at the scene clock — turns both into -Earth-fixed coordinates. +Both layers are in ICRF/J2000. The cube faces use the WebGL face layout, +X +to the March equinox and +Z to the north celestial pole, uploaded without +`flipY`. diff --git a/src/sky/starrySky.js b/src/sky/starrySky.js index b31109fde..8cd7f5d58 100644 --- a/src/sky/starrySky.js +++ b/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 -// every fragment on the far plane, inside the clip volume at any frustum. +// Directions, not points: w = 0 drops the camera translation, and z just +// under w keeps every fragment at the far plane, inside any frustum. const SKY_DIRECTION_GLSL = ` uniform mat3 u_icrfToFixed; vec4 skyClipPosition(vec3 icrfDirection) diff --git a/src/sky/stars.js b/src/sky/stars.js index 117823eb7..9fd5aa698 100644 --- a/src/sky/stars.js +++ b/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. - * - * 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. + * 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. * * @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; diff --git a/src/tooling/skyAssets.test.mjs b/src/tooling/skyAssets.test.mjs index 75e0ad063..07f7596a5 100644 --- a/src/tooling/skyAssets.test.mjs +++ b/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°. diff --git a/src/ui/visualEffects.js b/src/ui/visualEffects.js index f99ef3345..24cff6189 100644 --- a/src/ui/visualEffects.js +++ b/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 - // a post-process cannot tell the sky from far geometry reliably (near - // plane clamps, keyless terrain above the ellipsoid horizon): fade the - // glow out with the style instead. Bright stars survive as banded points. + // Anime's bands turn the faint Milky Way into blotches, and depth cannot + // tell the sky from far geometry, so the glow fades with the style. if (stage === this.stages.anime) this.viewer.scene.skyBox.milkyWayVisibility = 1 - value; if (stage.enabled && stage.uniforms.time !== undefined)