Library

abstract type AbstractTleFetcher

Abstract type for all TLE fetchers.

struct CelestrakTleFetcher <: AbstractTleFetcher

Fetcher that retrieves TLEs from the Celestrak service.

Create an instance with create_tle_fetcher(CelestrakTleFetcher) and query the service with fetch_tles. Celestrak provides publicly available data and does not require authentication.

Fields

• url::String: Address of the Celestrak endpoint used to perform the queries.

struct TLE

Store the elements of a TLE (two-line elements) using the same units of the TLE format.

The inner constructor enforces that every field can be represented in the fixed-width TLE format (see the ranges below), so that writing a TLE never fails. Create a TLE with the keyword constructor TLE(; kwargs...), whose keywords are the fields below plus the optional epoch.

Fields

• name::String: Name of the satellite. (Default: "UNDEFINED")

First line

• satellite_number::Int: Satellite catalog number, in the interval [0, 339999]. Numbers above 99999 are written using the Alpha-5 scheme. (Default: 0)
• classification::Char: Classification ('U', 'C', or 'S'). It must be an ASCII character. (Default: 'U')
• international_designator::String: International designator, with at most 8 ASCII characters. (Default: "00000")
• epoch_year::Int: Epoch year, with two digits in the interval [0, 99]. Years from 57 to 99 refer to the 20th century, and years from 0 to 56 to the 21st century.
• epoch_day::Float64: Epoch day of the year plus its fraction, in the interval [0, 367) [days].
• dn_o2::Float64: 1st time derivative of the mean motion divided by 2 [rev/day²]. (Default: 0)
• ddn_o6::Float64: 2nd time derivative of the mean motion divided by 6 [rev/day³]. (Default: 0)
• bstar::Float64: B* drag term [1/ER]. (Default: 0)
• ephemeris_type::Int: Ephemeris type, with one digit in the interval [0, 9]. (Default: 0)
• element_set_number::Int: Element set number, in the interval [0, 9999]. (Default: 0)

Second line

• inclination::Float64: Inclination [°].
• raan::Float64: Right ascension of the ascending node [°].
• eccentricity::Float64: Eccentricity [-], in the interval [0, 1).
• argument_of_perigee::Float64: Argument of perigee [°].
• mean_anomaly::Float64: Mean anomaly [°].
• mean_motion::Float64: Mean motion [rev/day], in the interval [0, 100).
• revolution_number::Int: Revolution number at epoch [rev], in the interval [0, 99999]. (Default: 0)

Extended help

Properties

Besides the fields, the property epoch returns the TLE epoch as a DateTime [UTC], as computed by tle_epoch.

Creating TLEs

The keyword constructor TLE(; kwargs...) requires inclination, raan, eccentricity, argument_of_perigee, mean_anomaly, and mean_motion. The epoch must be provided either by epoch_year and epoch_day, or by the keyword epoch::DateTime [UTC], from which the former are computed. The other keywords are optional and receive the default values listed above.

Throws

• ArgumentError: If a field is outside the range that can be represented in the TLE format, or if the epoch is not provided exactly once.

TLE(; kwargs...) -> TLE

Create a TLE from the keyword arguments kwargs..., which have the same names as the structure fields, plus the optional keyword epoch.

The keywords inclination, raan, eccentricity, argument_of_perigee, mean_anomaly, and mean_motion are required. The epoch must be provided either by epoch_year and epoch_day, or by epoch, from which the former are computed. The other keywords are optional. An ArgumentError is thrown if a field cannot be represented in the TLE format or if the epoch is not provided exactly once.

Keywords

• name::AbstractString: Name of the satellite. (Default: "UNDEFINED")
• satellite_number::Integer: Satellite catalog number, in the interval [0, 339999]. (Default: 0)
• classification::Char: Classification ('U', 'C', or 'S'). (Default: 'U')
• international_designator::AbstractString: International designator, with at most 8 ASCII characters. (Default: "00000")
• epoch::Union{DateTime, Nothing}: Epoch [UTC] used to compute epoch_year and epoch_day. It cannot be provided together with those keywords. (Default: nothing)
• epoch_year::Union{Integer, Nothing}: Epoch year with two digits, in the interval [0, 99]. It is required if epoch is not provided. (Default: nothing)
• epoch_day::Union{Number, Nothing}: Epoch day of the year plus its fraction, in the interval [0, 367) [days]. It is required if epoch is not provided. (Default: nothing)
• dn_o2::Number: 1st time derivative of the mean motion divided by 2 [rev/day²]. (Default: 0)
• ddn_o6::Number: 2nd time derivative of the mean motion divided by 6 [rev/day³]. (Default: 0)
• bstar::Number: B* drag term [1/ER]. (Default: 0)
• ephemeris_type::Integer: Ephemeris type, in the interval [0, 9]. (Default: 0)
• element_set_number::Integer: Element set number, in the interval [0, 9999]. (Default: 0)
• inclination::Number: Inclination [°].
• raan::Number: Right ascension of the ascending node [°].
• eccentricity::Number: Eccentricity [-], in the interval [0, 1).
• argument_of_perigee::Number: Argument of perigee [°].
• mean_anomaly::Number: Mean anomaly [°].
• mean_motion::Number: Mean motion [rev/day], in the interval [0, 100).
• revolution_number::Integer: Revolution number at epoch [rev], in the interval [0, 99999]. (Default: 0)

struct TleFetchError <: Exception

Exception thrown when a request to a TLE service fails.

Fields

• msg::String: Description of the request failure.
• url::Union{String, Nothing}: URL of the failed request, if available.
• status::Union{Int, Nothing}: HTTP status code of the failed request, if available.

TleFetchError(msg::String; kwargs...) -> TleFetchError

Create a TleFetchError with the description msg.

Keywords

• url::Union{String, Nothing}: URL of the failed request, if available. (Default: nothing)
• status::Union{Int, Nothing}: HTTP status code of the failed request, if available. (Default: nothing)

struct TleParseError <: Exception

Exception thrown when a TLE cannot be parsed from its text representation.

Fields

• msg::String: Description of the parsing failure.
• line::Int: Number of the line in the input where the failure was detected, or 0 if the position is unknown.

TleParseError(msg::String; kwargs...) -> TleParseError

Create a TleParseError with the description msg.

Keywords

• line::Int: Number of the line in the input where the failure was detected, or 0 if the position is unknown. (Default: 0)

_check_tle_line(line::AbstractString, line_number::Int, position::Int) -> Nothing

Throw a TleParseError at position if line is not a valid TLE line line_number (1 or 2): 69 ASCII characters starting with the line number followed by a space. The ASCII check allows the fields to be sliced by bytes.

_datetime_to_tle_epoch(epoch::DateTime) -> Int, Float64

Convert the epoch [UTC] to the two-digit epoch year and the epoch day of the year plus its fraction [days] used by the TLE format. An ArgumentError is thrown if epoch is outside the years that can be represented in a TLE (from 1957 to 2056).

_is_tle_line(line::AbstractString, line_number::Int) -> Bool

Return true if line has the shape of the TLE line line_number (1 or 2): 69 bytes starting with the line number followed by a space.

_next_tle_input_line(io::IO, line_num::Int) -> Union{SubString{String}, Nothing}, Int

Read from io the next line that is neither blank nor a comment starting with #, returning it without the surrounding whitespace together with its number in the input, given that line_num lines were read before. If io is exhausted, the returned line is nothing.

_parse_satellite_number(
    cu::AbstractVector{UInt8},
    line_number::Int,
    position::Int
) -> Int

Parse the satellite catalog number in bytes 3 to 7 of the TLE line cu, which is the line line_number (1 or 2) at position in the input. Besides the plain 5-digit numbers, the Alpha-5 scheme is supported, in which the first character is a letter encoding the two leading digits (A = 10, B = 11, ..., Z = 33, skipping I and O). A TleParseError is thrown if the characters cannot be parsed.

_parse_tle(l1::AbstractString, l2::AbstractString; kwargs...) -> TLE

Parse the TLE with the first line l1 and the second line l2, both without surrounding whitespace, throwing a TleParseError if the lines are not valid.

Keywords

• name::AbstractString: Satellite name assigned to the parsed TLE. (Default: "UNDEFINED")
• l1_position::Int: Number of l1 in the input, used in the error messages, or 0 if unknown. (Default: 0)
• l2_position::Int: Number of l2 in the input, used in the error messages, or 0 if unknown. (Default: 0)
• verify_checksum::Bool: If true, the checksum of both lines is verified. (Default: true)

_parse_tle_ephemeris_type(cu::AbstractVector{UInt8}, position::Int) -> Int

Parse the ephemeris type in byte 63 of the first TLE line cu, at position in the input. A blank field is interpreted as 0, and a TleParseError is thrown if the character is not a digit.

_parse_tle_exponential(
    cu::AbstractVector{UInt8},
    start::Int,
    line_number::Int,
    position::Int,
    field::String
) -> Float64

Parse the 8-byte field starting at byte start of the TLE line cu, which is the line line_number (1 or 2) at position in the input, written in the TLE exponential notation ±MMMMM±E: a sign (-, +, or space), 5 mantissa digits with an implied leading decimal point, and a signed exponent digit. A TleParseError naming field is thrown if the characters cannot be parsed.

_parse_tle_float(
    line::AbstractString,
    range::UnitRange{Int},
    line_number::Int,
    position::Int,
    field::String
) -> Float64

Parse the floating-point number in the bytes range of the TLE line, which is the line line_number (1 or 2) at position in the input, throwing a TleParseError naming field if the characters cannot be parsed.

_parse_tle_int(
    cu::AbstractVector{UInt8},
    range::UnitRange{Int},
    line_number::Int,
    position::Int,
    field::String;
    kwargs...
) -> Int

Parse the integer in the bytes range of the TLE line cu, which is the line line_number (1 or 2) at position in the input. Leading spaces are ignored, and a TleParseError naming field is thrown if the remaining characters are not a sign followed by digits.

Keywords

• allow_sign::Bool: If true, a + or - sign may precede the digits. (Default: true)

_parse_tles(io::IO; kwargs...) -> Vector{TLE}

Parse every TLE in io, returning them in a vector. Blank lines and lines starting with # are ignored, and the surrounding whitespace of each line is discarded. A TLE consists of an optional satellite name line followed by the two TLE lines. If a TLE cannot be parsed, a warning is emitted and the TLE is skipped.

Keywords

• verify_checksum::Bool: If true, the checksum of both lines of each TLE is verified. (Default: true)

_scale_by_power_of_ten(x::Number, k::Int) -> Float64

Return x × 10^k for k in the interval [-14, 14], multiplying or dividing x by an exactly representable power of ten so that the result is correctly rounded.

_throw_tle_field_error(line_number::Int, position::Int, field::String) -> Nothing

Throw the TleParseError reporting that field of the TLE line line_number (1 or 2), at position in the input, could not be parsed.

_tle_epoch_year(epoch_year::Int) -> Int

Return the four-digit year related to the two-digit TLE epoch_year, using the SGP4 reference pivot: years from 57 to 99 refer to the 20th century, and years from 0 to 56 to the 21st century.

_tle_line_checksum(bytes::AbstractVector{UInt8}) -> Int

Compute the checksum modulo 10 of the line encoded in UTF-8 by bytes, as described in tle_line_checksum.

The computation can be performed byte by byte because only the ASCII digits and the minus sign have a value, and the bytes of the multi-byte characters never match them.

_tle_mantissa_and_exponent(value::Float64, field::String) -> Int, Int

Return the 5-digit integer mantissa and the exponent that represent the non-negative value in the TLE exponential notation, i.e. value ≈ 0.MMMMM × 10^E. The mantissa is normalized to the interval [10000, 99999] whenever the exponent fits in the single digit of the field. Otherwise, the field is saturated if value is too large, or the mantissa is denormalized and set to 0 if value is too small, emitting a warning that names field.

_tle_parse_error_message(e::TleParseError) -> String

Return the message of e prefixed by the line number in the input, if known.

_verify_tle_line_checksum(
    line::AbstractString,
    line_number::Int,
    position::Int
) -> Nothing

Throw a TleParseError at position if the checksum in the last character of the TLE line, which is the line line_number (1 or 2), does not match the checksum computed from the other characters.

_write_digits(io::IO, value::Int, num_digits::Int) -> Nothing

Write to io the num_digits least significant decimal digits of the non-negative integer value, zero-padded to the left.

_write_exponential_field(io::IO, value::Float64, field::String) -> Nothing

Write to io the 8-character TLE field with value in the format ±MMMMM±E, where MMMMM are the mantissa digits with an implied leading decimal point and E is the exponent digit. field names the field in the warnings emitted when value cannot be represented and must be saturated or set to 0.

_write_fixed_point(
    io::IO,
    value::Int,
    int_width::Int,
    frac_digits::Int;
    kwargs...
) -> Nothing

Write to io the fixed-point number value / 10^frac_digits with exactly frac_digits decimal digits and the integer part right-justified to int_width characters using pad.

Keywords

• pad::Char: Character used to pad the integer part. (Default: ' ')

_write_line_with_checksum(io::IO, buf::IOBuffer) -> Nothing

Write to io the line assembled in buf followed by its checksum and a newline, emptying buf.

_write_padded_int(io::IO, value::Int, width::Int; kwargs...) -> Nothing

Write to io the non-negative integer value right-justified to width characters using pad. If value has more digits than width, all of them are written.

Keywords

• pad::Char: Character used to pad the number. (Default: ' ')

_write_padded_string(io::IO, str::AbstractString, width::Int) -> Nothing

Write to io the string str followed by the spaces required to fill width characters.

_write_satellite_number(io::IO, satellite_number::Int) -> Nothing

Write to io the 5-character field with the satellite_number. Numbers up to 99999 are written as plain digits. Otherwise, the first character is the letter of the Alpha-5 scheme that encodes the two leading digits (A = 10, B = 11, ..., Z = 33, skipping I and O).

_write_tle_angle(io::IO, angle::Float64) -> Nothing

Write to io the 8-character TLE field with the angle [°] normalized to the interval [0, 360)°, with 4 decimal digits. An angle that rounds to 360° at this precision is written as 0°.

_write_tle_line_1(io::IO, tle::TLE) -> Nothing

Write to io the first line of tle without the checksum.

_write_tle_line_2(io::IO, tle::TLE) -> Nothing

Write to io the second line of tle without the checksum.

create_tle_fetcher(::Type{CelestrakTleFetcher}; kwargs...) -> CelestrakTleFetcher

Create a TLE fetcher from the Celestrak service.

Keywords

• url::String: URL of the Celestrak query endpoint. (Default: "https://celestrak.org/NORAD/elements/gp.php")

create_tle_fetcher(::Type{T}, args...; kwargs...) where {T <: AbstractTleFetcher} -> T

Create a TLE fetcher of type T.

The positional and keyword arguments are specific to each fetcher type; see the documentation of the corresponding method. An ArgumentError is thrown if T has no registered fetcher method.

fetch_tles(fetcher::CelestrakTleFetcher; kwargs...) -> Vector{TLE}

Fetch TLEs from the Celestrak service using the query parameters in kwargs....

Exactly one of international_designator, satellite_number, and satellite_name must be provided. If no matching TLE is found, an empty vector is returned with a warning. If an error prevents the request from succeeding, a TleFetchError is thrown.

Keywords

• international_designator::Union{Nothing, AbstractString}: International designator of the satellite in the format YYYY-NNN or YYYY-NNNP, where YYYY is the launch year, NNN is the launch number, and P is the piece of the launch. (Default: nothing)
• satellite_number::Union{Nothing, Integer}: Satellite catalog number (NORAD). (Default: nothing)
• satellite_name::Union{Nothing, AbstractString}: Satellite name. The service returns every satellite whose name contains this string. (Default: nothing)

Extended help

Throws

• ArgumentError: If the number of query parameters is not exactly one, or if a query parameter is not valid.
• TleFetchError: If the request fails or if the service rejects the query.

fetch_tles(fetcher::T; kwargs...) where {T <: AbstractTleFetcher} -> Vector{TLE}

Fetch TLEs using fetcher.

The keywords kwargs... customize the search and are specific to each fetcher type; see the documentation of the corresponding method. An ArgumentError is thrown if the fetcher type T is not registered.

read_tle(l1::AbstractString, l2::AbstractString; kwargs...) -> TLE

Read the TLE whose first line is l1 and second line is l2, throwing a TleParseError if it is not valid. The surrounding whitespace of the lines is discarded.

Keywords

• name::AbstractString: Satellite name assigned to the returned TLE. (Default: "UNDEFINED")
• verify_checksum::Bool: If true, the checksum of both TLE lines is verified. (Default: true)

Extended help

Throws

• TleParseError: If the TLE cannot be parsed.

read_tle(str::AbstractString; kwargs...) -> TLE

Read the single TLE in the string str, throwing a TleParseError if it is not valid.

str must contain only one TLE, i.e. two or three non-empty lines: the optional satellite name and the two TLE lines. Blank lines and lines starting with # are discarded.

See also: read_tles, @tle_str

Keywords

• verify_checksum::Bool: If true, the checksum of both TLE lines is verified. (Default: true)

Extended help

Throws

• TleParseError: If str does not contain exactly one TLE, or if the TLE cannot be parsed.

read_tles(str::AbstractString; kwargs...) -> Vector{TLE}

Read the set of TLEs in the string str, returning them in a vector.

Each TLE consists of an optional satellite name line followed by the two TLE lines. Blank lines and lines starting with # are discarded. The TLEs that cannot be parsed are skipped with a warning.

See also: read_tle, read_tles_from_file, @tles_str

Keywords

• verify_checksum::Bool: If true, the checksum of both lines of each TLE is verified. (Default: true)

read_tles_from_file(filename::AbstractString; kwargs...) -> Vector{TLE}

Read the set of TLEs in the file filename, returning them in a vector.

Each TLE consists of an optional satellite name line followed by the two TLE lines. Blank lines and lines starting with # are discarded. The TLEs that cannot be parsed are skipped with a warning.

See also: read_tles, write_tles

Keywords

• verify_checksum::Bool: If true, the checksum of both lines of each TLE is verified. (Default: true)

tle_epoch(tle::TLE) -> Float64

Return the Julian day [UTC] related to the tle epoch.

The two-digit epoch year is interpreted according to the SGP4 reference implementation: years from 57 to 99 refer to the 20th century, and years from 0 to 56 to the 21st century.

tle_epoch(DateTime, tle::TLE) -> DateTime

Return the DateTime [UTC] related to the tle epoch, rounded to the millisecond.

The two-digit epoch year is interpreted according to the SGP4 reference implementation: years from 57 to 99 refer to the 20th century, and years from 0 to 56 to the 21st century.

tle_line_checksum(str::AbstractString) -> Int

Compute the checksum of the line str modulo 10.

The algorithm is simple: add all the numbers in the line, ignoring letters, spaces, periods, and plus signs, but assigning +1 to the minus signs. The checksum is the remainder of the division by 10.

write_tle(io::IO, tle::TLE) -> Nothing
write_tle(file::AbstractString, tle::TLE) -> Nothing
write_tle(String, tle::TLE) -> String

Write the text representation of tle to the stream io or to the file file, which is created or overwritten. If the first argument is the type String, the text is returned instead.

The output has three lines terminated by a newline: the satellite name padded to 24 characters, and the two TLE lines with recomputed checksums. The angles (inclination, RAAN, argument of perigee, and mean anomaly) are normalized to the interval [0, 360)° before being written. If the magnitude of dn_o2, ddn_o6, or bstar cannot be represented in its TLE field, the field is saturated, or set to 0 if the value is too small, and a warning is emitted. The other fields are validated by the TLE constructor, so they always fit.

See also: write_tles

write_tles(io::IO, tles::AbstractVector{TLE}) -> Nothing
write_tles(file::AbstractString, tles::AbstractVector{TLE}) -> Nothing
write_tles(String, tles::AbstractVector{TLE}) -> String

Write the text representation of every TLE in tles to the stream io or to the file file, which is created or overwritten. If the first argument is the type String, the text is returned instead. Each TLE is written as described in write_tle, one after the other.

@tle_nc_str(str)

Parse the single TLE in the string str at macro expansion time, returning a TLE. The checksums of the lines are not verified. A TleParseError is thrown if str is not a valid TLE.

str must contain only one TLE, i.e. two or three non-empty lines: the optional satellite name and the two TLE lines. Blank lines and lines starting with # are discarded.

See also: @tle_str, read_tle

Example

julia> tle = tle_nc"""
       CBERS 4
       1 40336U 14079A   18166.15595376 -.00000014  00000-0  10174-4 0  9993
       2 40336  98.4141 237.7928 0001694  75.7582 284.3804 14.35485112184485
       """

@tle_str(str)

Parse the single TLE in the string str at macro expansion time, returning a TLE. The checksums of both lines are verified. A TleParseError is thrown if str is not a valid TLE.

str must contain only one TLE, i.e. two or three non-empty lines: the optional satellite name and the two TLE lines. Blank lines and lines starting with # are discarded.

See also: @tle_nc_str, read_tle

Example

julia> tle = tle"""
       CBERS 4
       1 40336U 14079A   18166.15595376 -.00000014  00000-0  10174-4 0  9993
       2 40336  98.4141 237.7928 0001694  75.7582 284.3804 14.35485112184485
       """

@tles_nc_str(str)

Parse the set of TLEs in the string str at macro expansion time, returning a Vector{TLE}. The checksums of the lines are not verified, and the TLEs that cannot be parsed are skipped with a warning.

See also: @tles_str, read_tles

Example

julia> tles = tles_nc"""
       CBERS 4
       1 40336U 14079A   18166.15595376 -.00000014  00000-0  10174-4 0  9993
       2 40336  98.4141 237.7928 0001694  75.7582 284.3804 14.35485112184485
       SCD 1
       1 22490U 93009B   18165.62596833  .00000225  00000-0  11410-4 0  9991
       2 22490  24.9690 231.7852 0042844 200.7311 292.7198 14.44524498338066
       SCD 2
       1 25504U 98060A   18165.15074951  .00000201  00000-0  55356-5 0  9994
       2 25504  24.9961  80.1303 0017060 224.4822 286.6438 14.44043397 37312
       """

@tles_str(str)

Parse the set of TLEs in the string str at macro expansion time, returning a Vector{TLE}. The checksums of the lines are verified, and the TLEs that cannot be parsed are skipped with a warning.

See also: @tles_nc_str, read_tles

Example

julia> tles = tles"""
       CBERS 4
       1 40336U 14079A   18166.15595376 -.00000014  00000-0  10174-4 0  9993
       2 40336  98.4141 237.7928 0001694  75.7582 284.3804 14.35485112184485
       SCD 1
       1 22490U 93009B   18165.62596833  .00000225  00000-0  11410-4 0  9991
       2 22490  24.9690 231.7852 0042844 200.7311 292.7198 14.44524498338066
       SCD 2
       1 25504U 98060A   18165.15074951  .00000201  00000-0  55356-5 0  9994
       2 25504  24.9961  80.1303 0017060 224.4822 286.6438 14.44043397 37312
       """