| Earth Observation Mission CFI Software DataHandling Software User Manual |

Earth Observation Mission CFI Software
DATAHANDLING SOFTWARE USER MANUAL

Code | EO-MA-DMS-GS-012
Issue | 4.4
Date | 05/07/12

| 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: | 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. | 27/03/09 |
4.1 | Second release - Issue in line with C 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. | 05/07/12 |
4.4 | Fifth release These libraries corresponds to version 4.4 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-017. Issue 4.4 05/07/12

## Reference Documents

[MCD] | Earth Observation Mission CFI Software. Conventions Document. EO-MA-DMS-GS-0001. Issue 4.4 05/07/12.
[MSC] | Earth Observation Mission CFI Software. Mission Specific Customizations. EO-MA-DMS-GS-0018. Issue 4.4 05/07/12.
[EE_COMMON_SUM] | Earth Observation Mission CFI Software. EECommon Software User Manual. EO-MA-DMS-GS-010. Issue 4.4 05/07/12.
[F_H_SUM] | Earth Observation Mission CFI Software. FileHandling Software User Manual. EO-MA-DMS-GS-011. Issue 4.4 05/07/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.

### Memory usage

Note: due to the implementation of the third-party library handling XML files, large amount memory may be needed by an application handling (reading of writing) a file with many entries. Therefore the user is recommended to perform handling of large files on computers equipped with adequate memory resources. If these resources are not available, the user has to properly configure virtual memory and take into account long execution times. In extreme cases, due to platform limitation or operating system settings, the operation may fail. In order to give an indication, a restituted orbit file covering a period of 10 days and a time interval between OSVs of 30 sec contains 28800 OSVs and its size on disk is about 14MB. The memory usage peak during the writing of such file is about 215MB.

# 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 DATA_HANDLING 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 GPL library:

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

To use the DATA_HANDLING 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
  -lCfiDataHandling -lCfiFileHandling -lCfiEECommon -lxml2 -lpthread
- MacOS:
  -Icfi_include_dir -Lcfi_lib_dir
  -lCfiDataHandling -lCfiFileHandling -lCfiEECommon -lpthread
  -framework libxml
- WINDOWS (dynamic libraries):
  /I "cfi_include_dir" /libpath:"cfi_lib_dir"
  libCfiDataHandling.lib libCfiFileHandling.lib libCfiEECommon.lib
- WINDOWS (static libraries):
  /I "cfi_include_dir" /libpath:"cfi_lib_dir"
  libCfiDataHandling.lib libCfiFileHandling.lib libCfiEECommon.lib libxml2.lib pthread.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;)

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, the xerces library has to be included in the LD_LIBRARY_PATH instead).

# ERROR HANDLING

The error management in C++ 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