Custom Orbit Definition File Format (*.csv)
A custom orbit definition file is an ASCII text file that is formatted for compatibility with STK and ends in a .csv extension.
The file contains header information and two tables of comma-separated data. Use this file to define a Satellite Collection object by listing each satellite entry by name in a row. The row should also contain the orbit definition for the entry and any optional metadata. STK supports several orbit definitions.
STK ignores blank lines in the file. For lines with a '#' character as the first character in the row, STK treats them as comments and does not process them.
Keywords
Keywords used in custom orbit definition files are NOT case-sensitive; the capitalization used in this document is for readability.
Keyword | Required | Description |
---|---|---|
Version | Yes | This is the version of the format of the file. STK only supports 1.0. This should be the first keyword in the file and must appear before the CustomColumns and Columns sections.
This is not the STK software version. |
MaxNumErrorsToReport | No | This is the maximum number of error messages to report to the message viewer. By default, the maximum is 10. After reaching the maximum number, STK suppresses further messages. This must appear before the CustomColumns and Columns sections. |
ContentType | Yes | Choose one of the following: OrbitElements, EphemerisFile, SSC, or Metadata. The value determines the orbit definition specification and required columns (see the sections below).
Use the Metadata content type for supplemental data; you cannot use it for orbit definitions. |
BeginCustomColumns End CustomColumns |
No | These set off the section that defines metadata for each satellite collection entry. |
Begin Columns End Columns |
Yes | These set off the section that defines satellite collection entries, with its orbit definition and metadata. |
CustomColumns section format
The CustomColumns section defines metadata that are associated with each satellite collection entry in the content of the Columns section.
The first nonblank, noncomment line is the header row, which contains the keywords to be read, separated by commas.
You can place Keywords in any order, though typically the ColumnName column appears first and DataType appears second.
Each nonblank, noncomment line that follows the header line contains comma-separated content defining a metadata value. The values correspond to the order defined by the header row. You may leave values for optional columns blank.
Keyword | Required | Description |
---|---|---|
ColumnName | Yes | This is the name of the metadata item. Valid characters are A-Z, a-z, 0-9, _, and space. STK ignores leading and trailing white space. You can enclose the value within quotes (e.g., "Column Name"), but the quotes are not part of the name. |
DataType | Yes | Choose one of the following: String, Integer, Double, Bool, Epoch, or Enumeration. The value indicates the type of data. You may use Boolean in place of Bool, Enum in place of Enumeration, and Date and DateTime in place of Epoch. Double indicates a real value, such as 1.234. Bool indicates a value where true is represented by Y|Yes|True|1 and false by N|No|False|0. Epoch represents a UTC date in ISO-YMD or ISO-YD format. Enumeration indicates that the value must be one of a specified set of String values. |
Dimension | No | This is the name of the dimension of the data. If you include Dimension in the file, you must also include UnitAbbrv. |
UnitAbbrv | No | This is the unit abbreviation that describes the units of the native data contained in the file. The unit must be valid for the Dimension. If you include Dimension in the file, you must also include UnitAbbrv. If you do not include Dimension in the file, you must also not include UnitAbbrv. |
Required | No | This sets whether the file reader enforces that you must provide the column value. The default value is No. If you set the metadata item to required and a content line in the Columns section does not contain a value for this item, STK treats that row as badly formatted and ignores the satellite collection entry defined by that row. Use Y|Yes|True|1 to set the value as true; use N|No|False|0 for false. |
MinValue | No | This sets whether the file reader enforces that the column value must be greater than or equal to this specified value. By default, no minimum value is required. If you specify a minimum and a content line in the Columns section has a value for this item less than the minimum value, STK treats that row as badly formatted and ignores the satellite collection entry defined by that row.
This keyword only applies when the DataType is Integer or Double. |
MaxValue | No | This sets whether the file reader enforces that the column value must be less than or equal to this specified value. By default, no maximum value is required. If you specify a maximum and a content line in the Columns section has a value for this item greater than the maximum value, STK treats that row as badly formatted and ignores the satellite collection entry defined by that row.
This keyword only applies when the DataType is Integer or Double. |
EnumValues | No | This is required if DataType is Enumeration. It specifies a set of acceptable values. Delineate the acceptable values in the array using '|' as a separator, for example a | b | c | d. STK ignores leading and trailing white space around each value. |
CreateSubsets | No | This indicates that STK should use the metadata item's values to automatically generate subsets, using the values found in the content. It is most appropriate for use with Enumeration data. STK ignores this value if the DataType is Double.
Be cautious when using this for an Integer, String, or Epoch column. If you do not repeat values in the content, then the code could create many subsets containing few entries. |
This is an example of a CustomColumns section within a file.
Begin CustomColumns
ColumnName, DataType, Required, EnumValues, MinValue, MaxValue, CreateSubsets, Dimension, UnitAbbrv
Shell, String, Yes
Plane, String, Yes
Generation, Integer, Yes, , 1, 3, Yes
Frequency Band, Enum, No, S|C|X|Ka|Ku
Active, Bool, No
Rcs, Double, No, , 0.0, , No, Small Area, m^2
Subset, String, Yes
Bus, Enumeration, No, LH57Y | BFG64K
End CustomColumns
Columns section format
The Columns section defines the members of the satellite collection by specifying their names, orbit definition, and optional metadata. The first nonblank, noncomment line is the header row, which contains the keywords to be read, separated by commas. You can place keywords in any order, though typically the Name column appears first. The names of all required columns for the content type specified must appear; optional names and metadata column names (defined in the CustomColumns section) may also appear.
Each nonblank, noncomment line that follows the header line contains comma-separated content defining a satellite collection entry. The values correspond to the order defined by the header row. For optional columns and custom columns, you may leave the values blank, unless otherwise documented above.
ContentType is OrbitElements
The following table specifies the required columns when the orbit definition is specified using orbit elements.
Keyword | Required | Description |
---|---|---|
Name | Yes | This is the name of the satellite in the satellite collection. It must be a unique name within the collection. |
Semimajoraxis | Yes | Value in km; must be greater than 1 mm |
Eccentricity | Yes | Must be between 0.0 and 0.999999 |
Inclination | Yes | Value in degrees; must be between 0.0 and 180.0 |
RAAN | Yes | Right ascension of the ascending node; value in degrees; must be between -360.0 and 360.0 |
ArgumentofPeriapse | Yes | Value in degrees; must be between -360.0 and 360.0 |
MeanAnomaly | No | Value in degrees; must be between -360.0 and 360.0; specify either MeanAnomaly or TrueAnomaly as a column, but not both; values cannot be blank |
TrueAnomaly | No | Value in degrees; must be between -360.0 and 360.0; specify either MeanAnomaly or TrueAnomaly as a column, but not both; values cannot be blank |
Epoch | No | Value must be in ISO-YMD or ISO-YD format; If you do not specify the Epoch, then STK uses the default orbit epoch defined by the satellite collection |
AvailabilityStartTime | No | Restricts the availability of the entry to be no earlier than the specified date, no matter what the SatelliteCollection interval start date is specified to be. The value must be in ISO-YMD or ISO-YD format. |
AvailabilityStopTime | No | Restricts the availability of the entry to be no later than the specified date, no matter what the SatelliteCollection interval stop date is specified to be. The value must be in ISO-YMD or ISO-YD format. |
If you specify both AvailabilityStartTime and AvailabilityStopTime for an entry, but AvailabilityStopTime < AvailabilityStartTime, then STK will ignore these values when determining the entry's availability.
Here is an example of the required columns for ContentType is OrbitElements, with custom columns defined as Shell, Frequency Band, and Generation.
Begin Columns
Name, Epoch, SemiMajorAxis, Eccentricity, Inclination, RAAN, ArgumentOfPeriapse, TrueAnomaly, Shell, Frequency Band, Generation
Sat1, 2021-02-23T16:00:00.00, 8000.0, 0.000, 55.0, 90.0, 0.0, 15.0, 1, Ka, 2
Sat2, , 8000.0, 0.000, 55.0, 135.0, 60.0, 75.0, 2, X, 1
Sat3, , 8000.0, 0.000, 55.0, 275.0, 120.0, 60.0, 2, , 1
End Columns
ContentType is EphemerisFile
The following are required columns if the orbit definition is an STK ephemeris file.
Keyword | Required | Description |
---|---|---|
Name | Yes | This is the name of the satellite in the satellite collection. It must be a unique name within the collection. |
Filename | Yes | This is an ephemeris file name (not an absolute path). Each ephemeris file is loaded from the folder specified by the custom ephemeris directory of the satellite collection that loads this file. |
AvailabilityStartTime | No | Restricts the availability of the entry to be no earlier than the specified date, no matter what the SatelliteCollection interval start date is specified to be. The value must be in ISO-YMD or ISO-YD format. |
AvailabilityStopTime | No | Restricts the availability of the entry to be no later than the specified date, no matter what the SatelliteCollection interval stop date is specified to be. The value must be in ISO-YMD or ISO-YD format. |
If you specify both AvailabilityStartTime and AvailabilityStopTime for an entry, but AvailabilityStopTime < AvailabilityStartTime, then STK will ignore these values when determining the entry's availability.
The following is an example of required columns when ContentType is EphemerisFile, with custom columns defined as Subset, Active, and RCS.
Begin Columns
Name, Subset, Active, Filename, RCS
Chaser, BlueGroup, Y, Chaser.e, 12.3
Target1, RedGroup, No, Target1_RunA.e,
Target2, RedGroup, True, Target2_RunC.e, 3.4
End Columns
ContentType is SSC
STK uses the SSC identifier to obtain the orbit definition from a file specified by the Satellite Collection. The required columns are defined in the table below.
Keyword | Required | Description |
---|---|---|
Name | Yes | This is the name of the satellite in the satellite collection. It must be a unique name within the collection. |
SSC ID | Yes | The value must be a valid SSC number specification, meeting one of the following criteria:
|
AvailabilityStartTime | No | Restricts the availability of the entry to be no earlier than the specified date, no matter what the SatelliteCollection interval start date is specified to be. The value must be in ISO-YMD or ISO-YD format. |
AvailabilityStopTime | No | Restricts the availability of the entry to be no later than the specified date, no matter what the SatelliteCollection interval stop date is specified to be. The value must be in ISO-YMD or ISO-YD format. |
If you specify both AvailabilityStartTime and AvailabilityStopTime for an entry, but AvailabilityStopTime < AvailabilityStartTime, then STK will ignore these values when determining the entry's availability.
STK does not support the SSC ContentType value.
ContentType is Metadata
Use this ContentType to designate the file as supplemental data. It does not define an orbit and is only used to assign metadata to satellite entries already defined by the satellite collection. The required columns are defined in the table below.
Keyword | Required | Description |
---|---|---|
Name | Yes | This is the name of the satellite to be used in the satellite collection. |
AvailabilityStartTime | No | Restricts the availability of the entry to be no earlier than the specified date, no matter what the SatelliteCollection interval start date is specified to be. The value must be in ISO-YMD or ISO-YD format. |
AvailabilityStopTime | No | Restricts the availability of the entry to be no later than the specified date, no matter what the SatelliteCollection interval stop date is specified to be. The value must be in ISO-YMD or ISO-YD format. |
If you specify both AvailabilityStartTime and AvailabilityStopTime for an entry, but AvailabilityStopTime < AvailabilityStartTime, then STK will ignore these values when determining the entry's availability.
Here is an example of a Metadata file with custom columns defined as Subset, Active, RCS, Bus, and Frequency Band.
Begin Columns
Name, Subset, Active, RCS, Bus, Frequency Band
Chaser, BlueGroup, Y, 3.9, LH57Y, X
Target1, RedGroup, No, , BFG64K, Ka
Target2, RedGroup, True, 1.2, LH57Y,
End Columns
Supplemental data file format (*.csv)
A supplemental data file is an ASCII text file that contains custom metadata. Its format is the same as the custom orbit definition file, where the ContentType value is specified as Metadata and no columns defining orbit definitions are required.
You may use a custom orbit definition file to specify supplemental data. In that case, STK ignores the orbit definitions that are loaded.
If the Satellite Collection is defined by an Orbit Definition File that contains columns for AvailabilityStartTime or AvailabilityStopTime (or both), STK will ignore the AvailabilityStartTime and AvailabilityStopTime columns appearing in the supplemental metadata file.
Example of OrbitElement file with custom columns:
VERSION 1.0
ContentType OrbitElements
Begin CustomColumns
ColumnName, DataType, Required, EnumValues, Dimension, UnitAbbrv, MinValue, MaxValue, CreateSubsets
Shell, String, Yes
Plane, String, Yes
Subset, String, Yes
LaunchDate, String, Yes, , , , , , Yes
Generation, Enum, Yes, 0.9| 2.1 | 2.0 | 1.0, , , , , No
FrequencyBand, Enum, No, S|C|X|Ka|Ku, , , , , Yes
Active, Bool, No, , , , , , Yes
Rcs, Double, No, , , , 12.1, 12.6, Yes
End CustomColumns
Begin Columns
Name, Epoch, SemiMajorAxis, Eccentricity, Inclination, RAAN, ArgumentOfperiapse, TrueAnomaly, Shell, Plane, Active, FrequencyBand, Rcs, Launchdate, Generation, Subset,
S1_P1_S1, "2020-05-28T16:00:00.00", 8000.0, 0.000, 80.0, 90.0, 0.0, 5.0, 1, 1, Yes, Ka, 12.1, 2007-12-09, 0.9, BlueGroup
S1_P1_S2, "2020-05-28T16:00:00.00", 8000.0, 0.000, 80.0, 90.0, 0.0, 100.0, 1, 1, Y, Ka, 12.1, 2007-12-09, 0.9, BlueGroup
S1_P1_S3, "2020-05-28T16:00:00.00", 8000.0, 0.000, 80.0, 90.0, 0.0, 200.0, 1, 1, 1, Ku, 12.2, 2007-12-09, 1.0, RedGroup
S1_P1_S4, "2020-05-28T16:00:00.00", 8000.0, 0.050, 80.0, 90.0, 0.0, 300.0, 1, 1, True, Ku, 12.3, 2007-12-09, 1.0, RedGroup
S1_P2_S1, "2020-05-28T16:00:00.00", 8000.0, 0.040, 70.0, 18.0, 0.0, 5.0, 1, 2, No, Ku, 12.4, 2007-12-09, 1.0, RedGroup
S1_P2_S2, "2020-05-28T16:00:00.00", 8000.0, 0.030, 70.0, 18.0, 0.0, 100.0, 1, 2, N, S, 12.5, 2007-12-09, 2.0, BlueGroup
S1_P2_S3, "2020-05-28T16:00:00.00", 8000.0, 0.020, 70.0, 18.0, 0.0, 200.0, 1, 2, 0, S, 12.6, 2007-12-09, 2.1, BlueGroup
S1_P2_S4, "2020-05-28T16:00:00.00", 8000.0, 0.010, 70.0, 18.0, 0.0, 300.0, 1, 2, False, S, 12.6, 2007-12-09, 2.1, RedGroup