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)

## Public predicates

### `parse/2`

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])`

## Protected predicates

(none)

## Private predicates

(none)

## Operators

(none)

See also

tle_orbits, crs_projections_protocol