Sidereon.Format.TLE (Sidereon v0.8.0)

Parse and encode Two-Line Element sets.

TLE is the legacy fixed-width format for satellite orbital elements, designed for 80-column punch cards in the 1960s. Despite its age, it remains the most widely used format for distributing orbital data.

The format grammar lives in the Rust core (astrodynamics::tle): fixed-width field extraction and validation, the modulo-10 checksum, the "assumed decimal" drag-term codec, per-field number formatting, and the two-digit-year pivot. This module keeps the Sidereon API shape: it marshals the epoch between its native DateTime and the (epoch_year, epoch_day_of_year) pair the core exposes, applies input defaults, logs advisory checksum warnings, and maps errors.

Parsing

The parser is liberal in what it accepts:

Trailing whitespace and extra characters are trimmed
Leading dots in floats (.123 → 0.123)
Spaces in numeric fields

Checksum validation is performed and reported but does not prevent parsing.

Examples

{:ok, elements} = Sidereon.Format.TLE.parse(line1, line2)
{:ok, {line1, line2}} = Sidereon.Format.TLE.encode(elements)

Summary

Types

encode_error()

Functions

encode(el)

Encode an %Sidereon.Elements{} struct as TLE-format strings.

encode!(el)

Like encode/1 but raises on malformed elements.

parse(longstr1, longstr2)

Parse a two-line element set into an %Sidereon.Elements{} struct.

Types

encode_error()

@type encode_error() ::
  {:missing_field, atom()}
  | {:invalid_field, atom(), term()}
  | {:encode_error, String.t()}

Functions

encode(el)

@spec encode(Sidereon.Elements.t()) ::
  {:ok, {String.t(), String.t()}} | {:error, encode_error()}

Encode an %Sidereon.Elements{} struct as TLE-format strings.

Returns {:ok, {line1, line2}}: two 69-character strings with valid checksums, or {:error, reason} for malformed elements. Round-trips are character-exact for standard TLEs.

Examples

iex> l1 = "1 25544U 98067A   18184.80969102  .00001614  00000-0  31745-4 0  9993"
iex> l2 = "2 25544  51.6414 295.8524 0003435 262.6267 204.2868 15.54005638121106"
iex> {:ok, el} = Sidereon.Format.TLE.parse(l1, l2)
iex> {:ok, {gen_l1, gen_l2}} = Sidereon.Format.TLE.encode(el)
iex> gen_l1 == l1
true
iex> gen_l2 == l2
true

encode!(el)

@spec encode!(Sidereon.Elements.t()) :: {String.t(), String.t()}

Like encode/1 but raises on malformed elements.

parse(longstr1, longstr2)

@spec parse(String.t(), String.t()) ::
  {:ok, Sidereon.Elements.t()} | {:error, String.t()}

Parse a two-line element set into an %Sidereon.Elements{} struct.

Returns {:ok, elements} or {:error, reason}. Logs a warning if checksums are invalid but still parses.

Examples

iex> {:ok, el} = Sidereon.Format.TLE.parse(
...>   "1 25544U 98067A   18184.80969102  .00001614  00000-0  31745-4 0  9993",
...>   "2 25544  51.6414 295.8524 0003435 262.6267 204.2868 15.54005638121106"
...> )
iex> el.catalog_number
"25544"
iex> el.inclination_deg
51.6414