astronomy

package module
v1.2.0 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 28, 2026 License: MIT Imports: 9 Imported by: 0

README

go-astronomy 🔭

🌍 Observer-aware Sun, Moon, star, and constellation positions for Go — altitude/azimuth, twilight bands, arc tracks, and moon phases for any (latitude, longitude, timezone, time).

Go Reference Go Report Card CI

go-astronomy computes where the Sun, Moon, and stars are in the sky for a given observer and instant. It emits degrees (altitude, azimuth) and time-progress — never pixels — so any consumer can drive an animated sky, a rise/set table, a twilight timeline, or a moon-phase widget from the same data.

It is designed for a service that computes a distinct sky per site visitor, so the API is stateless, deterministic, and concurrency-safe: time.Time is always a parameter, never captured at construction. The math is an in-house implementation of Jean Meeus' Astronomical Algorithms with no third-party ephemeris dependency (arcsecond-class accuracy).

Status: v1.0.0. Everything below ships, and every signature shown matches go doc. One item is marked (roadmap) where it appears: blue-moon detection.

🚀 Quick start

Install:

go get github.com/Bugs5382/go-astronomy

Where is the Sun for an observer right now, and when does it rise and set today?

package main

import (
	"fmt"
	"time"

	"github.com/Bugs5382/go-astronomy"
	"github.com/Bugs5382/go-astronomy/earth"
)

func main() {
	tz, _ := time.LoadLocation("America/New_York")
	obs := astronomy.Observer{Lat: 40.678, Lng: -73.944, TZ: tz} // Brooklyn, NY
	now := time.Now().In(tz)

	// Earth vantage: geometric altitude/azimuth of the Sun's disc center.
	pos := earth.SunPosition(obs, now)
	fmt.Printf("sun alt=%.2f° az=%.2f°\n", pos.Altitude, pos.Azimuth)

	// Earth-bound traits: one civil day of twilight bands, resolved in obs.TZ.
	day, err := earth.NewSunTimes(obs, now)
	if err != nil {
		panic(err)
	}
	if noon, ok := day.SolarNoon(); ok {
		fmt.Println("solar noon:", noon.Format(time.Kitchen))
	}
}

The library returns (value, bool) / (value, error) where a value may be absent (for example, no sunrise during a polar day) — never -1 or false sentinels. Polar conditions are an explicit state (MidnightSun / PolarNight), never a nil panic.

Every returned error is a go-apperr coded error carrying a stable numeric code. Match a condition with errors.Is (for example earth.ErrInvalidLatitude) or recover the code with apperr.Code(err); astronomy.Errors() exposes the code registry (used for Present, Describe, and a Markdown code table). The library is quiet by default — it never logs on its own — but the registry has go-log wired as go-apperr's logger, so a service that renders a coded error with Registry.PresentContext gets a structured line correlated with its OpenTelemetry trace when one is active. OpenTelemetry is a transitive dependency only; this library never starts a tracer or exporter, so it stays dormant until the surrounding service turns it on.

✨ Features

  • ☀️ Universal Sun physics — sun.ApparentDiameter / sun.ApparentSemidiameter give the Sun's apparent angular size for any distance in AU, from the semidiameter-at-1-AU constant. This is the only observer-independent part of the Sun, so any vantage body reuses it with its own distance.
  • 🌅 Earth vantage on the Sun — earth.SunPosition (geometric alt/az of the disc center, paired with apparent diameter) and earth.SunTrack (arc samples of {Time, Altitude, Azimuth, TimeProgress}). The alt/az, sidereal time, and Earth-Sun distance are all Earth-specific, so they live with the Earth vantage rather than in sun.
  • 🌇 Earth twilight bands — earth.NewSunTimes resolves one civil day in the observer's timezone with Earth refraction (−0.833° upper limb, Bennett): astronomical/nautical/civil dawn, sunrise, golden hour, day split at solar noon, golden hour, sunset, and the matching dusk bands. Each band is {from, to, seconds}.
  • 🌗 Moon (Luna) — earth/moon position and apparent position, next rise/set, the eight named phases, Age, Illumination, PhaseAngle, next new/full, and Track. PhaseAt names the phase from the Moon's elongation from the Sun rather than from its age, so the name follows the sky rather than a mean cycle length. BrightLimbAt says which way the lit side faces, from celestial north and from "up" on the observer's screen. Blue-moon detection is (roadmap). The Moon belongs to Earth; other bodies own their own moons.
  • 🪐 Planets — one package per planet, planet/mercury to planet/neptune, each with its own VSOP87 table and the same API: topocentric apparent position (light-time, aberration, nutation), apparent diameter, phase, magnitude (Mallama and Hilton 2018), elongation with a near-Sun flag, rise, set, and transit, and the observer-independent heliocentric position. Importing one planet links only its table; planet/all iterates over them all. Positions match JPL Horizons to about 1″ (2″ for Uranus and Neptune).
  • 🔭 Other worlds — the sky package stands the observer on the Moon, Mars, or any planet and resolves any other body from there, with that body's IAU rotation, shape, refraction, and twilight: Earth from Mars, the Sun from the Moon. Rise, set, and transit follow the body's own day, and a target that never crosses the horizon says so (AlwaysAbove: Earth from the lunar near side). It matches JPL Horizons to under half an arc second from Mars.
  • 🛰️ Satellites — the satellite package propagates a caller-supplied TLE or CCSDS OMM (JSON or XML) with SGP4/SDP4, ported from the Vallado et al. reference code, and gives altitude, azimuth, range, sunlight, and magnitude, plus passes with rise, peak, set, visibility, and shadow entry and exit. It never fetches element sets; Elements.Age tells a caller how stale one is.
  • ⭐ Stars — an embedded HYG-derived named-star catalog with RA/Dec, distance, proper motion, and radial velocity. Star.PositionAt carries a star along its space motion, and earth.StarPosition gives its apparent alt/az for the observer and instant, matching the IAU SOFA library to about 0.1″.
  • 🌌 Constellations — constellation.FindAt looks up the constellation containing an RA/Dec over the IAU (Delporte/Roman) default dataset, with List and Lookup alongside it. The lookup machinery is universal; the dataset is consumer-overridable.
  • 📐 Discs, not points — Sun and Moon positions are the center of the disc, always paired with angular diameter, so a consumer can size the disc and compute alignment/overlap (eclipses, occultations) purely from the data.
  • 🖥️ Pixel-agnostic projection — the project package maps (altitude°, azimuth°, timeProgress) to (x, y) with selectable strategies (XMode = time-progress or azimuth; YMode = normalized-by-peak or geometric) and a configurable horizon anchor.
  • 🧭 Configurable segmentation — twilight thresholds and band labels are data. Earth defaults ship (−18/−12/−6°, golden hour, sunrise/sunset), and earth.NewSunTimesWith takes a Segmentation to redefine them wholesale.
  • 🕛 Seamless midnight rollover — earth.SegmentAt answers "which band, and how far through it, at now" and stitches across midnight with no gap. Callers ask only for now, never for the previous or next day.
  • 🧵 Stateless & concurrency-safe — every call takes the observer and time.Time; nothing is captured at construction, so the same instance serves many visitors at once.

🪐 Planets

Each planet is its own package: planet/mercury, planet/venus, planet/mars, planet/jupiter, planet/saturn, planet/uranus, and planet/neptune. Each holds only its own VSOP87 table and has the same API, so importing planet/mars links the Mars table and no other. planet holds the shared result types, and planet/all imports every planet for a caller who wants them all.

Position, brightness, and phase
import "github.com/Bugs5382/go-astronomy/planet/mars"

greenwich := astronomy.Observer{Lat: 51.4769, Lng: -0.0005, TZ: time.UTC}
r, err := mars.Position(greenwich, time.Date(2027, 2, 19, 22, 0, 0, 0, time.UTC)) // near opposition
if err != nil {
	panic(err)
}
fmt.Printf("alt %.2f az %.2f\n", r.Altitude, r.Azimuth)                     // alt 44.53 az 129.60
fmt.Printf("%.2f arcsec, mag %.2f\n", float64(r.Diameter)*3600, r.Magnitude) // 13.82 arcsec, mag -1.28

Every planet returns a planet.Result: the topocentric geometric altitude and azimuth with the apparent diameter, the apparent RA/Dec of date, distance in au, light-time, magnitude (Mallama and Hilton 2018, with Saturn's rings), phase angle, illuminated fraction, elongation, and a NearSun flag.

Rise, set, and transit
import "github.com/Bugs5382/go-astronomy/planet/jupiter"

rise, ok, err := jupiter.NextRise(greenwich, time.Date(2027, 9, 1, 0, 0, 0, 0, time.UTC))
transit, _, _ := jupiter.NextTransit(greenwich, rise)
set, _, _ := jupiter.NextSet(greenwich, transit)
// 05:06:53, 11:58:08, 18:49:07 UTC; ok is false when nothing happens within 30 days
Heliocentric positions
h := jupiter.Heliocentric(when)              // ecliptic of date: Lon, Lat in degrees, DistanceAU
e := planet.EarthHeliocentric(when).Vector() // Earth, for the geometric view of Jupiter from Earth
Every planet
import "github.com/Bugs5382/go-astronomy/planet/all"

for _, p := range all.Planets() { // Mercury to Neptune; each p is a planet.Body
	r, _ := p.Position(london, when)
	fmt.Println(p.Name(), r.Altitude, r.Magnitude)
}
p, ok := all.ByName("saturn")
Accuracy

Against JPL Horizons DE441 (2020 to 2030, plus two conjunctions), the apparent place is within 0.3″ for Mercury, Venus, and Mars, 0.6″ for Jupiter and Saturn, and 1.7″ for Uranus and Neptune. Magnitudes agree to 0.08, and rise, set, and transit fall within Horizons' one-minute step. See the planets overview for the shared types, VSOP87 coverage, frames, and units, and one page per planet under website/docs/reference/planets/.

🛰️ Satellites

The satellite package is the engine: TLE and CCSDS OMM parsing, SGP4/SDP4, look angles, sunlight, magnitude, and passes. The named packages fix one object each: satellite/iss, satellite/hubble, and satellite/tiangong in Earth orbit, and satellite/jwst and satellite/roman out at the Sun-Earth L2 point. Nothing is fetched implicitly: element sets and ephemerides come from a source the caller passes in, either its own or the explicit fetchers satellite/celestrak and satellite/horizons.

ISS passes and position
import (
	"github.com/Bugs5382/go-astronomy/satellite"
	"github.com/Bugs5382/go-astronomy/satellite/celestrak"
	"github.com/Bugs5382/go-astronomy/satellite/iss"
)

tracker := iss.New(celestrak.New())   // or iss.New(satellite.StaticElements(myElements))
denver := astronomy.Observer{Lat: 39.74, Lng: -104.99}

passes, err := tracker.Passes(ctx, denver, now, now.Add(24*time.Hour))
for _, p := range passes {
	// p.Rise, p.Peak, p.Set; p.Visible (sunlit while you are in darkness);
	// p.ShadowEntry, where it vanishes into the Earth's shadow; p.Peak.Magnitude
}
l, err := tracker.Position(ctx, denver, now) // l.Altitude, l.Azimuth, l.RangeKm, l.Sunlit
Fetching, rarely
  • celestrak caches each element set by catalogue number and never makes a caller wait once it has one: every call answers from the cache, and a set older than 3 days is refreshed in the background (one refresh per satellite, never sooner than every 2 hours, following CelesTrak's guidance; a failed refresh keeps the old set). celestrak.NeverExpire() fetches once and never refreshes. Every position and pass is propagated locally, and ElementEpoch on each result says how old the set behind it is.
  • horizons fetches a 30-day table at a one-hour step in one request, caches it, and interpolates locally (eight-point Lagrange, within 4.4 milliarcseconds of a ten-minute table). It refetches only when an instant leaves the window.
  • Shared behaviour. Both take ctx, have a default timeout, accept an injected *http.Client, and use a pluggable satellite.Cache.
  • What is cached. CelesTrak sets are cached by catalogue number only, never per observer or time, so one daily fetch serves every observer at every time; positions and passes are always propagated locally.
  • Restarts and replicas. The default in-memory cache is lost on restart. To keep sets across restarts and share them between replicas, implement the two-method satellite.Cache over Redis in your own code (go-astronomy has no Redis dependency):
// RedisCache adapts a go-redis client to satellite.Cache. It lives in your
// code; go-astronomy has no Redis dependency.
type RedisCache struct{ R *redis.Client }

func (c RedisCache) Get(ctx context.Context, key string) ([]byte, bool, error) {
	b, err := c.R.Get(ctx, key).Bytes()
	if errors.Is(err, redis.Nil) {
		return nil, false, nil
	}
	return b, err == nil, err
}

func (c RedisCache) Set(ctx context.Context, key string, v []byte, expiry time.Duration) error {
	return c.R.Set(ctx, key, v, expiry).Err() // an expiry of 0 keeps it
}

elements := celestrak.New(celestrak.WithCache(RedisCache{R: rdb}))
tracker := iss.New(elements)
  • Drift. A set's error grows with age. For the ISS it is about a kilometre when fresh and a few kilometres after a few days. It reaches tens to hundreds of kilometres after about a week, and can be far off after a month or an ISS reboost. The default 3-day background refresh keeps it within a few kilometres, well under a second of pass timing. With NeverExpire, a set too old for SGP4 gives an error, never a wrong position.
Why JWST and Roman have no Passes

At L2, 1.2 to 1.8 million km out, SGP4 and element sets do not apply, so their ephemerides come from JPL Horizons. The telescopes drift about a degree a day near the anti-Sun point and rise and set once a day like faint stars, so they expose Position only. Roman launched on 2026-08-30. Horizons has its predicted trajectory only through its latest published file, and an instant past it is an error, not an extrapolation.

Accuracy

The SGP4 port matches the reference verification output to under 0.1 m. Against Skyfield on the same element set, passes agree to 0.2 s and shadow crossings to 0.05 s. The real limit is the element set's age (Elements.Age). See the satellite reference and the per-package pages under website/docs/reference/satellites/.

🌓 Which way the Moon is lit

moon.BrightLimbAt says which way the Moon's lit side faces, as numbers rather than a guess from the phase name. It returns three angles in degrees, all turning counter-clockwise as the observer sees the sky (90 is left of the reference, 270 right):

  • PositionAngle: from celestial north through east (Meeus 48.5). A property of the sky.
  • Parallactic: the angle from celestial north to the zenith at the Moon (Meeus 14.1).
  • ZenithAngle: PositionAngle − Parallactic, measured from "up" on the observer's sky. This is the one a screen needs.
Drawing the crescent
obs := astronomy.Observer{Lat: 39.74, Lng: -104.99}
when := time.Date(2027, 6, 8, 4, 0, 0, 0, time.UTC) // a June evening crescent, low in the west

bl, err := moon.BrightLimbAt(obs, when)
if err != nil {
	panic(err)
}
// ZenithAngle = 230.5: between down (180) and right (270), toward the set Sun.
a := bl.ZenithAngle * math.Pi / 180
x, y := -math.Sin(a), -math.Cos(a) // screen vector toward the lit side (x right, y down): 0.77, 0.64

The angle points at the Sun even below the horizon, because both bodies use their topocentric apparent places. Near New and Full Moon (under about 0.1% or over 99.9% lit) there is no visible bright limb to orient, and the angle should be treated as undefined. Against JPL Horizons DE441 (PsAng) the position angle agrees to within 0.01°.

🔭 Other worlds

sky is the general form of the Earth observer. A sky.Site stands on a sky.Body (sky.Sun, sky.Earth, sky.Moon, or any planet through sky.Planet(mars.Planet), which links only that planet's table), and sky.Position resolves any other body from it. Everything that made the sky Earth-only is a property of the body: its IAU WGCCRE 2015 pole and prime meridian, its reference ellipsoid, its refraction (34′ on Earth, zero on the airless Moon), and its twilight (Earth's bands, none elsewhere).

moonSite := sky.Site{Body: sky.Moon, Lat: 0, Lon: 0}
earth, _ := sky.Position(moonSite, sky.Earth, when) // altitude 80.6, 62% lit on 2027-01-01
rise, _ := sky.NextRise(moonSite, sky.Earth, when)  // rise.State == sky.AlwaysAbove

m, _ := sky.Planet(mars.Planet)
jezero := sky.Site{Body: m, Lat: 18.44, Lon: 77.45}
sunrise, _ := sky.NextRise(jezero, sky.Sun, when) // 18:38:12 UTC on 2027-01-01
lmst := mars.LocalMeanSolarTime(sunrise.Time, jezero.Lon) // 5.75 Mars hours
  • 🌍 Earth is the special case. A site on Earth answers through earth, earth/moon, and the planet packages, so it gives exactly their numbers.
  • 🌗 Phases everywhere. Every result carries the phase angle and lit fraction: Earth from the Moon is the complement of the Moon from Earth.
  • 🌑 No twilight without air. sky.Segments divides the lunar day at sunrise and sunset only, into days and nights of about two weeks.
  • 🎯 Accuracy. Against JPL Horizons the direction agrees to under 0.4″ from Mars and Venus and to about 11″ from the Moon, where the IAU lunar model approximates the mean Earth frame Horizons uses. Rise and set fall inside Horizons' one-minute step from Mars.

Times are time.Time in UTC: a Site has no time zone. Mars keeps its own clock in planet/mars (SolDate, LocalMeanSolarTime, Sol).

⛰️ Observer height

An Observer's height above sea level is optional. From height the sea horizon lies below the astronomical horizon by the dip, so the Sun, the Moon, and the planets rise earlier and set later, and the height enters their parallax. The air up there is thinner, so it refracts less and gives a little of that back: at Denver's 1609 m in June sunrise comes 6.8 minutes earlier, 7.3 for the dip less half a minute for the refraction (see Dip and refraction below). There are three ways to give an observer its height.

Always sea level

Leave Height out. The zero value is astronomy.SeaLevel, the answers are the sea-level answers, and nothing reaches the network.

obs := astronomy.Observer{Lat: 40.71, Lng: -74.01, TZ: tz}
By hand

Set Height with astronomy.Feet or astronomy.Meters (1 ft = 0.3048 m exactly). Any real value is used as given, with no check against the terrain: below sea level (the Dead Sea shore is -430 m), a mountain, or a plane at cruising altitude. New York at 5000 ft is valid on purpose.

obs := astronomy.Observer{Lat: 40.71, Lng: -74.01, TZ: tz, Height: astronomy.Feet(5000)} // same as Meters(1524)
day, err := earth.NewSunTimes(obs, date) // sunrise 6.7 minutes earlier than at sea level

Only NaN and the infinities are invalid: every function that returns an error rejects them with astronomy.ErrInvalidHeight (code 7011), and Height.Err() checks one up front.

Lookup

An astronomy.ElevationResolver finds the height at a coordinate. Elevation(ctx, lat, lon) returns (Height, source, error), with the source "caller", "static", "open-meteo", or "sea-level". Every lookup failure falls back to sea level with the source "sea-level"; the error is only for a cancelled or expired context.

// The Open-Meteo default: worldwide, free, no key.
obs, source, err := openmeteo.ResolveObserver(ctx, 39.74, -104.99)

// Or composed: a height you already have, then a fixed value, then Open-Meteo.
resolver := astronomy.ChainElevation(
	astronomy.CallerElevation(weatherHeight, haveWeatherHeight), // "caller"
	astronomy.StaticElevation(astronomy.Meters(21)),             // "static"
	openmeteo.New(openmeteo.WithHTTPClient(client)),             // "open-meteo"
)
obs, source, err = astronomy.ResolveObserverWith(ctx, resolver, lat, lon)

The openmeteo resolver respects ctx, bounds each lookup with a default 10 s timeout (WithTimeout), takes an injected *http.Client (WithHTTPClient), caches each 0.01° cell in process with no expiry (WithRound, Cached, Store), and logs through go-log: coordinates at debug, fallbacks at warn, nothing else about the caller. It lives in its own package, so a program that never imports it never links net/http.

Moving observers

A caller in motion, such as a plane, passes the position and height for each instant to each time-based call. Example_flightNYCToLondon follows a JFK to Heathrow flight at 36000 ft: at 04:54 UTC over the Atlantic the Sun is up for the plane (-2.43°, above its horizon of -3.51°) but not yet for the ocean below.

for _, f := range []float64{0, 0.25, 0.5, 0.7, 0.75, 1} {
	lat, lng := greatCircle(jfk, lhr, f) // the point f of the way along the route
	obs := astronomy.Observer{Lat: lat, Lng: lng, Height: astronomy.Feet(36000)}
	sun := earth.SunPosition(obs, depart.Add(time.Duration(f*float64(7*time.Hour))))
	up := sun.Altitude > earth.HorizonAltitudeAt(obs.Height) // dip and thinner air
	_ = up
}
🌫️ Dip and refraction

Two things move the horizon for an observer above sea level, and they pull in opposite directions:

  • 📉 The dip lowers it. The sea horizon lies 1.76′ × √h below the astronomical horizon (earth.HorizonDip, the Nautical Almanac value, which already includes the bending of the line of sight down to the sea).
  • 📈 Thinner air raises it back a little. The 34′ of refraction that lifts a body on the horizon scales with the density of the air. By default the library takes the air at the observer's height from the ISA standard atmosphere (earth.StandardAtmosphere): its factor is exactly 1 at sea level, so sea-level answers do not change, and it follows the ISA layers well past 15 km.
height dip refraction factor Sun's centre at sunrise
sea level 0° 1.000 −0.833°
1524 m (5000 ft) 1.145° 0.862 −1.900°
1609 m (Denver) 1.177° 0.854 −1.927°
10668 m (35000 ft) 3.030° 0.311 −3.472°

earth.HorizonAltitudeAt(h) gives the last column. The Sun, the Moon's and the planets' rise and set, and the Moon's ApparentPosition all use the scaled refraction. With a local reading of station pressure and temperature, pass the measured air instead: it applies the absolute factor P/1010 × 283/(273+T).

cold := earth.MeasuredAtmosphere(845, -15) // hPa, °C, at the observer
day, err := earth.NewSunTimesWith(obs, date, earth.DefaultSegmentation.WithAtmosphere(cold))
r := cold.Refraction(apparentAlt, obs.Height) // degrees, for any altitude

📋 Requirements

  • Go >= 1.27

🧭 Architecture

Universal celestial geometry and per-body trait packages sit over an unexported internal/ math core. Only the Sun is universal to the solar system; per-body packages own that body's observer, atmosphere, and naming traits. Consumers import the universal packages plus the body package they need (earth, including earth/moon).

flowchart TD
    subgraph universal["universal geometry"]
      SUN["sun<br/>Position, Track"]
      STAR["star<br/>HYG catalog (RA/Dec + distance)"]
      CONST["constellation<br/>boundary lookup (IAU default)"]
    end

    subgraph earthPkg["earth (Earth-bound traits)"]
      EARTH["earth<br/>SunTimes, twilight bands,<br/>refraction, seasons, polar states"]
      MOON["earth/moon<br/>Luna: position, phases, rise/set, Track"]
    end

    subgraph internalPkg["internal (unexported math core)"]
      ANG["angles"]
      JUL["julian / sidereal / obliquity"]
      COORD["coordinates<br/>ecliptic ⇄ equatorial ⇄ horizontal"]
      PROJ["project<br/>alt/az/progress → x/y"]
      EPH["ephemeris<br/>Meeus series: solar, lunar, precession, nutation"]
    end

    APP["your code / service"] --> SUN
    APP --> STAR
    APP --> CONST
    APP --> EARTH
    APP --> MOON
    APP --> SKY["sky<br/>any body from any body"]
    SKY --> EARTH
    SKY --> MOON
    SKY --> EPH

    EARTH --> SUN
    MOON --> COORD
    SUN --> COORD
    STAR --> COORD
    CONST --> COORD
    COORD --> ANG
    COORD --> JUL
    COORD --> EPH
    JUL --> EPH
    EARTH --> EPH
    MOON --> EPH

Other vantages go through sky, which takes each body's rotation, shape, refraction, and twilight as data, so a new body needs its IAU elements and a position, and no change to sun or earth.

🛠️ Working in the repo

The repo uses a Taskfile:

task build        # go build ./...
task test         # go test ./...
task test-cover   # go test ./... -cover
task fmt          # gofmt + goimports
task lint         # gofmt check, golangci-lint, yamllint
task license      # verify MIT headers (golic, dry run)
task license:fix  # inject any missing MIT headers

Plain go works too:

go build ./...
go test ./...

Commit discipline, AI-tell/emoji blocking, and the pre-push gofmt/vet/lint/test gate are enforced by the governance hooks. Install them once per clone:

bash .claude/hooks/install.sh

📚 Documentation

Accuracy target is arcsecond-class. The Sun and Moon are computed on Terrestrial Time (ΔT from the IERS leap-second table) with nutation and the observer's parallax, and agree with JPL Horizons DE441 to within about 2″ for the Sun (VSOP87) and, for the Moon, 0.5″ geocentric and 1.5″ as the observer sees it (the ELP 2000-82B series, about a thousand terms; the Meeus chapter 47 abridgement it replaced was good to 10″). Stars are carried along their Hipparcos proper motion and radial velocity and reduced to their apparent place (precession, nutation, annual aberration, and parallax); against the IAU SOFA library they agree to about 0.1″ around the present and 0.35″ by 1950 or 2100.

🤝 Contributing

Contributions are welcome — bug reports, fixes, new coverage, and docs improvements.

  1. 🍴 Fork the repo and create a topic branch (<type>/<issue#>-<slug>).
  2. ✅ Add tests for any behavior change. Run the suite with go test ./... (or task test).
  3. 🧹 Lint and format with task lint from the repo root (commits follow Conventional Commits).
  4. 🚀 Open a PR. CI runs build, tests, and linters on every push.

🙏 Acknowledgements

  • Jean Meeus, Astronomical Algorithms — the algorithmic foundation. The series in internal/ephemeris were ported from soniakeys/meeus, which this library no longer depends on.
  • P. Bretagnon and G. Francou, VSOP87 (IMCCE) — the planetary theory behind the Sun's position, generated into a truncated table.
  • The HYG star database (Hipparcos-Yale-Gliese) — the source for the embedded star catalog, used under CC BY-SA 4.0.
  • The IAU constellation boundaries of Eugène Delporte (1930), digitized by Nancy Roman (1987) as VizieR VI/42 — the source for the embedded boundary table.

See NOTICE for the full attribution and licensing of the embedded data.

📄 License

MIT

Documentation

Overview

Package astronomy is an observer-aware Go astronomy library: sun, moon, star, and constellation positions with twilight bands, arc tracks, and moon phases.

This root package holds the shared domain types (Observer, Horizontal, Position, AngularDiameter) used across the body-specific packages. The heavy math lives in unexported internal packages built on the meeus ephemeris algorithms.

Example (FlightNYCToLondon)

A moving observer passes its position and height for each instant. Here a flight from New York (JFK) to London (LHR) on the June solstice, leaving at 00:00 UTC and cruising at 36000 ft: from altitude the Sun clears the dipped horizon before it rises for anyone on the ground below.

package main

import (
	"fmt"
	"math"
	"time"

	astronomy "github.com/Bugs5382/go-astronomy"
	"github.com/Bugs5382/go-astronomy/earth"
)

func main() {
	jfk := [2]float64{40.64, -73.78}
	lhr := [2]float64{51.47, -0.45}
	depart := time.Date(2027, 6, 21, 0, 0, 0, 0, time.UTC)
	const flight = 7 * time.Hour

	for _, f := range []float64{0, 0.25, 0.5, 0.7, 0.75, 1} {
		lat, lng := greatCircle(jfk, lhr, f)
		height := astronomy.Feet(36000)
		if f == 0 || f == 1 {
			height = astronomy.SeaLevel // on the runway
		}
		obs := astronomy.Observer{Lat: lat, Lng: lng, Height: height}
		when := depart.Add(time.Duration(f * float64(flight)))

		sun := earth.SunPosition(obs, when)
		// The Sun is up when its centre clears the refracted horizon, which
		// the dip lowers for an observer at height and the thinner air there
		// raises a little, since it refracts the Sun less.
		horizon := earth.HorizonAltitudeAt(obs.Height)
		ground := sun.Altitude > earth.HorizonAltitude
		fmt.Printf("%s %6.2f %7.2f %6.0f ft sun %6.2f up in the air %-5v on the ground %v\n",
			when.Format("15:04"), lat, lng, obs.Height.Feet(), sun.Altitude, sun.Altitude > horizon, ground)
	}
}

// greatCircle returns the point a fraction f of the way from a to b along the
// great circle, as latitude and longitude in degrees.
func greatCircle(a, b [2]float64, f float64) (float64, float64) {
	const r = math.Pi / 180
	la1, lo1, la2, lo2 := a[0]*r, a[1]*r, b[0]*r, b[1]*r
	d := math.Acos(math.Sin(la1)*math.Sin(la2) + math.Cos(la1)*math.Cos(la2)*math.Cos(lo2-lo1))
	s1, s2 := math.Sin((1-f)*d)/math.Sin(d), math.Sin(f*d)/math.Sin(d)
	x := s1*math.Cos(la1)*math.Cos(lo1) + s2*math.Cos(la2)*math.Cos(lo2)
	y := s1*math.Cos(la1)*math.Sin(lo1) + s2*math.Cos(la2)*math.Sin(lo2)
	z := s1*math.Sin(la1) + s2*math.Sin(la2)
	return math.Atan2(z, math.Hypot(x, y)) / r, math.Atan2(y, x) / r
}
Output:
00:00  40.64  -73.78      0 ft sun   3.98 up in the air true  on the ground true
01:45  47.58  -59.32  36000 ft sun -12.86 up in the air false on the ground false
03:30  52.22  -41.30  36000 ft sun -13.76 up in the air false on the ground false
04:54  53.64  -24.90  36000 ft sun  -2.43 up in the air true  on the ground false
05:15  53.64  -20.70  36000 ft sun   1.66 up in the air true  on the ground true
07:00  51.47   -0.45      0 ft sun  26.78 up in the air true  on the ground true
Example (HeightByHand)

By hand: a height in feet or metres, used as given. New York at 5000 ft is not the real ground, and that is allowed.

package main

import (
	"fmt"
	"time"

	astronomy "github.com/Bugs5382/go-astronomy"
	"github.com/Bugs5382/go-astronomy/earth"
)

// sunrise returns the start of the sunrise band on the civil day of date.
func sunrise(obs astronomy.Observer, date time.Time) time.Time {
	day, err := earth.NewSunTimes(obs, date)
	if err != nil {
		panic(err)
	}
	for _, s := range day.Segments() {
		if s.Label == earth.LabelSunrise {
			return s.From
		}
	}
	return time.Time{}
}

func main() {
	date := time.Date(2027, 6, 21, 12, 0, 0, 0, time.UTC)
	nyc := astronomy.Observer{Lat: 40.71, Lng: -74.01, TZ: time.UTC}
	high := astronomy.Observer{Lat: 40.71, Lng: -74.01, TZ: time.UTC, Height: astronomy.Feet(5000)}
	same := astronomy.Observer{Lat: 40.71, Lng: -74.01, TZ: time.UTC, Height: astronomy.Meters(1524)}

	fmt.Println("5000 ft is", high.Height, "and equal to Meters(1524):", high == same)
	fmt.Printf("dip %.3f degrees\n", earth.HorizonDip(high.Height))
	fmt.Printf("sunrise %.1f minutes earlier\n", sunrise(nyc, date).Sub(sunrise(high, date)).Minutes())
}
Output:
5000 ft is 1524 m and equal to Meters(1524): true
dip 1.145 degrees
sunrise 6.7 minutes earlier
Example (Lookup)

Lookup: a chain tries a height the caller already has, then a fixed value, and falls back to sea level only when nothing answers. The Open-Meteo lookup (package openmeteo) slots into the same chain.

package main

import (
	"context"
	"fmt"

	astronomy "github.com/Bugs5382/go-astronomy"
)

func main() {
	ctx := context.Background()
	weatherHeight, haveIt := astronomy.Meters(0), false // no reading this time

	resolver := astronomy.ChainElevation(
		astronomy.CallerElevation(weatherHeight, haveIt),
		astronomy.StaticElevation(astronomy.Meters(21)),
	)
	obs, source, err := astronomy.ResolveObserverWith(ctx, resolver, 40.71, -74.01)
	if err != nil {
		panic(err) // only for a cancelled or expired ctx
	}
	fmt.Println(obs.Height, "from", source)

	obs, source, _ = astronomy.ResolveObserverWith(ctx, astronomy.ChainElevation(), 40.71, -74.01)
	fmt.Println(obs.Height, "from", source)
}
Output:
21 m from static
0 m from sea-level
Example (SeaLevel)

Always sea level: an observer with no height. Nothing is looked up.

package main

import (
	"fmt"
	"time"

	astronomy "github.com/Bugs5382/go-astronomy"
	"github.com/Bugs5382/go-astronomy/earth"
)

// sunrise returns the start of the sunrise band on the civil day of date.
func sunrise(obs astronomy.Observer, date time.Time) time.Time {
	day, err := earth.NewSunTimes(obs, date)
	if err != nil {
		panic(err)
	}
	for _, s := range day.Segments() {
		if s.Label == earth.LabelSunrise {
			return s.From
		}
	}
	return time.Time{}
}

func main() {
	nyc := astronomy.Observer{Lat: 40.71, Lng: -74.01, TZ: time.UTC}
	fmt.Println("height:", nyc.Height)
	fmt.Println("sunrise:", sunrise(nyc, time.Date(2027, 6, 21, 12, 0, 0, 0, time.UTC)).Format("15:04:05 MST"))
}
Output:
height: 0 m
sunrise: 09:25:00 UTC

Index

Examples

Constants

View Source
const (
	// CodeInvalidLatitude marks an observer latitude outside [-90, 90].
	CodeInvalidLatitude = 7001
	// CodeInvalidLongitude marks an observer longitude outside [-180, 180].
	CodeInvalidLongitude = 7002
	// CodeInvalidSegmentation marks a Segmentation whose levels are empty or not
	// in strictly ascending altitude order.
	CodeInvalidSegmentation = 7003
	// CodeInvalidMagnitudeRange marks a stellar magnitude query whose bright
	// bound is fainter than its faint bound, which can select no star.
	CodeInvalidMagnitudeRange = 7004
	// CodeInvalidCanvas marks a screen projection whose canvas width or height is
	// not positive, so it spans no pixels.
	CodeInvalidCanvas = 7005
	// CodeInvalidHorizonFraction marks a viewport whose horizon fraction is
	// outside [0, 1], so the horizon line would fall off the canvas.
	CodeInvalidHorizonFraction = 7006
	// CodeInvalidPeakAltitude marks a NormalizedByPeak projection whose peak
	// altitude is not positive, which cannot normalize an arch.
	CodeInvalidPeakAltitude = 7007
	// CodeInvalidFieldOfView marks an azimuth-based projection whose field of view
	// (Directional) or sunrise-to-sunset azimuth span (FullArc) is not positive.
	CodeInvalidFieldOfView = 7008
	// CodeInvalidElevationScale marks a Geometric projection whose elevation
	// degrees-per-pixel is not positive.
	CodeInvalidElevationScale = 7009
	// CodeXModeNotAzimuth marks a column-to-azimuth inverse query on a projection
	// whose horizontal mode is not azimuth-based, so no azimuth axis exists.
	CodeXModeNotAzimuth = 7010
	// CodeInvalidHeight marks an observer Height that is NaN or infinite.
	CodeInvalidHeight = 7011
	// CodeInvalidElements marks a satellite element set (TLE or OMM) that
	// could not be parsed.
	CodeInvalidElements = 7014
	// CodeSatellitePropagation marks an element set SGP4 could not propagate
	// to the requested instant, such as a satellite that has decayed.
	CodeSatellitePropagation = 7015
	// CodeInvalidPassWindow marks a pass search whose end is not after its
	// start, or which spans more than 31 days.
	CodeInvalidPassWindow = 7016
	// CodeInvalidAtmosphere marks measured air for the refraction model whose
	// pressure is not a positive finite number or whose temperature is not
	// finite or at or below -273 C.
	CodeInvalidAtmosphere = 7017
	// CodeUnknownBody marks a sky Site or target with no body, a Site on the
	// Sun, or a planet with no IAU rotation model.
	CodeUnknownBody = 7018
	// CodeSameBody marks a sky target that is the body the site stands on.
	CodeSameBody = 7019
)

Stable numeric error codes for the module. Each error-returning function wraps its cause with one of these via go-apperr, so a caller can recover the code with apperr.Code and branch on it without matching error strings. The values are part of the public contract: never renumber a code, only add new ones.

View Source
const (
	// SourceCaller is a height the caller already had (CallerElevation).
	SourceCaller = "caller"
	// SourceStatic is a fixed, configured height (StaticElevation).
	SourceStatic = "static"
	// SourceOpenMeteo is a height from the Open-Meteo elevation API.
	SourceOpenMeteo = "open-meteo"
	// SourceSeaLevel means no resolver produced a height, so the answer is
	// sea level.
	SourceSeaLevel = "sea-level"
)

Sources an ElevationResolver reports for the height it returns.

View Source
const ErrorServiceDigit = 7

ErrorServiceDigit is the leading digit that every go-astronomy error code shares, so a code is attributable to this module at a glance. It is the go-apperr service prefix for the module's code namespace.

View Source
const MetersPerFoot = 0.3048

MetersPerFoot is the international foot, exactly.

Variables

View Source
var ErrInvalidHeight = errors.New("astronomy: height is not a finite number")

ErrInvalidHeight is the cause when a Height is NaN or infinite; the coded error carries CodeInvalidHeight.

View Source
var SeaLevel = Height{}

SeaLevel is the zero Height, and the height of an Observer that gives none.

Functions

func Errors

func Errors() *apperr.Registry

Errors returns the module's go-apperr registry: the stable code table plus the presentation and logging policy around it. A consumer renders a coded error at its edge with Registry.Present (or PresentContext, which also drives the wired go-log logger) to obtain a sanitized, quotable message, looks a code up with Registry.Describe, or emits the whole table as Markdown with Registry.Markdown. The registry is built once and is safe for concurrent use.

Types

type AngularDiameter

type AngularDiameter float64

AngularDiameter is the apparent angular size of a body's disc, in degrees.

func (AngularDiameter) Radius

func (a AngularDiameter) Radius() float64

Radius returns half the angular diameter, in degrees.

type ElevationResolver added in v1.1.0

type ElevationResolver interface {
	Elevation(ctx context.Context, lat, lng float64) (Height, string, error)
}

ElevationResolver finds the height of the ground at a coordinate (degrees, latitude positive north and longitude positive east).

Elevation returns the height and the source that produced it. A resolver that cannot produce a height, for any reason, returns SeaLevel and SourceSeaLevel instead of an error: a missing height is never fatal. The error is only for a cancelled or expired context, which it returns with SeaLevel. Implementations must be safe for concurrent use.

func CallerElevation added in v1.1.0

func CallerElevation(h Height, ok bool) ElevationResolver

CallerElevation returns a resolver for a height the caller may already have, such as the ground elevation in a weather reading: with ok set it answers h with SourceCaller, and with ok unset it reports sea level so a chain moves on to the next resolver.

func ChainElevation added in v1.1.0

func ChainElevation(resolvers ...ElevationResolver) ElevationResolver

ChainElevation returns a resolver that asks each of resolvers in order and returns the first answer that is not SourceSeaLevel, with that resolver's source. When every resolver reports sea level, so does the chain; it only falls back at the end. A done context stops the chain with its error.

func StaticElevation added in v1.1.0

func StaticElevation(h Height) ElevationResolver

StaticElevation returns a resolver that always answers h, with SourceStatic, whatever the coordinate: for a fixed installation whose height is configured. A NaN or infinite h is no answer, so the resolver reports sea level.

type Height added in v1.1.0

type Height struct {
	// contains filtered or unexported fields
}

Height is a height above sea level. Build one with Meters or Feet; the zero value is SeaLevel. Any real value is valid as given: below sea level (the Dead Sea shore is -430 m), on a mountain, or in flight. Only NaN and the infinities are invalid (see Err), and the functions that take an observer reject them with ErrInvalidHeight.

A Height is stored in metres, the unit every calculation uses.

func Feet added in v1.1.0

func Feet(ft float64) Height

Feet returns the height of ft feet above sea level (one foot is 0.3048 m).

func Meters added in v1.1.0

func Meters(m float64) Height

Meters returns the height of m metres above sea level.

func (Height) Err added in v1.1.0

func (h Height) Err() error

Err returns the coded ErrInvalidHeight for a NaN or infinite height, and nil for every real value.

func (Height) Feet added in v1.1.0

func (h Height) Feet() float64

Feet returns the height in feet.

func (Height) Meters added in v1.1.0

func (h Height) Meters() float64

Meters returns the height in metres.

func (Height) String added in v1.1.0

func (h Height) String() string

String formats the height in metres, for example "1524 m".

type Horizontal

type Horizontal struct {
	Altitude float64
	Azimuth  float64
}

Horizontal is a direction in the local horizontal (alt-az) frame. Azimuth is measured clockwise from true north and Altitude is the angle above the horizon; both are in degrees. A negative Altitude is below the horizon.

func (Horizontal) AboveHorizon

func (h Horizontal) AboveHorizon() bool

AboveHorizon reports whether the direction is above the geometric horizon.

type Observer

type Observer struct {
	// Lat is the geographic latitude in degrees, positive north, in [-90, 90].
	Lat float64
	// Lng is the geographic longitude in degrees, positive east, in [-180, 180].
	Lng float64
	// TZ is the observer's local time zone. A nil value is treated as UTC.
	TZ *time.Location
	// Height is the observer's height above sea level, optional: the zero
	// value is SeaLevel, which reproduces the sea-level answers exactly and
	// needs no lookup. Set it with Meters or Feet, or look it up with an
	// ElevationResolver (see ResolveObserverWith).
	//
	// From height the sea horizon lies below the astronomical horizon by the
	// dip (see earth.HorizonDip), so the Sun and Moon rise earlier and set
	// later, and the thinner air refracts less (see earth.StandardAtmosphere),
	// which gives a little of that back; the height also enters their
	// parallax. The dip assumes an
	// unobstructed sea horizon. For an observer in motion, such as a plane,
	// pass the position and height for each instant to each call.
	Height Height
}

Observer is a location on the Earth's surface for which celestial positions are computed. Time is never captured here; it is always supplied as a parameter to the calculation functions, keeping the library stateless.

func ResolveObserverWith added in v1.1.0

func ResolveObserverWith(ctx context.Context, r ElevationResolver, lat, lng float64) (Observer, string, error)

ResolveObserverWith returns an observer at the coordinate with its height from r, and the source that produced it. The time zone is left nil (UTC); set TZ on the result. The error is only for a cancelled or expired context; every lookup failure falls back to sea level with SourceSeaLevel.

func (Observer) Location

func (o Observer) Location() *time.Location

Location returns the observer's time zone, defaulting to UTC when TZ is nil.

type Position

type Position struct {
	Horizontal
	Diameter AngularDiameter
}

Position is the apparent placement of a body: the direction to the center of its disc paired with the disc's apparent angular size. Pairing the center with the angular diameter lets a consumer size and place the disc and reason about alignment and overlap between bodies.

Directories

Path Synopsis
Package constellation identifies which of the 88 IAU constellations a celestial position falls in, and lists the constellations.
Package constellation identifies which of the 88 IAU constellations a celestial position falls in, and lists the constellations.
Package earth adds Earth-bound conventions on top of the universal solar geometry in the sun package: named twilight bands, sunrise and sunset, solar noon, polar states, and atmospheric refraction.
Package earth adds Earth-bound conventions on top of the universal solar geometry in the sun package: named twilight bands, sunrise and sunset, solar noon, polar states, and atmospheric refraction.
moon
Package moon provides the Earth vantage on Luna, the Earth's moon: its topocentric horizontal position and apparent size, its phase and illumination, its rise and set for an observer, and an arc track over a time span.
Package moon provides the Earth vantage on Luna, the Earth's moon: its topocentric horizontal position and apparent size, its phase and illumination, its rise and set for an observer, and an arc track over a time span.
internal
angles
Package angles provides small, dependency-free helpers for working with angles expressed in degrees: conversion to and from radians, normalization into the range [0, 360), and clamping of declinations to [-90, 90].
Package angles provides small, dependency-free helpers for working with angles expressed in degrees: conversion to and from radians, normalization into the range [0, 360), and clamping of declinations to [-90, 90].
cmd/genelp command
Command genelp generates the truncated ELP 2000-82B lunar series used by internal/elp from the 36 files IMCCE publishes.
Command genelp generates the truncated ELP 2000-82B lunar series used by internal/elp from the 36 files IMCCE publishes.
cmd/genvsop command
Command genvsop generates the truncated VSOP87 tables in internal/ephemeris.
Command genvsop generates the truncated VSOP87 tables in internal/ephemeris.
coordinates
Package coordinates converts celestial positions between the ecliptic, equatorial, and local horizontal (alt-az) frames.
Package coordinates converts celestial positions between the ecliptic, equatorial, and local horizontal (alt-az) frames.
elp
Package elp evaluates the ELP 2000-82B lunar theory of M. Chapront-Touze and J. Chapront (Astronomy and Astrophysics 124, 50, 1983, and 190, 342, 1988), with its constants fitted to the JPL DE200/LE200 integration, as IMCCE distributes it with the Fortran subroutine ELP82B_2.
Package elp evaluates the ELP 2000-82B lunar theory of M. Chapront-Touze and J. Chapront (Astronomy and Astrophysics 124, 50, 1983, and 190, 342, 1988), with its constants fitted to the JPL DE200/LE200 integration, as IMCCE distributes it with the Fortran subroutine ELP82B_2.
ephemeris
Package ephemeris implements the astronomical series this library needs, ported directly rather than pulled in as a dependency.
Package ephemeris implements the astronomical series this library needs, ported directly rather than pulled in as a dependency.
iau
Package iau holds the IAU Working Group on Cartographic Coordinates and Rotational Elements (WGCCRE) models of the Sun, the planets, and the Moon: the direction of each body's north pole and the angle of its prime meridian at an instant, and its reference ellipsoid.
Package iau holds the IAU Working Group on Cartographic Coordinates and Rotational Elements (WGCCRE) models of the Sun, the planets, and the Moon: the direction of each body's north pole and the angle of its prime meridian at an instant, and its reference ellipsoid.
julian
Package julian converts civil instants into the time quantities the ephemeris math depends on: the Julian Date, Greenwich and local mean sidereal time, and the mean obliquity of the ecliptic.
Package julian converts civil instants into the time quantities the ephemeris math depends on: the Julian Date, Greenwich and local mean sidereal time, and the mean obliquity of the ecliptic.
planetary
Package planetary reduces a planet's VSOP87 table to what an observer on Earth sees: the light-time, the apparent place, the phase, the magnitude, and rise, set, and transit.
Package planetary reduces a planet's VSOP87 table to what an observer on Earth sees: the light-time, the apparent place, the phase, the magnitude, and rise, set, and transit.
planettest
Package planettest holds the checks every planet package runs against the committed JPL Horizons fixtures in planet/testdata.
Package planettest holds the checks every planet package runs against the committed JPL Horizons fixtures in planet/testdata.
vsop87
Package vsop87 evaluates the VSOP87 planetary theory: the series types the generated tables are written in, and the sum that turns a table into a heliocentric position.
Package vsop87 evaluates the VSOP87 planetary theory: the series types the generated tables are written in, and the sum that turns a table into a heliocentric position.
Package openmeteo looks an observer's height up from the Open-Meteo elevation API (https://open-meteo.com/en/docs/elevation-api), which is worldwide, free, and needs no key, and serves the Copernicus DEM at 90 m.
Package openmeteo looks an observer's height up from the Open-Meteo elevation API (https://open-meteo.com/en/docs/elevation-api), which is worldwide, free, and needs no key, and serves the Copernicus DEM at 90 m.
Package planet holds the types every planet package shares: the result of placing a planet for an observer, the heliocentric position, the Body interface each planet satisfies, and the errors they return.
Package planet holds the types every planet package shares: the result of placing a planet for an observer, the heliocentric position, the Body interface each planet satisfies, and the errors they return.
all
Package all lists every planet package, for a caller who wants to iterate over the planets or pick one by name.
Package all lists every planet package, for a caller who wants to iterate over the planets or pick one by name.
jupiter
Package jupiter places Jupiter in an observer's sky: topocentric apparent position, apparent diameter, phase, magnitude, elongation from the Sun, rise, set, and transit, and Jupiter's heliocentric position.
Package jupiter places Jupiter in an observer's sky: topocentric apparent position, apparent diameter, phase, magnitude, elongation from the Sun, rise, set, and transit, and Jupiter's heliocentric position.
mars
Package mars places Mars in an observer's sky: topocentric apparent position, apparent diameter, phase, magnitude, elongation from the Sun, rise, set, and transit, and Mars's heliocentric position.
Package mars places Mars in an observer's sky: topocentric apparent position, apparent diameter, phase, magnitude, elongation from the Sun, rise, set, and transit, and Mars's heliocentric position.
mercury
Package mercury places Mercury in an observer's sky: topocentric apparent position, apparent diameter, phase, magnitude, elongation from the Sun, rise, set, and transit, and Mercury's heliocentric position.
Package mercury places Mercury in an observer's sky: topocentric apparent position, apparent diameter, phase, magnitude, elongation from the Sun, rise, set, and transit, and Mercury's heliocentric position.
neptune
Package neptune places Neptune in an observer's sky: topocentric apparent position, apparent diameter, phase, magnitude, elongation from the Sun, rise, set, and transit, and Neptune's heliocentric position.
Package neptune places Neptune in an observer's sky: topocentric apparent position, apparent diameter, phase, magnitude, elongation from the Sun, rise, set, and transit, and Neptune's heliocentric position.
saturn
Package saturn places Saturn in an observer's sky: topocentric apparent position, apparent diameter, phase, magnitude, elongation from the Sun, rise, set, and transit, and Saturn's heliocentric position.
Package saturn places Saturn in an observer's sky: topocentric apparent position, apparent diameter, phase, magnitude, elongation from the Sun, rise, set, and transit, and Saturn's heliocentric position.
uranus
Package uranus places Uranus in an observer's sky: topocentric apparent position, apparent diameter, phase, magnitude, elongation from the Sun, rise, set, and transit, and Uranus's heliocentric position.
Package uranus places Uranus in an observer's sky: topocentric apparent position, apparent diameter, phase, magnitude, elongation from the Sun, rise, set, and transit, and Uranus's heliocentric position.
venus
Package venus places Venus in an observer's sky: topocentric apparent position, apparent diameter, phase, magnitude, elongation from the Sun, rise, set, and transit, and Venus's heliocentric position.
Package venus places Venus in an observer's sky: topocentric apparent position, apparent diameter, phase, magnitude, elongation from the Sun, rise, set, and transit, and Venus's heliocentric position.
Package project maps already-computed celestial positions, expressed in degrees, to canvas pixels.
Package project maps already-computed celestial positions, expressed in degrees, to canvas pixels.
Package satellite places Earth satellites, the International Space Station among them, in an observer's sky from an element set the caller supplies.
Package satellite places Earth satellites, the International Space Station among them, in an observer's sky from an element set the caller supplies.
celestrak
Package celestrak fetches satellite element sets from CelesTrak's GP API (https://celestrak.org/NORAD/elements/gp.php) as CCSDS OMM JSON, for a caller who wants the current set rather than supplying its own.
Package celestrak fetches satellite element sets from CelesTrak's GP API (https://celestrak.org/NORAD/elements/gp.php) as CCSDS OMM JSON, for a caller who wants the current set rather than supplying its own.
horizons
Package horizons fetches spacecraft ephemerides from the JPL Horizons API (https://ssd.jpl.nasa.gov/api/horizons.api), for objects SGP4 and two-line element sets cannot describe, such as the telescopes at the Sun-Earth L2 point (satellite/jwst, satellite/roman).
Package horizons fetches spacecraft ephemerides from the JPL Horizons API (https://ssd.jpl.nasa.gov/api/horizons.api), for objects SGP4 and two-line element sets cannot describe, such as the telescopes at the Sun-Earth L2 point (satellite/jwst, satellite/roman).
hubble
Package hubble follows the Hubble Space Telescope: its position in an observer's sky and its passes, propagated with SGP4 from an element set.
Package hubble follows the Hubble Space Telescope: its position in an observer's sky and its passes, propagated with SGP4 from an element set.
iss
Package iss follows the International Space Station: its position in an observer's sky and its passes, propagated with SGP4 from an element set.
Package iss follows the International Space Station: its position in an observer's sky and its passes, propagated with SGP4 from an element set.
jwst
Package jwst places the James Webb Space Telescope in an observer's sky, from JPL Horizons.
Package jwst places the James Webb Space Telescope in an observer's sky, from JPL Horizons.
roman
Package roman places the Nancy Grace Roman Space Telescope in an observer's sky, from JPL Horizons.
Package roman places the Nancy Grace Roman Space Telescope in an observer's sky, from JPL Horizons.
tiangong
Package tiangong follows the Tiangong space station (the Tianhe core module carries the station's catalogue entry): its position in an observer's sky and its passes, propagated with SGP4 from an element set.
Package tiangong follows the Tiangong space station (the Tianhe core module carries the station's catalogue entry): its position in an observer's sky and its passes, propagated with SGP4 from an element set.
Package sky places an observer on any body in the solar system and resolves any other body from there: Earth from Mars, the Sun from the Moon, Jupiter from Venus.
Package sky places an observer on any body in the solar system and resolves any other body from there: Earth from Mars, the Sun from the Moon, Jupiter from Venus.
Package star provides a universal, observer-independent catalog of stars: the quantities that belong to a star itself, not to any vantage.
Package star provides a universal, observer-independent catalog of stars: the quantities that belong to a star itself, not to any vantage.
Package sun provides universal Sun physics: quantities that depend only on the Sun itself, not on any observer, atmosphere, or vantage body.
Package sun provides universal Sun physics: quantities that depend only on the Sun itself, not on any observer, atmosphere, or vantage body.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL