Attitude File Format (*.a)

An attitude file is an ASCII text file that ends with (.a), formatted for compatibility with STK. Attitude files are useful when you need to provide STK with data for a vehicle to model unique circumstances. Vehicle attitude is a basic property of all vehicles in STK. You can use the Precomputed option on the Attitude page of any vehicle's Basic properties to import the attitude data from any properly formatted attitude file.

Attitude data represents the orientation of the vehicle’s body frame relative to some other coordinate axes as a sequence of time-tagged values. Attitude files contain data used to compute the orientation of the vehicle at whatever time values it needs to support analysis and animation. When necessary, STK will interpolate between points to do so. Interpolation methods use the same coordinate frame as the input data.

Attitude data must represent a transformation from the reference coordinate frame to the vehicle body frame. The reference coordinate frame is specified using the CentralBody, CoordinateAxes, and CoordinateAxesEpoch keywords described below. For information on how STK handles differentiation, see Attitude Interpolation and Differentiation in STK.

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

How is the data formatted? Is it a set of quaternions; Euler angles; yaw, pitch, and roll angles; direction cosine matrices; or something else?

What is the reference frame that you are rotating from? Is it an inertial frame, such as J2000; a fixed frame, such as Earth Centered Fixed; or relative to an orbital frame, such as VVLH?

Once you know the answers to these questions, you can use keywords recognized by STK to describe the orientation of the vehicle.

Keywords

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

Keywords used in attitude files are not case sensitive; the capitalization used in this topic is for readability.

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 Attitude
END Attitude 		Yes These set off the beginning and end of the attitude or covariance data. All other keyword phrases and data point specifications, except the version keyword, will be inside these two keyword phrases. The sample files included in the File Format section below provide examples of this formatting.
ScenarioEpoch No

This is the reference epoch time for the time values of the attitude data in the file. Specify the scenario epoch using Gregorian UTC time (dd mmm yyyy hh:mm:ss.s). There is no relationship between ScenarioEpoch and the scenario epoch in your STK scenario.

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 attitude point would correspond to a time of 1 Jan 2003 00:00:05.5.
CentralBody No

This is the central body that the attitude 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
CoordinateAxes No

AGI recommends that you supply these, but they are not required.

These are the reference axes from which the rotation to the body axes is performed. Normally, the coordinate axes 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, but some bodies support additional systems.


You can use any of the predefined reference axes. For a complete list of VGT central body frames, go to the Vector Geometry tool in STK's Analysis Workbench capability and select a primary or secondary body or an object on a particular central body. All supported VGT components, including reference frames, will be displayed for your selection.


You can also define a new set of axes using the Vector Geometry Tool (VGT). You can then specify the name of your new axes and the name of the STK object that it corresponds to. VGT-created axes must use the keyword CoordinateAxes AWB. For example, CoordinateAxes AWB NorthEastDown Aircraft/AircraftName.


The default Coordinate Axes is Inertial, which is ICRF for Earth and Sun.


Examples:

    CoordinateAxes TrueOfEpoch
    CoordinateAxes AWB TopoCentric Facility/MyLaunchSite

The name of the STK object is optional if the object that is importing the attitude is the object on which axes are defined.
CoordinateAxesEpoch See Note

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

This parameter is required with coordinate axes that reference an epoch:

  • MeanOfEpoch
  • TrueOfEpoch
  • TEMEOfEpoch
  • AlignmentAtEpoch

Example:

    CoordinateAxesEpoch 1 Jun 2003 12:00:00.0

InterpolationMethod No

This is the method by which STK interpolates between attitude points. Valid values are:

  • Lagrange (Default)
  • Hermite - This option enables you to take advantage of angular velocity information to achieve smoother attitude interpolation. One application is if you are using files containing very irregularly spaced data points. Another is if you have data representing a spinning attitude that is susceptible to ringing and aliasing effects if derivative information is not considered during interpolation. Hermitian interpolation assumes that the velocity component of the attitude is the derivative of the position. Hermitian interpolation should not be used when velocity data is not available as part of the attitude file.

Example:

    InterpolationMethod Hermite
InterpolationOrder No

This is the order of interpolation that STK will use. You can override the default by specifying a different interpolation order. This parameter is often used with the AttitudeLLATimePos attitude format.

The default is 1.

Example:

    InterpolationOrder 2
NumberOfAttitudePoints No

AGI recommends that you specify this keyword. This value indicates the number of attitude points that STK will read from the file. When not specified, STK uses all attitude points in the file.

Example:

If you enter:
    NumberOfAttitudePoints 1000

then STK will read 1,000 attitude points and then stop.
AttitudeDeviations {Rapid |Mild} No

Select one of the following:.

  • AttitudeDeviations Rapid. This indicates to STK that the attitude points contain some very rapid deviations over time. STK will sample at a much smaller rate than normal when performing access and other calculations based on this data. This will slow down STK, but that may be necessary in some cases.
  • AttitudeDeviations Mild. Use this setting if the TrendingControl section is not present or fails to list any times.

Using the AttitudeDeviations keyword may result in decreased performance. Therefore, you should only use this keyword when rapid deviations are expected.
BlockingFactor No This specifies how much memory (in terms of sets of attitude points) will be allocated at a time while reading an attitude file. When usinglarge files, you can specify this keyword to speed up the loading process by avoiding reallocating small chunks of memory.
Sequence No Used by Euler and YPR angle representations to associate an axis rotations with angle values. There are 12 sequences valid for Euler angles (121, 123, 131, 132, 212, 213, 231, 232, 312 default = 313, 321, and 323). There are six (6) sequences valid for YPR angles (123, 132, 213, 231, 312 default = 321). For example, the sequence 321 for angles A, B, and C indicate that the orientation is determined by first rotating about the Z-axis by A, then rotating about the Y-axis by B, and then about the X-axis by C.
InitialQuaternion, InitialEulerAngle, or InitialYPRAngle No

This defines the initial orientation using one of the following formats:

  • InitialQuaternion <q1> <q2> <q3> <q4> (the 4th element is the scalar component)
  • InitialEulerAngle <Sequence> <RotA> <RotB> <RotC>
  • InitialYPRAngle <Sequence><Y> <P> <R>

STK pairs the selected orientation format with an angular velocity of compatible format — AttitudeTimeAngVels, AttitudeTimeEulerAngleRates, and AttitudeTimeYPRAngleRates, respectively.
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

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 TrendingControTimes subsection or the TrendingControlStep. These are described below.

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 the TrendingControlStep keyword is not used.

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

File formats

The sections below outline the formats used to specify data points in the attitude file.

Required data point conventions

You must observe the following conventions when specifying data points, in any format:

AttitudeTimeQuaternions format

The AttitudeTimeQuaternions format is designed to import vehicle attitude data provided as quaternions. The STK convention for quaternions is that the fourth element of the quaternion is the scalar component. STK will normalize the quaternions to have a magnitude of 1.0, if necessary, as they are read. The quaternions represent the rotation from the reference coordinate frame to the vehicle’s body coordinate frame.

Individual data points following the AttitudeTimeQuaternions keyword format look like this:

<TimeInSeconds> <q1> <q2> <q3> <q4>

where:

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the scenario epoch as defined by the ScenarioEpoch keyword.
<q1> <q2> <q3> <q4> The four elements of the quaternion.

An attitude file using the AttitudeTimeQuaternions format to specify quaternions that represent the rotation from the Earth’s J2000 inertial coordinate frame to the vehicle’s body frame would look like this sample file.

AttitudeTimeQuatScalarFirst format

The AttitudeTimeQuatScalarFirst format is designed to import vehicle attitude data provided as quaternions. In this format, the first element of the quaternion is the scalar component. STK will normalize the quaternions to have a magnitude of 1.0, if necessary, as they are read. The quaternions represent the rotation from the reference coordinate frame to the vehicle’s body coordinate frame.

Individual data points following the AttitudeTimeQuatScalarFirst keyword format look like this:

<TimeInSeconds> <q1> <q2> <q3> <q4>

where:

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the scenario epoch as defined by the ScenarioEpoch keyword.
<q1> <q2> <q3> <q4> The four elements of the quaternion.

An attitude file using the AttitudeTimeQuatScalarFirst format to specify quaternions would look like this sample file.

AttitudeTimeQuatAngVels format

The AttitudeTimeQuatAngVels format is similar to the AttitudeTimeQuaternions format, but you can also specify the angular velocity vector at each point in time. The angular velocity is of the body with respect to the coordinate system defined by the CoordinateAxes keyword phrase, expressed in body components.

Individual data points following the AttitudeTimeQuatAngVels keyword format look like this:

<TimeInSeconds> <q1> <q2> <q3> <q4> <X> <Y> <Z>

where:

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the scenario epoch as defined by the ScenarioEpoch keyword.
<q1> <q2> <q3> <q4> The four elements of the quaternion.
<X> <Y> <Z> The three elements of the angular velocity vector of the body frame with respect to the inertial frame written in the body frame. The units are degrees per second.

An attitude file specifying quaternions that represent the rotation from the Earth’s J2000 inertial coordinate frame to the vehicle’s body frame using the AttitudeTimeQuatAngVels format would look like this sample file.

An application of the AttitudeTimeQuatAngVels format would be to create an attitude file for a launch vehicle MyLauncher. Its attitude would be referenced to a topocentric coordinate frame for the launch site MyLaunchSite, and the file would be built using a custom coordinate system. In this example, the coordinate axes Topocentric was built on the facility MyLaunchSite using the Vector Geometry Tool. The resulting attitude data would look like the data contained in this sample file.

AttitudeTimeEulerAngles format

The AttitudeTimeEulerAngles format is designed to import vehicle attitude data provided as a series of Euler angle rotations. The Euler angles represent the rotation from the reference coordinate frame to the vehicle’s body coordinate frame. The rotations are performed in the manner of the classic Euler angle rotations, where each successive rotation is relative to the frame resulting from any previous rotations.

Before the AttitudeTimeEulerAngles keyword and its data points, you must include a Sequence keyword phrase specifying the order of rotation about the axes. There are 12 possible sequence values for Euler angles. For example, a value of 123 corresponds to a rotation about the X, Y, and Z-axes, in that order. If the Sequence keyword is not included, the default Euler sequence, 313, is assumed.

Data points following the AttitudeTimeEulerAngles keyword format look like this:

<TimeInSeconds> <RotA> <RotB> <RotC>

where:

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the scenario epoch as defined by the ScenarioEpoch keyword.
<RotA> <RotB> <RotC> The three rotation angles (in degrees) in the order that they will be applied as specified by the Sequence keyword. For example, if the angles are 10, 20, and 30 degrees with a Sequence value of 313, then the rotations will be 10 degrees about Z, 20 degrees about X, and then 30 degrees about Z again.

An attitude file modeling a spacecraft spinning about the J2000 Z-axis is modeled using the AttitudeTimeEulerAngles format would look like this sample file.

AttitudeTimeYPRAngles format

The AttitudeTimeYPRAngles format is designed to import vehicle attitude data provided as a series of yaw, pitch, and roll (YPR) rotations. The YPR angles represent the rotation from the reference coordinate frame to the vehicle’s body coordinate frame about the Z, Y, and X-axes of the reference frame. The rotations are not Euler angle rotations; each successive rotation is relative to the original reference frame axes.

Prior to this keyword and its data points, you must include a Sequence keyword phrase specifying the order of rotation about the reference frame’s Z, Y, and X axes. There are six possible Sequences for yaw-pitch-roll, where 123 corresponds to rotations about the X, Y, and Z axes respectively. The valid Sequence values are 123, 132, 213, 231, 312, and 321. If the Sequence keyword is not included, then the default of 321, or yaw-pitch-roll, is assumed.

Unlike the AttitudeTimeEulerAngles format, the rows of data are always given in the this order: time, yaw, pitch, and roll. The Sequence keyword controls the order of the rotations, not the order of the data.

Data points following the AttitudeTimeYPRAngles keyword format look like this:

<TimeInSeconds> <Y> <P> <R>

where:

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the scenario epoch as defined by the ScenarioEpoch keyword.
<Y> <P> <R> The yaw, pitch, and roll rotation angles (in degrees). For example, if the angles are 10, 20, and 30 degrees with a Sequence value of 312 then the rotations will be 10 degrees about Z, 30 degrees about X, and then 20 degrees about Y.

An attitude file modeling a spacecraft spinning about the J2000 Z-axis using the AttitudeTimeYPRAngles format would look like this sample file.

AttitudeTimeYPRAngleRates, AttitudeTimeEulerAngleRates, and AttitudeTimeAngVels formats

These formats are designed to import attitude data based on a time-ordered set of YPR, Euler, or Quaternion angle rates, respectively.

These formats are similar to AttitudeTimeYPRAngle, AttitudeTimeEulerAngles, and AttitudeTimeQuatAngVels, but you provide angle rates instead of angles.

Prior to one of these keywords — AttitudeTimeYPRAngleRates, AttitudeTimeEulerAngleRates, or AttitudeTimeAngVels — and its data points, you must specify the initial attitude in YPR angles, Euler angles, or quaternion angles. For example:

InitialYPRAngle 321 10 20 30

The initial attitude representation does not have to match the representation of the data points.

Data points will be a table, with each point composed of time in epoch seconds followed by three angle rates in degrees per second. The Sequence keyword identifies the order of rotations for converting the Euler or YPR angles to a quaternion. Valid YPR Sequence values are 123, 132, 213, 231, 312, and 321. Valid Euler values for Sequence are 121, 123, 131, 132, 212, 213, 231, 232, 312, 313, 321, and 323. The format is:

<TimeInSeconds> <rateA> <rateB> <rateC>

where:

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the scenario epoch as defined by the ScenarioEpoch keyword.
<rateA> <rateB> <rateC> The three rotation angle rates (in degrees/sec) in the order that they will be applied, either by quaternion definition or as specified by the Sequence keyword for YPR and Euler.

AttitudeTimeYPRAnglesAndRates, AttitudeTimeEulerAnglesAndRates

These formats are designed to import attitude data based on a time-ordered set of angles and rates in both YPR and Euler forms.

These formats are similar to AttitudeTimeYPRAngle and AttitudeTimeEulerAngles, but you specify both angles and angle rates.

Prior to one of these keywords — AttitudeTimeYPRAngleAndRates or AttitudeTimeEulerAnglesAndRates — and its data points, you must specify the initial attitude in Euler angles or YPR angles. For example:

InitialYPRAngle 321 10 20 30

The initial attitude representation does not have to match the representation of the data points.

Data points will be in a table, with each point composed of time in epoch seconds followed by three angles in degrees and three angle rates in degrees per second. The Sequence keyword identifies the order of rotations for converting the Euler or YPR angles to a quaternion. Valid YPR Sequence values are 123, 132, 213, 231, 312, and 321. Valid Euler values for Sequence are 121, 123, 131, 132, 212, 213, 231, 232, 312, 313, 321, and 323. The format is:

<TimeInSeconds> <Y> <P> <R><rateA> <rateB> <rateC> for YPR, or
<TimeInSeconds> <rotA> <rotB> <rotC><rateA> <rateB> <rateC> for Euler,

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.

<Y> <P> <R> or

<RotA> <RotB> <RotC>

For YPR: The yaw, pitch, and roll rotation angles (in degrees). For example, if the angles are 10, 20, and 30 degrees with a Sequence of 312 then the rotations will be 10 degrees about Z, 30 degrees about X, and then 20 degrees about Y.

For Euler: The three rotation angles (in degrees) in the order that they will be applied as specified by the Sequence keyword. For example, if the angles are 10, 20, and 30 degrees with a Sequence value of 313, then the rotations will be 10 degrees about Z, 20 degrees about X, and then 30 degrees about Z again.
<rateA> <rateB> <rateC> The three rotation angle rates (in degrees/sec) in the order that they will be applied as specified by the Sequence keyword for either YPR or Euler.

AttitudeTimeDCM format

The AttitudeTimeDCM format is used to specify a 3X3 direction cosine matrix (DCM) for each attitude point.

Individual data points following the AttitudeTimeDCM keyword format look like this:

<TimeInEpochSeconds> <m11-first row, first element> <m12-first row, second element> <m13-first row, third element> <m21-second row, first element> <m22-second row, second element> <m23-second row, third element> <m31-third row, first element> <m32-third row, second element> <m33-third row, third element>

where:

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the scenario epoch as defined by the ScenarioEpoch keyword.
<m11> <m12> <m13> <m21> <m22> <m23> <m31> <m32> <m33> The direction cosine values that make up the three rows of the DCM.

An attitude file using the AttitudeTimeDCM format to specify a DCM looks like this sample file.

AttitudeTimeDCMAngVels format

The AttitudeTimeDCMAngVels format is similar to the AttitudeTimeDCM format, but you can also specify the angular velocity vector at each point in time. The angular velocity is of the body with respect to the coordinate system defined by the CoordinateAxes keyword phrase, expressed in body components.

Individual data points following the AttitudeTimeDCMAngVels keyword format look like this:

<TimeInSeconds> <m11-first row, first element> <m12-first row, second element> <m13-first row, third element> <m21-second row, first element> <m22-second row, second element> <m23-second row, third element> <m31-third row, first element> <m32-third row, second element> <m33-third row, third element> <X> <Y> <Z>

where:

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the scenario epoch as defined by the ScenarioEpoch keyword.
<m11> <m12> <m13> <m21> <m22> <m23> <m31> <m32> <m33> The direction cosine values that make up the three rows of the DCM.
<X> <Y> <Z> The three elements of the angular velocity vector of the body frame with respect to the inertial frame written in the body frame. The units are degrees per second.

AttitudeTimeECIVector & AttitudeTimeECFVector keywords

The AttitudeTimeECIVector and AttitudeTimeECFVector formats are used to indicate that vehicle attitude data is specified as a vector in the ECI or ECF frame. These keywords are primarily used for missiles and launch vehicles where the direction of the main axis is known but orientation about that axis may not be. The main axis is assumed to be the body-fixed X-axis, which is aligned with the input vector (specified in either the ECI or ECF reference frames). The body-fixed Z-axis is constrained toward the nadir vector.

AttitudeTimeECFVector and AttitudeTimeECIVector do not require the CoordinateAxes header line. They identify the expected data explicitly. Any CoordinateAxes header lines will be ignored, and a message will be posted in the Message Viewer.

Data points following the AttitudeTimeECIVector and AttitudeTimeECFVector keyword formats look like this:

<TimeInSeconds> <V1> <V2> <V3>

where:

<TimeInSeconds> The time value of the point in seconds (in the format xxxx.xxx) relative to the scenario epoch as defined by the ScenarioEpoch keyword.
<V1> <V2> <V3> The three components of the vector. The vector specifies the orientation of the body X-axis in the ECI or ECF frame. The body is then rotated so that the body Z-axis is at the minimum angle relative to nadir.

An attitude file using the AttitudeTimeECIVector format would look like this sample file.

Missiles and launch vehicles

Missiles and launch vehicles typically have attitude data in one of several frames. Examples are topocentric, relative to the launch pad, and inertial, where Z is along the Earth’s Z-axis and X is through the longitude line corresponding to the launch site location at the time of launch. You can model this in STK by defining a custom coordinate system and creating the appropriate reference frame using the Vector Geometry Tool. See the launch application example in the description of AttitudeTimeQuatAngVels.