| Earth Observation Mission CFI Software Visibility Software User Manual for JAVA |

Earth Observation Mission CFI Software
VISIBILITY SOFTWARE USER MANUAL
for JAVA

Code | EO-MA-DMS-GS-026
Issue | 4.19
Date | 29/05/20

| Name | Function | Signature
Prepared by: | Carlos Villanueva Muñoz | Project Manager |
Checked by: | Carlos Villanueva Muñoz | Project Manager |
Approved by: | José Antonio González Abeytua | 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-016-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 |

# 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
OSF | Orbit Scenario File
SCF | Swath Control File
SDF | Swath Definition File
SRAR | Satellite Relative Actual Reference
SSP | Sub Satellite Point
STF | Swath Template File
SUM | Software User Manual
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-019. Issue 4.19 29/05/20

## Reference Documents

[MCD] | Earth Observation Mission CFI Software. Conventions Document. EO-MA-DMS-GS-0001. Issue 4.19 29/05/20.
[MSC] | Earth Observation Mission CFI Software. Mission Specific Customizations. EO-MA-DMS-GS-0018. Issue 4.19 29/05/20.
[EE_COMMON_SUM] | Earth Observation Mission CFI Software. EECommon Software User Manual. EO-MA-DMS-GS-020. Issue 4.19 29/05/20.
[F_H_SUM] | Earth Observation Mission CFI Software. FileHandling Software User Manual. EO-MA-DMS-GS-021. Issue 4.19 29/05/20.
[D_H_SUM] | Earth Observation Mission CFI Software. DataHandling Software User Manual. EO-MA-DMS-GS-022. Issue 4.19 29/05/20.
[LIB_SUM] | Earth Observation Mission CFI Software. Lib Software User Manual. EO-MA-DMS-GS-023 Issue 4.19 29/05/20.
[ORBIT_SUM] | Earth Observation Mission CFI Software. Orbit Software User Manual. EO-MA-DMS-GS-024. Issue 4.19 29/05/20.
[POINT_SUM] | Earth Observation Mission CFI Software. Pointing Software User Manual. EO-MA-DMS-GS-025. Issue 4.19 29/05/20.
[FORMATS] | Earth Explorer File Format Guidelines. CS-TN-ESA-GS-0148.

# INTRODUCTION

## Classes and methods overview

This software library contains the CFI classes required to compute time segments at which an Earth Observation satellite, or one of its instruments is in view of various targets:

- zones (defined as polygons or circles, on the earth ellipsoid or at a given altitude)
- ground stations
- data relay satellites
- stars

The following classes are included:

- DRSVis: Class for data relay satellite visibility.
- OrbitExtra: Class to extract orbital extra information.
- Swath: Class to make operations involving a swath for zone and station visibility.
- SwathStar: Class to make operations involving a swath for star visibility.
- VisibilityList: Class to store list of visibility segments.
- VisibilitySegment: Class to store a visibility segment.

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

- VisExtraInfo: Base class for visibility extra information.
- ZoneExtraInfo: Additional information to visibility segments computed for one zone.
- StationExtraInfo: Additional information to visibility segments computed for one station.
- MultiZonesExtraInfo: Additional information to visibility segments computed for multiple zones.
- MultiStationsExtraInfo: Additional information to visibility segments computed for multiple zones.
- MappingExtraInfo: Additional information to visibility segments computed for mapping.
- StarExtraInfo: Additional information to star visibility segments.
- OrbitExtraInfo: Orbit extra information.
- ScfAppear: Swath Control File appearance data structure.

This library is to be used for planning of Earth Observation operations. It includes, the following CFI methods:

- DrsVis.drsVisTime: computes visibility time segments for a data relay satellite
- SwathStar.starVisTime: computes visibility time segments for a star.
- Swath.stationVisTime: compute visibility time segments for a ground station
- Swath.zoneVisTime: compute visibility time segments for an instrument swath in visibility of a zone.
- Swath.getPos: computes location of a swath at a given time (additional routine to help refine the results of zoneVisTime)
- Swath.multiZonesVisTime: computes the visibility segments of several zones and sort them to different criteria.
- Swath.multiStationsVisTime: computes the visibility segments of several ground stations and sort them according to different criteria.
- Swath.genSwath generate the instrument swath template file for a given satellite, instrument mode and orbit.
- Swath.genScf generates a swath control file for the ESOV tool.
- Time Segments Manipulation Routines:
  - VisList.not: returns the complement of 1 vector of time segments.
  - VisList.and: returns the intersection segments from 2 vectors of time segments.
  - VisList.or: returns the joined segments from 2 vectors of time segments
  - VisList.delta: add or subtract time durations at the beginning and end of each time segment in a vector.
  - VisList.sort: returns the vector of time segments sorted according to absolute or relative orbits.
  - VisList.merge: merges all the overlapped segments in a list.
  - Swath.mapping: returns a subset of the time segments vector, such that this subset covers entirely a zone or line swath.

Several files are required to operate properly the above methods:

- Orbit Scenario File (all functions)
- Swath Template Files (Swath.stationVisTime, Swath.zoneVisTime, Swath.getPos)
- Ground Stations Database File (Swath.stationVisTime)
- (optionally) Zones Database File (Swath.zoneVisTime)
- (optionally) Star Database File (Swath.starVisTime)

## Calling Sequence

An overview of the data flow is presented in following figure:

# 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 VISIBILITY software library, the following other CFI software libraries are required:

- EE_COMMON
- FILE_HANDLING
- DATA_HANDLING
- LIB
- ORBIT
- POINTING

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 Pointing functions (see [POINT_SUM]) 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 Visibility 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;jar_directoryVisibility.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:jar_directory/Visibility.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 Visibility 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].