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


FreeFlyer provides the capability to read TLE files via the Spacecraft, TwoLineElement, Formation, and TLECatalog objects.

 

All the examples in this section use this sample Three-Line Element file:

 

threeStates.tle

0 AQUA

1 27424U 02022A   15020.82218866  .00000465  00000-0  11324-3 0  2491

2 27424 098.2255 323.8633 0001418 088.0133 006.7657 14.57093363676367

0 ISS (ZARYA)

1 25544U 98067A   15021.59242667  .00016124  00000-0  25567-3 0  7585

2 25544 051.6481 095.9241 0005737 283.2820 218.1353 15.53529390925229

0 GPM

1 39574U 14009C   15020.55092466  .00016648  00000-0  23883-3 0  3702

2 39574 065.0186 028.2192 0010836 269.4707 090.5196 15.56224760 50848

 

Spacecraft

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).

 

String threeStatesFile = "threeStates.tle";

Variable spacecraftIdx = 1; // 0-based index of spacecraft

 

Spacecraft ISS;

 

ISS.LoadNoradTLE(threeStatesFile, "ISS (ZARYA)");

 

/*** OR ***/

 

ISS.LoadNoradTLE(threeStatesFile, spacecraftIdx);

 

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:

 

StringArray tleContents;

tleContents.ReadFromFile(threeStatesFile);

 

Spacecraft ISS;

 

ISS.LoadNoradTLE(tleContents[3:5]); // The ISS Norad state is in indices 3 through 5

 

Note: See the StringArray properties and methods page for more information on reading text files through the StringArray object.

 

TwoLineElement

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:

 

String threeStatesFile = "threeStates.tle";

Variable spacecraftIdx = 1; // 0-based index of spacecraft

 

TwoLineElement IssTwoLineElement;

 

IssTwoLineElement.LoadNoradTLE(threeStatesFile, "ISS (ZARYA)");

 

/*** OR ***/

 

IssTwoLineElement.LoadNoradTLE(threeStatesFile, spacecraftIdx);

 

/*** OR ***/

 

StringArray tleContents;

tleContents.ReadFromFile(threeStatesFile);

 

IssTwoLineElement.LoadNoradTLE(tleContents[3:5]);

 

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:

 

Spacecraft ISS;

 

IssTwoLineElement.InitializeTLEFromSpacecraft(ISS);

 

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):

 

Spacecraft ISS;

 

IssTwoLineElement.SetSpacecraftNoradStateFromTLE(ISS);

 

Formation

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:

 

String threeStatesFile = "threeStates.tle";

 

Formation LEOSet;

 

LEOSet.LoadNoradTLE(threeStatesFile);

 

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).

 

TLECatalog

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:

 

String threeStatesFile = "threeStates.tle";

 

TLECatalog simpleCatalog;

 

simpleCatalog.LoadNoradTLE(threeStatesFile);

 

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:

 

Spacecraft ISS;

Variable spacecraftIdx = 1; // 0-based index of spacecraft

 

simpleCatalog[spacecraftIdx].SetSpacecraftNoradStateFromTLE(ISS);

 

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:

 

Variable fitSpan = 2; // Days

 

// Set up a 'definitive' Spacecraft with the ephemeris

Spacecraft scDefinitive;

scDefinitive.SetPropagatorType(TypeOf(Ephemeris));

(scDefinitive.Propagator AsType Ephemeris).LoadEphemeris("myDefinitive.ephem");

 

// Set up a Spacecraft for processing

Spacecraft scSGP4;

scSGP4.SetPropagatorType(TypeOf(Norad));

 

// Make sure initial states are lined up

scSGP4.Epoch = scDefinitive.Epoch;

scSGP4.Position = scDefinitive.Position;

scSGP4.Velocity = scDefinitive.Velocity;

 

Once the Spacecraft objects are configured, the NoradStateEstimator can be configured as follows:

 

// Configure NoradStateEstimator object

NoradStateEstimator noradEstimator;

noradEstimator.SetReferenceSpacecraft(scDefinitive);

noradEstimator.SetSpacecraftToProcess(scSGP4);

noradEstimator.FitSpanDuration = fitSpan;

 

// This call will execute 3 iterations of the Batch OD process to determine a Norad state

noradEstimator.PerformFit(); 

 

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:

 

// Configure NoradStateEstimator object

NoradStateEstimator noradEstimator;

noradEstimator.SetReferenceSpacecraft(scDefinitive);

noradEstimator.SetSpacecraftToProcess(scSGP4);

 

// Specify the Element set to use when estimating the orbit state

noradEstimator.ObservationModel.ElementSetToUse = "Equinoctial";

 

// Set option flags

noradEstimator.ObservationModel.SpanStartEpochOption = 1;

noradEstimator.ObservationModel.SpanIntervalOption = 1;

 

// Configure sampling start and frequency

noradEstimator.ObservationModel.DataSpanStartEpoch = scDefinitive.Epoch; 

noradEstimator.ObservationModel.StepSize = TimeSpan.FromSeconds(60);

 

// Solve for B*

scSGP4.OD.BStar.ProcessAction = 1; 

 

// This call will execute 3 iterations of the Batch OD process to determine a Norad state

noradEstimator.PerformFit(); 

 

 

// The final Norad state is stored in Spacecraft properties and TwoLineElement properties

Report scSGP4.NoradE, scSGP4.NoradI, scSGP4.NoradMA, scSGP4.NoradMeanMotion, scSGP4.NoradRAAN, scSGP4.NoradW;

 

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:

 

FFGroundObservationFile ffGroundObservationData;

 

ffGroundObservationData.Filename = "groundstationObservations.txt";

 

ffGroundObservationData.SetObservedSpacecraft(scSGP4);

ffGroundObservationData.AddObservationSource(myGroundstation);

 

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:

 

// Configure NoradStateEstimator object

NoradStateEstimator noradEstimator;

noradEstimator.SetSpacecraftToProcess(scSGP4);

 

// Do not use the ObservationModel child object to generate observations

noradEstimator.UseObservationModel = 0;

 

// Register the tracking data file to the BatchLeastSquaresOD child object

noradEstimator.Batch.RegisterTrackingDataFile(ffGroundObservationData);

 

// Solve for B*

scSGP4.OD.BStar.ProcessAction = 1; 

 

Variable numIterations = 5;

 

// This call will iterate the Batch OD process 5 times to determine a Norad state

noradEstimator.Batch.Iterate(numIterations); 

 

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:

 

NoradStateEstimator IssStateEstimator;

 

String outFile = "states.tle";

 

// Option to specify whether or not the spacecraft name will be written

// i.e. whether to write a two-line element set or a three-line element set

Variable writeSCName = 1; 

 

// Option to specify whether or not to append the TLE to an existing file

Variable appendToFile = 1; 

 

IssStateEstimator.TLEHandler.Classification = 'U'// Set classification of object

IssStateEstimator.TLEHandler.SatelliteNumber = 25544; // Set catalog ID of object

IssStateEstimator.TLEHandler.InternationalDesignator = "98067A"// Set international designator of object

 

/*** Script used to generate Norad state will go here ***/

 

IssStateEstimator.TLEHandler.WriteToFile(writeSCName, outFile);

 

/*** OR ***/

 

IssStateEstimator.TLEHandler.WriteToFile(writeSCName, outFile, appendToFile);

 

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):

 

String tleLine1;

String tleLine2;

 

IssStateEstimator.TLEHandler.GenerateTwoLineStrings(tleLine1, tleLine2);

 

The TLECatalog object allows the user to export a collection of TwoLineElement objects to a file via the TLECatalog.WriteToFile method:

 

TLECatalog fullCatalog;

 

String scName;

String tleLine1;

String tleLine2;

 

// Flag indicating whether or not there are Spacecraft objects that need to be processed

Variable scLeftToProcess = 1;

Variable writeSCName = 1; 

 

While (scLeftToProcess == 1);

 

    /*** Script used to generate Norad state will go here, updating scLeftToProcess ***/

    /*** Assume the NoradStateEstimator object is used to generate the Norad state ***/

 

    // Cache Norad state

    scName = noradEstimator.TLEHandler.SpacecraftName;

    noradEstimator.TLEHandler.GenerateTwoLineStrings(tleLine1, tleLine2);

 

    // Increment number of catalog objects

    fullCatalog.Count++;

 

    // Add Norad state to catalog

    fullCatalog[fullCatalog.Count - 1].InitializeFromStrings(scName, tleLine1, tleLine2);

 

End;

 

String outFile = "fullCatalog.tle";

fullCatalog.WriteToFile(writeSCName, outFile);

 

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:

 

Spacecraft ISS;

 

ReportInterface tleFile;

tleFile.Filename = "singleState.tle";

 

ISS.Report_TLE(tleFile);

 

Alternatively, the method is able to return a String object:

 

Spacecraft ISS;

 

String tleState;

 

tleState = ISS.Report_TLE();

 

The same Spacecraft.Report_TLE method can be used with a Formation object:

 

Formation LEOSet;

Variable i;

 

// LEOSet filled in with different states

 

ReportInterface tleFile;

tleFile.Filename = "singleState.tle";

tleFile.Append = 1; // Make sure file is not being overwritten

 

For i = 0 to LEOSet.Count - 1;

 

    LEOSet[i].Report_TLE(tleFile);

 

End;

 

 

See Also


Including Tracking Data in an Estimator

Setting up Batch Least Squares

Norad Two-Line Element Set File

Spacecraft Properties and Methods

Formation Properties and Methods

TwoLineElement Properties and Methods

TLECatalog Properties and Methods

OrbitStateObservationGenerator Properties and Methods

NoradStateEstimator Properties and Methods