protocol

`tle_orbits_protocol`

Protocol for parsing Two-Line Element sets and performing approximate portable orbit propagation with near-earth and deep-space variants plus ground-track sampling.

Availability:

logtalk_load(tle_orbits(loader))

Author: Paulo Moura
Version: 1:1:0
Date: 2026-07-13

Compilation flags:

static

Dependencies:

(none)

Remarks:

(none)

Inherited public predicates:

(none)

Parses one or more TLE records from a source specification into canonical tle(...) terms. Supported source specifications are atom(Atom), chars(List), codes(List), stream(Stream), and file(Path).

Compilation flags:

static

Template:

parse(Source,TLEs)

Mode and number of proofs:

parse(++compound,--list(compound)) - one_or_error

Exceptions:

Source is a variable or contains a variable source argument:

instantiation_error

Source is neither a variable nor a valid source specification:

domain_error(tle_source,Source)

The parsed non-blank lines cannot be grouped into valid TLE records:

domain_error(tle_records,Lines)

`parse_lines/4`

Parses a single TLE record given an optional name atom or the atom none plus the two raw TLE lines.

Compilation flags:

static

Template:

parse_lines(Name,Line1,Line2,TLE)

Mode and number of proofs:

parse_lines(++nonvar,++atom,++atom,--compound) - one_or_error

Exceptions:

Name is a variable:

instantiation_error

Name is neither the atom none nor an atom name:

domain_error(tle_name,Name)

Line1 is a variable:

instantiation_error

Line1 is neither a variable nor an atom:

domain_error(tle_line,Line1)

Line2 is a variable:

instantiation_error

Line2 is neither a variable nor an atom:

domain_error(tle_line,Line2)

The given name and lines do not form a valid TLE record because of invalid syntax, checksum, field encoding, or orbital element ranges:

domain_error(tle_lines,[Name,Line1,Line2])

`propagate/3`

Propagates a parsed TLE using the default approximate model and returns a geographic(Latitude,Longitude,Height) coordinate. Supported time specifications are date_time(Year,Month,Day,Hours,Minutes,Seconds), julian_date(JulianDate), and offset_seconds(SecondsSinceEpoch).

Compilation flags:

static

Template:

propagate(TLE,Time,Coordinate)

Mode and number of proofs:

propagate(++compound,++nonvar,--compound) - one_or_error

Exceptions:

Time is not one of the supported time specifications with the required numeric components:

domain_error(tle_time,Time)

`propagate/4`

Propagates a parsed TLE using the default approximate model and returns coordinates in the requested frame. Supported frames are eci returning eci(X,Y,Z), ecef returning ecef(X,Y,Z), and wgs84_3d returning geographic(Latitude,Longitude,Height).

Compilation flags:

static

Template:

propagate(TLE,Time,Frame,Coordinate)

Mode and number of proofs:

propagate(++compound,++nonvar,++atom,--compound) - one_or_error

Exceptions:

Frame is not one of the supported reference frame identifiers:

domain_error(tle_reference_frame,Frame)

Time is not one of the supported time specifications with the required numeric components:

domain_error(tle_time,Time)

`propagate/5`

Propagates a parsed TLE using the requested propagation model and returns coordinates in the requested frame. Supported models are approximate for automatic near-earth versus deep-space dispatch, approximate_near_earth for the low-period approximate branch with J2 secular and short-period corrections plus low-order B* drag handling, approximate_deep_space for the dedicated deep-space approximate branch with resonance-aware long-period corrections, and two_body for the legacy Keplerian approximation.

Compilation flags:

static

Template:

propagate(TLE,Time,Frame,Model,Coordinate)

Mode and number of proofs:

propagate(++compound,++nonvar,++atom,++atom,--compound) - one_or_error

Exceptions:

Frame is not one of the supported reference frame identifiers:

domain_error(tle_reference_frame,Frame)

Model is not one of the supported propagation model identifiers:

domain_error(tle_propagation_model,Model)

Time is not one of the supported time specifications with the required numeric components:

domain_error(tle_time,Time)

`propagate_state/4`

Propagates a parsed TLE using the default approximate model and returns state(Position,Velocity) in the requested frame. Velocity is derived directly from the propagated orbital elements in ECI and analytically transformed to the requested frame. Supported frames are eci returning state(eci(X,Y,Z), eci(VX,VY,VZ)), ecef returning state(ecef(X,Y,Z), ecef(VX,VY,VZ)), and wgs84_3d returning state(geographic(Latitude,Longitude,Height), enu(East,North,Up)).

Compilation flags:

static

Template:

propagate_state(TLE,Time,Frame,State)

Mode and number of proofs:

propagate_state(++compound,++nonvar,++atom,--compound) - one_or_error

Exceptions:

Frame is not one of the supported reference frame identifiers:

domain_error(tle_reference_frame,Frame)

Time is not one of the supported time specifications with the required numeric components:

domain_error(tle_time,Time)

`propagate_state/5`

Propagates a parsed TLE using the requested propagation model and returns state(Position,Velocity) in the requested frame. Velocity is derived directly from the propagated orbital elements in ECI and analytically transformed to the requested frame. Supported models are approximate, approximate_near_earth, approximate_deep_space, and two_body.

Compilation flags:

static

Template:

propagate_state(TLE,Time,Frame,Model,State)

Mode and number of proofs:

propagate_state(++compound,++nonvar,++atom,++atom,--compound) - one_or_error

Exceptions:

Frame is not one of the supported reference frame identifiers:

domain_error(tle_reference_frame,Frame)

Model is not one of the supported propagation model identifiers:

domain_error(tle_propagation_model,Model)

Time is not one of the supported time specifications with the required numeric components:

domain_error(tle_time,Time)

`ground_track/5`

Samples the propagated sub-satellite ground track between two UTC date_time/6 instants separated by a positive step size in seconds using the default approximate model, returning sample(DateTime, geographic(Latitude,Longitude,Height)) terms.

Compilation flags:

static

Template:

ground_track(TLE,StartDateTime,EndDateTime,StepSeconds,Samples)

Mode and number of proofs:

ground_track(++compound,++compound,++compound,++number,--list(compound)) - one_or_error

Exceptions:

StartDateTime, EndDateTime, or StepSeconds do not define a valid ground-track sampling interval for the default model:

domain_error(tle_ground_track,[StartDateTime,EndDateTime,StepSeconds,approximate])

`ground_track/6`

Samples the propagated sub-satellite ground track between two UTC date_time/6 instants separated by a positive step size in seconds using the requested propagation model. Supported models are approximate, approximate_near_earth, approximate_deep_space, and two_body.

Compilation flags:

static

Template:

ground_track(TLE,StartDateTime,EndDateTime,StepSeconds,Model,Samples)

Mode and number of proofs:

ground_track(++compound,++compound,++compound,++number,++atom,--list(compound)) - one_or_error

Exceptions:

Model is not one of the supported propagation model identifiers:

domain_error(tle_propagation_model,Model)

StartDateTime, EndDateTime, or StepSeconds do not define a valid ground-track sampling interval for the requested model:

domain_error(tle_ground_track,[StartDateTime,EndDateTime,StepSeconds,Model])

`tle_orbits_protocol`

Public predicates 

`parse/2`

`parse_lines/4`

`propagate/3`

`propagate/4`

`propagate/5`

`propagate_state/4`

`propagate_state/5`

`ground_track/5`

`ground_track/6`

Protected predicates 

Private predicates 

Operators 

tle_orbits_protocol

`tle_orbits_protocol`