Sidereon.Bodies (Sidereon v0.11.1)

Ground-observer Sun and Moon geometry.

From a ground station and a UTC instant, answer the "observe the sky from a site" questions: the topocentric azimuth/elevation/range of the Sun or Moon, the Moon's illuminated fraction, and the Moon's rise/set and meridian-transit events over a window. The azimuth/elevation convention matches the satellite look-angle path; the Moon vector is geocentric, so the station-to-target reduction applies the diurnal parallax that matters for the nearby Moon.

Precision follows the underlying analytic Sun/Moon series (sub-degree positions); this is a planning/visualization lens, not an almanac-grade reduction. The ephemeris, topocentric reduction, phase-angle geometry, and event refinement all live in the sidereon-core Rust core.

A station is {latitude_deg, longitude_deg, altitude_km} or a map with :latitude_deg, :longitude_deg, :altitude_km. A time is a DateTime, a NaiveDateTime (interpreted as UTC), or a {{y, m, d}, {h, min, s, us}} tuple.

Summary

Types

az_el()

Topocentric look angle of a body from a site.

event()

A Moon rise/set or meridian-transit event.

station()

time()

Functions

find_moon_elevation_crossings(station, start_time, end_time, opts \\ [])

Moon elevation-threshold crossings (moonrise / moonset) over a UTC window.

find_moon_transits(station, start_time, end_time, opts \\ [])

Moon meridian transits (upper and lower culminations) over a UTC window.

moon_az_el(station, time)

Topocentric azimuth/elevation/range of the Moon from a site.

moon_elevation_deg(station, time)

Topocentric geometric Moon (disk-center) elevation at a site, degrees.

moon_illumination(station, time)

Illuminated fraction of the Moon as seen from a site.

sun_az_el(station, time)

Topocentric azimuth/elevation/range of the Sun from a site.

Types

az_el()

@type az_el() :: %{azimuth_deg: float(), elevation_deg: float(), range_km: float()}

Topocentric look angle of a body from a site.

event()

@type event() :: %{time: DateTime.t(), kind: atom(), elevation_deg: float()}

A Moon rise/set or meridian-transit event.

station()

@type station() ::
  {number(), number(), number()}
  | %{latitude_deg: number(), longitude_deg: number(), altitude_km: number()}

time()

@type time() :: DateTime.t() | NaiveDateTime.t() | {tuple(), tuple()}

Functions

find_moon_elevation_crossings(station, start_time, end_time, opts \\ [])

@spec find_moon_elevation_crossings(station(), time(), time(), keyword()) ::
  {:ok, [event()]} | {:error, atom()}

Moon elevation-threshold crossings (moonrise / moonset) over a UTC window.

Options

:elevation_threshold_deg - crossing threshold (default -0.833, the standard upper-limb-on-the-horizon convention).
:step_seconds - event-finder scan step (default 600.0).
:time_tolerance_seconds - crossing-time refinement tolerance (default 1.0).

Returns {:ok, [%{time: DateTime, kind: :rising | :setting, elevation_deg:}]}.

find_moon_transits(station, start_time, end_time, opts \\ [])

@spec find_moon_transits(station(), time(), time(), keyword()) ::
  {:ok, [event()]} | {:error, atom()}

Moon meridian transits (upper and lower culminations) over a UTC window.

Options

:step_seconds - event-finder scan step (default 600.0).
:time_tolerance_seconds - crossing-time refinement tolerance (default 1.0).

Returns {:ok, [%{time: DateTime, kind: :upper | :lower, elevation_deg:}]}.

moon_az_el(station, time)

@spec moon_az_el(station(), time()) :: {:ok, az_el()} | {:error, atom()}

Topocentric azimuth/elevation/range of the Moon from a site.

moon_elevation_deg(station, time)

@spec moon_elevation_deg(station(), time()) :: {:ok, float()} | {:error, atom()}

Topocentric geometric Moon (disk-center) elevation at a site, degrees.

moon_illumination(station, time)

@spec moon_illumination(station(), time()) ::
  {:ok, %{illuminated_fraction: float(), phase_angle_deg: float()}}
  | {:error, atom()}

Illuminated fraction of the Moon as seen from a site.

Returns {:ok, %{illuminated_fraction: k, phase_angle_deg: a}} with k in [0, 1] (0 = new, 1 = full) and the Sun-Moon-observer phase angle in degrees.

sun_az_el(station, time)

@spec sun_az_el(station(), time()) :: {:ok, az_el()} | {:error, atom()}

Topocentric azimuth/elevation/range of the Sun from a site.