Earth Observation Software
Orbit and Attitude Adapter Tool

Code
Issue	1.3
Date	08/11/2021

	Name	Function	Signature
Prepared by:	Juan José Borrego	Project Engineer
Checked by:	Inês Estrela	Project Manager
Approved by:	Inês Estrela	Project Manager

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.8.12
Electronic file name:

Document Status Log

Issue	Change Description	Date	Approval
1.0	First release This library is linked to EOCFI version 4.21 and DFDL4S 1.7.0	01/08/2021

Issue

Change Description

Date

Approval

1.0

First release
This library is linked to EOCFI version 4.21 and DFDL4S 1.7.0

01/08/2021

ACRONYMS, NOMENCLATURE AND TERMINOLOGY

Acronyms

ANX	Ascending Node Crossing
AOCS	Attitude and Orbit Control Subsystem
EOCFI	Earth Observation Customer Furnished Item
EOM	End Of Mission
ESA	European Space Agency
ESTEC	European Space Technology and Research Centre
GPL	GNU Public License
IERS	International Earth Rotation Service
OSF	Orbit Scenario File
SUM	Software User Manual
TAI	International Atomic Time
UTC	Coordinated Universal Time
UT1	Universal Time UT1

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

Reference Documents

[RD 1]	EOCFI documentation main page
[RD 2]	Earth Observation Mission CFI Software. Data Handling User Manual, v4.12
[RD 3]	Earth Observation Ground Segment File Format Standard
[RD 4]	Wikipedia: “Data Format Description Language"
[RD 5]	DFDL4S Project

INTRODUCTION

Purpose

The Earth Observation Mission Software (EOCFI SW) is a set of multiplatform software libraries which are made available free of charge to any user involved in supporting the Earth Observation missions preparation and exploitation. The EOCFI SW is typically used in Ground Segment operational facilities and in tools developed by ESA and their partners for Earth Observation Missions. The EOCFI SW libraries provide functionalities for a wide range of high-level computations: orbit (e.g. interpolation, propagation using different models); attitude (e.g. interpolation, attitude law); target pointing (e.g. direct/inverse geo-location with DEM); geometric properties of calculated targets; instrument swath computation and zone intersection; zone/station visibility events; observation opportunities for instruments (time segments and coverage). Low level functions are also provided, for example to support for several file formats read/write; co-ordinates / time transformations. The main inputs to the above functions are related to the satellite state. This information can be originated from different sources i.e.: models (e.g. propagators) implemented within the EOCFI SW itself; simulations or dedicated services (e.g. POD); S/C telemetry.

ESA

Data required to initialise the satellite state is typically:

a list of position and velocity at given times (OSVs);
a list of attitude parameters at a given times (e.g. quaternions, roll-pitch-yaw angles).

Such inputs can be passed to EOCFI functions via dedicated data structures or files. The EOCFI SW supports several types of files (see [RD 2]) and, in particular, orbit and attitude files compliant with the EO GS File Format Standard (see [RD 3]). However, very often such inputs may be made available using formats that are not directly supported by the EOCFI SW. For example, downlinked OSVs and quaternions are received within Instrument Source Packets (ISPs) whose format is mission dependent. Normally, for each specific format, a dedicated decoder needs to be implemented. The Orbit Attitude adapter tool preforms the translation between formats. The Orbit Attitude adapter tool / API receives as input:

Data (i.e. files) containing orbit and attitude;
Optionally, data format description in e.g. DFDL language (DFDL is “a modeling language for describing general text and binary data in a standard way“, see [RD 4]);
A main configuration file that includes the required configuration parameters (for example the parser that, for the DFDL language is the DFDL4S parser, see[RD 5]). And generating as output OSV and quaternions/rpy as lists in memory structures or files that can be ingested by EOCFI functions.

The Orbit Attitude Adapter Tool

The Orbit Attitude Adapter tool consists in:

An executable program that can be called from a command prompt window.
A JAVA library (a jar file ) that can be used in a JAVA program.

The executable program allows parsing input data files using a predefined parser that is already implemented in the tool. The JAVA library allows parsing the input data files using either a predefined parser or a CUSTOM parser that has to be implemented by the user. The current version allows the following predefined parsers:

DFDL4S parser.

INSTALLATION

Requirements

Software requirements:

Java 1.8
DFDL4S libraries v1.7.0
EOCFI libraries v4.21

Installation instructions

To install the library and the executable program just unzip the distribution archive EO_ADAPTER-X.X-JAVA-OS.zip (for example EO_ADAPTER-1.0-JAVA-LINUX64.zip) into an installation directory. The folder structure resultant of this action is as follows:

EO_ADAPTER: main folder containing the LICENSE and README files.
EO_ADAPTER/bin: Adapater tool ready to use from a command line.
EO_ADAPTER/examples: Ready-to-use example with a standalone Java program (including a script to compile and run).
EO_ADAPTER/files: It contains the schema and template for the configuration file.
EO_ADAPTER/lib: The EO Orbit and Attitude adapter library.
README and TERMS_AND_CONDITIONS.TXT

USAGE GUIDE

Executable program

An executable (in installation_folder/bin/EoOrbAttAdapter_CLI.sh) program is provided to parser the data files to EOCFI orbit and attitude files. This program can be called from a command prompt terminal in the following way:

>EoOrbAttAdapter_CLI.sh [ARGUMENTS]

[ARGUMENTS] list could be:
-help : Shows this help
-v : Shows library versions
-cfg "configuration_file" : Input configuration file (Mandatory)
-df "input_data_files" : Input data files. (Optional)
Several files can be provided separated by a blank space. If not provided, the data file will be taken from the "configuration file"
-of "output_orbit_file" : Output orbit file. (Optional)
If not provided, the output orbit file name will be taken from the "configuration file"
-af "output_attitude_file": Output attitude file. (Optional)
If not provided, the output attitude file name will be taken from the "configuration file"
-disableOrbitParser : Orbit parser disabled (Optional).
Orbit file will not be created.
-disableAttitudeParser : Attitude parser disabled (Optional).
Attitude file will not be created.

Example

> EoOrbAttAdapter_CLI.sh –cfg ./my_configuration_file.xml

Library Usage

In order to decode a data file using the JAVA library, the user can create its own parser (CUSTOM) or can use the predefined parsers. The parser to be used is set in the configuration file.

Using predefined parsers.

For using a predefined parser, the following steps should be given:

Import the tool package:
import EoOrbAttAdapter.*;
[OPTIONAL] Get the configuration for the tool (class AdpMainConfiguration).
Nominally the configuration is loaded from file (adapter_configuration_file. See section 5), although it could be set manually (see the API for AdpMainConfiguration in section 6).
AdpMainConfiguration adpConfig = new AdpMainConfiguration();

adpConfig.loadMainConfiguration("adapter_configuration_file");
Create the adapter (EoOrbAttAdapter class) and set the configuration.
The configuration can be set with the AdpMainConfiguration object if the step 2 was done, if not, the configuration can be set directly with the adapter_configuration_file:
EoOrbAttAdapter myAdapter = new EoOrbAttAdapter();

myAdapter.setMainConfiguration(adpConfig);

or
myAdapter.setMainConfiguration("./adp_configuration_file.xml");
Parse the data files.
The data file can be given as an input parameter or if it is not specified, the data file will be the given in the AdpMainConfiguration object. Note that several data files can be parsed so that all data will be joined together to be returned afterwards as a single file:
myAdapter.parse(); // parse the file in the AdpMainConfiguration object

or
myAdapter.parse(inputDataFile_1);

myAdapter.parse(inputDataFile_2);

myAdapter.parse(inputDataFile_3);

…
Get the orbit/attitude data and/or write the files to disk.
OrbitFile myOrbitFile = myAdapter.getOrbitData();

AttFile myAttFile = myAdapter.getAttitudeData();

myAdapter.writeOrbitDataToFile("./output_orbit_file.xml");

myAdapter.writeAttitudeDataToFile("./output_att_file.xml");

if the filename is not provided in the writing methods, the file name is taken from the AdpMainConfiguration object.

For an example of a predefined parser see Example 1.

Custom parser

In order to use a custom parser, the user has to implement the following JAVA classes:

A Class UserParser, that inherits the class AdpDefaultParser. This class has to override the abstract methods parseOrbit and parseAttitude. These methods are in charge of reading the data file and filling the output objects with the data.
For an example of a custom parser, see the class MyParser in Example 2.
A Class UserParserConfiguration that inherits the class AdpParserConfiguration. This class overrides the method loadFromFile. This method reads the configuration file, that is inside the path: /Earth_Explorer_File/Data_Block/Orbit_Attitude_Adapter_Configuration/Input_Configuration/ Parser_Configuration If the parser does not need any parameter from configuration, the method could be empty.

For an example of a custom parser configuration, see the class MyParserConfiguration in Example 2.

Once the custom parser is defined, the following steps should be given:

Import the tool package:
import EoOrbAttAdapter.*;
[OPTION 1] Set the adapter main configuration with a file:
2.1. Create the custom parser configuration
UserParserConfiguration parserConfig = new UserParserConfiguration();

2.2. Create the custom parser and set the configuration
UserParser myTextParser = new UserParser();

myTextParser.setParserConfiguration(parserConfig);

2.3. Create the adapter and set parser and configuration with an input file:
EoOrbAttAdapter myAdapter = new EoOrbAttAdapter();

myAdapter.setParser(myTextParser);

myAdapter.setMainConfiguration("./adp_configuration_file.xml");
Continue with steps 4 and 5 as for the predefined parser.

For an example of a custom parser see Example 2.

Examples

Several examples are provided in installation_folder/examples/example_# (#=1,2, 4, 5)
The explanations of the examples are inside the .java files.

Example 1

This example consists in parsing a Sentinel3 data file with DFDL4S format. For details, see the README file inside the example directory.

Example 2

This example consists in parsing a text file using a parser implemented by the user (Custom Parser). For details, see the README file inside the example directory.

Example 4

This example consists in parsing a data set provided as a byte array using the DFDL4S parser. For details, see the README file inside the example directory.

Example 5

This example consists in parsing a MetOPSG data file using the DFDL4S parser. For details, see the README file inside the example directory.

For running one example:

Go to the example directory:
>cd installation_folder/examples/example_# ((#=1,2, 4, 5)
Run the script example_compile_and_run.sh. This script compiles the example program (EoAdapterCustomExample.java) and executes it.
>cd ./example_compile_and_run.sh

CONFIGURATION FILE DESCRIPTION

Operations of the adapter are controlled by a main configuration file. This configuration file is compliant with Earth Observation file format standard. The following defines the sections enclosed in the Data Block relevant to the adapter configuration (i.e. header information is omitted).

<Data_Block type="xml">
    <Orbit_Attitude_Adapter_Configuration>
        <Input_Configuration>
            <Default_Values>...</Default_Values>
            <Parser_Configuration type=DFDL4S version=1.6.1>...</Parser_Configuration>
            <Common>...</Common>
        </Input_Configuration>
        <Output_Configuration>
            <Orbit>...</Orbit>
            <Attitude>...</Attitude>
            <Common>...</Common>
        </Output_Configuration>
    </Orbit_Attitude_Adapter_Configuration>
</Data_Block>

The file is composed by a node named Orbit_Attitude_Adapter_Configuration that contains Input_Configuration and Output_Configuration nodes:

Input Configuration

The <Input_Configuration> tag contains the following data:

Default Values: contains the tag Input_Data_Filename, that defines a default filename for the input data file. This file name is used only in case that the user did not provide explicitly a data file name in the tool inputs.
<Default_Values>

<Input_Data_Filename>...</Input_Data_Filename>

</Default_Values>
Parser Configuration: contains specific data for the parser configuration. In general the parser configuration tag has the following structure:
<Parser_Configuration type=... version=...>

<Schema_Filename>...</Schema_Filename>

<Orbit>...</Orbit>

<Attitude>...</Attitude>

</Parser_Configuration>

The content of the tags <Orbit> and <Attitude> are different depending on parser to be used. For the custom parser, it can be filled with tags chosen by the users to their needs. For the predefined parsers (as for the DFDL4S) the data structure is fixed (see the following subsections). For the custom parser, the reading of the tags inside <Orbit> and <Attitude> has to be implemented by the user. For this, the user has to create a class that implements the interface for AdpParserConfiguration. This interface contains a method (loadFromFile) where the <Parser_Configuration> can be read.
Common: This section contains:
- The Model section: it can be used to specify the model used by EOCFI computations. Only the DEFAULT model is supported;
- The Time_correlations section is used to define the relation amongst UTC, TAI, UT1, GPS. The method used depends on the type attribute:
  - FILE: the file defined in Time_correlations_file tag will be used.
  - FIXED_CORRELATIONS: the fields UTC_UT1, UTC_TAI, UTC_GPS will be used (e.g. UTC_UT1 = UTC time – UT1 time in seconds).
  - NONE: UTC_UT1 will be set to 0 and UTC_TAI / UTC_GPS to the values known by the tool.

<Common>
    <Model type=...\>
    <Time_Correlations type="...">
        <Time_Correlations_File>...</Time_Correlations_File>
        <Default_Values>
            <UTC_UT1 unit="s">...</UTC_UT1>
            <UTC_TAI unit="s">...</UTC_TAI>
            <UTC_GPS unit="s">...</UTC_GPS>
        </Default_Values>      
    <Time_Correlations>
</Common>

DFDL4S Parser configuration

As described above, the parser configuration tag contains three sections: the <Schema_Filename>, the <Orbit> and the <Attitude>, being the <Orbit> and the <Attitude> the specifics parts. For the DFDL4S are as follows:

<Parser_Configuration type=DFDL4S version=1.4>
   <Schema_Filename>...</Schema_Filename>
   <Orbit status=enabled>...</Orbit>
      <Mapping type="OSV">
         <Time_Reference>...</Time_Reference>
         <Time>...</Time>
         <Reference_Frame>...</Reference_Frame>
         <X correction_factor="..">...</X>
         <Y correction_factor="..">...</Y>
         <Z correction_factor="..">...</Z>
         <VX correction_factor="..">...</VX>
         <VY correction_factor="..">...</VY>
         <VZ correction_factor="..">...</VZ>
         <Orbit_number default="true">...</Orbit_number>
         <Quality default="true">...</Quality>
         <Default_Values>
            <Quality>...</Quality>
            <Orbit_Number type="OSF">
               <OSF_Filename>...</OSF_Filename>
            </Orbit_Mumber>
         </Default_Values>
      </Mapping>
   </Orbit>
        <Attitude status=enabled>
      <Mapping type="Quaternions">
         <Time_Reference>..</Time_Reference>
         <Time>...</Time>
         <Reference_Frame>...</Reference_Frame>
         <Q1 correction_factor="..">...</Q1>
         <Q2 correction_factor="..">...</Q2>
         <Q3 correction_factor="..">...</Q3>
         <Q4 correction_factor="..">...</Q4>
      </Mapping>
      <Axes_Mapping>
           <X>...</X>
           <Y>...</Y>
           <Z>...</Z>
      </Axes_Mapping>
   </Attitude>
</Parser_Configuration >

The Orbit section in the input configuration contains:

Attribute status: it can be “enabled or “disabled. When it is disabled, the orbit data will not be parsed.
The Mapping section: it defines the correspondence between items defining an orbit and elements in the DFDL4S schema. The type of mapping is defined by the type attribute (currently only OSV is allowed). The elements are described as a path from the root node. In particular:
- Time_Reference: either TAI, UTC, UT1 or N/A; It is the time reference for the read time;
- Time: the OSV epoch;
- Reference_Frame: Reference frame of the OSV (BAR_MEAN_2000, HEL_MEAN_2000, GEO_MEAN_2000, MEAN_DATE, TRUE_DATE, EARTH_FIXED, BAR_MEAN_1950, QUASI_MEAN_DATE, PSE_TRUE_DATE, PSEUDO_EARTH_FIXED);
- X, Y, Z: position. The correction_factor attribute defines a correction to be applied to the data in order to have the position consistent to EOCFI conventions (i.e. expressed in meters);
- VX, VY, VZ: position. The correction_factor attribute defines a correction to be applied to the data in order to have the velocity consistent to EOCFI conventions (i.e. expressed in meters/sec);
- Orbit_Number: Orbit number of the OSV. It contains the attribute default(=true or false).When default is true, the orbit number is not read from the file with the path but computed with an OSF specified below, in the Default_Values section.
- Quality: quality value of the OSV; It contains the attribute default(=true or false).When default is true, the quality is not read from the path specified, it will have the value specified below, in the Default_Values section.
- Default_Values: this section is used when the attribute default is set to true. It contains:
  - A default value of Orbit_Number (if its attribute type is set to “OSF (currently the only value allowed), the Orbit number will be calculated using an Orbit Scenario File).
  - A default value for Quality; All OSV will have the same quality value.

The Attitude section has a structure similar to the Orbit section:

Attribute status: it can be “enabled or “disabled. When it is disabled, the attitude data will not be parsed.
The Mapping section: it defines the correspondence between items defining an attitude and elements in the DFDL4S schema. The type of mapping is defined by the type attribute, it could be “Quaternions or “Angles. For Quaternions:
- Time_Reference: either TAI, UTC, UT1 or N/A; It is the time reference for the read time;
- Time: the quaternion epoch;
- Reference_Frame: Reference frame that is the origin frame for the rotation represented by the quaternions (BAR_MEAN_2000, HEL_MEAN_2000, GEO_MEAN_2000, MEAN_DATE, TRUE_DATE, EARTH_FIXED, BAR_MEAN_1950, QUASI_MEAN_DATE, PSE_TRUE_DATE, PSEUDO_EARTH_FIXED);
- Q1, Q2, Q3, Q4: Path for the Quaternions elements. Quaternions numbering follows the EOCFI conventions (i.e. Q4 is the real component).
For Angles:
- Time_Reference, Time and Reference_Frame: as defined for the quaternions.
- Rotation_Angle_1, Rotation_Angle_2, Rotation_Angle_3: Path for the rotation angle elements.
Axis_Mapping: Attitude data represent a transformation from two co-ordinate systems, for example GM2000 to satellite attitude frame. Axes of this attitude frame are not necessarily defined according to EOCFI conventions. The Axes_Mapping section provides the correspondence between co-ordinate system axes in EOCFI conventions and input data. For example: <X>Y_positive</X> means that the EOCFI X axos os the Y positive axis in the data convention.

Output Configuration

The <Output_Configuration> tag has the following tags (see example below):

Orbit: contains the configuration data required for the output orbit file.
Attitude: contains the configuration data required for the output attitude file.
Common: Contains the tag <Satellite_Id> with the satellite/mission name.

The <Orbit> and <Attitude> tags are have a similar structure. The content is as follows:

Attribute Type: it can be:
- EOCFI_FILE: the output is written to a EOCFI compliant file (currently this is the only value allowed).
Default_Filename: this is the filename used in case no filename is provided via the adapter interface. If the Default_Filename field is empty and no output file is specified via the adapter interface, the file name will be generated as per File Format Standard.
Time_Reference: Default Time reference. (Allowed values: TAI, UTC, UT1, N/A).
Reference_Frame: For the orbit file, it is the reference frame of the state vectors. For the attitude file, it is the reference frame for the source inertial frame. (Allowed values: BAR_MEAN_2000, HEL_MEAN_2000, GEO_MEAN_2000, MEAN_DATE, TRUE_DATE, EARTH_FIXED, BAR_MEAN_1950, QUASI_MEAN_DATE, PSE_TRUE_DATE, PSEUDO_EARTH_FIXED)
Target_Frame (only for Attitude): Attitude target frame (Allowed values: Sat_Nominal_Attitude, Sat_Attitude, Instr_Attitude). Header_Configuration defines the header fields as defined by the File Format Standard that cannot be generated automatically by the adapter:
- Notes
- File_Class
- File_Type
- File_Version
- Source/System

<Output_Configuration>
  <Orbit type=EO_FILE>
    <Default_Filename>...</Default_Filename>
    <Time_Reference>...</Time_Reference>
    <Reference_Frame>...</Reference_Frame>
    <Header_Configuration>
        <Notes>...</Notes>
        <Mission>...</Mission>
        <File_Class>...</File_Class>
        <File_Type>...</File_Type>
        <File_Version>...</File_Version>
        <Source>
            <System>...</System>
        </Source>        
    </Header_Configuration>
  </Orbit>
 
  <Attitude type=EO_FILE>
    <Default_Filename>...</Default_Filename>
    <Time_Reference>...</Time_Reference>
    <Reference_Frame>...</Reference_Frame>
    <Target_Frame>...</Target_Frame>
    <Header_Configuration>
        <Notes>...</Notes>
        <Mission>...</Mission>
        <File_Class>...</File_Class>
        <File_Type>...</File_Type>
        <File_Version>...</File_Version>
        <Source>
            <System>...</System>
        </Source> 
    </Header_Configuration>    
  </Attitude>
 
  <Common>
     <Satellite_Id>...<Satellite_Id>
  </Common>
<Output_Configuration>