Library

module SatelliteToolboxOrbitDataMessages

Create, fetch, parse, and write CCSDS Orbit Data Messages (ODM).

The package currently supports Orbit Mean-Elements Messages (OMM) in the XML and KVN formats, including Navigation Data Messages (NDM) that wrap multiple messages in XML, and fetching OMMs from the Celestrak and Space-Track services.

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.

const OMM = OrbitMeanElementsMessage

Short alias of OrbitMeanElementsMessage.

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.
• status::Union{Int, Nothing}: HTTP status code of the failed request, if available.

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

Create an OdmFetchError 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 OdmLoginError <: Exception

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

Fields

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

struct OdmParseError <: Exception

Exception thrown when an Orbit Data Message cannot be parsed because the input is malformed or violates the CCSDS 502.0-B-3 rules (e.g. a missing mandatory field or an unknown tag).

Fields

• msg::String: Description of the problem.
• keyword::Union{String, Nothing}: CCSDS keyword or XML tag related to the problem, if any.
• line::Union{Int, Nothing}: Line of the input where the problem was found, if known (KVN input only).

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

Create an OdmParseError with the description msg.

Keywords

• keyword::Union{AbstractString, Nothing}: CCSDS keyword or XML tag related to the problem, if any. (Default: nothing)
• line::Union{Int, Nothing}: Line of the input where the problem was found, if known. (Default: nothing)

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 lower-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., with the rows and columns ordered as (x, y, z, ẋ, ẏ, ż). Create it with the keyword constructor OmmCovarianceMatrix(; kwargs...), whose keywords are the fields below, or from a 6×6 matrix with OmmCovarianceMatrix(matrix; kwargs...). The full matrix is obtained with Matrix(cov) or SMatrix(cov).

Fields

• comments::Vector{String}: Comments for the covariance matrix section. (Default: String[])
• cov_ref_frame::Union{String, Nothing}: Reference frame of the covariance matrix. (Default: nothing)
• 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²].

OmmCovarianceMatrix(matrix::AbstractMatrix; kwargs...) -> OmmCovarianceMatrix

Create the covariance matrix section from the 6×6 matrix, whose rows and columns must be ordered as (x, y, z, ẋ, ẏ, ż). Only the lower triangle of matrix is read, since the section stores a symmetric matrix. An ArgumentError is thrown if matrix is not 6×6.

Keywords

• comments::Vector{String}: Comments for the covariance matrix section. (Default: String[])
• cov_ref_frame::Union{String, Nothing}: Reference frame of the covariance matrix. (Default: nothing)

OmmCovarianceMatrix(section::OmmCovarianceMatrix; kwargs...) -> OmmCovarianceMatrix

Create a copy of section, overriding the fields specified in kwargs....

struct OmmData

Data section of an Orbit Mean-Elements Message (OMM) as defined by the CCSDS 502.0-B-3 standard, containing the mean Keplerian elements and the optional spacecraft parameters, TLE-related parameters, covariance matrix, and user-defined parameters. Create it with the keyword constructor OmmData(; kwargs...), whose keywords are the fields below. The rules relating the fields (e.g. exactly one of semi_major_axis and mean_motion) are checked when the section is assembled into an OrbitMeanElementsMessage.

Fields

• 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.
• semi_major_axis::Union{Float64, Nothing}: Semi-major axis [km]. (Default: nothing)
• mean_motion::Union{Float64, Nothing}: Mean motion [rev/day]. (Default: nothing)
• eccentricity::Float64: Eccentricity.
• inclination::Float64: Inclination [deg].
• raan::Float64: Right ascension of the ascending node [deg].
• arg_of_pericenter::Float64: Argument of pericenter [deg].
• mean_anomaly::Float64: Mean anomaly [deg].
• 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/ER]. (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 AGOM [m²/kg]. (Default: nothing)
• covariance_matrix::Union{OmmCovarianceMatrix, Nothing}: Covariance matrix of the message. (Default: nothing)
• user_defined_parameters::Vector{Pair{String, String}}: User-defined parameters as a vector of key => value pairs. An empty vector means that the section is absent. (Default: Pair{String, String}[])

OmmData(section::OmmData; kwargs...) -> OmmData

Create a copy of section, overriding the fields specified in kwargs....

struct OmmHeader

Header section of an Orbit Mean-Elements Message (OMM) as defined by the CCSDS 502.0-B-3 standard. Create it with the keyword constructor OmmHeader(; kwargs...), whose keywords are the fields below.

Fields

• comments::Vector{String}: Comments for the header section. (Default: String[])
• classification::Union{String, Nothing}: Message classification. (Default: nothing)
• creation_date::Union{NanoDate, Nothing}: Message creation date. It can only be nothing for parsed messages whose input omits it, which cannot be written until a creation date is set. (Default: nothing)
• originator::String: Message originator.
• message_id::Union{String, Nothing}: Unique message identifier. (Default: nothing)

OmmHeader(section::OmmHeader; kwargs...) -> OmmHeader

Create a copy of section, overriding the fields specified in kwargs....

struct OmmMetadata

Metadata section of an Orbit Mean-Elements Message (OMM) as defined by the CCSDS 502.0-B-3 standard. Create it with the keyword constructor OmmMetadata(; kwargs...), whose keywords are the fields below.

Fields

• comments::Vector{String}: Comments for the metadata section. (Default: String[])
• object_name::String: Spacecraft name.
• object_id::String: International designator, usually in the format YYYY-NNNP.
• center_name::String: Origin of the reference frame.
• ref_frame::String: Reference frame of the mean elements.
• 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.
• mean_element_theory::String: Theory describing the mean elements, e.g. "SGP4".

OmmMetadata(section::OmmMetadata; kwargs...) -> OmmMetadata

Create a copy of section, overriding the fields specified in kwargs....

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 contains the three sections defined by the standard: a header, a metadata, and a data section. The individual fields can be accessed through these sections, for example omm.metadata.object_name or omm.data.epoch, or directly as properties of the message, for example omm.object_name or omm.epoch (see the extended help).

To create a message, use the flat keyword constructor OrbitMeanElementsMessage(; kwargs...), which assembles all the internal sections automatically, or build the sections with OmmHeader, OmmMetadata, and OmmData and pass them to OrbitMeanElementsMessage(header, metadata, data; version). Every constructor checks the rules relating the fields, throwing an ArgumentError if they are violated. The alias OMM can be used instead of the full name.

Fields

• version::VersionNumber: OMM format version (2.0 or 3.0).
• header::OmmHeader: Message header (creation date, originator, etc.).
• metadata::OmmMetadata: Message metadata (object identification, reference frame, etc.).
• data::OmmData: Mean elements data (mean Keplerian elements, TLE parameters, etc.).

Extended help

Properties

Every field of the header, metadata, and data sections is also available as a property of the message with the same name, so omm.epoch is equivalent to omm.data.epoch. The only exception is the comments field, which exists in every section and must be accessed through the section, e.g. omm.header.comments. The complete list is returned by propertynames(omm).

OrbitMeanElementsMessage(
    header::OmmHeader,
    metadata::OmmMetadata,
    data::OmmData;
    version::VersionNumber = v"3.0"
) -> OrbitMeanElementsMessage

Create an Orbit Mean-Elements Message (OMM) with version from its header, metadata, and data sections. An ArgumentError is thrown if version is not v"2.0" or v"3.0" or the data section violates the message rules (see the extended help of the keyword constructor).

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

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

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 with version 3.0 unless version is provided. The required keywords are the message creation date, the 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. An ArgumentError is thrown if the keyword combination violates the message rules (see the extended help). The sections can also be built individually and assembled with OrbitMeanElementsMessage(header, metadata, data; version).

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

• version::VersionNumber: OMM format version (v"2.0" or v"3.0"). The version-specific field rules are enforced by the parsers, and the writers always emit version 3.0. (Default: v"3.0")
• header_comments::Vector{String}: Comments for the header section. (Default: String[])
• classification::Union{String, Nothing}: Message classification. (Default: nothing)
• creation_date::Union{NanoDate, Nothing}: Message creation date (required). It can only be nothing for parsed messages whose input omits it (see parse_omm), which cannot be written until a creation date is set.
• 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/ER]. (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 AGOM [m²/kg]. (Default: nothing)
• covariance_matrix::Union{OmmCovarianceMatrix, Nothing}: Covariance matrix of the message. (Default: nothing)
• user_defined_parameters::Vector{Pair{String, String}}: User-defined parameters as a vector of key => value pairs. An empty vector means that the section is absent. (Default: Pair{String, String}[])

Extended help

Throws

• ArgumentError: If version is not v"2.0" or v"3.0".
• ArgumentError: If not exactly one of semi_major_axis and mean_motion is provided.
• ArgumentError: If the TLE-related parameters section is present (any of its keywords or comments is set) and not exactly one of bstar and bterm is provided, or mean_motion_dot is missing, or not exactly one of mean_motion_ddot and agom is provided.

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.

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

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

Keywords

• url::String: URL of the Celestrak 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.

Extended help

Throws

• OdmLoginError: If the login fails, e.g. due to invalid credentials or a network error.

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

Create an Orbit Mean-Elements Message (OMM) 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_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.

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

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)

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

Fetch Orbit Mean-Elements Messages (OMM) 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.

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, which is converted to a string and URL-encoded, keeping the characters used by the Space-Track operators (see the extended help for more details). (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, Integer}: 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)

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 the Orbit Data Messages (ODM) in the string str and return the parsed message(s).

The return value is always a Vector{OrbitDataMessage}. For XML input, the document can be a stand-alone message, yielding a single-element vector, or a Navigation Data Message (NDM) wrapping multiple messages. For KVN input, the messages are written sequentially, each one starting at its version keyword. Unsupported message types (OPM, OEM, OCM) are skipped with a warning; if no supported message remains, an empty vector is returned. If the root tag is not recognized or the input is malformed, an OdmParseError is thrown. See parse_omm for the accommodated deviations from the standard.

Keywords

• format::Symbol: The input format. If :auto, the format is inferred from the content. It can be :auto, :kvn, or :xml. (Default: :auto)

parse_omm(str::AbstractString; kwargs...) -> OrbitMeanElementsMessage

Parse an Orbit Mean-Elements Message (OMM) in the string str and return the parsed message.

If the XML is a Navigation Data Message (NDM), only the first OMM message is returned. An OdmParseError is thrown if the input does not contain an OMM message, is malformed, or violates the CCSDS 502.0-B-3 rules.

The parsers accommodate the deviations commonly found in real-world files: the XML tags and the OMM id attribute value are matched ignoring the case, empty XML elements are treated as absent fields, and a missing CREATION_DATE yields a message whose creation date is nothing, which cannot be written until a creation date is set.

Keywords

• format::Symbol: The input format. If :auto, the format is inferred from the content. It can be :auto, :kvn, or :xml. (Default: :auto)

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.

For XML input, the document can be a stand-alone message or a Navigation Data Message (NDM): only the OMM messages are returned, and other message types (OPM, OEM, OCM) are skipped with a warning. If the root tag is not recognized, an OdmParseError is thrown, as for any malformed input. For KVN input, each message must begin with its CCSDS_OMM_VERS keyword. If the input does not contain an OMM message, an empty vector is returned. See parse_omm for the accommodated deviations from the standard.

Keywords

• format::Symbol: The input format. If :auto, the format is inferred from the content. It can be :auto, :kvn, or :xml. (Default: :auto)

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

Read the Orbit Data Messages (ODM) from the provided file or io stream.

For more information, see parse_odm.

Keywords

• format::Symbol: The input format. If :auto, the format is inferred from the content. It can be :auto, :kvn, or :xml. (Default: :auto)

read_omm(file::AbstractString; kwargs...) -> OrbitMeanElementsMessage
read_omm(io::IO; kwargs...) -> OrbitMeanElementsMessage

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

If the input contains multiple messages, only the first OMM is returned. If it does not contain an OMM, an OdmParseError is thrown. For more information, see parse_omm.

Keywords

• format::Symbol: The input format. If :auto, the format is inferred from the content. It can be :auto, :kvn, or :xml. (Default: :auto)

read_omms(file::AbstractString; kwargs...) -> Vector{OrbitMeanElementsMessage}
read_omms(io::IO; kwargs...) -> Vector{OrbitMeanElementsMessage}

Read a set of Orbit Mean-Elements Messages (OMM) from the provided file or io stream.

If the input contains messages of other types, only the OMMs are returned. If it does not contain an OMM, an empty vector is returned. For more information, see parse_omms.

Keywords

• format::Symbol: The input format. If :auto, the format is inferred from the content. It can be :auto, :kvn, or :xml. (Default: :auto)

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

Write the given odm (or the set of messages in vodm) to the provided io stream. In the XML format, the messages are wrapped in a Navigation Data Message (NDM) document, whereas in the KVN format they are written sequentially, each one starting at its version keyword.

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

Write the given odm (or the set of messages in vodm) to the file at file, overwriting its contents.

Message types that cannot be written yet are skipped with a warning.

Keywords

• format::Symbol: The output format, which can be :xml or :kvn. The methods that write to a file also accept :auto, which infers the format from the file extension (case-insensitive): .kvn selects the KVN format, whereas any other extension selects the XML format. (Default: :xml when writing to an io stream, :auto when writing to a file)

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

Write the given omm to the provided io stream.

write_omm(io::IO, vomm::AbstractVector{OrbitMeanElementsMessage}; kwargs...) -> Nothing

Write the set of Orbit Mean-Elements Messages in the vector vomm to the provided io stream. In XML format, the messages are wrapped in a Navigation Data Message (NDM) document, whereas in KVN format they are written sequentially, delimited by their CCSDS_OMM_VERS keyword.

write_omm(file::AbstractString, omm::OrbitMeanElementsMessage; kwargs...) -> Nothing
write_omm(
    file::AbstractString,
    vomm::AbstractVector{OrbitMeanElementsMessage};
    kwargs...
) -> Nothing

Write the given omm (or the set of messages in vomm) to the file at file, overwriting its contents.

The written version is always 3.0, regardless of the version stored in the messages.

Keywords

• format::Symbol: The output format, which can be :xml or :kvn. The methods that write to a file also accept :auto, which infers the format from the file extension (case-insensitive): .kvn selects the KVN format, whereas any other extension selects the XML format. (Default: :xml when writing to an io stream, :auto when writing to a file)

abstract type AbstractOmmFetcher

Supertype of all Orbit Mean-Elements Message (OMM) fetchers.

Every supported service defines a concrete subtype (e.g. CelestrakOmmFetcher) together with methods for create_omm_fetcher and fetch_omms.

Matrix(cov::OmmCovarianceMatrix) -> Matrix{Float64}

Return the full, symmetric 6×6 covariance matrix of cov, with the rows and columns ordered as (x, y, z, ẋ, ẏ, ż).

SMatrix(cov::OmmCovarianceMatrix) -> SMatrix{6, 6, Float64, 36}

Return the full, symmetric 6×6 covariance matrix of cov as a static matrix, with the rows and columns ordered as (x, y, z, ẋ, ẏ, ż).