Library

struct CelestrakOmmFetcher <: AbstractOmmFetcher

Fetcher that retrieves Orbit Mean-Elements Messages (OMM) from the Celestrak service.

Create an instance with create_omm_fetcher(CelestrakOmmFetcher) and query the service with fetch_omms. Celestrak provides publicly available data and does not require authentication.

Fields

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

struct OdmFetchError <: Exception

Exception thrown when a request to an Orbit Data Message service fails.

Fields

• msg::String: Description of the request failure.
• 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 OdmLoginError <: Exception

Exception thrown when the authentication with an Orbit Data Message service fails.

Fields

• msg::String: Description of the login failure.

struct OmmCovarianceMatrix

Covariance matrix of an Orbit Mean-Elements Message (OMM) as defined by the CCSDS 502.0-B-3 standard.

The matrix is symmetric, so only the upper-triangular 21 elements are stored. The elements follow the CCSDS naming convention where CX_X is the (1,1) entry, CY_X is the (2,1) entry, etc.

Fields

• comments::Vector{String}: Comments for the covariance matrix section.
• cov_ref_frame::Union{String, Nothing}: Reference frame of the covariance matrix.
• cx_x::Float64: (1,1) element [km²].
• cy_x::Float64: (2,1) element [km²].
• cy_y::Float64: (2,2) element [km²].
• cz_x::Float64: (3,1) element [km²].
• cz_y::Float64: (3,2) element [km²].
• cz_z::Float64: (3,3) element [km²].
• cx_dot_x::Float64: (4,1) element [km²/s].
• cx_dot_y::Float64: (4,2) element [km²/s].
• cx_dot_z::Float64: (4,3) element [km²/s].
• cx_dot_x_dot::Float64: (4,4) element [km²/s²].
• cy_dot_x::Float64: (5,1) element [km²/s].
• cy_dot_y::Float64: (5,2) element [km²/s].
• cy_dot_z::Float64: (5,3) element [km²/s].
• cy_dot_x_dot::Float64: (5,4) element [km²/s²].
• cy_dot_y_dot::Float64: (5,5) element [km²/s²].
• cz_dot_x::Float64: (6,1) element [km²/s].
• cz_dot_y::Float64: (6,2) element [km²/s].
• cz_dot_z::Float64: (6,3) element [km²/s].
• cz_dot_x_dot::Float64: (6,4) element [km²/s²].
• cz_dot_y_dot::Float64: (6,5) element [km²/s²].
• cz_dot_z_dot::Float64: (6,6) element [km²/s²].

abstract type OrbitDataMessage

Supertype of all Orbit Data Messages (ODM) defined by the CCSDS 502.0-B-3 standard.

Every concrete message type supported by this package (for example, OrbitMeanElementsMessage) is a subtype of OrbitDataMessage. Functions that handle generic messages, such as parse_odm and write_odm, operate on this abstract type.

struct OrbitMeanElementsMessage <: OrbitDataMessage

Orbit Mean-Elements Message (OMM) as defined by the CCSDS 502.0-B-3 standard.

The structure follows the nested hierarchy of the standard: a header, and a body that contains a segment with the metadata and data sections. The individual fields can be accessed through this hierarchy, for example omm.body.segment.metadata.object_name or omm.body.segment.data.epoch.

To create a message, use the keyword constructor OrbitMeanElementsMessage(; kwargs...), which assembles all the internal sections automatically.

Fields

• version::VersionNumber: OMM format version (2.0 or 3.0).
• header::OmmHeader: Message header (creation date, originator, etc.).
• body::OmmBody: Message body containing the metadata and the mean elements data.

OrbitMeanElementsMessage(; kwargs...) -> OrbitMeanElementsMessage

Create an Orbit Mean-Elements Message (OMM) from the keyword arguments kwargs....

This constructor assembles the internal header, metadata, and data sections defined by the CCSDS 502.0-B-3 standard, returning a message compatible with version 3.0. The required keywords are the message originator, the object identification, the reference frame and time system, and the mean Keplerian elements. All angular quantities (inclination, raan, arg_of_pericenter, and mean_anomaly) are expressed in degrees.

The date keywords (creation_date, epoch, and ref_frame_epoch) must be provided as NanoDate objects so that the sub-second precision is preserved.

Keywords

• header_comments::Vector{String}: Comments for the header section. (Default: String[])

• classification::Union{String, Nothing}: Message classification. (Default: nothing)

• creation_date::NanoDate: Message creation date (required).

• originator::String: Message originator (required).

• message_id::Union{String, Nothing}: Unique message identifier. (Default: nothing)

• metadata_comments::Vector{String}: Comments for the metadata section. (Default: String[])

• object_name::String: Spacecraft name (required).

• object_id::String: International designator, usually in the format YYYY-NNNP (required).

• center_name::String: Origin of the reference frame (required).

• ref_frame::String: Reference frame of the mean elements (required).

• ref_frame_epoch::Union{NanoDate, Nothing}: Epoch of the reference frame, if it is not intrinsic to its definition. (Default: nothing)

• time_system::String: Time system used for the message (required).

• mean_element_theory::String: Theory describing the mean elements, e.g. "SGP4" (required).

• data_comments::Vector{String}: Comments for the data section. (Default: String[])

• mean_elements_comments::Vector{String}: Comments for the mean elements section. (Default: String[])

• epoch::NanoDate: Epoch of the mean Keplerian elements (required).

• semi_major_axis::Union{Float64, Nothing}: Semi-major axis [km]. Either this keyword or mean_motion must be provided. (Default: nothing)

• mean_motion::Union{Float64, Nothing}: Mean motion [rev/day]. Either this keyword or semi_major_axis must be provided. (Default: nothing)

• eccentricity::Float64: Eccentricity (required).

• inclination::Float64: Inclination [deg] (required).

• raan::Float64: Right ascension of the ascending node [deg] (required).

• arg_of_pericenter::Float64: Argument of pericenter [deg] (required).

• mean_anomaly::Float64: Mean anomaly [deg] (required).

• GM::Union{Float64, Nothing}: Gravitational coefficient [km³/s²]. (Default: nothing)

• spacecraft_parameters_comments::Vector{String}: Comments for the spacecraft parameters section. (Default: String[])

• mass::Union{Float64, Nothing}: Spacecraft mass [kg]. (Default: nothing)

• solar_rad_area::Union{Float64, Nothing}: Effective area for solar radiation pressure [m²]. (Default: nothing)

• solar_rad_coeff::Union{Float64, Nothing}: Solar radiation pressure coefficient. (Default: nothing)

• drag_area::Union{Float64, Nothing}: Effective area for atmospheric drag [m²]. (Default: nothing)

• drag_coeff::Union{Float64, Nothing}: Atmospheric drag coefficient. (Default: nothing)

• tle_parameters_comments::Vector{String}: Comments for the TLE-related parameters section. (Default: String[])

• ephemeris_type::Union{Int, Nothing}: Default ephemeris type associated with the TLE. (Default: nothing)

• classification_type::Union{Char, Nothing}: Classification type, e.g. 'U' for unclassified. (Default: nothing)

• norad_cat_id::Union{Int, Nothing}: NORAD catalog number. (Default: nothing)

• element_set_number::Union{Int, Nothing}: Element set number. (Default: nothing)

• rev_at_epoch::Union{Int, Nothing}: Revolution number at epoch. (Default: nothing)

• bstar::Union{Float64, Nothing}: SGP4 drag term (B*) [1/earth radii]. (Default: nothing)

• bterm::Union{Float64, Nothing}: Ballistic coefficient [m²/kg]. (Default: nothing)

• mean_motion_dot::Union{Float64, Nothing}: First time derivative of the mean motion [rev/day²]. (Default: nothing)

• mean_motion_ddot::Union{Float64, Nothing}: Second time derivative of the mean motion [rev/day³]. (Default: nothing)

• agom::Union{Float64, Nothing}: Solar radiation pressure coefficient [m²/kg]. (Default: nothing)

• user_defined_parameters::Union{Nothing, Vector{Pair{String, String}}}: User-defined parameters as a vector of key => value pairs. (Default: nothing)

  OrbitMeanElementsMessage( omm::OrbitMeanElementsMessage; kwargs... ) -> OrbitMeanElementsMessage

Create a copy of omm, overriding the fields specified in kwargs.... Any keyword accepted by the main constructor can be used; the remaining fields are copied from omm.

struct SpacetrackOmmFetcher <: AbstractOmmFetcher

Fetcher that retrieves Orbit Mean-Elements Messages (OMM) from the Space-Track service.

Create an instance with create_omm_fetcher(SpacetrackOmmFetcher) and query the service with fetch_omms. Space-Track requires a (free) registered account; the login cookie is cached locally and reused until it expires.

Fields

• username::String: Space-Track username used to authenticate the requests.
• cookiejar::HTTP.CookieJar: Cookie jar holding the authentication cookie for the session.

_add_omm_tags!(parent::XML.Node, omm::OrbitMeanElementsMessage) -> Nothing

Add the OMM tags from the given omm message to the parent XML node.

_empty_omm_spacecraft_parameters() -> NamedTuple

Return default values for an omitted OMM spacecraftParameters section.

_empty_omm_tle_parameters() -> NamedTuple

Return default values for an omitted OMM tleParameters section.

_field_name_width(fields::AbstractVector{NTuple{3, String}}) -> Int

Compute the maximum width of the field names in fields.

_format_value(value) -> String

Convert value to its display String. This function is the single formatting seam for field values, allowing consistent formatting across every message.

The default method uses string, which for AbstractFloat yields the shortest representation that round-trips exactly (e.g., 7134.084, 4.47e-6), avoiding any loss of precision in the orbital elements.

_is_odm_tag(tag::AbstractString) -> Bool

Return whether tag is an ODM message tag defined by the CCSDS 502.0-B-3 standard.

_odm_to_xml_element(odm::OrbitDataMessage) -> Union{Nothing, XML.Node}

Convert odm to an XML element suitable for embedding in an NDM document. Message types that cannot be written yet emit a warning and return nothing.

To add support for a new message type, define a method for the corresponding concrete type.

_omm_scalar_value(xml::Cursor) -> String

Read the text or CDATA value of the current OMM scalar element while advancing the cursor past that element. Non-value child nodes are ignored.

All text and CDATA chunks are concatenated and the surrounding whitespace is stripped, matching the whitespace-collapse behavior of the XML schema types used by the CCSDS 502.0-B-3 standard.

_omm_tag(node::Cursor, strict::Bool) -> Union{String, Nothing}

Return the canonical OMM tag for node, matching case-insensitively unless strict is true.

_omm_to_xml(omm::OrbitMeanElementsMessage, stand_alone::Val{true}) -> XML.Document

Convert the given omm to an XML Document assuming it is a stand-alone document. Hence, the XML declaration is included.

_omm_to_xml(omm::OrbitMeanElementsMessage, stand_alone::Val{false}) -> XML.Element

Convert the given omm to an XML Element assuming it is to be embedded within another XML document. Hence, the XML declaration is omitted.

The written version is always 3.0, regardless of the version stored in the omm. This matches the schema against which the output is validated.

_parse_message(::Val{tag}, xml::Cursor, strict::Bool) -> Union{Nothing, OrbitDataMessage}

Parse the ODM message with the root tag at the current position of the Cursor xml, dispatching on Val(tag). Message types that are not supported yet emit a warning and return nothing.

To add support for a new message type, define a method for the corresponding tag, e.g. _parse_message(::Val{:opm}, xml::XML.Cursor, strict::Bool).

_parse_ndm(xml::Cursor, strict::Bool) -> Vector{OrbitDataMessage}

Parse a Navigation Data Message (NDM) from a Cursor xml and return a vector of Orbit Data Messages (ODM).

_parse_ndm_date(str::AbstractString) -> NanoDate

Parse an NDM date/time string into a NanoDate.

The CCSDS 502.0-B-3 standard allows two formats for absolute time tags and epochs:

• YYYY-MM-DDThh:mm:ss[.d→d][Z] (calendar date)
• YYYY-DDDThh:mm:ss[.d→d][Z] (ordinal day-of-year)

NanoDate natively handles the calendar form (including the optional trailing Z), so this function only needs to convert the ordinal form before delegating to NanoDate.

_parse_omm(xml::Cursor, strict::Bool) -> OrbitMeanElementsMessage

Parse an Orbit Mean-Elements Message (OMM) from a Cursor xml representation.

_parse_omm_body(xml::Cursor, strict::Bool) -> OmmBody

Parse the body of an Orbit Mean-Elements Message (OMM) from a Cursor xml representation.

_parse_omm_covariance_matrix(xml::Cursor, strict::Bool) -> OmmCovarianceMatrix

Parse an OMM covarianceMatrix section at the cursor's current position.

_parse_omm_data(xml::Cursor, strict::Bool) -> OmmData

Parse the data of the segment body of an Orbit Mean-Elements Message (OMM) from a Cursor xml representation.

_parse_omm_header(xml::Cursor, strict::Bool) -> OmmHeader

Parse the header of an Orbit Mean-Elements Message (OMM) from a Cursor xml representation.

_parse_omm_mean_elements(xml::Cursor, strict::Bool) -> NamedTuple

Parse an OMM meanElements section at the cursor's current position.

_parse_omm_metadata(xml::Cursor, strict::Bool) -> OmmMetadata

Parse the metadata of the segment body of an Orbit Mean-Elements Message (OMM) from a Cursor xml representation.

_parse_omm_number(::Type{T}, v::AbstractString, field::AbstractString) where T <: Number -> T

Parse the string v as a number of type T, throwing an ArgumentError that names the OMM field if the value is not a valid number.

_parse_omm_segment(xml::Cursor, strict::Bool) -> OmmSegment

Parse a segment of the body of an Orbit Mean-Elements Message (OMM) from a Cursor xml representation.

_parse_omm_spacecraft_parameters(xml::Cursor, strict::Bool) -> NamedTuple

Parse an OMM spacecraftParameters section at the cursor's current position.

_parse_omm_tle_parameters(xml::Cursor, strict::Bool) -> NamedTuple

Parse an OMM tleParameters section at the cursor's current position.

_parse_omm_user_defined_parameters(
    xml::Cursor,
    strict::Bool
) -> Vector{Pair{String,String}}

Parse an OMM userDefinedParameters section at the cursor's current position.

_print_fields(io::IO, fields::AbstractVector{NTuple{3, String}}, rail::String) -> Nothing

Print to io the fields, each preceded by rail (the tree rails drawn before the field name). The field names are left-aligned to the widest name in fields.

_print_node(io::IO, name::String, rail::String, connector::String, face::Symbol) -> Nothing

Print to io a tree node opening with the given name styled with face, preceded by rail (the ancestor tree rails) and connector (e.g., "├─ ", "└─ ", or "" for a top-level heading).

_push_output!(vector::AbstractVector{NTuple{3, String}}, field::Tuple{String, Any, String}) -> Nothing

Push to vector the field if its value is not nothing. The field is a tuple of (name::String, value::Any, unit::String), where value is converted to a string using _format_value.

_register_faces() -> Nothing

Register the named StyledStrings faces used to render the orbit data messages. This function is idempotent: faces already registered are not overwritten.

The registered faces are:

• :satellitetoolbox_odm_title: Structure name (e.g., OrbitMeanElementsMessage:).
• :satellitetoolbox_odm_section: Top-level sections (Header and Body).
• :satellitetoolbox_odm_node: Tree nodes (Segment, Metadata, Data, and the data subsection titles).
• :satellitetoolbox_odm_tree: Tree rails and connectors.
• :satellitetoolbox_odm_field: Field names.
• :satellitetoolbox_odm_unit: Field units.

_render_field(field_name::String, field_value::String, unit::String, name_width::Int) -> String

Render a single field row <name> : <value> <unit>, left-aligning field_name to name_width. The unit is appended inline separated by a space, except for the degree unit "°", which hugs the value. The returned string has no trailing whitespace.

_spacetrack__cookie_expire_date(cookiejar::HTTP.CookieJar) -> Union{DateTime, Nothing}

Get the expiration date of the spacetrack cookie in the cookiejar. If the cookie is not found, it returns nothing.

_spacetrack__is_cookie_valid(cookiejar::Union{HTTP.CookieJar, Nothing}) -> Bool

Check if the spacetrack cookie in the cookiejar is valid. To load the cookiejar, use the function _spacetrack__load_cookiejar.

_spacetrack__load_cookiejar(username::String) -> Union{HTTP.CookieJar, Nothing}

Load the cookie jar for the given username from the scratch space. If the cookie file does not exist or could not be loaded, it returns nothing.

_spacetrack__login(username::String, password::Base.SecretBuffer) -> HTTP.CookieJar

Login to the Space-Track service using the provided username and password. The password is a Base.SecretBuffer; its plaintext is materialized only inside this function and shredded immediately after the request body is built. If the login is successful, it saves the cookies to the scratch space and returns the cookie jar. Otherwise, it throws an OdmLoginError.

_spacetrack__purge_cookiejar(username::String) -> Nothing

Purge the cookiejar file for the given username from the scratch space.

_spacetrack__save_cookiejar(cookiejar::HTTP.CookieJar, username::String) -> Nothing

Save the cookiejar to the scratch space for the given username.

_validate_writable_omm_header(omm::OrbitMeanElementsMessage) -> Nothing

Validate that the header of omm contains the fields required for OMM 3.0 output.

_xml_add_tag!(parent::XML.Node, tag::String, value::Any) -> Nothing

Add a child XML tag to parent with the given tag name and value.

_xml_render(value::T) -> String

Render the given value of type T as a string suitable for XML.

NanoDate values are rendered with nanosecond precision (yyyy-mm-ddTHH:MM:SS.sssssssss).

create_omm_fetcher(::Type{CelestrakOmmFetcher}; kwargs...) -> CelestrakOmmFetcher

Create an Orbit Mean-Elements Message (OMM) fetcher from Celestrak service.

Keywords

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

create_omm_fetcher(::Type{SpacetrackOmmFetcher}; kwargs...) -> SpacetrackOmmFetcher

Create an Orbit Mean-Elements Message (OMM) fetcher from the Space-Track service.

Keywords

• username::String: Space-Track username. If empty, the user will be prompted to input it. (Default: "")
• password::String: Space-Track password. If empty, the user will be prompted to input it if a valid cookie is not found. (Default: "")
• force_login::Bool: If true, the user will be prompted to input the password even if a valid cookie is found. (Default: false)

Returns

• SpacetrackOmmFetcher: The created fetcher. If the login fails, an OdmLoginError is thrown.

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

Create an Orbit Mean-Elements Message (OMM) fetcher of type T.

fetch_omms(fetcher::CelestrakOmmFetcher; kwargs...) -> Vector{OrbitMeanElementsMessage}

Fetch Orbit Mean-Elements Messages (OMM) from the Celestrak service using the query parameters in kwargs....

This function returns a Vector{OrbitMeanElementsMessage} with the fetched OMMs. If no matching OMM is found, an empty vector is returned. If an error prevents the request from succeeding, an OdmFetchError is thrown.

Keywords

• international_designator::Union{Nothing, AbstractString}: International designator of the satellite in the format YYYY-NNN or YYYY-NNNP. (Default: nothing)
• satellite_number::Union{Nothing, Integer}: NORAD catalog number of the satellite. (Default: nothing)
• satellite_name::Union{Nothing, AbstractString}: Name of the satellite. (Default: nothing)
• strict::Bool: Require schema-defined XML tag casing when parsing the fetched OMMs. For more information, see parse_omms. Celestrak currently emits empty required OMM 2.0 header values, hence the relaxed default. (Default: false)

Exactly one of international_designator, satellite_number, and satellite_name must be provided.

fetch_omms(fetcher::T; kwargs...) -> Vector{OrbitMeanElementsMessage}

Fetch Orbit Mean-Elements Messages (OMM) using fetcher.

The keywords kwargs... are used to customize the search. It depends on the fetcher type T.

fetch_omms(fetcher::SpacetrackOmmFetcher; kwargs...) -> Vector{OrbitMeanElementsMessage}

Fetch Orbit Mean-Elements Messages (OMM) from the Space-Track service using the query parameters in kwargs....

This function returns a Vector{OrbitMeanElementsMessage} with the fetched OMMs. If the login cookie expired, an OdmLoginError is thrown. If the request to the service fails, an OdmFetchError is thrown.

Keywords

• interval::Union{Nothing, Tuple{Union{Date, DateTime}, Union{Date, DateTime}}}: A tuple with the start and end date of the interval to fetch the OMMs. This interval is appended to the predicates using the EPOCH field. If nothing, no interval is used. Notice that if the space data is :gp and an interval is specified, the space data is automatically changed to :gp_history; if the space data is already :gp_history, no change occurs. (Default: nothing)
• order_by::Union{Nothing, Vector{Pair{String, Symbol}}}: A vector of Pair{String, Symbol} with the fields to order the results by. The first element of each Pair is the field name whereas the second is the order direction, which can be either :ascending or :descending. This field is appended to the predicates using the orderby field. If nothing, no ordering is used. (Default: nothing)
• predicates::Union{Nothing, Vector{Pair{String, Any}}}: A vector of Pair{String, Any} with the query predicates to filter the OMMs. The first element of each Pair is the field name whereas the second is the field value. See the extended help for more details. If the field value is of type HTML{String}, it is used as is. Otherwise, it is converted to a string and URL-encoded. (Default: nothing)
• query_limits::Union{Nothing, Int, UnitRange{Int}}: The maximum number of OMMs to fetch. If an Int is provided, it is used as the limit. If a UnitRange{Int} is provided, it is used as the start and end indices of the fetched data. If nothing, no limit is used. This field is appended to the predicates using the limit field. (Default: nothing)
• satellite_name::Union{Nothing, AbstractString}: The name of the satellite to fetch the OMMs. This field is appended to the predicates using the OBJECT_NAME field. If nothing, no satellite name is used. If both satellite_name and satellite_number are provided, satellite_number takes precedence. (Default: nothing)
• satellite_number::Union{Nothing, Number}: The NORAD catalog number of the satellite to fetch the OMMs. This field is appended to the predicates using the NORAD_CAT_ID field. If nothing, no satellite number is used. If both satellite_name and satellite_number are provided, satellite_number takes precedence. (Default: nothing)
• space_data::Symbol: The space data to fetch the OMMs from. It can be either :gp or :gp_history. If :gp, the latest OMM for each satellite is fetched. If :gp_history, all the OMMs that match the predicates are fetched. If an interval is specified and the space data is :gp, it is automatically changed to :gp_history. For more information, see the Space-Track API documentation. (Default: :gp)
• strict::Bool: Require schema-defined XML tag casing when parsing the fetched OMMs. For more information, see parse_omms. (Default: true)

Extended Help

Query Predicates

This section describes the query predicates that can be used to filter the OMMs. Those expressions can be passed using the predicates keyword argument. This description is a simplified version of the documentation that can be found at https://www.space-track.org/documentation#/api.

The following fields are available for querying the Space-Track database:

We can use the following REST operators to build the query predicates:

• >: Greater Than (alternate is %3E).
• <: Less Than (alternate is %3C).
• <>: Not Equal (alternate is %3C%3E).
• ,: Comma Delimited 'OR' (ex. 1,2,3).
• --: Inclusive Range (ex. 1--100 returns 1 and 100 and everything in between). Date ranges are expressed as YYYY-MM-DD%20HH:MM:SS--YYYY-MM-DD%20HH:MM:SS or YYYY-MM-DD--YYYY-MM-DD.
• null-val: Value for 'NULL', can only be used with Not Equal (<>) or by itself.
• ~~: "Like" or Wildcard search. You may put the ~~ before or after the text; wildcard is evaluated regardless of location of ~~ in the URL. For example, ~~OB will return 'OBJECT 1', 'GLOBALSTAR', 'PROBA 1', etc.
• ^: Wildcard after value with a minimum of two characters (alternate is %5E). The wildcard is evaluated after the text regardless of location of ^ in the URL. For example, ^OB will return 'OBJECT 1', 'OBJECT 2', etc. but not 'GLOBALSTAR'.
• now: Variable that contains the current system date and time. Add or subtract days (or fractions thereof) after 'now' to modify the date/time, e.g. now-7, now+14, now-6.5, now+2.3. Use <, >, and -- to get a range of dates; e.g. >now-7, now-14--now.

Hence, we can build complex queries like:

1. Return all OMMs where the satellite number is between 40,000 and 40,100 and the mean motion is lower than 14.9:

predicates = [
    "NORAD_CAT_ID" => "40000--40100",
    "MEAN_MOTION"  => "<14.9",
]

1. Return all OMMs with epoch in the last 7 days where the right ascension of the ascending node (RAAN) is between 140 and 141 degrees:

predicates = [
    "EPOCH"          => "now-7--now",
    "RA_OF_ASC_NODE" => "140--141",
]

1. Return the OMMs for the Starlink satellites that have decayed in the last 10 days:

predicates = [
    "OBJECT_NAME" => "^STARLINK"
    "EPOCH"       => "now-10--now"
    "DECAY_DATE"  => "<>null-val"
]

Examples

Create the OMM fetcher by logging in to Space-Track.

julia> f = create_omm_fetcher(SpacetrackOmmFetcher)
Space-Track username: username@email.com
Space-Track password:
[ Info: Successfully logged in to Space-Track.
SpacetrackOmmFetcher: username@email.com (Login expires in 5 hours)

Fetch all the OMMs for the SCD 1 satellite between June 19 and June 20, 2024.

julia> omm = fetch_omms(f, satellite_name="SCD 1", interval = (Date(2024, 6, 19), Date(2024, 6, 20)))
3-element Vector{OrbitMeanElementsMessage}:
 OMM: SCD 1 [1993-009B] (Epoch = 2024-06-19T07:28:48.714816)
 OMM: SCD 1 [1993-009B] (Epoch = 2024-06-19T20:30:29.736576)
 OMM: SCD 1 [1993-009B] (Epoch = 2024-06-19T22:16:28.479360)

Fetch the latest OMM for the Amazonia 1 satellite.

julia> omm = fetch_omms(f, satellite_name="Amazonia 1")
1-element Vector{OrbitMeanElementsMessage}:
 OMM: AMAZONIA 1 [2021-015A] (Epoch = 2025-09-09T04:34:22.789920)

parse_odm(str::AbstractString; kwargs...) -> Vector{OrbitDataMessage}

Parse an Orbit Data Message (ODM) from the string str, which must contain a complete XML document, and return the parsed message(s).

parse_odm(xml::Cursor; kwargs...) -> Vector{OrbitDataMessage}

Parse an Orbit Data Message (ODM) from the Cursor xml and return the parsed message(s).

The return value is always a Vector{OrbitDataMessage}: a single-element vector for a stand-alone message, or a multi-element vector for a Navigation Data Message (NDM) wrapping multiple messages. Unsupported message types (OPM, OEM, OCM) are skipped with a warning, returning an empty vector. If the root tag is not recognized, an ArgumentError is thrown.

Keywords

• strict::Bool: Require schema-defined XML tag casing. If false, match tags and the OMM id attribute value case-insensitively. (Default: true)

parse_omm(str::AbstractString; kwargs...) -> Union{Nothing, OrbitMeanElementsMessage}

Parse an Orbit Mean-Elements Message (OMM) in the string str and return the parsed message. The input format must be XML.

parse_omm(xml::Cursor; kwargs...) -> Union{Nothing, OrbitMeanElementsMessage}

Parse an Orbit Mean-Elements Message (OMM) from a Cursor xml and return the parsed message.

If the XML is a Navigation Data Message (NDM), only the first OMM message is returned. If the file does not contain an OMM message, nothing is returned.

Keywords

• strict::Bool: Require schema-defined XML tag casing. If false, match tags and the OMM id attribute value case-insensitively. (Default: true)

parse_omms(str::AbstractString; kwargs...) -> Vector{OrbitMeanElementsMessage}

Parse a set of Orbit Mean-Elements Messages (OMM) in the string str and return the parsed messages. The input format must be XML.

parse_omms(xml::Cursor; kwargs...) -> Vector{OrbitMeanElementsMessage}

Parse a set of Orbit Mean-Elements Messages (OMM) from a Cursor xml and return the parsed messages.

If the XML is a Navigation Data Message (NDM), only the OMM messages are returned; other message types (OPM, OEM, OCM) are skipped with a warning. If the document does not contain an OMM message, an empty vector is returned. If the root tag is not recognized, an ArgumentError is thrown.

Keywords

• strict::Bool: Require schema-defined XML tag casing. If false, match tags and the OMM id attribute value case-insensitively. (Default: true)

read_odm(file::AbstractString; kwargs...) -> Vector{OrbitDataMessage}

Read an Orbit Data Message (ODM) from the provided file.

read_odm(io::IO; kwargs...) -> Vector{OrbitDataMessage}

Read an Orbit Data Message (ODM) from the provided io stream.

Keywords

• strict::Bool: Require schema-defined XML tag casing. (Default: true)

read_omm(file::AbstractString; kwargs...) -> Union{Nothing, OrbitMeanElementsMessage}

Read an Orbit Mean-Elements Message (OMM) from the provided file.

read_omm(io::IO; kwargs...) -> Union{Nothing, OrbitMeanElementsMessage}

Read an Orbit Mean-Elements Message (OMM) from the provided io stream.

Keywords

• strict::Bool: Require schema-defined XML tag casing. (Default: true)

write_odm(io::IO, odm::OrbitDataMessage) -> Nothing

Write the given odm to the provided io stream in XML format.

write_odm(io::IO, vodm::AbstractVector{T}) where T<:OrbitDataMessage -> Nothing

Write the set of Orbit Data Messages in the vector vodm to the provided io stream in XML format.

write_odm(file::AbstractString, odm::OrbitDataMessage) -> Nothing

Write the given odm to the file at file in XML format, overwriting its contents.

write_odm(file::AbstractString, vodm::AbstractVector{T}) where T<:OrbitDataMessage -> Nothing

Write the set of Orbit Data Messages in the vector vodm to the file at file in XML format, overwriting its contents.

write_omm(io::IO, omm::OrbitMeanElementsMessage) -> Nothing

Write the given omm to the provided io stream in XML format.

write_omm(file::AbstractString, omm::OrbitMeanElementsMessage) -> Nothing

Write the given omm to the file at file in XML format, overwriting its contents.

module ODM

Namespace with accessor functions for the fields of Orbit Data Messages (ODM).

The accessors flatten the nested CCSDS hierarchy so that the most common fields can be obtained without navigating the message structure, e.g. ODM.epoch(omm) instead of omm.body.segment.data.epoch. The functions live in this module to avoid polluting the namespace with the field names; access them qualified, or opt in with using SatelliteToolboxOrbitDataMessages.ODM.

ODM.GM(omm::OrbitMeanElementsMessage) -> Union{Float64, Nothing}

Return the gravitational coefficient [km³/s²] of the Orbit Mean-Elements Message omm.

ODM.agom(omm::OrbitMeanElementsMessage) -> Union{Float64, Nothing}

Return the solar radiation pressure coefficient AGOM [m²/kg] of the Orbit Mean-Elements Message omm.

ODM.arg_of_pericenter(omm::OrbitMeanElementsMessage) -> Float64

Return the argument of pericenter [deg] of the Orbit Mean-Elements Message omm.

ODM.bstar(omm::OrbitMeanElementsMessage) -> Union{Float64, Nothing}

Return the SGP4 drag term B* [1/earth radii] of the Orbit Mean-Elements Message omm.

ODM.bterm(omm::OrbitMeanElementsMessage) -> Union{Float64, Nothing}

Return the ballistic coefficient [m²/kg] of the Orbit Mean-Elements Message omm.

ODM.center_name(omm::OrbitMeanElementsMessage) -> String

Return the origin of the reference frame of the Orbit Mean-Elements Message omm.

ODM.classification(omm::OrbitMeanElementsMessage) -> Union{String, Nothing}

Return the classification of the Orbit Mean-Elements Message omm.

ODM.classification_type(omm::OrbitMeanElementsMessage) -> Union{Char, Nothing}

Return the classification type of the Orbit Mean-Elements Message omm.

ODM.covariance_matrix(omm::OrbitMeanElementsMessage) -> Union{OmmCovarianceMatrix, Nothing}

Return the covariance matrix of the Orbit Mean-Elements Message omm.

ODM.creation_date(omm::OrbitMeanElementsMessage) -> Union{NanoDate, Nothing}

Return the creation date of the Orbit Mean-Elements Message omm.

ODM.data_comments(omm::OrbitMeanElementsMessage) -> Vector{String}

Return the comments of the data section of the Orbit Mean-Elements Message omm.

ODM.drag_area(omm::OrbitMeanElementsMessage) -> Union{Float64, Nothing}

Return the effective area for atmospheric drag [m²] of the Orbit Mean-Elements Message omm.

ODM.drag_coeff(omm::OrbitMeanElementsMessage) -> Union{Float64, Nothing}

Return the atmospheric drag coefficient of the Orbit Mean-Elements Message omm.

ODM.eccentricity(omm::OrbitMeanElementsMessage) -> Float64

Return the eccentricity of the Orbit Mean-Elements Message omm.

ODM.element_set_number(omm::OrbitMeanElementsMessage) -> Union{Int, Nothing}

Return the element set number of the Orbit Mean-Elements Message omm.

ODM.ephemeris_type(omm::OrbitMeanElementsMessage) -> Union{Int, Nothing}

Return the default ephemeris type associated with the TLE of the Orbit Mean-Elements Message omm.

ODM.epoch(omm::OrbitMeanElementsMessage) -> NanoDate

Return the epoch of the mean Keplerian elements of the Orbit Mean-Elements Message omm.

ODM.header_comments(omm::OrbitMeanElementsMessage) -> Vector{String}

Return the comments of the header section of the Orbit Mean-Elements Message omm.

ODM.inclination(omm::OrbitMeanElementsMessage) -> Float64

Return the inclination [deg] of the Orbit Mean-Elements Message omm.

ODM.mass(omm::OrbitMeanElementsMessage) -> Union{Float64, Nothing}

Return the spacecraft mass [kg] of the Orbit Mean-Elements Message omm.

ODM.mean_anomaly(omm::OrbitMeanElementsMessage) -> Float64

Return the mean anomaly [deg] of the Orbit Mean-Elements Message omm.

ODM.mean_element_theory(omm::OrbitMeanElementsMessage) -> String

Return the theory describing the mean elements of the Orbit Mean-Elements Message omm.

ODM.mean_elements_comments(omm::OrbitMeanElementsMessage) -> Vector{String}

Return the comments of the mean elements section of the Orbit Mean-Elements Message omm.

ODM.mean_motion(omm::OrbitMeanElementsMessage) -> Union{Float64, Nothing}

Return the mean motion [rev/day] of the Orbit Mean-Elements Message omm.

ODM.mean_motion_ddot(omm::OrbitMeanElementsMessage) -> Union{Float64, Nothing}

Return the second time derivative of the mean motion [rev/day³] of the Orbit Mean-Elements Message omm.

ODM.mean_motion_dot(omm::OrbitMeanElementsMessage) -> Union{Float64, Nothing}

Return the first time derivative of the mean motion [rev/day²] of the Orbit Mean-Elements Message omm.

ODM.message_id(omm::OrbitMeanElementsMessage) -> Union{String, Nothing}

Return the message identifier of the Orbit Mean-Elements Message omm.

ODM.metadata_comments(omm::OrbitMeanElementsMessage) -> Vector{String}

Return the comments of the metadata section of the Orbit Mean-Elements Message omm.

ODM.norad_cat_id(omm::OrbitMeanElementsMessage) -> Union{Int, Nothing}

Return the NORAD catalog number of the Orbit Mean-Elements Message omm.

ODM.object_id(omm::OrbitMeanElementsMessage) -> String

Return the international designator of the Orbit Mean-Elements Message omm.

ODM.object_name(omm::OrbitMeanElementsMessage) -> String

Return the spacecraft name of the Orbit Mean-Elements Message omm.

ODM.originator(omm::OrbitMeanElementsMessage) -> String

Return the originator of the Orbit Mean-Elements Message omm.

ODM.raan(omm::OrbitMeanElementsMessage) -> Float64

Return the right ascension of the ascending node [deg] of the Orbit Mean-Elements Message omm.

ODM.ref_frame(omm::OrbitMeanElementsMessage) -> String

Return the reference frame of the mean elements of the Orbit Mean-Elements Message omm.

ODM.ref_frame_epoch(omm::OrbitMeanElementsMessage) -> Union{NanoDate, Nothing}

Return the epoch of the reference frame of the Orbit Mean-Elements Message omm.

ODM.rev_at_epoch(omm::OrbitMeanElementsMessage) -> Union{Int, Nothing}

Return the revolution number at epoch of the Orbit Mean-Elements Message omm.

ODM.semi_major_axis(omm::OrbitMeanElementsMessage) -> Union{Float64, Nothing}

Return the semi-major axis [km] of the Orbit Mean-Elements Message omm.

ODM.solar_rad_area(omm::OrbitMeanElementsMessage) -> Union{Float64, Nothing}

Return the effective area for solar radiation pressure [m²] of the Orbit Mean-Elements Message omm.

ODM.solar_rad_coeff(omm::OrbitMeanElementsMessage) -> Union{Float64, Nothing}

Return the solar radiation pressure coefficient of the Orbit Mean-Elements Message omm.

ODM.spacecraft_parameters_comments(omm::OrbitMeanElementsMessage) -> Vector{String}

Return the comments of the spacecraft parameters section of the Orbit Mean-Elements Message omm.

ODM.time_system(omm::OrbitMeanElementsMessage) -> String

Return the time system of the Orbit Mean-Elements Message omm.

ODM.tle_parameters_comments(omm::OrbitMeanElementsMessage) -> Vector{String}

Return the comments of the TLE-related parameters section of the Orbit Mean-Elements Message omm.

ODM.user_defined_parameters(omm::OrbitMeanElementsMessage) -> Union{Nothing, Vector{Pair{String, String}}}

Return the user-defined parameters of the Orbit Mean-Elements Message omm.