DEIMOS
Earth Observation Software
Orbit and Attitude Adapater Tool
 ESA

Earth Observation Software
Orbit and Attitude Adapter Tool
Code
Issue 1.4
Date 31/08/2023
  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  
Public  
Contract Issuer: ESA / ESTEC Industry X
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.25 and DFDL4S 1.7.0 		31/08/2023

 

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:

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:

The Orbit Attitude Adapter Tool

The Orbit Attitude Adapter tool consists in:

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:

INSTALLATION

Requirements

Software requirements:

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:

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:

  1. Import the tool package:
    import EoOrbAttAdapter.*;
  2. [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");
  3. 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");
  4. 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);
    …
  5. 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:

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:

  1. Import the tool package:
    import EoOrbAttAdapter.*;
  2. [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");
  3. 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:

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:

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

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

Output Configuration

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

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

<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>
Generated on Tue Nov 28 2023 19:35:30 for by doxygen 1.8.13