Keywords | Ephemeris Formats

Ephemeris File Format (*.e)

An ephemeris file is an ASCII text file formatted for compatibility with STK that ends in a .e extension. Ephemeris files can be useful when you need to provide STK with position and velocity data for a vehicle to model certain unique circumstances. Vehicle ephemeris is a Basic property of all vehicles in STK. The ephemeris data - organized in a properly formatted table - in any ephemeris file can be imported into STK using the StkExternal propagator.

STK uses ephemeris data to generate the position and velocity of a vehicle at whatever time values it needs to support analysis and animation. When necessary, STK will interpolate between points to do so. Interpolation is performed in the same coordinate frame (inertial or fixed) that the data is supplied in.

  • The reference coordinate frame is specified using the CentralBody, CoordinateSystem, and CoordinateSystemEpoch keywords.
  • Dates that are in Julian Data format can be entered in scientific notation.
  • STK imported ephemeris files for orbiting objects are expected to have at least 90 points per complete revolution around the central body.

The first step in creating an external ephemeris file is to understand what type of ephemeris data you need. Before starting to create a file, you should ask yourself the following questions:

How is the data formatted? Is it in Cartesian X, Y, Z coordinates; geodetic latitude, longitude, and altitude; or geocentric latitude, longitude, and radius?

What coordinate system is the data in? Is it in an inertial frame? If so, which inertial frame is it? or Is it a fixed frame?

Once you know the answers to these questions, you can use keywords recognized by STK to create a table that describes the position and velocity of the vehicle.

Keywords

Each ephemeris table, regardless of the type of ephemeris data in the table, contains some common elements called keywords. Keywords and their associated values must precede the specification of the ephemeris format and the actual data points.

The keywords used in ephemeris tables are not case-sensitive, and do not have to conform to the case scheme utilized here.

Keyword Required Description
stk.v.<major release number>.<minor release number> Yes

The version of STK software for which the file is formatted to be used.

Files can be created in and imported to STK software versions consistent with the file version stamp or higher.

The version stamp must be the first line in the ephemeris file.

Example:
stk.v.11.0

BEGIN Ephemeris
END Ephemeris
Yes Sets off the beginning and end of the ephemeris table, including all other keyword phrases and data point specification (except the version stamp). Refer to any of the sample files included in the Ephemeris Format section for examples.
ScenarioEpoch No

The reference epoch time for the time values of the ephemeris data in the table, where the times are represented as seconds since it's a reference epoch. Specify the scenario epoch using Gregorian UTC time (dd mmm yyyy hh:mm:ss.s). There is no relationship between the scenario epoch specified in the ephemeris table and the actual scenario epoch in your STK scenario. See also TimeFormat.

Default is the actual scenario epoch in the STK scenario.

Example:
ScenarioEpoch 1 Jan 2003 00:00:00.0

In this case, a time of 5.5 for a particular ephemeris point would correspond to a time of 1 Jan 2003 00:00:05.5.

Keyword History

The ScenarioEpoch keyword was introduced in an STK version that was earlier than STK 4.1.0.

CentralBody No

The central body to which the ephemeris points are relative. The keyword value that completes the phrase can be the name of any registered central body. Registered central bodies can be found in the STKData\CentralBodies directory.

Default is the central body for the vehicle, and Earth by default.

Example:

CentralBody Earth

Keyword History

The CentralBody keyword was introduced in an STK version that was earlier than STK 4.1.0.

SmoothData No

Declares that the files contain smooth data.

Smoothness of data impacts sampling characteristics of STK calculations, such as Access, calculation components, lighting times, etc. Non-smooth data is sampled judiciously around each time sharp changes may occur.

Without a TrendingControl section or SmoothData keyword, smoothness of ephemeris data is determined based on vehicle and propagator types. Ground vehicle, ship, and aircraft objects, as well as any file that declares interpolation to be based on a great arc type, are assumed to have non-smooth data. Otherwise, data is assumed to be smooth.

The SmoothData keyword is used only if the TrendingControl Section does not specify a time listing. If no TrendingControl section is specified, the Smooth Data setting specifies the smoothness of the data.

Valid values are Yes, No, True, False, On, and Off. Default is No.

Keyword History

The SmoothData keyword, with Yes and No values, was introduced in STK 10.1.0.

Additional values (True, On ,False, and Off) for this keyword were introduced in STK 11.2.0.

Begin TrendingControl

End TrendingControl

No

These keywords mark the beginning and end of the TrendingControl section. STK will sample the data in this section when determining trends for event detection. For example, a drastic change in motion may indicate an event (especially if the change is brief).

The TrendingControl section can include either the TrendingControlTimes subsection or the TrendingControlStep.

Keyword History

The TrendingControl keywords were introduced in STK 11.6.0.

Begin TrendingControlTimes

End TrendingControlTimes

No

You can include TrendingControlTimes section in the file if the TrendingControlStep keyword is not used.

This section contains a list of times (1 per line) that should be sampled for determining trends for event detection.

If a TimeFormat keyword precedes this section, then this section must adhere to the format. Otherwise, the times are in seconds since the ScenarioEpoch is specified in the file.

Keyword History

The TrendingControlTimes keywords were introduced in STK 11.6.0.

TrendingControlStep No

You can include the TrendingControlStep keyword in the file if the TrendingControlTimes section is not used.

The keyword specifies the step size, in seconds, that STK will use when sampling times in the file. STK will select samples as far apart as possible without exceeding the step size. Controlling the step size is most useful when the sample times in a file are dense. STK will sample at a lower density than the file's data, but the points will still be close enough to detect drastic changes in motion.

Keyword History

The TrendingControlStep keyword was introduced in STK 11.6.0.

CoordinateSystem No

Recommended, though not required.

The coordinate system in which the ephemeris points reside. Normally, the coordinate system is the name of a valid coordinate system for the central body specified above (see Central Body Coordinate Systems). Typically, each central body supports Fixed, J2000, ICRF, Inertial, TrueOfDate, and MeanOfDate though certain bodies support additional systems.

You can also define a new system using the Vector Geometry Tool (VGT). You can then specify the name of your new system and the name of the STK object to which it corresponds. It is required that the VGT-created system use the keyword CoordinateSystem AWB.


CoordinateSystem AWB replaces CoordinateSystem Custom as the required keyword for VGT-created systems. The CoordinateSystem Custom keyword is still supported for backward compatibility.


Default is Fixed.


Examples:
CoordinateSystem TrueOfEpoch
CoordinateSystem AWB TopoCentric Facility/MyLaunchSite

  • The name of the STK object is optional if the object that is importing the ephemeris is the object to which the coordinate system corresponds.
  • If you specify a coordinate system that is unknown to STK, the default fixed coordinate system will be used.

Keyword History

The CoordinateSystem Custom keyword was introduced in 4.4.0 as an indicator of a VGT System

The CoordinateSystem Custom keyword was replaced with the CoordinateSystem AWB keyword in 11.5.0.

The CoordinateSystem AWB keyword was introduced in 11.5.0.

CoordinateSystemEpoch See Note The epoch time for the coordinate system in Gregorian UTC time (dd mmm yyyy hh:mm:ss.s).

Required with coordinate systems that reference an Epoch:

  • MeanOfEpoch
  • TrueOfEpoch
  • TEMEOfEpoch
  • AlignmentAtEpoch

Example:

CoordinateSystemEpoch 1 Jun 2003 12:00:00.0

Keyword History

The CoordinateSystemEpoch keyword was introduced in an STK version that was earlier than STK 4.1.0.

DistanceUnit No

Set the distance unit to be used for all distance measurements in the ephemeris table. By default, STK assumes that all distance measurements in an ephemeris table are in meters and velocities are in meters/second. This may be overridden by setting the distance unit to be any valid STK distance unit.

To see a list of all available units of measure, open the Units page of the Scenario's Basic properties by double-clicking the scenario in the Object Browser and selecting the Units page.

Default for velocity is meters per second.

Default for the ephemeris table is meters.

Example:
DistanceUnit Kilometers

Keyword History

The DistanceUnit keyword was introduced in an STK version that was earlier than STK 4.1.0.

BlockingFactor No

Specifies how much memory (in terms of sets of ephemeris points) will be allocated at a time while reading an ephemeris file. When reading large files, this can speed up the loading process by avoiding re-allocating small chunks of memory.

Keyword History

The BlockingFactor keyword was introduced in STK version 4.3.0.

InterpolationMethod No

The method by which STK interpolates between ephemeris points. Valid values are:

  • Lagrange (Default)
  • Hermite - Allows you to take advantage of velocity information, if available, in order to achieve smoother ephemeris interpolation. It may be especially useful when using tables containing very irregularly spaced data points or data that can be susceptible to ringing and aliasing effects if derivative information is not considered during interpolation. Hermitian interpolation assumes that the velocity component of the ephemeris is the derivative of the position. Hermitian interpolation should not be used when velocity data is not available as part of the ephemeris table.
  • LagrangeVOP - When using this method, be sure to set the required mu value (see example below)
  • GreatArc - Fixed reference frame method. Interpolate as a great arc vehicle on WGS84.
  • GreatArcTerrain - Fixed reference frame method. Interpolate as a great arc vehicle using Terrain.
  • GreatArcMSL - Fixed reference frame method. Interpolate as a great arc vehicle using MSL.

Default is Lagrange.

Examples:
InterpolationMethod Hermite
InterpolationMethod LagrangeVOP 3.98600441500e+14

Keyword History

The InterpolationMethod keyword was introduced in STK version 4.3.0.

The Hermite value was added in 4.4.0.

The GreatArcTerrain, GreatArcOnTerrain, Gator, and AdvAircraft values were added in 6.2.0.

The GreatArcMSL and MissionModeler keywords were added in 7.0.0.

The TwoBodyBlending, J2Blending, J4Blending and Aviator values for this keyword were introduced in 11.0.0.

InterpolationOrder No

This keyword has been deprecated and replaced with InterpolationSamplesM1; it has the same format and function as its replacement.

Keyword History

The InterpolationOrder keyword was introduced in an STK version that was earlier than STK 4.1.0.

InterpolationSamplesM1 No

One less than the number of points used in the interpolation. For the Lagrange interpolation method, this is also the interpolation order. For the Hermitian interpolation method, the interpolation order is:
(2 x InterpolationSamplesM1) + 1.

Default is 5.

Example:
InterpolationSamplesM1 5

Keyword History

The InterpolationSamplesM1 keyword was introduced in STK version 5.0.4.

NumberOfEphemerisPoints No

Recommended though not required. When specified, indicates the maximum number of ephemeris points to read from the file. When not specified, all ephemeris points in the file will be used.

Prior to STK 11.5, this keyword was required.

Example:

If you enter
    NumberOfEphemerisPoints 1000

up to 1000 ephemeris points would be read.

Keyword History

The NumberOfEphemerisPoints keyword was introduced in an STK version that was earlier than STK 4.1.0.

NumberOfCovariancePoints No

Recommended though not required. When specified, indicates the maximum number of covariance points to read from the file. When not specified, all covariance points in the file will be used.

The NumberOfCovariancePoints keyword was introduced in STK version 4.3.0.

Example:
If you enter

    NumberOfCovariancePoints 1000

Up to 1000 covariance points would be read.

Keyword History

The NumberOfCovariancePoints keyword was introduced in STK version 4.3.0.

CovarianceInterpolationMethod No

Determines the method for interpolating covariance that contains both position and velocity terms.

Valid values are None and TwoBodyQuadraticArithmeticBlending.

Default is TwoBodyQuadraticArithmeticBlending for Satellites and None for other vehicles.

TwoBodyQuadraticArithmeticBlending refers to the weighted average (with weights based on a quadratic in time polynomial) of the covariance matrices computed using two-body covariance propagation from the previous and next time samples. This is only appropriate for objects whose motion is dominated by two-body motion (i.e., satellites orbiting a central body).

Keyword History

The CovarianceInterpolationMethod keyword was introduced in STK version 11.0.0.

CovarianceFormat No

Specifies the portion of the covariance matrix that will appear in the CovarianceTimePos or CovarianceTimePosVel sections of the file. Valid values are:

  • LowerTriangular
  • LT
  • UpperTriangular
  • UT

If LowerTriangular or LT is specified, the order of entries is assumed to be:

C[0][0]
C[1][0] C[1][1]
C[2][0] C[2][1] C[2][2]
   .
   .
   .

If UpperTriangular or UTis specified, the order of entries is assumed to be:

C[0][0] C[0][1] C[0][2] . . .
        C[1][1] C[1][2] . . .
                C[2][2] . . .
                   .
                   .
                   .

The default for CovarianceTimePos is UpperTriangular; the default for CovarianceTimePosVel is LowerTriangular.

Keyword History

The CovarianceFormat keyword was introduced in STK version 6.0.0.

BEGIN SegmentBoundaryTimes
END SegmentBoundaryTimes
No

Sets off the beginning and end of a list of time values (relative to the time specified using the ScenarioEpoch keyword) in ascending order. During interpolation of the ephemeris, the interpolator will not choose reference points that span across a time listed between the BEGIN SegmentBoundaryTimes and END SegmentBoundaryTimes keywords. For this reason, the ephemeris table is permitted to contain more than one ephemeris point at the same time as long as it is listed as a time in the SegmentBoundaryTimes section. This mechanism is especially convenient when modeling the pre and post instantaneous maneuver ephemeris states. This is the only time when duplicate time values are allowed when specifying ephemeris points. By convention, a blank line is left between duplicate points to make them easier to visually discern.

Example:

BEGIN SegmentBoundaryTimes

2.90998893289423e+003

7.61935679863377e+003

END SegmentBoundaryTimes

Keyword History

The  SegmentBoundaryTimes keyword was introduced in an STK version that was earlier than STK 4.1.0.

TimeFormat No

Specifies a keyword defining the date format of time tags. If set, each line of data in the file begins with a time in the specific date format followed by the rest of the data.

Spaces are valid whenever the format admits them (e.g., 1 Jan 2007 12:00:00.000).

Quotes around time strings are invalid.

The TimeFormat keyword is the time format abbreviation; e.g., EpSec for Epoch Seconds or JDate for Julian Date. For time format abbreviations, see DateTime Formats.

Examples:

TimeFormat DD/MM/YYYY

TimeFormat GPSZ

Keyword History

The TimeFormat keyword was introduced in STK version 9.0.0 and was used only for ephemeris.

Starting with STK 11.6, this keyword also works for covariance.

TimeScale No

Specifies that the times contained in the ephemeris and covariance sections should be interpreted as being in the TDB time scale, not TAI.

Value is TDB.

Keyword History

The TimeScale keyword was introduced in STK version 8.1.0.

Ephemeris Formats

While the sections above outline the basic format for an ephemeris table, the list below outline the formats used to specify actual data points in the ephemeris table. The format keyword must be included in the file on its own line, after the header keywords and before the actual data point array.

The following conventions must be observed when specifying data points in any format:

  • Each line contains only one data point.
  • The values on each line must be separated by at least one space.
  • The lines must be listed in ascending order in time but do not have to be evenly spaced in time.
  • You cannot have multiple points at the same time (except as described in the SegmentBoundaryTimes section).
  • There must be at least as many points as specified by the NumberOfEphemerisPoints and/or NumberOfCovariancePoints keywords.

To view information on a particular format, click that precedes the format name.

Systems Tool Kit (STK),  v11.7;  Latest Help Update: December, 2019