Earth Observation Mission CFI Software
LIB SOFTWARE USER MANUAL
for JAVA

Code	EO-MA-DMS-GS-023
Issue	4.27
Date	07/06/24

	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-013-10

Document Status Log

Issue	Change Description	Date	Approval
1.0	These libraries corresponds to version 4.0 of C libraries.	22/06/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
4.27	These libraries corresponds to version 4.27 of C libraries.	07/06/24

---

ACRONYMS, NOMENCLATURE AND TERMINOLGY

Acronyms

ANX	Ascending Node Crossing
AOCS	Attitude and Orbit Control Subsystem
ASCII	American Standard Code for Information Interchange
BOM	Beginning Of Mission
CFI	Customer Furnished Item
EOM	End Of Mission
ESA	European Space Agency
ESTEC	European Space Technology and Research Centre
GPL	GNU Public License
GPS	Global Positioning System
IERS	International Earth Rotation Service
I/F	Interface
LS	Leap Second
OBT	On-board Binary Time
OSF	Orbit Scenario File
SRAR	Satellite Relative Actual Reference
SUM	Software User Manual
TAI	International Atomic Time
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-019. Issue 4.27 07/06/24

Reference Documents

[MCD]	Earth Observation Mission CFI Software. Conventions Document. EO-MA-DMS-GS-0001. Issue 4.27 07/06/24.
[MSC]	Earth Observation Mission CFI Software. Mission Specific Customizations. EO-MA-DMS-GS-0018. Issue 4.27 07/06/24.
[EE_COMMON_SUM]	Earth Observation Mission CFI Software. EECommon Software User Manual. EO-MA-DMS-GS-020. Issue 4.27 07/06/24.
[F_H_SUM]	Earth Observation Mission CFI Software. FileHandling Software User Manual. EO-MA-DMS-GS-021. Issue 4.27 07/06/24.
[D_H_SUM]	Earth Observation Mission CFI Software. DataHandling Software User Manual. EO-MA-DMS-GS-022. Issue 4.27 07/06/24.
[IERS]	http://www.iers.org/iers/publications/bulletins/

---

INTRODUCTION

Classes Overview

This software library contains all low-level generic routines, supporting all the other CFI functions. The following CFI classes are included:

• AeolusObt: Class for Aeolus on-board time.
• CfiId: Base class for CFI Id objects.
• Coord: Class to store coordinates.
• Time (defined in EETime.h): Class for time operations.
• EnvisatObt: Class for Envisat on-board time.
• Geodetic: Class for geodetic coordinates.
• GoceObt: Class for GOCE on-board time.
• LibFunc: Class with several algebraic operations in static methods.
• ModelId: Class for Model Id.
• ObtTime: Base class for on-board time classes.
• SatId: Class for Satellite Id.
• SmosObt: Class for SMOS on-board time.
• StarData (defined in Star.h): Class for operations with Stars.
• StateVector: Class to store Orbit State Vector.
• TimeCorrelation: Class for Time Id.

The following auxiliary classes are also included (in LibData.h):

• Kepler: Class defining keplerian elements.
• LeapSecondInfo: Class defining leap second information.
• ModelData: Class for model data.
• OrbitInterval: Class defining am orbit interval.
• TimeCorrelationData: Class defining timeCorrelations.
• TimeData: Class defining reference time relations.
• TimeInterval: Class defining a time interval.
• Topocentric: Class for topocentric coordinates.

TIME COMPUTATIONS

All time time computations are peformed internally using the continuous TAI time reference. Therefore the input and output parameters are converted internally to the adequate time reference.

Time Reference Transformations Initialization

• TimeCorrelation.TimeCorrelation: constructor that initialize time correlations between TAI, UTC, UT1 and GPS times from:
  • reference data files.
  • input reference times.
• TimeCorrelation.getLeapSecondInfo: retrieves the leap second location (if any) in the initialised time range.

Time Format and Reference Transformations, operations between dates

• Time.setAscii: transforms a time expressed in a given ASCII format and reference (TAI, UTC, UT1 or GPS) into a time in Processing format, performing a reference transformation if necessary (to TAI, UTC, UT1 or GPS), and storing the result in the object.
• Time.getAscii: transforms the time stored in the object, expressed in Processing format and a given reference (TAI, UTC, UT1 or GPS), into a time in an ASCII format, performing a reference transformation if necessary (to TAI, UTC, UT1 or GPS).
• Time.getTransport: transforms the time stored in the object, expressed in Processing format and a given reference (TAI, UTC, UT1 or GPS) into a time in a Transport format, performing a reference transformation if necessary (to TAI, UTC, UT1 or GPS).
• Time.getProcessing and Time.change: transforms a time expressed in Processing format and a given reference (TAI, UTC, UT1 or GPS) into a time in Processing format with a different reference (TAI, UTC, UT1 or GPS).
• Time.setTransport: transforms a time expressed in a given Transport format and reference (TAI, UTC, UT1 or GPS) into a time in Processing format, performing a reference transformation if necessary (to TAI, UTC, UT1 or GPS),and storing result in object.

Operation between Dates

• Time.operator+: adds a duration to time stored in Time object.
• Time.operator-: subtracts a duration to time stored in Time object / subtracts two Time objects.

Transformations from/to On-board Times

Operations with On-board times are done with the class corresponding with the satellite being studied: AeolusObt, EnvisatObt, GoceObt, SmosObt. Each one has the following methods:

• getTime: transforms the On-board Time (OBT) stored in the corresponding object into a Time object.
• setTime: set the OBT of the object transforming the processing time stored in a Time object.

COORDINATE SYSTEMS TRANSFORMATIONS

Reference Frames Transformations

• StateVector.change: transforms a state vector between different coordinate systems.
• Coord.topocentricToEf: transforms a state vector from topocentric coordinates to the Earth Fixed CS.
• Coord.efToTopocentric: transforms a state vector from the Earth Fixed CS to topocentric coordinates.

Attitude-related Computations

• LibFunc.eulerToMatrix: computes the elements of the coordinate transformation matrix with respect to the attitude frame given the corresponding Euler rotation vector in the roll, pitch and yaw sequence.
• LibFunc.matrixToEuler: derives the Euler rotation vector with respect to the attitude frame in the roll, pitch and yaw sequence given the corresponding coordinate transformation matrix.
• LibFunc.getRotationAngles: calculates the rotation angles between two sets of orthonormal right-handed unit vectors expressed wrt an identical coordinate frame.
• LibFunc.getRotatedVector: calculates the rotated unit vectors given a set of unit vectors and the rotation angles expressed wrt an identical coordinate frame.
• LibFunc.quaternionsToVectors: calculates the orthonormal unit vectors from a given set of quaternions.
• LibFunc.vectorsToQuaternions: calculates the set of quaternions that correspond to a set of orthonormal unit vectors.

Coordinates Transformations

• Coord.setGeodetic: transforms from Geodetic to Cartesian coordinates.
• Coord.getGeodetic: transforms from Cartesian to Geodetic coordinates.
• Coord.getRaDec: transforms from a cartesian vector to right ascension and declination.
• StarData.getCart: transforms from right ascension and declination to a cartesian vector.

State Vector Transformations

• Coord.setKepler: transforms from Keplerian to Cartesian coordinates.
• Coord.getKepler: transforms from Cartesian to Keplerian coordinates.

Position on orbit calculations

• StateVector.getPositionOnOrbit: calculates a value describing the position of the satellite within the orbit, using as input a Cartesian orbit state vector.

Other Basic Computations

• StateVector.setSun: calculates the position and velocity of the Sun in the Earth Fixed coordinate system
• StateVector.setMoon: calculates the Moon position and velocity in the Earth Fixed coordinate system
• StateVector.setPlanet: calculates the position and velocity of a selected planet in the Earth Fixed coordinate system
• StarData.getStar: calculates the right ascension and declination of a star in the True of Date coordinate system.
• StarData.changeCatalog: calculates the star coordinates in a star catalogue reference frame.
• Geodetic.geoDistance: calculates the geodesic distance between two points that lay on the same ellipsoid, and the azimuth of the related geodesic line at both points.

Astronomical model selection

Models can be initialized using the Model class and its methods.

Time Reference Transformations Calling Sequence

Time reference transformations, and other functions with time as input, requires the user to initialise correlations between the different allowed time references, i.e. TAI, UTC, UT1 and GPS time. This can be done using the constructors of the Time class. Once the initialisation has been performed, the user is able to transform any date expressed in one of the allowed time references to another, through the methods in Time class. A Time object must be initialized with the TimeCorrelation object previously created, and its methods provide the trasnformations. A complete view of the time reference transformations sequence is presented in following figure:

Please refer also to:

• [MCD] for a detailed description of the time references and formats, coordinate systems, 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.

Earth and Astronomical model selection calling sequence

The CFI functions can work with different Earth and astronomical models. These models have been divided in the following categories:

• Star model
• Sun model
• Planet model
• Earth model
• Moon model
• Nutation model
• Precession model
• Constants model

In order to work with different models, these have to be stored in a CFI Id called Model ID. The Model ID is an object of type ModelId. The calling sequence for a C program where the Model ID is needed, would be as follows:

• Create the modelId object: ModelId modelId;
• Optionally, initialise the modelId with ModelId.init method. This method would set the requested models in the modelId. Note that if the modelId is not initialised this way, the CFI functions will use the default models.
• The modelId is used as an input parameter in the CFI methods if it is needed.

Please refer also to:

• [MCD] for a detailed description of the models implemented for the Earth Observation CFI. (For the current version, only the default models are available)
• [GEN_SUM] for a detailed description of the Id concept.

---

LIBRARY INSTALLATION

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

---

LIBRARY USAGE

Compilation hints

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

• EE_COMMON
• FILE_HANDLING
• DATA_HANDLING

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 CFI LIB software library in an user application, that application must import the classes that are going to be used. To do this, it must be taken into account that all CFI classes are part of EECFI package. For instance, to import class OneCfiClass:

• import EECFI.OneCfiClass;

For Java to find the classes, the jar files where they are defined must be included in the CLASSPATH environment variable. For Lib library, CLASSPATH must be something like:

• WINDOWS: CLASSPATH=jar_directoryEECommon.jar;jar_directoryFileHandling.jar;jar_directoryDataHandling.jar;jar_directoryLib.jar;other_class_paths
• Other operating systems: CLASSPATH=jar_directory/EECommon.jar:jar_directory/FileHandling.jar:jar_directory/DataHandling.jar:jar_directory/Lib.jar:other_class_paths

where jar_directory is the directory where the jar files are stored.

CFI libraries call C++ native methods. These methods are defined in dynamic libraries, which name and extension depend on the operating system:

• LINUX and SOLARIS: libJLibrary.so
• MAC systems: libJLibrary.jnilib
• WINDOWS: JLibrary.dll

If these libraries are stored in cfi_lib_dir, this directory must be included in the path where the system looks for dynamic libraries (LD_LIBRARY_PATH in LINUX and SOLARIS, DYLD_LIBRARY_PATH in MAC systems, PATH in WINDOWS sytem).

Enumerations

Every CFI library has defined constant values that can be used as input for several methods of the classes. They are grouped in a class with the name EnumLibrary. To use them, a static import is recommended:

import static EECFI.EnumLibrary.*;

so the constants can be used directly, without prefixing with package name and class name.
You can consult the constants available for this library here.

---

ERROR HANDLING

The error management in Java LIB 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].