Earth Observation Mission CFI Software
POINTING SOFTWARE USER MANUAL
for JAVA

Code	EO-MA-DMS-GS-025
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
Contract Number:	4000102614/1O/NL/FF/ef	Public
Contract Issuer:	ESA / ESTEC	Industry	X
Contract Issuer:	ESA / ESTEC	Confidential

External Distribution
Name	Organization	Copies

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

Document Status Log

Issue	Change Description	Date
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

ACRONYMS, NOMENCLATURE AND TERMINOLOGY

Acronyms

ANX	Ascending Node Crossing
AOCS	Attitude and Orbit Control Subsystem
ASCII	American Standard Code for Information Interchange
CFI	Customer Furnished Item
CS	Coordinate System
DRS	Data Relay Satellite
ESA	European Space Agency
ESTEC	European Space Technology and Research Centre
GPL	GNU Public License
GPS	Global Positioning System
GS	Ground Station
IERS	International Earth Rotation Service
I/F	Interface
LOS	Line Of Sight
LUT	Look-Up Table
OBT	On-board Binary Time
OSF	Orbit Scenario File
RAM	Random Access Memory
SBT	Satellite Binary Time
SRAR	Satellite Relative Actual Reference
SSP	Sub Satellite Point
SUM	Software User Manual
S/W	Software
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.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-020. Issue 4.26 31/10/23.
[F_H_SUM]	Earth Observation Mission CFI Software. FileHandling Software User Manual. EO-MA-DMS-GS-021. Issue 4.26 31/10/23.
[D_H_SUM]	Earth Observation Mission CFI Software. DataHandling Software User Manual. EO-MA-DMS-GS-022. Issue 4.26 31/10/23.
[LIB_SUM]	Earth Observation Mission CFI Software. Lib Software User Manual. EO-MA-DMS-GS-023 Issue 4.26 31/10/23.
[LOS_ALG]	LOS Intersection. PE-TN-ESA-SY-0043

INTRODUCTION

Classes Overview

This software library contains the CFI classes with the methods required to perform accurate computation of pointing parameters from and to a satellite for various types of targets. It includes a set of methods to initialize the attitude of the platform and the instruments. The values provided by these methods are later used by all the other methods of the library.
The following CFI classes are included:

AtmosId: Class for the atmospheric model.
Attitude: Class for attitude data and configuration.
DemId: Class for DEM parameters.
InstrTransId: Class for Instrument Attitude.
SatNomTransId: Class for satellite nominal attitude.
SatTransId: Class for satellite attitude.
Target: Class for target calculations.

and the following auxiliary classes:

AttDataRec: Attitude data.
AtmosIdData: Atmospheric Id data.
AttFileModel: File Model for Nominal attitude and instrument attitude.
AttitudeData: Attitude id data.
AzElDefinition: Azimuth/elevation definition.
CsTra: Coordinate system matrix.
GenericTargetData: Generic target data.
ParDer: Parameter.
QuatPlusAnglesModel: Quaternion plus angles model.
QuatPlusMatrixModel: Quaternion plus matrix model.
SatAttFileModel: File Model for satellite attitude.
StarTrackerAux: Star tracker aux data.
TargetData: Target data.
TargetIdData: Target id data.

For furher information, 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 usage and the error handling functions

Attitude Data Flow

The following figure shows the tipical data flow for the attitude methods. First, the different transformations between the various reference frames are initialised. Then, given the spacecraft position, the attitude is calculated:

Each different transformation can be initialised with different models:

Geolocation Routines Data Flow

The following figure shows the tipical data flow for the geolocation routines functions. First, the attitude should be calculated, and, if needed, the refraction and Digital Elevation Models initialised.

The table below and the diagrams on the next pages describe the various Target.targetXXX methods.

Target.targetXXX method	Description
Target.targetInter / Target.multiTargetInter	It calculates the intersection point(s) of the line of sight defined by an elevation and an azimuth angle expressed in the input Attitude frame, with a surface(s) located at a certain geodetic altitude(s) over the Earth.
Target.targetTravelTime / Target.multiTargetTravelTime	It calculates the point of the line or sight from the satellite (defined by an elevation and an azimuth angle expressed in the selected Attitude Frame) at a given travel time(s) along the (curved) line of sight.
Target.targetGroundRange	It calculates the location of a point that is placed on a surface at a certain geodetic altitude over the Earth, that lays on the plane defined by theS/C position, the nadir and a reference point, and that is at a certain distance or ground range measured along that surface from that reference point. This reference point is calculated being the intersection of the previous surface with the line of sight defined by an elevation and azimuth angle in the input Attitude coordinate system.
Target.targetIncidenceAngle	It calculates the location of a point that is placed on a surface at a certain geodetic altitude over the Earth and that is seen from the S/C on a line of sight that forms a certain azimuth angle in the input Attitude frame and that intersects that surface with a certain incidence angle.
Target.targetRange	It calculates the location of a point that is placed on a surface at a certain geodetic altitude over the Earth, that is seen from the S/C on a line of sight that forms a certain azimuth angle in the input Attitude frame, and that is at a certain range or slant-range from the S/C.
Target.targetRangeRate	It calculates the location of a point that is placed on a surface at a certain geodetic altitude over the Earth, that is at a certain range from S/C, and whose associated Earth-fixed target has a certain range-rate value.
Target.targetTangent	It calculates the location of the tangent point over the Earth that is located on the line of sight defined by an elevation and azimuth angles expressed in the input Attitude frame.
Target.targetAltitude	It calculates the location of the tangent point over the Earth that is located on a surface at a certain geodetic altitude over the Earth and that is on a line of sight that forms a certain azimuth angle in the input Attitude frame.
Target.targetStar	It calculates the location of the tangent point over the Earth that is located on the line of sight that points to a star defined by its right ascension and declination coordinates.
Target.targetGeneric	The cartesian state vector of the target is taken as an input.
Target.targetTangentSun	It calculates the location of the tangent point over the Earth that is located on the line of sight that points to the Sun
Target.targetTangentMoon	It calculates the location of the tangent point over the Earth that is located on the line of sight that points to the Moon
Target.targetStation	It calculates the most relevant observation parameters of the link between the satellite and a ground station
Target.targetSc	It calculates the most relevant observation parameters of the link between one source satellite and anothr target satellite.

As it can be seen from the list of functions, there are some functions that calculate several targets (Target.multiTargetXXX). The number of targets found by the functions is stored in the Target object. In addition to these "user" targets, two other categories of targets can be defined, "LOS" targets and "DEM" targets.

LOS targets

The idea is to get information about all the ray path points computed by a specific target routine along the Line of Sight (LOS) trajectory. For every target method, the Target parameter numLosTarget will store the number of points in the path. It applies when the variable "targetType" is equal to XPCFI_LOS_TARGET_TYPE.

Start point of LOS. The spacecraft position (Instrument CS) shall be considered as the start point for the LOS path.
Stop point of LOS. The stop point for the LOS path will be different depending on the selected target function; nominally it will be the resulting target point.

Target.targetInter and Target.multiTargetInter: 1st or 2nd intersection point (Point corresponding to the last altitude for the multi_target routine)
Target.targetGround: Target point
Target.targetIncidenceAngle: Target point
Target.targetRange: Target point
Target.targetRangeRate: Target point
Target.targetTangent: Two different cases to consider depending on whether refraction is selected or not:
- No refraction mode: Tangent point
- Refraction mode:
  - The 2nd intersection point with a surface located at Refraction Model Maximum Height (geodetic altitude) over the Earth if tangent height <= Refraction Model Maximum Height
  - The tangent point if tangent height > Refraction Model Maximum Height
Target.targetAltitude: Point at selected altitude
Target.targetStar: Two different cases to consider depending on whether refraction is selected or not:
- No refraction mode: Tangent point
- Refraction mode:
  - The 2nd intersection point with a surface located at Refraction Model Maximum Height (geodetic altitude) over the Earth if tangent height <= Refraction Model Maximum Height
  - The tangent point if tangent height > Refraction Model Maximum Height
Target.targetStation: Ground Station position
Target.targetDRS: DRS position
Target.targetGeneric: Target position
Target.targetReflected: Reflection point
Target.targetTravelTime and Target.multiTargetTravelTime: Point at selected travel time (Point corresponding to the last travel time for the multiTarget routine)
Target.targetTangentSun: Tangent point
Target.targetTangentMoon: Tangent point

DEM targets

A DEM Target is defined as the intersection of a line of sight with the Earth Surface defined using a digital elevation model (DEM).
A DEM Target is calculated using as line of sight the LOS targets that has been computed previously with a target routine (Note that such LOS consist in a polygonal line, no necessarily a straight line). Consequently, to get a DEM target it is neccessary to follow these steps:

Initialize the DEM model creating a DemId object and using the DemId.init method and a configuration file.
One call to the target method for getting the LOS targets.
One call to the target extra routine requesting the DEM target.

The digital elevation model of the Earth consists in a set of points defining a grid for which a measure of the altitude over the Earth reference elipsoid is given. The altitude of the points within each cell of the grid is computed by the CFI using a bilinear interpolation with the points of the corner of the cell. Details about the bilinear algorithm used to compute the intersection can be seen in [LOS_ALG].[LOS_ALG]

Light propagation model

When the light propagation model is enabled, the target functions keep into account the time spent by a generic signal travelling at the speed of light to:

in the TRANSMITTER mode: go from the satellite to the target;
in the RECEIVER mode: go from the target to the satellite.

Two distinct times are considered:

The satellite time (T) is the time provided as input to the target function. It is:
- in the TRANSMITTER mode: the time at which the satellite (instrument) emits the signal towards the target;
- in the RECEIVER mode: the time at which the satellite (instrument) receives the signal emitted by the target.
The target time is the satellite time T plus or minus the light travel time between satellite and target (dT). It is:
- in the TRANSMITTER mode: T+dT, i.e. the target receives the signal sent by the sarellite with a delay dT;
- in the RECEIVER mode: : T-dT, i.e. the satellite receives the signal emitted by the target with a delay dT.

dT is calculated as the light travel time from the satellite to target calculated with dT=0. When the light propagation model is not activated, it is assumed dT=0, therefore target and satellite are considered at the same time T.
According to the definitions above, the Line of Sight (LOS) can be defined as the segment joining satellite and target at their correspondent times.
For the following functions the calculation method is slightly different:

Target.targetRange: the input range is used to calculate the light travel time;
Target.targetTravelTime: the input travel time is used as dT;
Target.targetGeneric, Target.targetSc: in this case the input is the target at time T+/-dT. The function estimates the target at T to compute the line of sight parameters also considering (if provided as inputs) velocity and acceleration of the target.

Target geometric properties (returned by the extra functions) are evaluated considering the two distinct times, for example:

The target position (i.e. position in EF co-ordinates and geodetic co-ordinates) is evaluated at time T-dT;
Direction from satellite to target and viceversa are evaluated considering the satellite position at time T and target position at time T+/-dT;
Direction from target to e.g. sun/moon take into account the target position at T+/-dT and other celestial bodies at the same time.

Following figure shows an example using the Target.targetInter function.

The light propagation mode is set to RECEIVER and input azimuth,elevation are 0, 90 deg (assuming a local normal pointing). The signal is emitted by the target at time T-dT (blue point, let’s assume at geodetic co-ordinates (lon,lat,h) and EF co-ordinates (X,Y,Z) ) and is received by the satellite at time T (red triangle). Due to Earth rotation, at time T the observed target has moved to the red point.
Here are some examples of results from Target.extra… functions:

Target.extraVector:
- Target position: the vector (X,Y,Z), i.e. the target point considered at T-dT;
- Direction LOS: the vector corresponding to the purple line in Fig. X (it is the line joining satellite position at time T and target position at time T-dT);
Target.extraMain:
- Target geodetic co-ordinates: (lon,lat,h)
- Satellite to target azimuth, elevation: 0,90, i.e. the same azimuth and elevation used as input for xp_target_inter.
- Target to satellite azimuth, elevation: 0,90,, this is the view direction from the target at time T-dT to the satellite at time T.

The same results are given by the Target.extra… functions if the Target.targetGeneric is called with input target at EF co-ordinates (X,Y,Z) and velocity set to zero.

To activate the light propagation mode the modelId object must be initialized as follow:

for TRANSMITTER mode:

long mode;
vector<long> models;

mode = XLCFI_MODEL_CONFIG;
models.clear();
...
models.push_back(XLCFI_MODEL_LIGHT_PROPAGATION_TRANSMITTER);
modelId = new ModelId(mode, models);
for RECEIVER mode:

long mode;
vector<long> models;

mode = XLCFI_MODEL_CONFIG;
models.clear();
...
models.push_back(XLCFI_MODEL_LIGHT_PROPAGATION_RECEIVER);
modelId = new ModelId(mode, models);

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 POINTING 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).

In order to improve run-time performance, some methods (e.g. Target.extraListVector, Target.extraListMain, Target.extraListAux, Target.extraListEfTarget, Target.extraListTargetToSun, Target.extraListTargetToMoon,Target.extraListSpecularReflection) perform their computations in multi-threading mode. The multi-threading code of the Pointing functions uses the OpenMP API (see http://en.wikipedia.org/wiki/OpenMP). OpenMP is not supported in the clang compiler, therefore such functions work in single-thread mode in MacOS.

To use the CFI ORBIT 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 Pointing library, CLASSPATH must be something like:

WINDOWS: CLASSPATH=jar_directoryEECommon.jar;jar_directoryFileHandling.jar;jar_directoryDataHandling.jar;jar_directoryLib.jar;jar_directoryOrbit.jar;jar_directoryPointing.jar;other_class_paths
Other operating systems: CLASSPATH=jar_directory/EECommon.jar:jar_directory/FileHandling.jar:jar_directory/DataHandling.jar:jar_directory/Lib.jar:jar_directory/Orbit.jar:jar_directory/Pointing.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 POINTING 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].