aric/moon-sighting
1
0
Fork 0
mirror of https://github.com/acamarata/moon-sighting.git synced 2026-07-01 11:24:24 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

style: fix prettier table formatting in wiki

Browse source
This commit is contained in:
Aric Camarata 2026-03-08 17:30:54 -04:00
parent 0bf9e6eb16
commit b032fb596f
10 changed files with 184 additions and 170 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
.wiki/API-Reference.md
View file

@ -120,7 +120,7 @@ function getMoonPosition(
**Parameters:** **Parameters:**
| Parameter | Type | Description | | Parameter | Type | Description |
| --------- | ---- | ----------- | | ----------- | --------- | ------------------------------------------- |
| `date` | `Date?` | Date to evaluate. Defaults to now | | `date` | `Date?` | Date to evaluate. Defaults to now |
| `lat` | `number` | Geodetic latitude, degrees (north positive) | | `lat` | `number` | Geodetic latitude, degrees (north positive) |
| `lon` | `number` | Longitude, degrees (east positive) | | `lon` | `number` | Longitude, degrees (east positive) |
@ -161,7 +161,7 @@ function getMoonIllumination(date?: Date): MoonIlluminationResult
**Parameters:** **Parameters:**
| Parameter | Type | Description | | Parameter | Type | Description |
| --------- | ---- | ----------- | | --------- | ------- | --------------------------------- |
| `date` | `Date?` | Date to evaluate. Defaults to now | | `date` | `Date?` | Date to evaluate. Defaults to now |
**MoonIlluminationResult:** **MoonIlluminationResult:**
@ -233,7 +233,7 @@ function getMoonVisibilityEstimate(
**Parameters:** **Parameters:**
| Parameter | Type | Description | | Parameter | Type | Description |
| --------- | ---- | ----------- | | ----------- | --------- | -------------------------------------------------------------------------------- |
| `date` | `Date?` | Observation time. Defaults to now. Use a post-sunset time for meaningful results | | `date` | `Date?` | Observation time. Defaults to now. Use a post-sunset time for meaningful results |
| `lat` | `number` | Geodetic latitude, degrees (north positive) | | `lat` | `number` | Geodetic latitude, degrees (north positive) |
| `lon` | `number` | Longitude, degrees (east positive) | | `lon` | `number` | Longitude, degrees (east positive) |
@ -275,12 +275,7 @@ console.log(est.isVisibleNakedEye) // true/false
Combined kernel-free snapshot: phase, position, illumination, and visibility estimate in one call. Combined kernel-free snapshot: phase, position, illumination, and visibility estimate in one call.
```ts ```ts
function getMoon( function getMoon(date?: Date, lat: number, lon: number, elevation?: number): MoonSnapshot
date?: Date,
lat: number,
lon: number,
elevation?: number,
): MoonSnapshot
``` ```
**MoonSnapshot:** **MoonSnapshot:**
@ -434,4 +429,4 @@ ODEH_DESCRIPTIONS // Record<OdehZone, string>
--- ---
*Previous: [Home](Home) | Next: [Architecture](Architecture)* _Previous: [Home](Home) | Next: [Architecture](Architecture)_

4
.wiki/Architecture.md
View file

@ -124,7 +124,7 @@ Target: a full sighting report (sunset + moonset + best-time geometry + Yallop +
A crescent sighting report's accuracy is limited by the worst source in the chain: A crescent sighting report's accuracy is limited by the worst source in the chain:
| Source | Contribution | | Source | Contribution |
| ------ | ------------ | | -------------------------------------------------- | --------------------------------------- |
| DE442S position error | < 1 km (~0.001 arcsec at Moon distance) | | DE442S position error | < 1 km (~0.001 arcsec at Moon distance) |
| IERS Q·R·W transform (with user-supplied EOP) | < 1 mas | | IERS Q·R·W transform (with user-supplied EOP) | < 1 mas |
| IERS Q·R·W transform (polynomial ΔT approximation) | < 5 arcsec | | IERS Q·R·W transform (polynomial ΔT approximation) | < 5 arcsec |
@ -136,4 +136,4 @@ In practice, refraction uncertainty dominates all other error sources for cresce
--- ---
*Previous: [API Reference](API-Reference) | Next: [Crescent Visibility](Crescent-Visibility)* _Previous: [API Reference](API-Reference) | Next: [Crescent Visibility](Crescent-Visibility)_

6
.wiki/Crescent-Visibility.md
View file

@ -49,7 +49,7 @@ This polynomial represents the minimum ARCV observed in historical crescent sigh
### Categories ### Categories
| Category | q range | Meaning | | Category | q range | Meaning |
| -------- | ------- | ------- | | -------- | ---------- | -------------------------------------------------- |
| A | q > +0.216 | Easily visible to the naked eye | | A | q > +0.216 | Easily visible to the naked eye |
| B | q > −0.014 | Visible under perfect conditions | | B | q > −0.014 | Visible under perfect conditions |
| C | q > −0.160 | May need optical aid to locate; naked eye possible | | C | q > −0.160 | May need optical aid to locate; naked eye possible |
@ -88,7 +88,7 @@ V = ARCV - (11.8371 - 6.3226·W + 0.7319·W² - 0.1018·W³)
### Zones ### Zones
| Zone | V range | Meaning | | Zone | V range | Meaning |
| ---- | ------- | ------- | | ---- | --------- | --------------------------------------------------------------------- |
| A | V ≥ 5.65 | Visible with naked eye | | A | V ≥ 5.65 | Visible with naked eye |
| B | V ≥ 2.00 | Visible with optical aid; may be naked eye under excellent conditions | | B | V ≥ 2.00 | Visible with optical aid; may be naked eye under excellent conditions |
| C | V ≥ −0.96 | Visible with optical aid only | | C | V ≥ −0.96 | Visible with optical aid only |
@ -146,4 +146,4 @@ This approach requires additional atmospheric inputs (aerosol optical depth, hum
--- ---
*Previous: [Architecture](Architecture) | Next: [Ephemeris](Ephemeris)* _Previous: [Architecture](Architecture) | Next: [Ephemeris](Ephemeris)_

4
.wiki/Ephemeris.md
View file

@ -60,6 +60,7 @@ Each record covers a fixed time interval and stores coefficients for X, Y, Z:
``` ```
The polynomial degree n is derived from RSIZE (record size in doubles): The polynomial degree n is derived from RSIZE (record size in doubles):
``` ```
n = (RSIZE - 2) / 3 - 1 n = (RSIZE - 2) / 3 - 1
``` ```
@ -93,6 +94,7 @@ result = c_0 + x·b_1 - b_2
This produces the position. Velocity requires the derivative d(result)/dt, computed via the Chebyshev derivative recurrence, not by finite differencing, which would lose accuracy. This produces the position. Velocity requires the derivative d(result)/dt, computed via the Chebyshev derivative recurrence, not by finite differencing, which would lose accuracy.
Transforming from normalized domain back to physical time: Transforming from normalized domain back to physical time:
``` ```
x = (et - MID) / RADIUS x = (et - MID) / RADIUS
dx/dt = 1/RADIUS dx/dt = 1/RADIUS
@ -152,4 +154,4 @@ See [Validation](Validation) for the test methodology.
--- ---
*Previous: [Crescent Visibility](Crescent-Visibility) | Next: [Time Scales](Time-Scales)* _Previous: [Crescent Visibility](Crescent-Visibility) | Next: [Time Scales](Time-Scales)_

7
.wiki/Getting-Started.md
View file

@ -127,7 +127,10 @@ import { initKernels, getSunMoonEvents } from 'moon-sighting'
await initKernels() await initKernels()
const events = await getSunMoonEvents(new Date('2025-03-29'), { const events = await getSunMoonEvents(new Date('2025-03-29'), {
lat: 21.4225, lon: 39.8262, elevation: 300, name: 'Mecca' lat: 21.4225,
lon: 39.8262,
elevation: 300,
name: 'Mecca',
}) })
console.log(events.sunsetUTC) console.log(events.sunsetUTC)
@ -202,4 +205,4 @@ npx moon-sighting benchmark
--- ---
*Previous: [Home](Home) | Next: [API Reference](API-Reference)* _Previous: [Home](Home) | Next: [API Reference](API-Reference)_

4
.wiki/Home.md
View file

@ -38,7 +38,9 @@ import { initKernels, getMoonSightingReport } from 'moon-sighting'
await initKernels() await initKernels()
const report = await getMoonSightingReport(new Date('2025-03-29'), { const report = await getMoonSightingReport(new Date('2025-03-29'), {
lat: 51.5074, lon: -0.1278, elevation: 10 lat: 51.5074,
lon: -0.1278,
elevation: 10,
}) })
console.log(report.yallop.category) // 'A' console.log(report.yallop.category) // 'A'

8
.wiki/Observer-Model.md
View file

@ -5,6 +5,7 @@
The library uses the WGS84 (World Geodetic System 1984) reference ellipsoid, which is the standard for GPS coordinates, Google Maps, and most modern mapping systems. The library uses the WGS84 (World Geodetic System 1984) reference ellipsoid, which is the standard for GPS coordinates, Google Maps, and most modern mapping systems.
Key constants: Key constants:
``` ```
a = 6378137.0 m (semi-major axis, equatorial radius) a = 6378137.0 m (semi-major axis, equatorial radius)
1/f = 298.257223563 (inverse flattening) 1/f = 298.257223563 (inverse flattening)
@ -45,6 +46,7 @@ Up = (cos φ cos λ, cos φ sin λ, sin φ)
``` ```
These are unit vectors. To convert a topocentric ECEF displacement Δ (in meters) to ENU: These are unit vectors. To convert a topocentric ECEF displacement Δ (in meters) to ENU:
``` ```
e = East · Δ e = East · Δ
n = North · Δ n = North · Δ
@ -67,6 +69,7 @@ Altitude is the angle above the horizontal plane: 0° = horizon, 90° = zenith,
The Moon's geocentric position (from the ephemeris) differs from its topocentric position (as seen by a surface observer) because the Moon is close enough that the baseline between Earth's center and the observer's surface position is significant. This is the diurnal parallax. The Moon's geocentric position (from the ephemeris) differs from its topocentric position (as seen by a surface observer) because the Moon is close enough that the baseline between Earth's center and the observer's surface position is significant. This is the diurnal parallax.
The correction is simply: The correction is simply:
``` ```
topocentric_direction = moon_ITRS − observer_ITRS topocentric_direction = moon_ITRS − observer_ITRS
``` ```
@ -103,6 +106,7 @@ Standard conditions: P = 1013.25 mbar, T = 15°C. The correction factors adjust
### Accuracy limits ### Accuracy limits
The Bennett formula is accurate to: The Bennett formula is accurate to:
- ~0.1 arcminute for h > 5° - ~0.1 arcminute for h > 5°
- ~0.5 arcminute for h = 2°–5° - ~0.5 arcminute for h = 2°–5°
- ~1–2 arcminutes for h < 2° - ~1–2 arcminutes for h < 2°
@ -115,7 +119,7 @@ This is why crescent sighting criteria use "airless" (refraction-free) altitudes
### When to apply refraction ### When to apply refraction
| Use case | Mode | | Use case | Mode |
|----------|------| | ------------------------------------ | ------------------- |
| Yallop ARCV input | Airless | | Yallop ARCV input | Airless |
| Odeh ARCV input | Airless | | Odeh ARCV input | Airless |
| Sunset/moonset threshold | Standard refraction | | Sunset/moonset threshold | Standard refraction |
@ -126,4 +130,4 @@ moon-sighting computes both airless and apparent altitudes for each body positio
--- ---
*Previous: [Reference Frames](Reference-Frames) | Next: [Validation](Validation)* _Previous: [Reference Frames](Reference-Frames) | Next: [Validation](Validation)_

8
.wiki/Reference-Frames.md
View file

@ -13,6 +13,7 @@ The IERS Conventions (2010) define the standard transformation:
``` ```
Where: Where:
- **GCRS** = Geocentric Celestial Reference System (essentially the inertial J2000 frame at Earth's center) - **GCRS** = Geocentric Celestial Reference System (essentially the inertial J2000 frame at Earth's center)
- **ITRS** = International Terrestrial Reference System (Earth-fixed frame, rotates with the solid Earth) - **ITRS** = International Terrestrial Reference System (Earth-fixed frame, rotates with the solid Earth)
- **Q(t)** = celestial motion matrix (precession + nutation) - **Q(t)** = celestial motion matrix (precession + nutation)
@ -31,6 +32,7 @@ The IAU 2006 precession model and IAU 2000A nutation model together parameterize
- **s:** CIO locator, a small angle that ensures continuity of the CIO position - **s:** CIO locator, a small angle that ensures continuity of the CIO position
The CIP X,Y series has: The CIP X,Y series has:
- A polynomial part (degree 5 in T = Julian centuries from J2000.0) - A polynomial part (degree 5 in T = Julian centuries from J2000.0)
- 1,306 luni-solar nutation terms - 1,306 luni-solar nutation terms
- 687 planetary nutation terms - 687 planetary nutation terms
@ -72,7 +74,7 @@ moon-sighting defaults to xp = yp = 0. Supply current values from IERS Bulletin
## IAU 2000A vs 2000B ## IAU 2000A vs 2000B
| Feature | 2000A | 2000B | | Feature | 2000A | 2000B |
|---------|-------|-------| | ---------------- | ------------- | ---------------- |
| Luni-solar terms | 1,306 | 77 | | Luni-solar terms | 1,306 | 77 |
| Planetary terms | 687 | 0 | | Planetary terms | 687 | 0 |
| Max error | < 0.1 mas | < 1 mas | | Max error | < 0.1 mas | < 1 mas |
@ -96,13 +98,15 @@ See [Observer Model](Observer-Model) for the WGS84 and ENU computation details.
## Accuracy ## Accuracy
With user-supplied EOP (Earth orientation parameters from IERS Bulletin A): With user-supplied EOP (Earth orientation parameters from IERS Bulletin A):
- Azimuth/altitude accuracy: < 0.1 arcsecond (dominated by nutation model error) - Azimuth/altitude accuracy: < 0.1 arcsecond (dominated by nutation model error)
With polynomial ΔT approximation (no user EOP): With polynomial ΔT approximation (no user EOP):
- Azimuth/altitude accuracy: typically < 5 arcseconds, occasionally up to ~30 arcseconds in pathological ΔT errors - Azimuth/altitude accuracy: typically < 5 arcseconds, occasionally up to ~30 arcseconds in pathological ΔT errors
For comparison, the Moon's angular diameter is ~1800 arcseconds, and refraction uncertainty near the horizon is 600–900 arcseconds. The frame transform is not the limiting factor for crescent sighting. For comparison, the Moon's angular diameter is ~1800 arcseconds, and refraction uncertainty near the horizon is 600–900 arcseconds. The frame transform is not the limiting factor for crescent sighting.
--- ---
*Previous: [Time Scales](Time-Scales) | Next: [Observer Model](Observer-Model)* _Previous: [Time Scales](Time-Scales) | Next: [Observer Model](Observer-Model)_

2
.wiki/Time-Scales.md
View file

@ -106,4 +106,4 @@ The NAIF LSK (`naif0012.tls`) is a plain-text file in NAIF text kernel format. I
--- ---
*Previous: [Ephemeris](Ephemeris) | Next: [Reference Frames](Reference-Frames)* _Previous: [Ephemeris](Ephemeris) | Next: [Reference Frames](Reference-Frames)_

8
.wiki/Validation.md
View file

@ -21,6 +21,7 @@ NASA NAIF's SPICE toolkit is the authoritative reference for reading JPL ephemer
Any deviation in the SPK Chebyshev evaluation from SPICE indicates a parsing or algorithm error in moon-sighting. Any deviation in the SPK Chebyshev evaluation from SPICE indicates a parsing or algorithm error in moon-sighting.
**How to compare:** **How to compare:**
```python ```python
import spiceypy as spice import spiceypy as spice
spice.furnsh('de442s.bsp') spice.furnsh('de442s.bsp')
@ -33,6 +34,7 @@ print(state[:3]) # position in km
``` ```
The moon-sighting equivalent: The moon-sighting equivalent:
```ts ```ts
const kernel = SpkKernel.fromFile('de442s.bsp') const kernel = SpkKernel.fromFile('de442s.bsp')
const ts = computeTimeScales(new Date('2025-03-29T20:00:00Z')) const ts = computeTimeScales(new Date('2025-03-29T20:00:00Z'))
@ -44,6 +46,7 @@ Expected agreement: < 1 meter (floating-point evaluation precision).
### JPL Horizons ### JPL Horizons
JPL Horizons is the online solar system ephemeris service. It uses the same JPL ephemerides and provides tabular output for: JPL Horizons is the online solar system ephemeris service. It uses the same JPL ephemerides and provides tabular output for:
- Apparent RA/Dec and az/alt for any observer and time - Apparent RA/Dec and az/alt for any observer and time
- Observer-centered quantities (elongation, illumination, phase angle) - Observer-centered quantities (elongation, illumination, phase angle)
- Rise/transit/set times - Rise/transit/set times
@ -52,6 +55,7 @@ Horizons uses SPICE internally, so it represents an independent end-to-end valid
**How to use for validation:** **How to use for validation:**
Go to https://ssd.jpl.nasa.gov/horizons/, select: Go to https://ssd.jpl.nasa.gov/horizons/, select:
- Target body: Moon (or Sun) - Target body: Moon (or Sun)
- Observer location: user-defined geodetic lat/lon/elevation - Observer location: user-defined geodetic lat/lon/elevation
- Time span: the date of interest - Time span: the date of interest
@ -62,7 +66,7 @@ Compare Horizons' output with moon-sighting's topocentric az/alt. Differences of
## Acceptance thresholds ## Acceptance thresholds
| Quantity | Expected error vs SPICE | Notes | | Quantity | Expected error vs SPICE | Notes |
|----------|------------------------|-------| | ---------------------------------- | ----------------------- | ------------------------------------------------------------------- |
| Geocentric position | < 1 m (< 0.001 arcsec) | SPK parsing precision | | Geocentric position | < 1 m (< 0.001 arcsec) | SPK parsing precision |
| Topocentric az/alt (with EOP) | < 0.1 arcsec | Frame transform precision | | Topocentric az/alt (with EOP) | < 0.1 arcsec | Frame transform precision |
| Topocentric az/alt (polynomial ΔT) | < 30 arcsec | ΔT polynomial error | | Topocentric az/alt (polynomial ΔT) | < 30 arcsec | ΔT polynomial error |
@ -98,4 +102,4 @@ Be cautious: ICOP records include weather and observer acuity information that t
--- ---
*Previous: [Observer Model](Observer-Model) | Next: [API Reference](API-Reference)* _Previous: [Observer Model](Observer-Model) | Next: [API Reference](API-Reference)_