Earth Explorer Mission CFI Software
DATAHANDLING SOFTWARE USER MANUAL

Code	EE-MA-DMS-GS-012
Issue	1.0
Date	27/03/2009

	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
Contract Number:	15583/01/NL/GS	Public
Contract Issuer:	ESA / ESTEC	Industry	X
Contract Issuer:	ESA / ESTEC	Confidential

External Distribution
Name	Organization	Copies

Electronic handling
Document generator:	Doxygen 1.5.8
Electronic file name:	ee-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

ACRONYMS AND NOMENCLATURE

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)

APPLICABLE AND REFERENCE DOCUMENTS

Applicable Documents

[GEN_SUM] Earth Explorer Mission CFI Software. General Software User Manual. EE-MA-DMS-GS-017. Issue 1.0 27/03/09

Reference Documents

[MCD] Earth Explorer Mission CFI Software. Mission Conventions Document. EE-MA-DMS-GS-0001. Issue 1.4 0208/07.

[EE_COMMON_SUM] Earth Explorer Mission CFI Software. EECommon Software User Manual. EE-MA-DMS-GS-010. Issue 1.0 27/03/09.

[F_H_SUM] Earth Explorer Mission CFI Software. FileHandling Software User Manual. EE-MA-DMS-GS-011. Issue 1.0 27/03//09.

[D_H_SUM] Earth Explorer Mission CFI Software. DataHandling Software User Manual. EE-MA-DMS-GS-012. Issue 1.0 27/03/09.

[IERS] http://www.iers.org/iers/publications/bulletins/

INTRODUCTION

Classes Overview

This software library contains a set of classes for reading and writing Earth Explorer 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 Explorer 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 Explorer 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

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 (see [GEN_SUM])
POSIX thread library: libpthread.so (pthread.lib for WINDOWS)

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):

SOLARIS/LINUX:
-Icfi_include_dir -Lcfi_lib_dir
-lCfiDataHandling -lCfiFileHandling -lCfiEECommon -lxml2 -lpthread
WINDOWS:
/I "cfi_include_dir" /libpath:"cfi_lib_dir"
libCfiDataHandling.lib libCfiFileHandling.lib libCfiEECommon.lib libxml2.lib pthread.lib
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 EECFI libraries are dynamic, cfi_lib_dir must be included in the path where the system looks for dynamic libraries (LD_LIBRARY_PATH in LINUX and SOLARIS, 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 and SOLARIS, 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].

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

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)

[MCD]	Earth Explorer Mission CFI Software. Mission Conventions Document. EE-MA-DMS-GS-0001. Issue 1.4 0208/07.
[EE_COMMON_SUM]	Earth Explorer Mission CFI Software. EECommon Software User Manual. EE-MA-DMS-GS-010. Issue 1.0 27/03/09.
[F_H_SUM]	Earth Explorer Mission CFI Software. FileHandling Software User Manual. EE-MA-DMS-GS-011. Issue 1.0 27/03//09.
[D_H_SUM]	Earth Explorer Mission CFI Software. DataHandling Software User Manual. EE-MA-DMS-GS-012. Issue 1.0 27/03/09.
[IERS]	http://www.iers.org/iers/publications/bulletins/