# Space astronomy sources

All runtime calculations and assets are served from the same Station or Merlin
host. No external catalog request is needed after the page has loaded.

## Ephemerides

`../astronomy.js` uses the unmodified ESM distribution of **Astronomy Engine
2.1.19**, by Donald Cross, under the MIT license. The complete MIT notice is
preserved at the top of `../vendor/astronomy.browser.js`.

- Source: https://github.com/cosinekitty/astronomy
- Pinned distribution: https://cdn.jsdelivr.net/npm/astronomy-engine@2.1.19/esm/astronomy.js
- API documentation: https://github.com/cosinekitty/astronomy/tree/master/source/js

Solar-system positions are physical heliocentric coordinates in the fixed
J2000 ecliptic frame, in astronomical units. Sky-body RA and declination are
topocentric equatorial coordinates of date; `raJ2000` and `decJ2000` provide
matching J2000 coordinates for the star atlas. Sky altitude/azimuth include
ordinary atmospheric refraction. The model includes light travel time,
aberration and the observer's parallax. These are computed positions, not
telescope measurements. Rise and set times assume an unobstructed sea-level
horizon; local terrain and atmospheric conditions change actual visibility.

Planet mean radii and sidereal periods are from JPL Solar System Dynamics:
https://ssd.jpl.nasa.gov/planets/phys_par.html

Sun and Moon physical values are from NASA NSSDCA fact sheets:
https://nssdc.gsfc.nasa.gov/planetary/factsheet/sunfact.html
https://nssdc.gsfc.nasa.gov/planetary/factsheet/moonfact.html

Planet trajectories sample one sidereal revolution starting at the selected
time. The lunar trajectory is Earth-relative, centered on Earth's position at
that selected time. It omits Earth's translation during the lunar month.

## Bright stars: stars.json

Derived from **HYG Database 4.1**, by David Nash / Astronexus and contributors.
HYG combines the Hipparcos, Yale Bright Star and Gliese catalogs.

- Source: https://github.com/astronexus/HYG-Database
- Revision: `c7f7f883fe678cc7680169a50ccd7dcc49b060ce`
- License: **Creative Commons Attribution-ShareAlike 4.0 International**
  (https://creativecommons.org/licenses/by-sa/4.0/)
- Upstream license notice: `LICENSE-HYG.txt`

This modified catalog retains 5,070 stars of visual magnitude 6.0 or brighter,
excludes the Sun, sorts by apparent magnitude, and rounds/reduces source fields.
The derived `stars.json` remains available under CC BY-SA 4.0.

Each record contains `id` (HYG number), `name` (proper name or catalog
designation), `proper` (nullable proper name), `ra` (J2000 sidereal hours),
`dec` (J2000 degrees), `mag` (visual magnitude), `bv` (nullable B−V color index),
`distance` (parsecs, null if unknown or dubious), `con` (IAU constellation
abbreviation), `hip` (nullable Hipparcos number), and `spectral` (nullable type).
Multiply parsecs by 3.26156 for light years.

Fixed star positions are J2000 catalog positions. Local horizon calculations
correct precession and nutation but do not propagate stellar proper motion
or apply stellar parallax. Catalog magnitudes do not account for atmospheric
extinction, light pollution, the Moon, or time-dependent variability.

## Constellations: constellations.json

Derived from **d3-celestial**, by Olaf Frohn, under the BSD 3-Clause license.

- Source: https://github.com/ofrohn/d3-celestial
- Revision: `7e720a3de062059d4c5400a379146a601d9010e0`
- Full license: `LICENSE-constellations.txt`

All 88 modern constellations are included. Upstream GeoJSON line coordinates
were converted from J2000 RA degrees into hours; both Serpens line groups were
merged into one constellation. Each record contains `id`, Latin `name`,
`english`, label position `ra`/`dec`, and `lines`, an array of polylines with
each vertex `[ra_hours, declination_degrees]`. Stick figures show conventional
patterns and do not represent IAU boundary polygons.

## Rebuilding and verification

Run `python build-catalog.py` to regenerate the two catalogs from their pinned
upstream revisions. `manifest.json` records every downloaded source URL and
SHA-256 hash. Node tests in `tests/space-astronomy.test.mjs` independently compare
calculated planetary vectors and local lunar altitude/azimuth against JPL
Horizons reference results, and check star-catalog coordinate integrity.