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 the application or externally provided.
Orekit must be configured appropriately to find and use such data.
For user convenience, data that is only a few tens of kilobytes and can be assumed to never change like precession-nutation models or atmospheric 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 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 META-INF directory as is usual with the Java language. 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.
Other types of data sets correspond to huge or changing data sets. These ones cannot realistically be embedded within a specific version of the library on the long run. A typical example for such data set is Earth Orientation Parameters which are mandatory for accurate frames conversion, 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.
User provided data sets must be stored as files using one of the supported formats within either directories trees or zip archives with read access permission.
Any number of directories trees or zip archives may be used. This allows for example system administrators to set up a zip archive in a network shared disk for system-wide use in an office department and individual users to provide their own data sets in addition to (or in replacement of some of) the system-wide data by setting up local directories trees or zip archives on their local disk.
Directories trees or zip archives may be used interchangeably. They both basically represent container for files or other directories trees or zip archives. Orekit opens zip archives on the fly and crawls into them as if they were regular directories, without writing anything to disk. Data files may also be compressed using gzip to save some disk space. Compressed files are also uncompressed directly in memory. Compressing text-based files like bulletinB or EOPC04 saves a lot of disk space, but compressing the JPL binary files does almost not save anything. Using compressed files inside a zip archive is also irrelevant as zip files are themselves compressed and stacking compression algorithm only slows down reading speed without any disk space gain.
Since nothing is written to disk (there are no temporary files), user provided data sets may be stored on non-writable media like disk partitions with restricted access or CD/DVD.
There is no mandatory layout within the data directories trees or zip 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. A drawback of this behavior is that if the users sets up a deep data directory tree containing a huge number of files, Orekit may need some time to explore it (but it will only open the files it knows about). The layout presented in the figure above is a simple example.
There is only one configuration parameter for Orekit, a java property named orekit.data.path . This property should be set to a colon or semicolon separated list of directories trees and zip archives containing the data files Orekit can use.
When some data type is searched for (say for example Earth Orientation Parameters from IERS), the path components are used sequentially in the order they are given. If the search succeeds while one component is explored, the data found will be returned without exploring the remaining components of the path, they will be ignored for this search. This feature allows users to provide their own version of some system-wide data (EOP data in our example) if they want, without being obliged to overwrite other types (like JPL ephemerides for example).
As 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 DataDirectoryCrawler 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).
For convenience, a 2.5 megabytes zip file containing some default data is available for download on orekit site: http://www.orekit.org/downloads/orekit-data.zip . Setting the orekit.data.path property to the location of this file on a local computer is enough to use Orekit efficiently. This zip archive contains Earth OrientationParameters from 1962 to 2008, JPL DE 406 ephemerides from 1962 to 2029 and UTC TAI history from 1972-01-01 to 2006-01-01. As explained below, Orekit also has some embedded data, so despite the leap second that will be introduced at the end of 2008 is not in the file, it is already known to Orekit.
The data files supported by Orekit are described in the following table, where the # character represents any digit and (m/p) represents either the m character or the p character. The [.gz] part at the end of all naming patterns means that a .gz suffix can be appended, in which case the files are considered to be compressed with gzip.
| file naming pattern | format | data type | source |
| UTC-TAI.history[.gz] | IERS history | leap seconds introduction history | http://hpiers.obspm.fr/eoppc/bul/bulc/UTC-TAI.history |
| bulletinb_IAU2000-###.txt[.gz] | IERS bulletin B | monthly Earth Orientation Parameters | http://www.iers.org/MainDisp.csl?pid=36-25788&prodid=18 |
| eopc04_IAU2000.##[.gz] | IERS EOP 05 C04 | yearly Earth Orientation Parameters | http://www.iers.org/MainDisp.csl?pid=36-25788&prodid=179 |
| unx(m/p)####.405[.gz] | DE 405 binary | JPL DE 405 planets ephemerides | ftp://ssd.jpl.nasa.gov/pub/eph/planets/unix/de405 |
| unx(m/p)####.406[.gz] | DE 406 binary | JPL DE 406 planets ephemerides | ftp://ssd.jpl.nasa.gov/pub/eph/planets/unix/de406 |
It is possible to use Orekit in some restricted way without configuring any data sets.
Since time is use throughout the library, the known history of leap seconds introduction at time of publication is already embedded in the library, thus allowing to work without the UTC-TAI.history for a short period of time (up to next leap second introduction after library publication). As of version 4.0, the embedded history includes all leap seconds introduced from 1972-01-01 to 2009-01-01.
The Earth Orientation Parameters are used only for conversions involving ITRF2005. If this frame is not used at all, then the bulletin B and EOP 05 C04 files are not needed. If the ITRF2005 frame is used but the files are not available (which is always the case when using dates a few months in the future), no error is triggered and the pole correction is simply set to 0. This induces an angular error in position. The order of magnitude of this error is about 15 meters at Earth surface.
The JPL ephemerides are used whenever Sun, Moon or solar system planets are used. As of version 4.0 of the library, there is no way to use these celestial bodies without the corresponding ephemerides.