Sidereon.Coordinates (Sidereon v0.8.0)

Copy Markdown View Source

Coordinate frame transformations for satellite state vectors.

Supports:

  • TEME → GCRS coordinate conversion with committed oracle fixtures
  • GCRS → ITRS (Earth-fixed / ECEF)
  • ITRS → GCRS
  • ITRS → Geodetic (WGS84 lat/lon/alt)
  • Geodetic → ITRS
  • Topocentric (azimuth/elevation/range) from a ground station

Time-scale handling is intentionally kept behind the public datetime inputs in this module. The Rust core and Python binding expose lower-level Instant, TimeScale, leap-second, and UT1 metadata APIs; the Elixir public surface does not expose those as standalone modules yet to avoid a partial time API.

Summary

Types

datetime()
geodetic_input()
ground_station()
state()
vec3()

Functions

gcrs_to_itrs(map, datetime, opts \\ [])

Convert a GCRS position to ITRS (Earth-fixed / ECEF).

geodetic_to_itrs(arg1)

Convert WGS84 geodetic coordinates to an ITRS/ECEF position.

itrs_to_gcrs(arg, datetime)

Convert an ITRS/ECEF position to GCRS.

teme_to_gcrs(map, datetime, opts \\ [])

Convert a TEME state vector to GCRS.

to_geodetic(arg)

Convert an ITRS/ECEF position to WGS84 geodetic coordinates.

to_topocentric(map, datetime, station, opts \\ [])

Compute topocentric azimuth, elevation, and range from a ground station to a satellite given in GCRS.

Types

datetime()

@type datetime() ::
  DateTime.t()
  | {{integer(), integer(), integer()}, {integer(), integer(), integer()}}

geodetic_input()

@type geodetic_input() ::
  Sidereon.Geodetic.t()
  | %{latitude: number(), longitude: number(), altitude_km: number()}
  | vec3()

ground_station()

@type ground_station() :: %{
  latitude: number(),
  longitude: number(),
  altitude_m: number()
}

state()

@type state() :: %{position: vec3(), velocity: vec3()}

vec3()

@type vec3() :: {number(), number(), number()}

Functions

gcrs_to_itrs(map, datetime, opts \\ [])

@spec gcrs_to_itrs(%{position: vec3()}, datetime(), keyword()) ::
  {float(), float(), float()}

Convert a GCRS position to ITRS (Earth-fixed / ECEF).

Accepts a map with a :position tuple (km) and a datetime. Set skyfield_compat: true to reproduce the committed Skyfield oracle vectors used by the validation suite. The default is sidereon's native path.

Returns {x, y, z} in km.

geodetic_to_itrs(arg1)

@spec geodetic_to_itrs(geodetic_input()) :: {float(), float(), float()}

Convert WGS84 geodetic coordinates to an ITRS/ECEF position.

Accepts %Sidereon.Geodetic{}, a map with :latitude, :longitude, and :altitude_km, or a {latitude, longitude, altitude_km} tuple. Latitude and longitude are degrees; altitude is kilometres.

Returns {x, y, z} in km.

itrs_to_gcrs(arg, datetime)

@spec itrs_to_gcrs(vec3(), datetime()) :: {float(), float(), float()}

Convert an ITRS/ECEF position to GCRS.

Accepts a position tuple {x, y, z} in km and a datetime.

Returns {x, y, z} in km.

teme_to_gcrs(map, datetime, opts \\ [])

@spec teme_to_gcrs(state(), datetime(), keyword()) :: state()

Convert a TEME state vector to GCRS.

Accepts a map with :position and :velocity tuples (km and km/s), and a datetime (either DateTime or {{y,m,d},{h,m,s}} tuple).

Options

  • :skyfield_compat - when true, reproduces the committed Skyfield oracle vectors used by the validation suite. Default false uses sidereon's native path.

Returns a map with GCRS :position and :velocity.

to_geodetic(arg)

@spec to_geodetic(vec3()) :: Sidereon.Geodetic.t()

Convert an ITRS/ECEF position to WGS84 geodetic coordinates.

Accepts a position tuple {x, y, z} in km.

Returns %{latitude: degrees, longitude: degrees, altitude_km: km}.

to_topocentric(map, datetime, station, opts \\ [])

@spec to_topocentric(%{position: vec3()}, datetime(), ground_station(), keyword()) ::
  Sidereon.LookAngle.t()

Compute topocentric azimuth, elevation, and range from a ground station to a satellite given in GCRS.

Parameters

  • gcrs_state - map with :position tuple (km) in GCRS
  • datetime - observation time
  • station - %{latitude: deg, longitude: deg, altitude_m: meters}

Returns %{azimuth: degrees, elevation: degrees, range_km: km}.