The Perl Toolchain Summit needs more sponsors. If your company depends on Perl, please support this very important event.
 / 
Astro-satpass-0.009
River stage one • 7 direct dependents • 8 total dependents
4 ++
/ Astro::Coord::ECI::TLE

NAME

Astro::Coord::ECI::TLE - Compute satellite locations using NORAD orbit propagation models

SYNOPSIS

 my @sats = Astro::Coord::ECI::TLE->parse ($tle_data);
 my $now = time ();
 foreach my $tle (@sats) {
     my @latlon = $tle->universal ($now)->geodetic ();
     my @xyz = $tle->eci ();    # For same time.
     print $tle->get ('id'), "\t@latlon\t@xyx\n";
     }

The acquisition of the orbital elements represented by $tle_data in the above example is left as an exercise for the student.

Hint: see http://www.space-track.org/, http://celestrak.com/, or Astro::SpaceTrack.

DESCRIPTION

This module implements the NORAD orbital propagation models described in their "SPACETRACK REPORT NO. 3, Models for Propagation of NORAD Element Sets." In other words, it turns the two- or three-line element sets available from such places as http://www.space-track.org/ or http://celestrak.com/ into predictions of where the relevant orbiting bodies will be. This module does not implement a complete satellite prediction system, just the NORAD models.

The models implemented are:

  SGP - fairly simple, only useful for near-earth bodies;
  SGP4 - more complex, only useful for near-earth bodies;
  SDP4 - corresponds to SGP4, but for deep-space bodies;
  SGP8 - more complex still, only for near-earth bodies;
  SDP8 - corresponds to SGP8, but for deep-space bodies.

There are also some meta-models, with the smarts to run either a near-earth model or the corresponding deep-space model depending on the body the object represents:

  model - uses the preferred model (sgp4 or sdp4);
  model4 - runs sgp4 or sdp4;
  model8 = runs sgp8 or sdp8.

The models do not return the coordinates directly, they simply set the coordinates represented by the object (by virtue of being a subclass of Astro::Coord::ECI) and return the object itself. You can then call the appropriate inherited method to get the coordinates of the body in whatever coordinate system is convenient.

It is also possible to run the desired model (as specified by the model attribute) simply by setting the time represented by the object.

At the moment, the recommended model to use is either SGP4 or SDP4, depending on whether the orbital elements are for a near-earth or deep-space body. For the purpose of these models, any body with a period of at least 225 minutes is considered to be a deep-space body.

The NORAD report claims accuracy of 5 or 6 places a day after the epoch of an element set for the original FORTRAN IV, which used (mostly) 8 place single-precision calculations. Perl typically uses many more places, but it does not follow that the models are correspondingly more accurate when implemented in Perl.

This class is a subclass of Astro::Coord::ECI. This means that the models do not return results directly. Instead, you call the relevant Astro::Coord::ECI method to get the coordinates you want. For example, to find the latitude, longitude, and altitude of a body at a given time, you do

  my ($lat, $long, $alt) = $body->model ($time)->geodetic;

Or, assuming the model attribute is set the way you want it, by

  my ($lat, $long, $alt) = $body->geodetic ($time);

This module is a computer-assisted translation of the FORTRAN reference implementation in "SPACETRACK REPORT NO. 3." That means, basically, that I ran the FORTRAN through a Perl script that handled the translation of the assignment statements into Perl, and then fixed up the logic by hand. Dominik Borkowski's SGP C-lib was used as a reference implementation for testing purposes, because I didn't have a Pascal compiler, and I have yet to get any model but SGP to run correctly under g77.

Methods

The following methods should be considered public:

$tle = Astro::Coord::ECI::TLE->new()

This method instantiates an object to represent a NORAD two- or three-line orbital element set. This is a subclass of Astro::Coord::ECI.

Any arguments get passed to the set() method.

It is both anticipated and recommended that you use the parse() method instead of this method to create an object, since the models currently have no code to guard against incomplete data.

$value = $tle->ds50($time)

This method converts the time to days since 1950 Jan 0, 0 h GMT. The time defaults to the epoch of the data set. This method does not affect the $tle object - it is exposed for convenience and for testing purposes.

It can also be called as a "static" method, i.e. as Astro::Coord::ECI::TLE->ds50 ($time), but in this case the time may not be defaulted, and no attempt has been made to make this a pretty error.

$value = $tle->get('attribute')

This method retrieves the value of the given attribute. See the "ATTRIBUTES" section for a description of the attributes.

$deep = $tle->is_deep();

This method returns true if the object is in deep space - meaning that its period is at least 225 minutes (= 13500 seconds).

$boolean = $tle->is_model_attribute ($name);

This method returns true if the named attribute is an attribute of the model - i.e. it came from the TLE data and actually affects the computations. It is really for the benefit of Astro::Coord::ECI::TLE::Set, so that class can determine how its set() method should handle the attribute.

$boolean = $tle->is_valid_model ($model_name);

This method returns true if the given name is the name of an orbital model, and false otherwise.

Actually, in the spirit of UNIVERSAL::can, it returns a reference to the code if the model exists, and undef otherwise.

This is really for the benefit of Astro::Coord::ECI::TLE::Set, so it can select the correct member object before running the model.

$tle = $tle->model($time)

This method calculates the position of the body described by the TLE object at the given time, using the preferred model. Currently this is either SGP4 for near-earth objects, and SDP4 for deep-space objects.

The intent is that this method will use whatever model is currently preferred. If the preferred model changes, this method will use the new preferred model as soon as I:

  - Find out about the change;
  - Can get the specifications for the new model;
  - Can find the time to code up the new model.

You need to call one of the Astro::Coord::ECI methods (e.g. geodetic () or equatorial ()) to retrieve the position you just calculated.

$tle = $tle->model4 ($time)

This method calculates the position of the body described by the TLE object at the given time, using either the SGP4 or SDP4 model, whichever is appropriate. If the preferred model becomes S*P8, this method will still use S*P4.

You need to call one of the Astro::Coord::ECI methods (e.g. geodetic () or equatorial ()) to retrieve the position you just calculated.

$tle = $tle->model8 ($time)

This method calculates the position of the body described by the TLE object at the given time, using either the SGP8 or SDP8 model, whichever is appropriate.

You need to call one of the Astro::Coord::ECI methods (e.g. geodetic () or equatorial ()) to retrieve the position you just calculated.

$tle = $tle->null ($time)

This method does nothing. It is a valid orbital model, though. If you call $tle->set (model => 'null'), no position calculation is done as a side effect of calling $tle->universal ($time).

@elements = Astro::Coord::ECI::TLE->parse (@data);

This method parses a NORAD two- or three-line element set (or a mixture), returning a list of Astro::Coord::ECI::TLE objects. The "ATTRIBUTES" section identifies those attributes which will be filled in by this method.

The input will be split into individual lines, and all blank lines and lines beginning with '#' will be eliminated. The remaining lines are assumed to represent two- or three-line element sets, in so-called external format. Internal format (denoted by a 'G' in column 79 of line 1 of the set, not counting the common name if any) is not supported, and the presence of such data will result in an exception being thrown.

$seconds = $tle->period ();

This method returns the orbital period of the object in seconds.

$tle->set (attribute => value ...)

This method sets the values of the various attributes. The changing of attributes actually used by the orbital models will cause the models to be reinitialized. This happens transparently, and is no big deal. For a description of the attributes, see "ATTRIBUTES".

Because this is a subclass of Astro::Coord::ECI, any attributes of that class can also be set.

$tle = $tle->sgp($time)

This method calculates the position of the body described by the TLE object at the given time, using the SGP model.

The result is the original object reference. You need to call one of the Astro::Coord::ECI methods (e.g. geodetic () or equatorial ()) to retrieve the position you just calculated.

"Spacetrack Report Number 3" (see "Acknowledgments") says that this model can be used for either near-earth or deep-space orbits, but the reference implementation they provide dies on an attempt to use this model for a deep-space object, and I have followed the reference implementation.

$tle = $tle->sgp4($time)

This method calculates the position of the body described by the TLE object at the given time, using the SGP4 model.

The result is the original object reference. See the DESCRIPTION heading above for how to retrieve the coordinates you just calculated.

"Spacetrack Report Number 3" (see "Acknowledgments") says that this model can be used only for near-earth orbits.

$tle = $tle->sdp4($time)

This method calculates the position of the body described by the TLE object at the given time, using the SDP4 model.

The result is the original object reference. You need to call one of the Astro::Coord::ECI methods (e.g. geodetic () or equatorial ()) to retrieve the position you just calculated.

"Spacetrack Report Number 3" (see "Acknowledgments") says that this model can be used only for deep-space orbits.

$tle = $tle->sgp8($time)

This method calculates the position of the body described by the TLE object at the given time, using the SGP8 model.

The result is the original object reference. You need to call one of the Astro::Coord::ECI methods (e.g. geodetic () or equatorial ()) to retrieve the position you just calculated.

"Spacetrack Report Number 3" (see "Acknowledgments") says that this model can be used only for near-earth orbits.

$tle = $tle->sdp8($time)

This method calculates the position of the body described by the TLE object at the given time, using the SDP8 model.

The result is the original object reference. You need to call one of the Astro::Coord::ECI methods (e.g. geodetic () or equatorial ()) to retrieve the position you just calculated.

"Spacetrack Report Number 3" (see "Acknowledgments") says that this model can be used only for near-earth orbits.

$self->time_set();

This method sets the coordinate of the object to whatever is computed by the model specified by the model attribute.

Although there is no reason this method can not be called directly, it exists to take advantage of the hook in the Astro::Coord::ECI object, to allow the position of the body to be computed when the time of the object is set.

ATTRIBUTES

This class has the following public attributes. The description gives the data type. It may also give one of the following if applicable:

parse - if the attribute is set by the parse() method;

read-only - if the attribute is read-only;

static - if the attribute may be set on the class.

Note that the orbital elements provided by NORAD are tweaked for use by the models implemented by this class. If you plug them in to the same-named parameters of other models, your mileage may vary significantly.

argumentofperigee (numeric, parse)

This attribute contains the argument of perigee (angular distance from ascending node to perigee) of the orbit, in radians.

bstardrag (numeric, parse)

This attribute contains the B* drag term, decoded into a number.

classification (string, parse)

This attribute contains the security classification. You should expect to see only the value 'U', for 'Unclassified.'

ds50 (numeric, readonly, parse)

This attribute contains the epoch, in days since 1950. Setting the epoch also modified this attribute.

eccentricity (numeric, parse)

This attribute contains the orbital eccentricity, with the implied decimal point inserted.

elementnumber (numeric, parse)

This attribute contains the element set number of the data set. In theory, this gets incremented every time a data set is issued.

ephemeristype (numeric, parse)

This attribute records a field in the data set which is supposed to specify which model to use with this data. In practice, it seems always to be zero.

epoch (numeric, parse)

This attribute contains the epoch of the orbital elements - that is, the 'as-of' date and time - as a Perl date. Setting this attribute also modifies the ds50 attribute.

firstderivative (numeric, parse)

This attribute contains the first time derivative of the mean motion, in radians per minute squared.

id (numeric, parse)

This attribute contains the NORAD SATCAT catalog ID.

inclination (numeric, parse)

This attribute contains the orbital inclination in radians.

international (string, parse)

This attribute contains the international launch designator. This consists of three parts: a two-digit number (with leading zero if needed) giving the last two digits of the launch year (in the range 1957-2056); a three-digit number (with leading zeros if needed) giving the order of the launch within the year, and one to three letters designating the "part" of the launch, with payload(s) getting the first letters, and spent boosters, debris, etc getting the rest.

meananomaly (numeric, parse)

This attribute contains the mean orbital anomaly at the epoch, in radians. In slightly less technical terms, this is the angular distance a body in a circular orbit of the same period (that is what the 'mean' means) would be from perigee at the epoch, measured in the plane of the orbit.

meanmotion (numeric, parse)

This attribute contains the mean motion of the body, in radians per minute.

model (string, static)

This attribute contains the name of the model to be run (i.e. the name of the method to be called) when the time_set() method is called, or a false value if no model is to be run. Legal model names are: model, model4, model8, sgp, sgp4, sgp8, sdp4, and sdp8.

The default is 'model'. Setting the value on the class changes the default.

name (string, parse (three-line sets only))

This attribute contains the common name of the body.

revolutionsatepoch (numeric, parse)

This attribute contains number of revolutions the body has made since launch, at the epoch.

rightascension (numeric, parse)

This attribute contains the right ascension of the ascending node of the orbit at the epoch, in radians.

secondderivative (numeric, parse)

This attribute contains the second time derivative of the mean motion, in radians per minute cubed.

tle (string, readonly, parse)

This attribute contains the input data used by the parse() method to generate this object.

ACKNOWLEDGMENTS

The author wishes to acknowledge the following individuals.

Dominik Brodowski (http://www.brodo.de/), whose SGP C-lib (available at http://www.brodo.de/space/sgp/) provided a reference implementation that I could easily run, and pick apart to help get my own code working. Dominik based his work on Dr. Kelso's Pascal implementation.

Felix R. Hoots and Ronald L. Roehric, the authors of "SPACETRACK REPORT NO. 3 - Models for Propagation of NORAD Element Sets," which provided the basis for the Astro::Coord::ECI::TLE module.

Dr. T. S. Kelso, who compiled this report and made it available at http://celestrak.com/NORAD/documentation/spacetrk.pdf. Dr. Kelso's Two-Line Element Set Format FAQ (http://celestrak.com/columns/v04n03/) was also extremely helpful, as was his discussion of the coordinate system used (http://celestrak.com/columns/v02n01/) and (indirectly) his Pascal implementation of these models.

SEE ALSO

I am aware of no other modules that perform calculations with NORAD orbital element sets. The Astro-Coords package by Tim Jenness provides calculations using orbital elements, but the NORAD elements are tweaked for use by the models implemented in this package.

AUTHOR

Thomas R. Wyant, III (wyant at cpan dot org)

COPYRIGHT

Copyright 2005, 2006 by Thomas R. Wyant, III (wyant at cpan dot org). All rights reserved.

This module is free software; you can use it, redistribute it and/or modify it under the same terms as Perl itself. Please see http://perldoc.perl.org/index-licence.html for the current licenses.

This software is provided without any warranty of any kind, express or implied. The author will not be liable for any damages of any sort relating in any way to this software.