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. If you have ephemeris data, organized in a properly formatted table, in any ephemeris file, you can import it into STK using the STK External propagator.

STK uses ephemeris data to generate the position and velocity of a vehicle at whatever time values needed to support analysis and animation. When necessary, STK will interpolate between points to do, in the same coordinate frame (inertial or fixed) as the data frame.

STK ephemeris files adhere to the following conventions:

  • The reference coordinate frame is specified using the CentralBody, CoordinateSystem, and CoordinateSystemEpoch keywords.
  • In Julian Dates format, you can enter dates 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? 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

This is the version of STK software associated with the file formatting. You can create files in this format and import them into any STK software version at this level or higher.

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

Example:

stk.v.11.0

A file created in and stamped with this version could be imported into STK software version 11.0 through the most recent version.

MessageLevel No

You can set this value to determine the level of message(s) you receive from STK as it attempts to read the file. The value options are:

  • Errors - You only receive the reported error messages.
  • Warnings - You receive error messages plus reporting on other information (e.g., unrecognized keywords).
  • Verbose - You receive all that is in Warnings plus a success message if STK reads and accepts the complete file.
BEGIN Ephemeris
END Ephemeris
Yes These set 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

This is 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.

The 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.

CentralBody No

This is the central body that the ephemeris points are relative to. The keyword value that completes the phrase can be the name of any registered central body. You can find registered central bodies in the STKData\CentralBodies directory.

The default is the central body for the vehicle, and that default is Earth.

Example:

    CentralBody Moon
SmoothData No

Including this 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 at which sharp changes may occur.

Without a TrendingControl section or SmoothData keyword, STK determines smoothness of ephemeris data based on vehicle and propagator types. STK assumes that ground vehicle, ship, and aircraft objects, as well as any object with a file that declares interpolation to be based on a great arc type, have non-smooth data. Otherwise, it assumes the data to be smooth.

Use the SmoothData keyword 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. The 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 a TrendingControlTimes section in the file if you do not use the TrendingControlStep keyword.

This section contains a list of times (one time 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

AGI recommends specifying this; is 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.The VGT-created system must use the keyword CoordinateSystem AWB.


CoordinateSystem AWB replaces CoordinateSystem Custom as the required keyword for VGT-created systems. STK still supports the CoordinateSystem Custom keyword for backward compatibility.


The 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 replaced with the CoordinateSystem AWB keyword in 11.5.0.

The CoordinateSystem AWB keyword was introduced in 11.5.0.

ComputeVelocity No

The manner in which Cartesian velocity is computed from the Cartesian position generated from the position data in the file if rate information is not provided directly by the file. The default value is DerivativeOfInterpolatingPolynominal. Other values are: 

  • ForwardDifference

  • BackwardDifference

  • CentralDifference

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

It is required with coordinate systems that reference an Epoch:

  • MeanOfEpoch
  • TrueOfEpoch
  • TEMEOfEpoch
  • AlignmentAtEpoch

Example:

CoordinateSystemEpoch 1 Jun 2003 12:00:00.0

DistanceUnit No

Set the distance unit 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. You can override this 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.

The default for velocity is meters per second.

The default for the ephemeris table is meters.

Example:
DistanceUnit Kilometers

BlockingFactor No

This specifies how much memory (in terms of sets of ephemeris points) STK will allocate 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.

InterpolationMethod No

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

  • Lagrange
  • Hermite - Select this to take advantage of velocity information, if available, in order to achieve smoother ephemeris interpolation. It is 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. Do not use Hermitian interpolation 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 - This is a Fixed reference frame method, with interpolation as a great arc vehicle on WGS84.
  • GreatArcTerrain - This is a Fixed reference frame method, with interpolation as a great arc vehicle using Terrain.
  • GreatArcMSL - This is a Fixed reference frame method, with interpolation as a great arc vehicle using MSL.

The default is Lagrange.

Examples:
InterpolationMethod Hermite
InterpolationMethod LagrangeVOP 3.98600441500e+14

Keyword History

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.

InterpolationSamplesM1 No

This is 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.

The default is 5.

Example:
InterpolationSamplesM1 5

NumberOfEphemerisPoints No

AGI recommends specifying this to indicate the maximum number of ephemeris points to read from the file. When not specified, STK will use all ephemeris points in the file.

Prior to STK 11.5, this keyword was required.

Example:

If you enter
    NumberOfEphemerisPoints 1000

STK will read up to 1000 ephemeris points.

NumberOfCovariancePoints No

AGI recommends specifying this to indicate the maximum number of covariance points to read from the file. When not specified, STK will read all covariance points in the file.

Example:
If you enter

    NumberOfCovariancePoints 1000

STK will read up to 1000 covariance points.

CovarianceInterpolationMethod No

You can specify the method for interpolating covariance that contains both position and velocity terms.

Valid values are None and TwoBodyQuadraticArithmeticBlending.

The 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 with motion 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

This 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 you specify LowerTriangular or LT, STK assumes the order of entries to be:

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

If you specify UpperTriangular or UT, STK assumes the order of entries 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.

StateErrorTransitionReferenceEpoch

Not Required

Default is ScenarioEpoch

State-error transition matrices provide a linear mapping of state deviations from this time to the time of the data point.

Example:

StateErrorTransitionReferenceEpoch 1 Jan 2003 00:00:00.0

CovarianceCoordinateSystem No

When you specify this keyword, STK interprets the covariance as being in either a special ephemeris-based local frame (indicated below) or the axes of the specified CoordinateSystem.

When not specified, STK interprets the covariance as being in the same frame as the ephemeris (i.e., expressed in the axes associated with the CoordinateSystem).

CovarianceCoordinateSystemEpoch No The epoch time for the covariance coordinate system in Gregorian UTC time (dd mm yyy hh:mm:ss.s).

You must specify this with coordinate systems that reference an Epoch:

  • MeanOfEpoch
  • TrueOfEpoch
  • TEMEOfEpoch
  • AlignmentAtEpoch

Example:

CovarianceCoordinateSystemEpoch 1 Jun 2020 12:00:00.0

CovarianceProjRefCoordinateSystem No

This specifies the reference frame that observed the covariance matrix before its transformation into the frame specified by CovarianceCoordinateSystem, where the transformation ignored the effects of the angular velocity of CovarianceCoordinateSystem. Valid values are Inertial or Fixed.

This keyword is only needed when velocity components of the covariance matrix are present and the values were created in their frame without fully accounting for the angular velocity of the frame. For example, the value should be set to Fixed when the covariance was computed in the Fixed frame. The value appears in the file using Body frame components (as specified by CovarianceCoordinateSystem) where the transformation from Fixed to Body ignored the angular velocity of the Body frame.

Example

CovarianceProjRefCoordinateSystem Fixed

CovarianceIncludeAngleVelInVelCovXfm No

This specifies whether the angular velocity of the frame should be included in the transformation of the covariance matrix's velocity components. Only use this when velocity components of the covariance matrix are present and CovarianceCoordinateSystem is not a local frame nor a VGT frame.

Valid values: Yes, True, On, No, False, Off

Default Value: Yes

This setting is rarely needed. It supports situations in which the ephemeris is provided in an Inertial frame, but the covariance is provided in the Fixed frame. The angular velocity of the Fixed frame should be ignored in the Inertial-to-Fixed transformation.

BEGIN SegmentBoundaryTimes
END SegmentBoundaryTimes
No

This 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

TimeFormat No

This defines the date format of time tags. If specified, each line of data in the file begins with a time in that date format; the rest of the data follows this date.

Spaces are valid if the format allows (e.g., 1 Jan 2007 12:00:00.000).

Quotes around time strings are invalid.

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

Examples:

TimeFormat DD/MM/YYYY

TimeFormat GPSZ

TimeScale No

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

If you use it, the value is TDB.

Keyword History

The TimeScale keyword was introduced in STK version 8.1.0.

Local Frames

Local Frame Description
RIC Radial Intrack Crosstrack frame with:
  • X along Radial
  • Y along Intrack
  • Z along CrossTrack
The names RSW, RTN, and UVW are also supported and indicate this frame.
NTC Normal Tangential CrossTrack frame with:
  • Y along velocity direction (Tangential)
  • Z along CrossTrack
  • X along Normal direction
The normal direction is outward like the Radial direction.
TNW

Tangential Normal CrossTrack frame with:

  • X along the velocity direction (Tangential)
  • Z along CrossTrack
  • Y along the Normal direction.
The Normal direction is inward, opposite to the Normal defined in NTC.
VNC Velocity Normal CoNormal frame with:
  • X along velocity direction (Velocity)
  • Y along CrossTrack (Normal)
  • Z along CoNormal direction
This is a rotation of the NTC frame.

When you use a local frame, you can specify the optional value IgnoreAngVel, indicating that the transformation from the ephmeris coordinate system's axes to the local frame should be performed without accounting for the angular velocity of the local frame itself. This is the appropriate setting if the covariance was determined in the same frame as the ephemeris, but then transformed into a local frame without accounting for the effect of the rotation of the local frame on the velocity components of the covariance matrix. If the covariance matrix only contains position components, the IgnoreAngVel setting has no effect.

Other options for specifying CovarianceCoordinateSystem are the same as those for CoordinateSystem.

When using VGT, you must specify a system, not axes, even though STK only uses the axes associated with a CoordinateSystem.

Be careful when using a VGT system (such as Body) that depends on an object's attitude, if that attitude can be modified after loading the ephemeris file. In that case, if the attitude changes, the covariance representing the uncertainty of the ephemeris will change, and it probably is not representative of the actual uncertainty of the ephemeris any longer. When using Body or other Systems that depend on attitude, AGI recommends that you set the attitude consistent with how the covariance was obtained and that you do not modify it.

Examples

CovarianceCoordinateSystem RIC IgnoreAngVel

CovarianceCoordinateSystem TrueOfDate

CovarianceCoordinateSystem AWB Body Satellite/MySatellite

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. You must include the format keyword in the file on its own line, after the header keywords and before the actual data point array.

You must observe the following conventions 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 NumberOfCovariancePoints keywords.

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