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

Earth Observation Mission CFI Software
DATAHANDLING SOFTWARE USER MANUAL
for JAVA

Code | EO-MA-DMS-GS-022
Issue | 4.3
Date | 06/02/12

| Name | Function | Signature
Prepared by: | Carlos Villanueva Muñoz | Project Engineer |
Checked by: | Juan José Borrego Bote | Project Manager |
Approved by: | José Antonio González Abeytua | Division Head |

# DOCUMENT INFORMATION

Contract Data | Classification
--- | ---
Contract Number: | 15583/01/NL/GS | 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-012-10

# Document Status Log

Issue | Change Description | Date | Approval
--- | --- | --- | ---
1.0 | First release These libraries corresponds to version 4.0 of C libraries. | 22/06/09 |
4.1 | Second release - Issue in line with C libraries version These libraries corresponds to version 4.1 of C libraries. | 07/05/10 |
4.2 | Third release These libraries corresponds to version 4.2 of C libraries. | 31/01/11 |
4.3 | Fourth release These libraries corresponds to version 4.3 of C libraries. | 06/02/12 |

# ACRONYMS, NOMENCLATURE AND TERMINOLOGY

## 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.3 06/02/12

## Reference Documents

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

# INTRODUCTION

## Classes Overview

This software library contains a set of classes for reading and writing Earth Observation Mission Files. The following CFI classes for reading/writing files are included:

- AttFile: Class for reading/writing attitude generic files
- DemConfFile: Class for reading DEM configuration files.
- DemFile: Class for reading DEM files.
- DorisFile: Class for reading/writing DORIS navigator files.
- EEFile: Base class for Earth Observation File.
- IersFile: Class for reading Iers bulletin.
- OrbitFile: Class for reading/writing orbit files.
- OsfFile: Class for reading/writing Orbit Scenario files.
- PropagPreciseConf: Class to read and store the data for numerical propagator configuration.
- SdfFile: Class for reading Swath defintion files.
- StarFile: Class for reading star files.
- StarTracker: Class for star tracker quaternion.
- StarTrackerConfFile: Class for reading Star tracker configuration files.
- StarTrackerFile: Class for reading star tracker files.
- StationFile: Class for reading Station files.
- StfFile: Class for reading/writing Swath Template Files.
- TleFile: Class for reading/writing Two Line Elements file.
- ZoneFile: Class for reading zone files.

The following classes to contain data are also included:

- AngleModel (defined in DataHandlingData.h): Angle model.
- Asar (defined in DataHandlingData.h): ASAR definition.
- AttitudeModel (defined in DataHandlingData.h): Attitude model.
- AttRec: Class for storing attitude data.
- BulbTable (defined in DataHandlingData.h): Class to store the data for one entry read from the IERS bulletin.
- DemPoint (defined in DataHandlingData.h): DEM point.
- DorisHeader (defined in DataHandlingData.h): Class to store DORIS navigator files header.
- FileModel (defined in DataHandlingData.h): File model.
- HarmonicData (defined in DataHandlingData.h): Harmonic model data.
- HarmonicModel (defined in DataHandlingData.h): Harmonic model.
- MatrixModel (defined in DataHandlingData.h): Matrix model.
- OsfRec: Class for containing data structure for Orbit Scenario File records.
- OsvRec: Class for containing a satellite state vector for a given time.
- ParamModel (defined in DataHandlingData.h): Parameter model.
- SdfRec: Class for containing Swath definition data.
- StarRec: Class for storing star information.
- StarTracker: Class for star tracker quaternion.
- StationRec: Class for storing station information.
- StfPt (defined in DataHandlingData.h): Swath point coordinates.
- StfRec: Class to contain a Swath record.
- StfVhr (defined in DataHandlingData.h): Class for containing Swath variable header.
- SwathGeometry (defined in DataHandlingData.h): Swath geometry data.
- TleRec: Class for containing data structure for Two Line Elements.
- TrackerLimits (defined in DataHandlingData.h): Star tracker limits.
- ZonePoint (defined in DataHandlingData.h): Zone point.
- ZoneRec: Class for storing zone information.

## Reading routines

- EEFile.readHeader: reads the fixed header for an Earth Observation XML file.
- IersFile.read: reads the time correlations from an IERS bulletin.
- OrbitFile:read: reads orbit files consisting in a list of state vectors of the satellite in the orbit.The following files are supported: Predicted Orbit files, Restituted Orbit files and DORIS Preliminary files.
- DorisFile.read: reads DORIS Navigator files for CRYOSAT.
- DorisFile.readHeader: reads the MPH and SPH data from a DORIS Navigator file for CRYOSAT.
- OsfFile.read: reads Orbit Scenario files.
- AttFile.read: reads a generic attitude file.
- StarTrackerFile.read: reads an star traker file for CRYOSAT.
- StarTrackerConfFile.read: reads an star tracker configuration file for CRYOSAT.
- DemFile.read: provides the points of a DEM that are adjacent to a given point.
- DemConfFile.read: reads a DEM configuration file.
- SdfFile.read: reads swath definition files.
- StfFile.read: reads swath template files.
- StfFile.readVhr: reads the variable header for swath template files
- ZoneFile.read: reads the parameters of one zone in a zone database file or a zone database file.
- ZoneFile.readIds: reads the list of zone names from a zone database file.
- StationFile.read: reads the parameters of one station in a station database file or a station database file.
- StationFile.readIds: reads the list of station names from a station database file
- StarFile.read: reads the parameters of one star in a star database file or a star database file.
- StarFile.readIds: reads the list of star id. from a star database file
- TleFile.read: reads a TLE file
- PropagPreciseConf:.read: reads a data file used to configure the numerical propagator

### Writing routines

- OrbitFile.write: writes an orbit file using as input an structure with the data of the file
- OsfFile.write: writes an orbit scenario file using as input an structure with the data of the file
- DorisFile.write: writes a DORIS Navigator file.
- AttFile.write: writes a generic attitude file.
- StfFile.write: writes a swath template file using as input the data structure containing the data for the swath.
- TleFile.write: writes a TLE file using as input a data structure.

### Validation of XML files

- EEFile.validate: validates an XML file using an XML schema as reference.

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

- EE_COMMON
- FILE_HANDLING

It is needed to have properly installed in the system the following external libraries:

- LIBXML2 (MIT license, see [GEN_SUM])
- POSIX thread library: libpthread.so (pthread.lib for WINDOWS, with license LGPL)

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

- WINDOWS: CLASSPATH=jar_directoryEECommon.jar;jar_directoryFileHandling.jar;jar_directoryDataHandling.jar;other_class_paths
- Other operating systems: CLASSPATH=jar_directory/EECommon.jar:jar_directory/FileHandling.jar:jar_directory/DataHandling.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).

Finally, in order to use the function EEFile.validate , it is neccessary the xerces-c 2.7 (or later) dynamic library and the SAX2Count executable program. Both of them are distributed under Apache 2.0 Licence (More information about xerces-c can be found in: http://xml.apache.org/xerces-c/index.html). EEFile.validate internally calls the SAX2Count program, so that in order to find it, the path for SAX2Count and the xerces-c dynamic library has to be included in the environment variable PATH (For LINUX and SOLARIS, the xerces library has to be included in the LD_LIBRARY_PATH instead).

## 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 DATA_HANDLING 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].

# EARTH OBSERVATION FILE VERSIONS

Next table shows the list of last version (default version) for the schema of the XML files that are handled by the CFI. The default schema depends on the mission, so different versions appear depending on the Mission Column. For the sake of simplicity, in this column could appear:

- Sat_1: All satellites except SENTINEL missions.
- Sat_2: SENTINEL missions.

Default schema's versions
File Type | Mission | Version | Schema
--- | --- | --- | ---
Predicted Orbit File | Sat_1 | 1.3 | EO_OPER_MPL_ORBPRE_0103.XSD
Sat_2 | 2.0 | EO_OPER_MPL_ORBPRE_0200.XSD
Restituted Orbit files | Sat_1 | 1.3 | EO_OPER_AUX_ORBRES_0103.XSD
Sat_2 | 2.0 | EO_OPER_AUX_ORBRES_0200.XSD
Doris Preliminary files | Sat_1 | 1.3 | EO_OPER_AUX_ORBDOP_0103.XSD
Sat_2 | 2.0 | EO_OPER_AUX_ORBDOP_0200.XSD
Doris Precise files | Sat_1 | 1.3 | EO_OPER_AUX_ORBDOR_0103.XSD
Sat_2 | 2.0 | EO_OPER_AUX_ORBDOR_0200.XSD
Orbit Scenario files | Sat_1 | 1.2 | EO_OPER_MPL_ORBSCT_0102.XSD
Sat_2 | 2.0 | EO_OPER_MPL_ORBSCT_0200.XSD
Orbit Event files | Sat_1 | 1.3 | EO_OPER_MPL_ORBREF_0103.XSD
Sat_2 | 2.0 | EO_OPER_MPL_ORBREF_0200.XSD
DORIS Navigator files | Sat_1 | 1.1 | EO_OPER_DOR_NAV_0_.HeaderTypes_0101.XSD with EO_OPER_DOR_NAV_0_.DataBlockTypes_0100.XSD
Sat_2 | 2.0 | EO_OPER_DOR_NAV_0_.HeaderTypes_0200.XSD with EO_OPER_DOR_NAV_0_.DataBlockTypes_0100.XSD
Star Tracker files | Sat_1 | 1.1 | EO_OPER_STR1ATT_0_HeaderTypes_0101.XSD with EO_OPER_STR1ATT_0_.DataBlockTypes_0100.XSD
Sat_2 | 1.1 | EO_OPER_STR1ATT_0_HeaderTypes_0200.XSD with EO_OPER_STR1ATT_0_.DataBlockTypes_0100.XSD
Satellite Configuration File | Sat_1 | 1.2 | EO_OPER_INT_SATCFG_0102.XSD
Sat_2 | 2.0 | EO_OPER_INT_SATCFG_0200.XSD
Attitude File | Sat_1 | 1.1 | EO_OPER_INT_ATTCFG_0101.XSD
Sat_2 | 2.0 | EO_OPER_INT_ATTREF_0200.XSD
Star tracker configuration File | Sat_1 | 1.1 | EO_OPER_INT_STRCFG_0101.XSD
Sat_2 | 2.0 | EO_OPER_INT_STRCFG_0200.XSD
DEM Configuration File | Sat_1 | 1.3 | EO_OPER_INT_DEMCFG_0103.XSD
Sat_2 | 2.0 | EO_OPER_INT_DEMCFG_0200.XSD
Swath Definition File | Sat_1 | 2.1 | EO_OPER_MPL_SW_DEF_0201.XSD
Sat_2 | 3.0 | EO_OPER_MPL_SW_DEF_0300.XSD
Swath Template File | Sat_1 | 2.1 | EO_OPER_MPL_SWTREF_0201.XSD
Sat_1 | 3.0 | EO_OPER_MPL_SWTREF_0300.XSD
Zone Database File | Sat_1 | 1.2 | EO_OPER_MPL_ZON_DB_0102.XSD
Sat_2 | 2.0 | EO_OPER_MPL_ZON_DB_0200.XSD
Station Database File | Sat_1 | 1.4 | EO_OPER_MPL_GND_DB_0104.XSD
Sat_2 | 2.0 | EO_OPER_MPL_GND_DB_0200.XSD
Precise Propagator Configuration File | Sat_1 | 1.0 | EO_OPER_INT_PPRCFG_0100.XSD
Sat_2 | 1.0 | EO_OPER_INT_PPRCFG_0200.XSD

However the current CFI libraries are able to use older XML file versions. Next table shows all the available schema's versions for the Earth Observation Missions files at the time of the CFI's package delivery, and which of them are supported by the current CFI's implementation.

The meaning of the column "Supp. CFI's" is:

- N: Version not supported for reading/writing.
- Y: Supported version.
- R: Supported only for reading

Note that the writing functions create files with the version labeled with "Y". Note also that for those files that can be written by the CFI, the written version depend on the satellite mission (For reading, the files can be read independently of the mission).

List of schema's versions
File Type | Version | Schema | Mission | Supp. CFI's
--- | --- | --- | --- | ---
Predicted Orbit File | 1.0 | EO_OPER_MPL_ORBPRE_0100.XSD | - | N
1.1 | EO_OPER_MPL_ORBPRE_0101.XSD | - | R
1.2 | EO_OPER_MPL_ORBPRE_0102.XSD | - | R
1.3 | EO_OPER_MPL_ORBPRE_0103.XSD | Sat_1 | Y
Sat_2 | N
2.0 | EO_OPER_MPL_ORBPRE_0200.XSD | Sat_1 | N
Sat_2 | Y
Restituted Orbit files | 1.0 | EO_OPER_AUX_ORBRES_0100.XSD | - | N
1.1 | EO_OPER_AUX_ORBRES_0101.XSD | - | R
1.2 | EO_OPER_AUX_ORBRES_0102.XSD | - | R
1.3 | EO_OPER_AUX_ORBRES_0103.XSD | Sat_1 | Y
Sat_2 | N
2.0 | EO_OPER_AUX_ORBRES_0200.XSD | Sat_1 | N
Sat_2 | Y
Doris Preliminary files | 1.0 | EO_OPER_AUX_ORBDOP_0100.XSD | - | N
1.1 | EO_OPER_AUX_ORBDOP_0101.XSD | - | R
1.2 | EO_OPER_AUX_ORBDOP_0102.XSD | - | R
1.3 | EO_OPER_AUX_ORBDOP_0103.XSD | Sat_1 | Y
Sat_2 | N
2.0 | EO_OPER_AUX_ORBDOP_0200.XSD | Sat_1 | N
Sat_2 | Y
Doris Precise files | 1.0 | EO_OPER_AUX_ORBDOR_0100.XSD | - | N
1.1 | EO_OPER_AUX_ORBDOR_0101.XSD | - | R
1.2 | EO_OPER_AUX_ORBDOR_0102.XSD | - | R
1.3 | EO_OPER_AUX_ORBDOR_0103.XSD | Sat_1 | Y
Sat_2 | N
2.0 | EO_OPER_AUX_ORBDOR_0200.XSD | Sat_1 | N
Sat_2 | Y
Orbit Scenario files | 1.0 | EO_OPER_MPL_ORBSCT_0100.XSD | - | N
1.1 | EO_OPER_MPL_ORBSCT_0101.XSD | - | R
1.2 | EO_OPER_MPL_ORBSCT_0102.XSD | Sat_1 | Y
Sat_2 | N
2.0 | EO_OPER_MPL_ORBSCT_0200.XSD | Sat_1 | N
Sat_2 | Y
Orbit Event files | 1.0 | EO_OPER_MPL_ORBREF_0100.XSD | - | Y
1.1 | EO_OPER_MPL_ORBREF_0101.XSD | - | R
1.2 | EO_OPER_MPL_ORBREF_0102.XSD | - | R
1.3 | EO_OPER_MPL_ORBREF_0103.XSD | Sat_1 | Y
Sat_2 | N
2.0 | EO_OPER_MPL_ORBREF_0200.XSD | Sat_1 | N
Sat_2 | Y
DORIS Navigator files | 1.1 | EO_OPER_DOR_NAV_0_.HeaderTypes_0101.XSD with EO_OPER_DOR_NAV_0_.DataBlockTypes_0100.XSD | Sat_1 | Y
Sat_2 | N
2.0 | EO_OPER_DOR_NAV_0_.HeaderTypes_0200.XSD with EO_OPER_DOR_NAV_0_.DataBlockTypes_0100.XSD | Sat_1 | N
Sat_2 | Y
Star Tracker files | 1.1 | EO_OPER_STR1ATT_0_HeaderTypes_0101.XSD with EO_OPER_STR1ATT_0_.DataBlockTypes_0100.XSD | Sat_1 | Y
Sat_2 | N
2.0 | EO_OPER_STR1ATT_0_HeaderTypes_0200.XSD with EO_OPER_STR1ATT_0_.DataBlockTypes_0100.XSD | Sat_1 | N
Sat_2 | Y
Satellite Configuration File | 1.0 | EO_OPER_INT_SATCFG_0100.XSD | - | N
1.1 | EO_OPER_INT_SATCFG_0101.XSD | - | N
1.2 | EO_OPER_INT_SATCFG_0102.XSD | - | R
2.0 | EO_OPER_INT_SATCFG_0200.XSD | - | R
Attitude File | 1.0 | EO_OPER_INT_ATTCFG_0100.XSD | - | N
1.1 | EO_OPER_INT_ATTREF_0101.XSD | Sat_1 | Y
Sat_2 | N
2.0 | EO_OPER_INT_ATTREF_0200.XSD | Sat_1 | N
Sat_2 | Y
Star tracker configuration File | 1.0 | EO_OPER_INT_STRCFG_0100.XSD | - | N
1.1 | EO_OPER_INT_STRCFG_0101.XSD | - | R
2.0 | EO_OPER_INT_STRCFG_0200.XSD | - | R
DEM Configuration File | 1.0 | EO_OPER_INT_DEMCFG_0100.XSD | - | N
1.1 | EO_OPER_INT_DEMCFG_0101.XSD | - | R
1.2 | EO_OPER_INT_DEMCFG_0102.XSD | - | R
1.3 | EO_OPER_INT_DEMCFG_0103.XSD | - | R
2.0 | EO_OPER_INT_DEMCFG_0200.XSD | - | R
Swath Definition File | 1.0 | EO_OPER_MPL_SW_DEF_0100.XSD | - | N
1.1 | EO_OPER_MPL_SW_DEF_0101.XSD | - | R
2.1 | EO_OPER_MPL_SW_DEF_0201.XSD | - | R
3.0 | EO_OPER_MPL_SW_DEF_0300.XSD | - | R
Swath Template File | 1.0 | EO_OPER_MPL_SWTREF_0100.XSD | - | N
1.1 | EO_OPER_MPL_SWTREF_0101.XSD | - | R
2.0 | EO_OPER_MPL_SWTREF_0200.XSD | - | R
2.1 | EO_OPER_MPL_SWTREF_0201.XSD | Sat_1 | Y
Sat_2 | N
3.0 | EO_OPER_MPL_SWTREF_0300.XSD | Sat_1 | N
Sat_2 | Y
Zone Database File | 1.0 | EO_OPER_MPL_ZON_DB_0100.XSD | - | N
1.1 | EO_OPER_MPL_ZON_DB_0101.XSD | - | R
1.2 | EO_OPER_MPL_ZON_DB_0102.XSD | - | R
2.0 | EO_OPER_MPL_ZON_DB_0200.XSD | - | R
Station Database File | 1.0 | EO_OPER_MPL_GND_DB_0100.XSD | - | N
1.1 | EO_OPER_MPL_GND_DB_0101.XSD | - | R
1.2 | EO_OPER_MPL_GND_DB_0102.XSD | - | R
1.3 | EO_OPER_MPL_GND_DB_0103.XSD | - | R
1.4 | EO_OPER_MPL_GND_DB_0104.XSD | - | R
2.0 | EO_OPER_MPL_GND_DB_0200.XSD | - | R
Precise Propagator Configuration File | 1.0 | EO_OPER_INT_PPRCFG_0100.XSD | - | R
2.0 | EO_OPER_INT_PPRCFG_0200.XSD | - | R