.. index:: single: tle_orbits_protocol
.. _tle_orbits_protocol/0:

.. rst-class:: right

**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)

.. contents::
   :local:
   :backlinks: top

Public predicates
-----------------

.. index:: parse/2
.. _tle_orbits_protocol/0::parse/2:

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


------------

.. index:: parse_lines/4
.. _tle_orbits_protocol/0::parse_lines/4:

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


------------

.. index:: propagate/3
.. _tle_orbits_protocol/0::propagate/3:

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


------------

.. index:: propagate/4
.. _tle_orbits_protocol/0::propagate/4:

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


------------

.. index:: propagate/5
.. _tle_orbits_protocol/0::propagate/5:

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


------------

.. index:: propagate_state/4
.. _tle_orbits_protocol/0::propagate_state/4:

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


------------

.. index:: propagate_state/5
.. _tle_orbits_protocol/0::propagate_state/5:

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


------------

.. index:: ground_track/5
.. _tle_orbits_protocol/0::ground_track/5:

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


------------

.. index:: ground_track/6
.. _tle_orbits_protocol/0::ground_track/6:

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

.. seealso::

   :ref:`tle_orbits <tle_orbits/0>`, :ref:`crs_projections_protocol <crs_projections_protocol/0>`

