Keywords | File Formats

Sensor Pointing File Format (*.sp)

A sensor pointing file is an ASCII text file that is formatted for compatibility with STK and ends in a .sp extension. The pointing file provides data for specifying the sensor's body axes. The file contains the orientation of the sensor body axes (with the Z axis being the sensor boresight) relative to a Reference Frame (described below).

When the file specifies a frame using the CoordinateAxes keyword, the Reference Frame is the specified frame. When the file does not specify a frame, the Reference Frame is determined by the object type of the parent of the sensor:

  • For sensors whose parent is a vehicle, the Reference Frame is the body axes frames of the parent.
  • For sensors whose parent is a Facility/Target/Place, the Reference Frame is the frame that results from rotating the Facility/Target/Place body axes about its X-axis by 180 degrees (i.e., flipped body axes).

Using sensor pointing files are useful when you need to import external sensor attitude information into STK to model unique circumstances. Sensor pointing is a Basic property of all sensors in STK. You can import the attitude data in any properly formatted Sensor Pointing file into STK using the External option on the Sensor pointing page of any sensor's Basic properties.

Keywords

Each sensor pointing 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 sensor pointing files are NOT case sensitive; the capitalization used in this document 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.
CentralBody No

This is the central body to which the attitude points are relative. The keyword value that completes the phrase can be the name of any registered central body. See the STKData\CentralBodies directory for a list of registered central bodies.

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

Example:

    CentralBody Earth
CoordinateAxes No

When specified, the Reference Frame associated with the altitude data: the orientation of the sensor's body axes are determined from the attitude data applied to this frame. When not specified the attitude data in the file is associated with the Reference Frame defined above, which depends on the object type of the sensor's parent.

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, though certain bodies support additional systems.


You can use any of the pre-defined reference axes. For a complete list of VGT central body frames, go to the Vector Geometry tool in Analysis Workbench and select a specific primary or secondary body, or an object on a particular central body. All supported VGT components, including reference frames, will appear 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 to which it corresponds. VGT-created axes must use the keyword CoordinateAxes AWB. For example, CoordinateAxes AWB NorthEastDown Aircraft/AircraftName.


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


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.
BEGIN Attitude
END Attitude		 Yes These are markers to set off the beginning and end of the actual attitude data. All other keyword phrases and data point specification (except the version stamp) will be inside these two keyword phrases. Refer to any of the sample files included in the File Format section for examples.
NumberOfAttitudePoints No

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

Prior to STK 11.5, this keyword was required.

Example:

If you entered
    NumberOfAttitudePoints 1000

STK would read up to 1000 attitude points.
Sequence No.

Used by Euler, YPR, and AzEl 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 = 312). There are two (2) sequences valid for AzEl angles (default = 323, 213).

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.

Prior to the AttitudeTimeAzElAngles keyword and its data points, you may include a Sequence keyword phrase specifying the order of rotation about the axes.

For AzEl angles, the last rotation is always set to 0.0 and thus is not provided in the table of data. When using AzEl angles, the 323 sequence is equivalent to using the Rotate About Boresight option for Fixed sensor pointing. The 213 sequence is equivalent to using Hold About Boresight option for Fixed sensor pointing.

STK will supply a default.

Example:

    Sequence 323

Refer to the Help topic on Sensor Orientation Methods for more information on rotation sequence options.
ScenarioEpoch No

When specified in the file, this is the reference epoch time for the time values of the attitude data in the file. Specify the value using Gregorian UTC time (dd mmm yyyy hh:mm:ss.s). When not specified, the time values of the attitude data in the file are referenced to the STK Scenario Epoch when the file is loaded. A subsequent change to the STK Scenario Epoch will not affect already loaded data. To use the new STK Scenario Epoch as the reference, you must reload the attitude file.

The Scenario Epoch keyword and value have no effect on the STK Scenario Epoch, only on the time values of the attitude data in the file.

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.
RepeatPattern No Selecting this will direct STK to use the attitude data in a cyclical manner. The input data should represent a closed pattern, with the first and last data points being the same.
AttitudeDeviations {Rapid |Mild} No

Select from the following options:

Rapid. The attitude may change suddenly from one data point to the next, so Access should take samples near each time in the data points to avoid missing accesses.

Mild. The attitude is sufficiently smooth over time so that no special Access sampling is required. The use of this setting will likely make Access computations faster, but accesses may be missed if the actual data isn't sufficiently smooth.

If you make no selection, the default is Rapid.
TimeFormat No

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

This defines the date format of time tags. If set, each line of data in the file begins with a time in this 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.

Examples:

TimeFormat DD/MM/YYYY

TimeFormat GPSZ

File formats

While the sections above outline the basic format for a Sensor Pointing file, the sections below outline the four formats used to specify actual data points in the Sensor Pointing file.

The first three formats used to specify attitude data for pointing a sensor are identical to those used in the Attitude file format. The links below will redirect you to the Help for those formats. The last format, AttitudeTimeAzElAngles, is described below.

Refer to the Help topic on Sensor Orientation Methods for more information on specifying attitude data using any of the four formats outlined here.

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.
  • There must be at least as many points as specified by the NumberOfAttitudePoints keyword.
  • If the attitude is very dynamic (e.g., spinning or slewing rapidly), you should specify more points during the period of rapid motion. For spinning spacecraft, you should have at least three or four points per revolution in order to create an accurate representation of the spinning motion within the Attitude file.

AttitudeTimeAzElAngles Format

The AttitudeTimeAzElAngles keyword phrase indicates that sensor attitude data is in time-ordered azimuth and elevation angles. These angles determine the direction of the sensor boresight (i.e., the sensor body +Z axis). The sensor body axes orientation is found using an Euler sequence of rotations, first by azimuth, then by elevation, with the third angle being 0.0.

The elevation is the angle of the boresight above the Reference Frame XY plane, positive toward the Reference Frame +Z axis. The azimuth angle is the angle of the projection of the boresight direction into the Reference Frame XY plane from the plane's +X axis. The azimuth is considered positive as it moves counter-clockwise about:

  • The Reference Frame +Z axis:
    • when the Reference Frame is specified
    • when the Reference Frame is not specified, but the sensor's parent is a vehicle
  • The Reference Frame -Z axis (which is also the Body +Z axis):
    • when the Reference Frame is not specified, but the sensor's parent is a Facility/Target/Place. (This is the normal convention for azimuth for a ground location being measured from North (+X) positive toward East.)

Individual data points following the AttitudeTimeAzElAngles keyword look like this:

<TimeInSeconds> <Azimuth> <Elevation>

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
<Azimuth> The azimuth angle entered in degrees
<Elevation> The elevation angle in degrees

Prior to the AttitudeTimeAzElAngles keyword and its data points, you must include a Sequence keyword phrase specifying the order of rotation about the axes.

A Sensor pointing file using the AttitudeTimeAzElAngles format to specify sensor pointing data would look like this sample file.