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.

NOTE: The reference coordinate frame is specified using the CentralBody, CoordinateSystem, and CoordinateSystemEpoch keywords.

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.

NOTE: 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.<Version_No.> 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.

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

Example:
stk.v.4.0
A file created in and stamped with this version could be imported into STK software version 4.0 through the most recent version.
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 Yes The reference epoch time for the time values of the ephemeris data in the table. 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.

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.
CentralBody No.
Default will be supplied.		 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. The default value is Earth.

Example:

CentralBody Earth
CoordinateSystem No.
Default will be supplied.		 The coordinate system in which the ephemeris points reside. If the central body is Earth (or not specified), valid values are:
  • Fixed (Default)
  • J2000
  • B1950
  • TrueOfDate
  • TrueOfEpoch
  • MeanOfDate
  • MeanOfEpoch
  • TEMEOfEpoch
  • TEMEOfDate
  • AlignmentAtEpoch
  • Custom
If the central body is Sun, valid values are:
  • Fixed
  • J2000
  • J2000_Ecliptic
  • Custom

NOTE: Also, refer to the STK Help topic on Coordinate Systems.

If your ephemeris is not in one of STK's predefined coordinate systems, you must define a new coordinate system using the Vector Geometry Tool. You may then specify the name of your new coordinate system and the name of the STK object to which it corresponds using the Custom coordinate system.

Examples:
CoordinateSystem TrueOfEpoch
CoordinateSystem Custom LaunchSiteCoordSys Facility/MyLaunchSite

NOTE: 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.
CoordinateSystemEpoch Required with coordinate systems that reference an epoch. The epoch time for the coordinate system in Gregorian UTC time (dd mmm yyyy hh:mm:ss.s). Must be included with:
  • MeanOfEpoch
  • TrueOfEpoch
  • TEMEOfEpoch
  • AlignmentAtEpoch

Example:

CoordinateSystemEpoch 1 Jun 2003 12:00:00.0
DistanceUnit No.
Default will be supplied.		 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.

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

Example:

DistanceUnit Kilometers
InterpolationMethod No.
Default will be supplied.		 The method by which STK interpolates between ephemeris points. Valid values are:
  • Lagrange (Default)
  • Hermitian - Allows you to take advantage of angular 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 representing spinning ephemeris 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.
Example:
InterpolationMethod Hermite
InterpolationOrder No.
Default will be supplied.		 The interpolation order to be used. By default, STK uses 5th order interpolation. Override the default by specifying a different interpolation order. Often used with the EphemerisLLATimePos ephemeris format.

Example:

InterpolationOrder 1
NumberOfEphemerisPoints Yes The maximum number of ephemeris points to read.

Example:

If you enter:
NumberOfEphemerisPoints 1000
1000 ephemeris points would be read.
NumberOfCovariancePoints No The maximum number of covariance points to read. Must be specified before the ephemeris format keyword. If not included, the number of covariance points is assumed to be the same as the number of ephemeris points indicated using the NumberOfEphemerisPoints keyword.

Example: If you enter:

NumberOfCovariancePoints 1000
1000 covariance points would be read.
CovarianceFormat No
default will be supplied		 Specifies the portion of the covariance matrix that will appear in the CovarianceTimePos or CovarianceTimePosVel sections of the file. Valid values are
  • LowerTriangular
  • UpperTriangular
If LowerTriangular 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 is 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] . . .
                   .
                   .
                   .
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

Ephemeris Formats

While the sections above outline the basic format for an ephemeris table, the sections below outline the eight 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:

EphemerisTimePos Format

The EphemerisTimePos format is designed to import cartesian position, without velocity points, in the coordinate system specified using the CentralBody, CoordinateSystem, and CoordinateSystemEpoch keywords.

This format is commonly used for modeling ground, air, or other near Earth objects when only position data is available.

Since no velocity data is supplied, STK automatically generates velocity data by creating the Lagrange interpolation function for the position, taking the analytical derivative of the interpolation function and evaluating it each time position data is available. The resulting velocity data is then stored along with the position data in the file. Velocity data obtained this way is not as desirable as having real velocity data in the file, but is sufficient when nothing else is available.

Individual data points following the EphemerisTimePosVel keyword look like this:

<TimeInSeconds> <X> <Y> <Z> 

where,

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the epoch as defined by the ScenarioEpoch keyword.
<X> <Y> <Z> The vehicle position.

NOTE: Certain conventions must be followed when specifying data points.

NOTE: By default, position values are in meters. Use the DistanceUnit keyword to change units of measure.

An ephemeris file for a launch vehicle MyLauncher that had ephemeris in a topocentric coordinate system for the launch site MyLaunchSite would be built using a custom coordinate system. In this case, the coordinate system Topocentric was built on the facility MyLaunchSite using the Vector Geometry Tool to combine the facility’s Center point and TopoCentric axes. The resulting file would look like this sample file.

EphemerisTimePosVel Format

The EphemerisTimePosVel format is designed to import cartesian position and velocity points in the coordinate system specified using the CentralBody, CoordinateSystem, and CoordinateSystemEpoch keywords.

Individual data points following the EphemerisTimePosVel keyword look like this:

<TimeInSeconds> <X> <Y> <Z> <xDot> <yDot> <zDot>

where,

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the epoch as defined by the ScenarioEpoch keyword.
<X> <Y> <Z> The vehicle position.
<xDot> <yDot> <zDot> The vehicle velocity.

NOTE: Certain conventions must be followed when specifying data points.

NOTE: By default, position values are in meters and velocities are in meters per second. Use the DistanceUnit keyword to change units of measure.

An ephemeris file for a satellite in a Molniya type orbit about the Earth using 5th order Lagrange interpolation with the ephemeris data itself expressed in J2000 coordinates, using the EphemerisTimePosVel format would look like this sample file. A similar satellite using True of Epoch coordinates and values in kilometers would look like this sample file.

An ephemeris file for a launch vehicle MyLauncher that had ephemeris in a topocentric coordinate system for the launch site MyLaunchSite would be built using a custom coordinate system. In this case, the coordinate system Topocentric was built on the facility MyLaunchSite using the Vector Geometry Tool to combine the facility’s Center point and TopoCentric axes. The resulting file would look like this sample file.

NOTE: Sometimes the ephemeris that you are importing contains maneuvers or other events which are difficult to interpolate across. These times may be identified using a SegmentBoundaryTimes block within the ephemeris file. For example, an ephemeris file for a satellite that performed two maneuvers, one at 2909 seconds and one at 7619 seconds would look like this sample file.

EphemerisLLATimePos Format

The EphemerisLLATimePos keyword is used to indicate that data points that follow are a vehicle's position in the fixed (to the central body) coordinate frame and specified using geodetic coordinates. This format is commonly used for modeling ground, air, or other near Earth objects when only position data is available.

Since no velocity data is supplied, STK will automatically generate velocity data by creating the Lagrange interpolation function for the position, taking the analytical derivative of the interpolation function and evaluating it each time position data is available. The resulting velocity data is then stored along with the position data in the file. Velocity data obtained this way is not as desirable as having real velocity data in the file, but is sufficient when nothing else is available.

The InterpolationOrder keyword is often used in conjunction with this format to fine-tune the interpolator. When importing position data for an aircraft, you may want to set the interpolation order to one (resulting in linear interpolation) to avoid oscillations (often referred to as ringing) in the interpolated position when the input position data is very irregularly spaced in time. The ringing effect is most noticeable when the path of the aircraft changes direction.

Individual data points following the EphemerisLLATimePos keyword look like this:

<TimeInSeconds> <Lat> <Lon> <Alt>

where,

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the epoch as defined by the ScenarioEpoch keyword.
<Lat> <Lon> <Alt> The vehicle position defined by its geodetic latitude, longitude and altitude in decimal degrees and meters respectively.

NOTE: Certain conventions must be followed when specifying data points.

An ephemeris file using the EphemerisLLATimePos format might look something like this sample file.

EphemerisLLATimePosVel Format

The EphemerisLLATimePosVel format is very similar to the EphemerisLLATimePos format, except that it also supplies the vehicle velocity. The data points that follow are a vehicle's position and velocity in the fixed (to the central body) coordinate frame specified in geodetic coordinates. This format is commonly used for modeling ground, air, or other near Earth objects.

NOTE: Irregularly spaced position data can result in oscillations.

Individual data points following the EphemerisLLATimePosVel keyword look like this:

<TimeInSeconds> <Lat> <Lon> <Alt> latDot> <lonDot> <altDot>

where

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the epoch as defined by the ScenarioEpoch keyword.
<Lat> <Lon> <Alt> The vehicle position defined by its geodetic latitude, longitude and altitude in decimal degrees and meters respectively.
<latDot> <lonDot> <altDot> The vehicle velocity defined by the rate of change of the geodetic latitude, longitude and altitude in decimal degrees/second and meters/second respectively.

NOTE: Certain conventions must be followed when specifying data points.

An ephemeris file using the EphemerisLLATimePosVel format might look something like this sample file.

EphemerisLLRTimePos Format

The EphemerisLLRTimePos format is similar to the EphemerisLLATimePos format, except for the following:

Individual data points following the EphemerisLLRTimePos keyword look like this:

<TimeInSeconds> <Lat> <Lon> <Alt>

where,

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the epoch as defined by the ScenarioEpoch keyword.
<Lat> <Lon> <Rad> The vehicle position defined by its geocentric latitude, longitude and radius in decimal degrees and meters respectively.

NOTE: Certain conventions must be followed when specifying data points.

An ephemeris file using the EphemerisLLRTimePos format would then look like this sample file.

EphemerisLLRTimePosVel Format

The EphemerisLLRTimePosVel format is similar to the EphemerisLLATimePosVel format, except for the following:

Individual data points following the EphemerisLLRTimePosVel keyword look like this:

<TimeInSeconds> <Lat> <Lon> <Rad> latDot> <lonDot> <radDot>

where

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the epoch as defined by the ScenarioEpoch keyword.
<Lat> <Lon> <Alt> The vehicle position defined by its geocentric latitude, longitude and altitude in decimal degrees and meters respectively.
<latDot> <lonDot> <radDot> The vehicle velocity defined by the rate of change of the geocentric latitude, longitude and altitude in decimal degrees/second and meters/second respectively.

NOTE: Certain conventions must be followed when specifying data points.

An ephemeris file using the EphemerisLLRTimePosVel format might look something like this sample file.

EphemerisGeocentricLLATimePosVel Format

Often whey you receive ephemeris data from another source, you may be unsure whether the latitude values are geodetic or geocentric. A general rule of thumb is to assume that if you have altitude data that the latitude is geodetic (in which case you should use the EphemerisLLATimePosVel format), if you have radius information then assume the latitude is geocentric (so use the EphemerisLLRTimePosVel format).

In rare cases, you may have altitude data but the latitude data that is geocentric. It is for this case that the EphemerisGeocentricLLATimePosVel format was designed. It is identical to the EphemerisLLATimePosVel format, except that it treats the latitude values as geocentric latitudes, not geodetic.

EphemerisGeodeticLLRTimePos and EphemerisGeodeticLLRTimePosVel Format

These two formats are identical to their counterparts EphemerisLLRTimePos and EphemerisLLRTimePosVel except that latitude is treated as geodetic latitude rather than geocentric latitude.

CovarianceTimePos Format

NOTE: This format must be used in conjunction with one of the other ephemeris formats.

The ephemeris file format allows you to supply covariance information in addition to position and velocity information. The CovarianceTimePos keyword is used in conjunction with one of the other ephemeris formats to indicate that data points that follow are the vehicle's position covariance in the same Cartesian coordinate system within which the ephemeris was defined. The number of covariance points may be specified using the NumberOfCovariancePoints keyword.

Typically the covariance information is obtained from an orbit determination tool as part of the calculating the ephemeris for the vehicle. The position covariance matrix is a three-by-three matrix that looks like this:

Since it is diagonally symmetric, only six values are necessary to represent the matrix. The data may be given in either lower triangular or upper triangular form, where the selection is specified via the CovarianceFormat keyword. In the absence of that keyword, the upper triangular form is assumed. (This is to ensure backwards compatability.) The data points following the keyword consist of a line per point where each line looks like the following if the upper triangular format is specified:

<Time in seconds> <CXX> <CXY> <CXZ> <CYY> <CYZ> <CZZ>

or like the following if the lower triangular format is specified:

<Time in seconds> <CXX> <CYX> <CYY> <CZX> <CZY> <CZZ>

where

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the epoch as defined by the ScenarioEpoch keyword.
<Cxx> Value (in meters squared) of the corresponding element of the covariance matrix.

NOTE: Certain conventions must be followed when specifying data points.

An ephemeris file using the CovarianceTimePos format might look something like this sample file.

CovarianceTimePosVel Format

This format is the same as the CovarianceTimePos format, except that it gives position/velocity covariance:

21 matrix entries are required. The required unit for a matrix entry depends on whether it is a product of two positions (e.g. <xy>), a position and a velocity (e.g. <xdy>, <xyd>) or two velocities (e.g. <xdyd>):

Entry Type Required Unit
<xy> meters^2
<xdy>, <xyd> meters^2/sec
<xdyd> (meters/sec)^2

If CovarianceFormat is set to LowerTriangular, data points appear as follows:

<Time in seconds> <Cxx> <Cyx> <Cyy> <Czx> <Czy> <Czz> <Cxdx>
                  <Cxdy> <Cxdz> <Cxdxd> <Cydx> <Cydy> <Cydz> <Cydxd>
                  <Cydyd> <Czdx> <Czdy> <Czdz> <Czdxd> <Czdyd> <Czdzd>

If CovarianceFormat is set to UpperTriangular, data points appear as follows:

<Time in seconds> <Cxx> <Cxy> <Cxz> <Cxxd> <Cxyd> <Cxzd> <Cyy>
                  <Cyz> <Cyxd> <Cyyd> <Cyzd> <Czz> <Czxd> <Czyd>
                  <Czzd> <Cxdxd> <Cxdyd> <Cxdzd> <Cydyd> <Cydzd> <Czdzd>