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 The name of the satellite in the satellite 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 to be used in the satellite 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 to be used in the Satellite Collection.
SSC ID Yes The value must be a valid SSC number specification, meeting one of the following criteria:
  • an integer between 1 and 999,999,999
  • an alpha5 number composed of a leading capital letter (other than 'I' or 'O') and four decimal digits, where leading zeros are used for numbers less than 1000
  • a string of nine or fewer alphanumeric characters
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