Configuration

The Orekit library relies on some external data for physical models. Typical
data are the Earth Orientation Parameters and the leap seconds history, both being
provided by the IERS or the planetary ephemerides provided by JPL. Such data is
stored in text or binary files with specific formats that Orekit knows how to read.
These files can be embedded with an application built on top of Orekit or externally
provided.

Orekit must be configured appropriately to find and use such data.

Data sets

For user convenience, data that is only a few tens of kilobytes and can be assumed to
never change like precession-nutation models are already embedded in the core library.
Small and simple data sets are defined by setting constants in the code itself. This is
the case for the 32.184 seconds offset between Terrestrial Time and International Atomic
Time scales for example. Large or complex data sets are embedded by copying the
corresponding resource files inside the compiled jar, under the assets directory as is.
This is the case for the IAU-2000 precession-nutation model tables for example. There is
nothing to configure for these data sets as they are embedded within the library, so
users may ignore them completely.

Other types of data sets correspond to huge or changing data sets. These cannot
realistically be embedded within a specific version of the library in the long run. A
typical example for such data set is Earth Orientation Parameters which are mandatory for
accurate frames conversions. Another example is planetary ephemerides. IERS regularly
publishes new Earth Orientation Parameter files covering new time ranges whereas planetary
ephemerides represent megabytes-sized files. These data sets must be provided by users and
Orekit must be configured to find and read them at run time.

Data formats

In order to simplify data updates for users and to avoid transformations errors, Orekit
uses each supported data set in the native format in which it is publicly available. So
if a user wants to take into account the Earth Orientation Parameters for a given year,
for example, he will simply download the corresponding file for IERS server at
http://www.iers.org/IERS/EN/DataProducts/EarthOrientationData/eop.html
and drop it in the data storage system Orekit is configured to use, without any change
to the data file itself.

If a data set format changes or a new data set should be supported, a modification of the
reading classes inside Orekit would be needed. This design choice has been selected because
format changes remain rare (except IERS EOP data perhaps ...).

Data storage

Data sets must be stored at locations where the Orekit library will find them. This may
be simply a directories tree on a disk, but may be almost anything else as this simple
solution would not fit all uses of the library.

The following use cases show different possible data storage strategies. All of them
can be handled by Orekit plugin mechanism. Most of the plugins are already available
in the library itself.

  • Application used from a few operator's desks in a control center without external
    network connections

    In this case, data may be stored in the main operational database, relying on the
    existing administration procedures (updates, backup, redundancy ...).

  • Simulation tool on a desk computer for everyday studies

    For everyday local use of a tool, data will mainly be stored in the user environment.
    A traditional architecture will involve two main data stores, one on a network shared
    disk for large general data sets handled at department level and another one as simple
    files on the local user disk where he can put his own data sets for specific purposes.
    The local data files may be set up in order to override system-level values for
    special cases.

  • New program added to an existing tools suite

    If a program using Orekit is integrated in an existing environment with its own
    established data management system, the library must be configured to use this system
    to retrieve the data instead of using its own internal system. This enables
    smoother integration. It also simplifies system administration of the complete
    suite. It may even allow sharing some of its data with other tools.

  • Standalone application on a small networked device

    An application used on a small device with network access (say a mobile phone), may
    be simpler to set up and use if it does not store the data at all on the device
    itself but retrieves it on the fly from the web when needed.

  • Computation service in an application server

    A service installed on an application server may be simpler to configure if, rather
    than using explicit files locations on the server, one stores the data in the
    application classpath where it will be managed by the application server together
    with the application code itself.

  • Small demonstration program distributed using Java WebStart for instant download/use

    A demonstration program can be distributed using Java WebStart so that any user can
    download it and try it almost instantly from a public web site. If the application is
    not signed, it will run in a sandbox environment for security reasons (the application
    is not trusted). The sandbox prevents access to the user disk. Data must be embedded
    within the application jar file, in the internal classpath.

Data handling in Orekit

The following diagram shows data handling in Orekit.

data class diagram

There is no mandatory layout within the data directories trees or zip/jar archives. Orekit
navigates through them and their sub-directories when looking for data files. Files are
identified by pattern matching rules on their names. Files that don't match the rules are
silently ignored. This allows the user to share the data directories trees with other tools
which need a specific layout or additional files. The layout presented in the figure above
is a simple example.

As with any other Java property, orekit.data.path can be initialized at application launch time by
the user (for example using the -D flag of the virtual machine) or from within the application
by calling the System.setProperty method. In the latter case, rather than the literal string
constants orekit.data.path, the OREKIT_DATA_PATH static field from the DataProvidersManager
class can be used. If the property is set up by the application, it must be done before any Orekit
feature is called, since some data are initialized very early (mainly frame and time related data
like leap seconds for UTC).

Setting up a customized configuration

If the default configuration doesn't suit users needs, a custom configuration must be set up.
This happens for example if data must be embedded within the application and loaded from
the classpath. This also happens if the data must be retrieved from a dynamic or virtual
storage medium like a database, a web site or a local data handling library.

The configuration corresponds to the list of data providers stored in the DataProvidersManager
singleton. In order to set up a custom configuration, the singleton must be purged and specific
data providers must be added in an appropriate order.

The data providers predefined by the Orekit library are the following ones:

  • DirectoryCrawler for loading files in a directory tree specified by its root
  • ZipJarCrawler for loading files stored in a zip or jar archive
  • ClasspathCrawler for loading files stored as resources in the classpath
  • NetworkCrawler for downloading files from remote hosts (it can be directly from internet sites through a corporate proxy server)

Users can also add their own implementations of the DataProvider interface and
register them to the DataProvidersManager singleton. Typical examples of user
defined implementations are providers fetching data from a relational database or
providers fetching data using an external library. This corresponds to the plugin feature
announced above.

Quick setup using default data

For convenience, a zip file containing some default data is available for
download on orekit forge:
https://www.orekit.org/forge/projects/orekit/files.
For a start, the simplest configuration is to download the orekit-data.zip file from the download page,
to unzip it anywhere you want, note the path of the orekit-data folder that will be created and add the
following lines at the start of your program:

File orekitData = new File("/path/to/the/folder/orekit-data");
DataProvidersManager manager = DataProvidersManager.getInstance();
manager.addProvider(new DirectoryCrawler(orekitData));

This zip file contains JPL DE 430 ephemerides from 1990
to 2069, IERS Earth orientation parameters from 1973
to June 2016 with predicted date to fall 2016 (both IAU-1980
and IAU-2000), UTC-TAI history from 1972 to end of 2016,
Marshall Solar Activity Futur Estimation from 1999 to mid 2016,
the Eigen 06S gravity field and the FES 2004 ocean tides model.

Supported data types

The data types supported by Orekit are described in the following table, where the #
character represents any digit, (m/p) represents either the m character or the p
character and * represents any character sequence. The [.gz] part at the end of all
naming patterns means that an optional .gz suffix can be appended, in which case the
data are considered to be compressed with gzip.

Earth Orientation Parameters are provided by observatories in many different formats
(Bulletin A, several different formats of Bulletin B, EOP 08 C04, finals file combining
both Bulletin A and Bulletin B information ...). They are also provided for different
precession-nutation models (IAU-1980 and IAU-2006/2000A). Orekit supports all of these
formats and supports both precession-nutation models. Two different
naming patterns for Bulletin B are supported by default. Both the old Bulletin B format
used up to 2009 and the new format used since 2010 are supported. The supported formats
for finals2000A files for IAU-2006/2000A and the finals files for IAU-1980 are both
the XML format and the columns format.

default naming pattern format data type source
tai-utc.dat[.gz] USNO tai-utc leap seconds introduction history http://maia.usno.navy.mil/ser7/tai-utc.dat
UTC-TAI.history[.gz] IERS history leap seconds introduction history http://hpiers.obspm.fr/eoppc/bul/bulc/UTC-TAI.history
bulletina-xxxx-###.txt[.gz] IERS Bulletin A weekly Earth Orientation Parameters, IAU-1980 and IAU-2000, rapid service and prediction ftp://ftp.iers.org/products/eop/rapid/bulletina/
bulletinb.###[.gz] IERS Bulletin B monthly Earth Orientation Parameters model IAU 2006/2000A, final values ftp://ftp.iers.org/products/eop/bulletinb/format_2009/
eopc04_08_IAU2000.##[.gz] IERS EOP 08 C04 yearly Earth Orientation Parameters model IAU 2006/2000A ftp://ftp.iers.org/products/eop/long-term/c04_08/iau2000/
eopc04_08.##[.gz] IERS EOP 08 C04 yearly Earth Orientation Parameters model IAU 1980 ftp://ftp.iers.org/products/eop/long-term/c04_08/iau1980/
finals2000A.*.[.gz] IERS standard EOP Earth Orientation Parameters model IAU 2006/2000A ftp://ftp.iers.org/products/eop/rapid/standard/finals2000A.all
finals.*.[.gz] IERS standard EOP Earth Orientation Parameters model IAU 1980 ftp://ftp.iers.org/products/eop/rapid/standard/finals.all
finals2000A.*.xml[.gz] IERS standard EOP Earth Orientation Parameters model IAU 2006/2000A ftp://ftp.iers.org/products/eop/rapid/standard/xml/finals2000A.all.xml
finals.*.xml[.gz] IERS standard EOP Earth Orientation Parameters model IAU 1980 ftp://ftp.iers.org/products/eop/rapid/standard/xml/finals.all.xml
(l/u)nx(m/p)####.4##[.gz] DE 4xx binary JPL DE 4xx planets ephemerides ftp://ssd.jpl.nasa.gov/pub/eph/planets/Linux/
inpop*m####p####*.dat[.gz] DE 4xx binary IMCCE inpop planets ephemerides ftp://ftp.imcce.fr/pub/ephem/planets/
eigen_*_coef SHM format Eigen gravity field (old format) http://op.gfz-potsdam.de/grace/results/main_RESULTS.html#gravity
*.gfc, g###_eigen_*_coef ICGEM format gravity fields from International Centre for Global Earth Models http://icgem.gfz-potsdam.de/ICGEM/modelstab.html
egm##_to#* EGM format EGM gravity field ftp://cddis.gsfc.nasa.gov/pub/egm96/general_info
Jan####F10.txt to Dec####F10.txt MSAFE format Marshall Solar Activity Future Estimation http://sail.msfc.nasa.gov/archive_index.htm

Supported data types

data-class-diagram.png - data class diagram (144 KB) Luc Maisonobe, 2014-07-01 13:43

directories-tree.png - directories tree (57 KB) Luc Maisonobe, 2014-07-01 13:44