@spec parse_tle(String.t(), String.t()) ::
  {:ok, Sgp4Ex.TLE.t()} | {:error, String.t()}

Parse a TLE (Two-Line Element) set into a TLE struct. The TLE consists of two lines, each with a specific format.

Parameters

• line1: The first line of the TLE.
• line2: The second line of the TLE.

Returns

• {:ok, TLE.t()}: The parsed TLE struct.
• {:error, String.t()}: An error message if the parsing fails.

Example

iex> line1 = "1 25544U 98067A   21275.54791667  .00001264  00000-0  39629-5 0  9993"
iex> line2 = "2 25544  51.6456  23.4367 0001234  45.6789 314.3210 15.48999999    12"
iex> case Sgp4Ex.parse_tle(line1, line2) do
...>   {:ok, %Sgp4Ex.TLE{}} -> :ok
...>   _ -> :error
...> end
:ok

@spec propagate_tle_to_epoch(Sgp4Ex.TLE.t(), DateTime.t()) ::
  {:ok, Sgp4Ex.TemeState.t()} | {:error, String.t()}

Propagate a TLE to a specific epoch using the SGP4 algorithm. The epoch is the time to which the TLE should be propagated.

Parameters

• tle: The TLE data structure containing the satellite's orbital elements.
• epoch: The epoch to which the TLE should be propagated.

Returns

• {:ok, TemeState.t()}: The propagated Teme state of the satellite.
• {:error, String.t()}: An error message if the propagation fails.

Example

iex> {:ok, tle} = Sgp4Ex.parse_tle(
...>   "1 25544U 98067A   21275.54791667  .00001264  00000-0  39629-5 0  9993",
...>   "2 25544  51.6456  23.4367 0001234  45.6789 314.3210 15.48999999    12"
...> )
iex> epoch = ~U[2021-10-02T14:00:00Z]
iex> case Sgp4Ex.propagate_tle_to_epoch(tle, epoch) do
...>   {:ok, %Sgp4Ex.TemeState{position: {x, y, z}, velocity: {vx, vy, vz}}} when is_float(x) and is_float(y) and is_float(z) and is_float(vx) and is_float(vy) and is_float(vz) -> :ok
...>   _ -> :error
...> end
:ok

@spec propagate_to_geodetic(Sgp4Ex.TLE.t(), DateTime.t()) ::
  {:ok, %{latitude: float(), longitude: float(), altitude_km: float()}}
  | {:error, String.t()}

Propagate a TLE to geodetic coordinates at a specific epoch.

This is a convenience function that propagates the satellite position and converts it to geodetic coordinates (latitude, longitude, altitude).

Parameters

• tle: The TLE data structure containing the satellite's orbital elements
• epoch: The UTC datetime to which the TLE should be propagated

Returns

• {:ok, %{latitude: float, longitude: float, altitude_km: float}} where:
  • latitude: Geodetic latitude in degrees (-90 to 90)
  • longitude: Geodetic longitude in degrees (-180 to 180)
  • altitude_km: Height above WGS84 ellipsoid in kilometers
• {:error, String.t()}: An error message if propagation fails

Example

iex> {:ok, tle} = Sgp4Ex.parse_tle(
...>   "1 25544U 98067A   21275.54791667  .00001264  00000-0  39629-5 0  9993",
...>   "2 25544  51.6456  23.4367 0001234  45.6789 314.3210 15.48999999    12"
...> )
iex> epoch = ~U[2021-10-02T14:00:00Z]
iex> case Sgp4Ex.propagate_to_geodetic(tle, epoch) do
...>   {:ok, %{latitude: lat, longitude: lon, altitude_km: alt}} when is_float(lat) and is_float(lon) and is_float(alt) -> :ok
...>   _ -> :error
...> end
:ok

@spec propagator() :: :nif | :elixir

Which propagator will be used for the next call.

• :nif – native Vallado C++ NIF
• :elixir – pure-Elixir Vallado fallback

Override with config :sgp4_ex, propagator: :auto | :nif | :elixir.