Earth Observation Mission CFI Software
ORBIT SOFTWARE USER MANUAL

Code	EO-MA-DMS-GS-014
Issue	4.26
Date	31/10/23

	Name	Function	Signature
Prepared by:	EOCFI Team	Project Engineers
Checked by:	Inês Estrela	Project Manager
Approved by:	Antonio Gutierrez	Division Head

---

DOCUMENT INFORMATION

Contract Data		Classification
Contract Number:	4000102614/1O/NL/FF/ef	Internal
		Public
Contract Issuer:	ESA / ESTEC	Industry	X
		Confidential

External Distribution
Name	Organization	Copies

Electronic handling
Document generator:	Doxygen 1.7.1
Electronic file name:	eo-ma-dms-gs-014-10

Document Status Log

Issue	Change Description	Date	Approval
1.0	These libraries corresponds to version 4.0 of C libraries.	27/03/09
4.1	These libraries corresponds to version 4.1 of C libraries.	07/05/10
4.2	These libraries corresponds to version 4.2 of C libraries.	31/01/11
4.3	These libraries corresponds to version 4.3 of C libraries.	06/02/12
4.4	These libraries corresponds to version 4.4 of C libraries.	05/07/12
4.5	These libraries corresponds to version 4.5 of C libraries.	01/03/13
4.6	These libraries corresponds to version 4.6 of C libraries.	03/10/13
4.7	These libraries corresponds to version 4.7 of C libraries.	28/03/14
4.8	These libraries corresponds to version 4.8 of C libraries.	29/10/14
4.9	These libraries corresponds to version 4.9 of C libraries.	23/04/15
4.10	These libraries corresponds to version 4.10 of C libraries.	29/10/15
4.11	These libraries corresponds to version 4.11 of C libraries.	15/04/16
4.12	These libraries corresponds to version 4.12 of C libraries.	03/11/16
4.13	These libraries corresponds to version 4.13 of C libraries.	05/04/17
4.14	These libraries corresponds to version 4.14 of C libraries.	16/11/17
4.15	These libraries corresponds to version 4.15 of C libraries.	20/04/18
4.16	These libraries corresponds to version 4.16 of C libraries.	09/11/18
4.17	These libraries corresponds to version 4.17 of C libraries.	10/05/19
4.18	These libraries corresponds to version 4.18 of C libraries.	08/11/19
4.19	These libraries corresponds to version 4.19 of C libraries.	29/05/20
4.20	These libraries corresponds to version 4.20 of C libraries.	30/11/20
4.21	These libraries corresponds to version 4.21 of C libraries.	23/06/21
4.22	These libraries corresponds to version 4.22 of C libraries.	22/12/21
4.23	These libraries corresponds to version 4.23 of C libraries.	23/06/22
4.24	These libraries corresponds to version 4.24 of C libraries.	29/11/22
4.25	These libraries corresponds to version 4.25 of C libraries.	10/05/23
4.26	These libraries corresponds to version 4.26 of C libraries.	31/10/23

---

ACRONYMS, NOMENCLATURE AND TERMINOLOGY

Acronyms

ANX	Ascending Node Crossing
AOCS	Attitude and Orbit Control Subsystem
CFI	Customer Furnished Item
EF	Earth Fixed reference frame
ESA	European Space Agency
ESTEC	European Space Technology and Research Centre
FOS	Flight Operations Segment
GS	Ground Station
OBT	On-board Binary Time
OEF	Orbit Event File
OSF	Orbit Scenario File
OSV	Orbit State Vector
POF	Predicted Orbit File
ROF	Restituted Orbit File
SSP	Sub-Satellite Point
SRAR	Satellite Relative Actual Reference
SUM	Software User Manual
TLE	Two Line Elements
TOD	True of Date reference frame
UTC	Coordinated Universal Time
UT1	Universal Time UT1
WGS[84	World Geodetic System 1984

Nomenclature

CFI	A group of CFI functions, and related software and documentation. that will be distributed by ESA to the users as an independent unit
CFI function	A single function within a CFI that can be called by the user
Library	A software library containing all the CFI functions included within a CFI plus the supporting functions used by those CFI functions (transparently to the user)

Notes in Terminology

In order to keep compatibility with legacy CFI libraries, the Earth Observation Mission CFI Software makes use of terms that are linked with missions already or soon in the operational phase like the Earth Explorers. This may be reflected in the rest of the document when examples of Mission CFI Software usage are proposed or description of Mission Files is given.

---

APPLICABLE AND REFERENCE DOCUMENTS

Applicable Documents

[GEN_SUM]

Earth Observation Mission CFI Software. General Software User Manual. EO-MA-DMS-GS-017. Issue 4.26 31/10/23

Reference Documents

[MCD]	Earth Observation Mission CFI Software. Conventions Document. EO-MA-DMS-GS-0001. Issue 4.26 31/10/23.
[MSC]	Earth Observation Mission CFI Software. Mission Specific Customizations. EO-MA-DMS-GS-0018. Issue 4.26 31/10/23.
[EE_COMMON_SUM]	Earth Observation Mission CFI Software. EECommon Software User Manual. EO-MA-DMS-GS-010. Issue 4.26 31/10/23.
[F_H_SUM]	Earth Observation Mission CFI Software. FileHandling Software User Manual. EO-MA-DMS-GS-011. Issue 4.26 31/10/23.
[D_H_SUM]	Earth Observation Mission CFI Software. DataHandling Software User Manual. EO-MA-DMS-GS-012. Issue 4.26 31/10/23.
[LIB_SUM]	Earth Observation Mission CFI Software. Lib Software User Manual. EO-MA-DMS-GS-013 Issue 4.26 31/10/23.
[FORMATS]	Earth Explorer File Format Guidelines. CS-TN-ESA-GS-0148.

---

INTRODUCTION

Classes Overview

The following CFI classes are included:

• ANXTime: This class contains a time instant given as an absolute orbit number plus the time elapsed since the ANX
• OrbitFunc: Class grouping several static functions
• OrbitId: Class that stores the orbit data
• RelANXTime: This class contains a time instant given as a relative orbit number plus the time elapsed since the ANX
• RelTimeSegment: This class contains a time interval given by a start RelANXTime and a stop RelANXTime
• TimeSegment: This class contains a time interval given by a start ANXTime and a stop ANXTime

and the following auxiliary classes (defined in OrbitData.h):

• ANXExtra: ANX extra information
• ValidityTime: Validity time
• OrbitInfo: Information of orbits
• StateVectorInfo: Information of state vector
• StateVectorExtraInfo: Extra information of state vector
• AnxInfo: Ascending node information
• RefOrbitInfo: Reference orbit information
• OsfRecords: Orbital changes records
• OrbitalInfo: Orbital information

Among these classes there are:

• CFI classes with methods allowing accurate computation of orbit state vectors, either at ascending node or (by propagation) at any point in the orbit of any Earth Observation satellite. The orbit propagation may be performed based on different propagation models. The initial set of models supported are:
  • Mean Keplerian model
  • TLE model
  • Numerical model
  • Spot model
  It includes an interpolator and orbit propagators.
• CFI classes with methods required to compute the orbit scenario file, used for Earth Observation mission planning purposes, and several orbit files useful for testing purposes (Predicted Orbit File, Restituted Orbit File, DORIS Navigator Files).

The following sections summarize the set of methods in classes of this library:

Orbit Initialisation

Before doing any orbit calculation, the orbit should be initialized using the corresponding constructor of OrbitId class or the corresponding init methods. The possibilities are:

• Generate a cartesian state vector around the true ascending node crossings as a function of the date (processing time), the longitude of the ascending node, the satellite Repeat Cycle Length, the mean local solar time and either the drift in mean local solar time or the inclination. For the Spot model, the routine generates the Spot elements.
• Initializes the orbit using as input a cartesian orbit state vector. The "precise" method allows the introduction of data to propagate an state vector with a numeric propagator.
• Initializes the orbit using a set of files containing the orbital information (state vectors, orbital geometry or TLE data). The "precise" function allows the introduction of data to propagate an state vector with a numeric propagator. The following input file types are accepted:
  • Flight Dynamics predicted ascending node state vectors
  • DORIS Navigator Data
  • FOS Restituted Orbit Files
  • DORIS Preliminary Orbit
  • DORIS Precise Orbit
  • Ascending node state vectors from the Orbit Scenario File
  • State vectors from Spot orbit files
  • TLE files (not for precise propagator)

In all cases an object of the type OrbitId is created. This variable keeps internally the orbit information that will be used for further calculations. That orbit information can be retrieved by calling the following CFI functions:

OrbitId method	Orbit ID data	Condition to get the data
status	Orbit ID initialisation status	Always
satId	Satellite ID	The Orbit ID is initialised
mode	Mode used for the Orbit ID initialisation	The Orbit ID is initialised
getOsv	OSV stored in the Orbit ID	The Orbit ID has bee initialised with state vectors
getAnx	ANX data stored in the Orbit ID	The Orbit ID has bee initialised with state vectors that are not located at the ANX (Restituted orbit files, DORIS Navigator files...)
getOsf	Orbital Geometry data stored in the Orbit ID	The Orbit ID has been initialised with orbit geometry data
getValTime	Validity time interval where the Orbit ID can be used except for OrbitId::osvCompute and OrbitId::osvComputeExtra	The Orbit ID is initialised.
getPrecisePropagConfig	Configuration for the precise propagator	The Orbit ID has been initialised with numerical propagation

Finally, note that it is possible to create a copy of Orbit ID with xo_orbit_id_clone .

State Vector Computation (Propagation/Interpolation)

The software provides a set of methods to compute orbit state vectors at a given time:

• OrbitId::osvCompute: This software computes the state vector at the requested time. The method used to compute that vector is transparent for the user and depends on the data type used for the orbit initialisation. Propagation is performed when the OrbitId object is initialised with:
  • One Orbit State Vector
  • Orbit Geometry
  • Orbit Scenario File
  • Predicted orbit file (plus an optional DORIS Navigator file)
  • Orbit Event Files TLE files
  Interpolation is used in these other cases:
  • DORIS Navigator Data
  • FOS Restituted Orbit Files
  • DORIS Preliminary Orbit
  • DORIS Precise Orbit

Ancillary Results Computation

• OrbitId::osvComputeExtra: This software returns ancillary results, i.e. mean and osculating Keplerian orbit state vectors, satellite osculating true latitude, latitude rate and latitude rate-rate, Sun zenith angle and many more.

Time/Orbit Transformation

• ANXTime::timeToOrbit: This software calculates the absolute orbit, number of seconds and number of microseconds since ascending node that corresponds to a given time in processing format.
• ANXTime::orbitToTime: This software calculates the time, in processing format, that corresponds to a given absolute orbit, number of seconds and number of microseconds since ascending node.

Orbit Information Parameters

• OrbitId::getOrbitNumbersFromAbs: This software calculates the relative orbit, the phase number giving as input an absolute orbit number.
• OrbitId::getOrbitNumbersFromRel: This software calculates the absolute orbit number giving as input a relative orbit number and its cycle number.
• OrbitId::getOrbitNumbersFromPhase: This software calculates the absolute orbit number, the relative orbit, the phase number giving as input a phase number.
• OrbitId::getOrbitInfo: This software calculates orbit related parameters providing as input the absolute orbit number.

File Generation

• OrbitFunc::genOsf: generates the orbit scenario file with user provided inputs.
• OrbitFunc::genOsfAppendOrbitChange: adds an orbit change to a previously generated OSF.
• OrbitFunc::genOsfChangeRepeatCycle: adds an orbit change for a given target orbit to an existing OSF.
• OrbitFunc::genOsfAddDriftCycle: adds an orbit change for a requested orbit with a particular ascending node longitude and an orbit for the manoeuvre.
• OrbitFunc::genPof: generates a Predicted Orbit File from several different reference input files.
• OrbitFunc::genRof and OrbitFunc::genRofPrototype: generates a Restituted Orbit File from several different reference input files.
• OrbitFunc::genOef generates an orbit event file from an orbit scenario file and a predicted orbit file.
• OrbitFunc::genDnf: generates a DORIS Navigator File from several different reference input files.
• OrbitFunc::genTle: generates a TLE file from a Predicted Orbit file.

Check Orbit files

• OrbitFunc::checkOsf: checks the continuity between the last orbit of an orbital change and the next orbit in an orbit scenario file.
• OrbitFunc::checkOef: checks the consistency between the list of the orbital changes and the list of orbit state vectors in an orbit event file.

State Vector Computation Calling Sequence (Propagation/Interpolation)

A complete propagation sequence consists of:

• A call to any of the initialization routines for OrbitId, OrbitId::init, to generate the internal data necessary for whatever calculation involving orbits.
• An optional call to OrbitId::osvComputeExtra to calculate any desired ancillary result related to the initializing state vector.
• A call to the OrbitId::osvCompute function to compute the orbit state vector at a requested time.
• To obtain some ancillary results associated to the computed OSV, the user might call the OrbitId::osvComputeExtra function.
• At the end of a sequence the memory is freed when the OrbitId object is destroyed.

The possible propagation sequences of calls allowing to produce an orbit state vector are shown in next figure:

Time/Orbit Transformation and Orbit Information Parameters Calling Sequence

A complete time/orbit transformation and orbit information parameters sequence consists of:

• A call to any of the initialization routines for OrbitId, OrbitId::init, to generate the internal data necessary for whatever calculation involving orbits.
• A call to a time/orbit transformation or an orbit information parameters routine.
• At the end of a sequence the memory is freed when the OrbitId object is destroyed.

The possible time/orbit transformation and orbit information parameters sequences of calls allowing to produce an orbit state vector are shown in previous figure. For further infomation, please refer also to:

• [MCD] for a detailed description of the time references and formats, reference frames, parameters and models used in this document.
• [GEN_SUM] for a complete overview of the CFI, and in particular the detailed description of the Id concept and the error handling functions.

File Generation Calling Sequence

The calling sequence for the file generators consists of:

• Initialization of TimeCorrelation and ModelId object
• One call to the generation method providing the input parameters. For OrbitFunc::genPof, OrbitFunc::genRof, OrbitFunc::genOef and OrbitFunc::genDnf a reference orbit file has to be provided as well.

The following figure shows an schema of the calling sequence:

---

LIBRARY INSTALLATION

For a detailed description of the installation of any CFI library, please refer to [GEN_SUM].

---

LIBRARY USAGE

Note that to use the ORBIT software library, the following other CFI software libraries are required:

• EE_COMMON
• FILE_HANDLING
• DATA_HANDLING
• LIB

Third party libraries:

• POSIX thread library: libpthread.so (Note: this library is normally pre-installed in Linux and MacOS platforms. For Windows platforms, pthread.lib is included in the distribution package, with license LGPL)
• GEOTIFF, TIFF, PROJ, LIBXML2 libraries (these libraries are included in the distribution package. Their usage terms and conditions are available in the file "TERMS_AND_CONDITIONS.TXT" which is part of the distribution package).

To use the ORBIT software library in an user application, that application must include in its source code the header files where the classes that are going to be used are defined.
To link correctly this application, the user must include in his linking command flags like (assuming cfi_lib_dir and cfi_include_dir are the directories where respectively all CFI libraries and include files have been installed, see [GEN_SUM] for installation procedures):

• LINUX:
  -Icfi_include_dir -Lcfi_lib_dir
  -lCfiOrbit -lCfiLib -lCfiDataHandling -lCfiFileHandling -lCfiEECommon -lm -lc
• MacOS:
  -Icfi_include_dir -Lcfi_lib_dir
  -lCfiOrbit -lCfiLib -lCfiDataHandling -lCfiFileHandling -lCfiEECommon -lm -lc
  Note: the EOCFI libraries are built using the switch -mmacosx-version-min=10.9 for backward compatibility, so the libraries are built for STL library libstdc++.
  Starting from Mavericks the default STL library is libc++, so link problems can appear if you do not use the same build switch as the EOCFI
• WINDOWS (dynamic libraries):
  /I "cfi_include_dir" /libpath:"cfi_lib_dir"
  libCfiOrbit.lib libCfiLib.lib libCfiDataHandling.lib libCfiFileHandling.lib libCfiEECommon.lib
• WINDOWS (static libraries):
  /I "cfi_include_dir" /libpath:"cfi_lib_dir"
  libCfiOrbit.lib libCfiLib.lib libCfiDataHandling.lib libCfiFileHandling.lib libCfiEECommon.lib pthread.lib libxml2.lib libgeotiff.lib libtiff.lib libproj.lib Ws2_32.lib

Note that, as Earth Observation CFI libraries are dynamic, cfi_lib_dir must be included in the path where the system looks for dynamic libraries (LD_LIBRARY_PATH in LINUX, DYLD_LIBRARY_PATH in MacOs). For WINDOWS sytem, the executable will look for .dll libraries, not the .lib ones that are used to create the executable, so they must be in the path described by PATH variable.
All the classes described in this document are defined in EECFI namespace, to avoid any possible conflict with classes of other libraries, so the user must choose one of the following two options in order to use the classes:

• Inserting using namespace EECFI; in the code.
• Using the classes with the namespace prefix (e.g.: EECFI::OrbitFile orbitFile;)

---

ERROR HANDLING

The error management in C++ ORBIT is made throw exceptions, that is, if any error is produced, an exception of type CfiError is thrown and it must be catched putting the code inside a try-catch block.
See [GEN_SUM] to know more about how to handle the CFI errors. For a descripton about the CfiError class and its methods, see [EE_COMMON_SUM].