Using Two-Line Element Sets
|Top Previous Next|
The US Air Force provides data for Earth-orbiting satellites in Two or Three-Line Orbital Element Sets (TLE). The descriptions of the Two and Three-Line Orbital Element Set formats are covered in the Norad Two-Line Element Set File page. These element sets are general perturbation mean elements constructed by a least squares estimation process from observation data. The Air Force provides the states using observations from the Space Surveillance Network, and FreeFlyer provides the capability to generate TLEs using an ephemeris or by processing observation data.
The mean state values (referred to as a Norad state in this guide) are constructed by removing periodic variations in the force model due to the oblateness of the Earth, atmospheric drag, and lunar and solar gravitational effects. In order to obtain good predictions from the state, the periodic variations must be reconstructed in exactly the same way they were removed. FreeFlyer's Norad propagator (which implements the SGP4/SDP4 algorithm) provides the means of reconstructing the variations, thus enabling the proper propagation of Norad states. Therefore, if you are loading a Spacecraft state from a TLE, you should use a Norad, NoradSP, or NoradSGP4 propagator when running your Mission Plan.
Importing Two Line Element Sets
All the examples in this section use this sample Three-Line Element file:
Through the Spacecraft.LoadNoradTLE method, the user is able to load a spacecraft state from a TLE file given the file name and either an index or the name of the spacecraft to load. The state of the ISS can be loaded with the following script:
Note: If a Spacecraft name is specified, the TLE file must be in the Three-Line Element format and the name must match the name in the file exactly (i.e. the search is case sensitive).
The Spacecraft.LoadNoradTLE method also provides the capability of reading the Norad state from a StringArray object. This specific overload may be useful when loading Norad states through a socket connection or by other means where reading a file is not necessary. Once again, the state of the ISS can be loaded from a StringArray object with the following script:
Note: See the StringArray properties and methods page for more information on reading text files through the StringArray object.
The TwoLineElement object gives access to a suite of tools used for TLE generation and reading (among other capabilities). The TwoLineElement.LoadNoradTLE method provides the same functionality as the Spacecraft.LoadNoradTLE method while additionally reading components of the TLE that are not used by the Spacecraft such as International Designator, B* dot, B* double dot, and element set number. The examples below are similar to those given above, re-written with the TwoLineElement object:
Note: The NoradStateEstimator object (used for TLE generation) owns a TwoLineElement object named TLEHandler. See the section on generating TLEs using the NoradStateEstimator.
The TwoLineElement can also be initialized from the state of an existing Spacecraft object:
To apply a loaded state to a Spacecraft object, use the TwoLineElement.SetSpacecraftNoradStateFromTLE method like so (this example assumes the Norad state has already been loaded into the TwoLineElement object as in the example above):
Using the Formation.LoadNoradTLE method, a text file containing multiple Norad states can be imported into a Formation object. Using the sample file 'threeStates.tle' given above, the syntax to load all three states into a Formation object is:
Note: The LoadNoradTLE method will resize the Formation object as long as the current number of Spacecraft in the Formation is less than the number of states in the TLE file. The size of the Formation cannot be reduced (i.e. a TLE file with 3 states cannot be read into a Formation object that has a size of 4).
The TLECatalog object is a container for one or more TwoLineElement objects. TLECatalogs are a specialized version of a List of TwoLineElements (you can create a List of most FreeFlyer objects). The benefit of a TLECatalog over a List of TwoLineElements is that the TLECatalog gives the user the ability to load a large list of Norad states and manipulate them in a central location. To load a list of Norad states, the same syntax from the Formation.LoadNoradTLE method can be used. For example, the syntax to load all three states into the TLECatalog object is:
Once the states have been loaded into the TLECatalog object, the user can set an individual state to a Spacecraft object in the same fashion described above with the TwoLineElement.SetSpacecraftNoradStateFromTLE method. Assuming the TLECatalog has been loaded, the syntax to load a specific state to a Spacecraft object is:
Note: The LoadNoradTLE method will resize the TLECatalog object as long as the TLE file contains an equal or higher number of entries compared to the TLECatalog object. The size of the TLECatalog cannot be reduced (e.g. a TLE file with 3 states cannot be read into a TLECatalog object that has a size of 4).
Generating Two Line Element Sets Using The NoradStateEstimator
The NoradStateEstimator object allows the user to generate a Norad state by using a Batch Least Squares estimator which computes incremental state updates to converge on a solution. In FreeFlyer, the user can specify a propagator type or observation data to be used in the estimation process to compute a Norad state. A common approach is to use an ephemeris file; thus, the procedure for generating a TLE using an ephemeris is provided.
Using an Ephemeris
Given an ephemeris, it is fairly easy to generate a Norad state which can then be exported to a TLE file. The process involves configuring two Spacecraft objects: one to be propagated with the ephemeris and another which will be processed through an estimator to generate the Norad state. Below is an example of how the Spacecraft objects can be configured:
Once the Spacecraft objects are configured, the NoradStateEstimator can be configured as follows:
The NoradStateEstimator object has a child object, the ObservationModel object, which generates observations to be used in the fit of the trajectory. The user can access the ObservationModel child object in order to configure how the observations will be generated. Some of the configuration options are shown in the following example:
Note: Any type of propagator can be used for the definitive Spacecraft object. This example used the Ephemeris type since it is a common use case.
See the 'Exporting Two Line Element Sets' section in this guide for information and examples on exporting the Norad state.
Using Observation Data
In place of having an ephemeris, a Norad state can be generated using observation data which will be processed through a Batch Least Squares estimator. The method of processing the observation data is similar to configuring a BatchLeastSquaresOD object in FreeFlyer. To start, the observation data needs to be imported into FreeFlyer:
See the Including Tracking Data in an Estimator guide for more detailed information on importing observation data into FreeFlyer. Once the data is imported, the NoradStateEstimator object needs to be configured to use the observation data:
See the Setting up Batch Least Squares guide for detailed information on configuring BatchLeastSquaredOD object. The next section, "Exporting Two Line Element Sets" provides information and examples on writing Norad states to file.
Exporting Two Line Element Sets
In addition to providing the capability to import TLE files, FreeFlyer allows the user to export Norad states from the TwoLineElement, TLECatalog, Spacecraft, and Formation objects.
TwoLineElement and TLECatalog
The NoradStateEstimator owns a TwoLineElement object called TLEHandler. Once the Norad state is generated from the NoradStateEstimator, the user is able to modify certain properties of the TLEHandler in order to write out the data in the TLE format. For example, assuming that a NoradStateEstimator object has a valid Norad state, the following syntax generates a TLE file containing a single Norad state of the ISS:
In addition to writing to a file, the Norad state can be written to a pair of String objects (one for each line in the two-line element set):
The TLECatalog object allows the user to export a collection of TwoLineElement objects to a file via the TLECatalog.WriteToFile method:
Spacecraft and Formation
The Spacecraft.Report_TLE method takes a differential correction of the state to minimize the error at the epoch that the method was called. This is different than when compared to the NoradStateEstimator because the NoradStateEstimator takes a differential correction to minimize the error across a time span.
Note: It is strongly recommended that the NoradStateEstimator object is used over the Spacecraft.Report_TLE method when generating Norad states. Using the NoradStateEstimator ensures better long term propagation when using an SGP4 propagator.
To write a Spacecraft state to a TLE file using a ReportInterface object, the following syntax can be used:
Alternatively, the method is able to return a String object:
The same Spacecraft.Report_TLE method can be used with a Formation object:
•Spacecraft Properties and Methods
•Formation Properties and Methods
•TwoLineElement Properties and Methods
•TLECatalog Properties and Methods
•OrbitStateObservationGenerator Properties and Methods
•NoradStateEstimator Properties and Methods