++ed by:
BKB TYLDUM HAMMER

3 PAUSE users

Tom Wyant
and 1 contributors

NAME

Astro::Coord::ECI Overview Documentation

MOTIVATION

This package was created in order to be able to forecast satellite visibility. This is not quite rocket science, but like many endeavors the devil is in the details, which in part accounts for the complexity of the package.

SYNOPSIS

Any system to forecast the visibility of an object in the sky needs to be told a few things: where you are, where the object in the sky is, and (maybe) what source of illumination is being used. This package provides classes for all these. Some of the objects (e.g. Astro::Coord::ECI::Sun) are pretty much self-sufficient. Others (e.g. Astro::Coord::ECI::TLE) need to be initialized before they can be used.

Typically a calculation is done by initializing an object representing the station (i.e. you), another representing the orbiting body (i.e. the satellite), then calling a method on one of them and passing it the other one.

For example, to calculate visibility of the International Space Station from your front yard you would initialize an Astro::Coord::ECI object with the latitude (in radians), longitude (in radians), and height above sea level (in kilometers). You would also initialize an Astro::Coord::ECI::TLE object with TLE data for the space station. Then you would call method pass() on the space station object, giving it the object that represents your location, and the times (as Perl times) you are interested in. The result would be an array of hashes with the visibility data.

This is actually a worst case. The position of a satellite is not dependent on you, so if all you need to know is it's position over the globe, all you need to do is set its object's time. This will cause the model to run. Then you call the method that gives the position in the coordinates you want. For absolute coordinates (e.g. geodetic latitude and longitude) no other objects are involved. For relative coordinates (e.g. azimuth and elevation) you need to make use of the object the coordinates are relative to.

This documentation assumes that you are interested in satellites, but there are a couple supporting classes which can equally well be used in their own right: Astro::Coord::ECI::Sun, which represents the Sun, and Astro::Coord::ECI::Moon.

So far this explanation has been in terms of a single Astro::Coord::ECI::TLE object. But there are cases (e.g. a Space Shuttle launch) where a single Astro::Coord::ECI::TLE object can not represent a single physical object over a conveniently-long period of time (say, a week, starting some time before the launch). In this case, the multiple Astro::Coord::ECI::TLE objects can be aggregated into a single Astro::Coord::ECI::TLE::Set object, using that class' aggregate() method. This method will assort its arguments into the appropriate number of containers, and return one object per OID. By default this will be an Astro::Coord::ECI::TLE object if there is only one instance of the given OID in the input, or an Astro::Coord::ECI::TLE::Set object if there is more than one.

The Astro::Coord::ECI::TLE::Set object can be used anywhere an Astro::Coord::ECI::TLE object can. There is a slight performance penalty, but on the other hand you get better results, or in extreme cases you actually get results where you would not with a single TLE.

EXAMPLES

The example code in the SYNOPSIS sections of the various modules is (or at least should be) working Perl. If you find that it is not working perl, please submit a bug report.

Other examples are available in the eg directory of the distribution.

Both the module documentation and the eg directory are available online at http://search.cpan.org/dist/Astro-satpass/. For the eg directory you will need to follow the [browse] link near the top of the page.

BUGS

Bugs should be reported to queue Astro-satpass at http://rt.cpan.org/, or to the author via electronic mail at wyant at cpan dot org.

UNITS

Different units of measure are usual in different applications. Since these modules span the disciplines of geodesy, aeronautics, and astronomy, a somewhat Procrustean approach has been necessary to provide consistency of interface and try to preserve the sanity of the author.

Angles

All angles, both input and output, are in radians. The Astro::Coord::ECI::Utils module exports functions deg2rad and rad2deg to convert degrees to and from radians. The user is on his or her own for degrees, minutes and seconds, or for hours, minutes and seconds of right ascension.

The expected range of an angle depends on what is customary for the quantity being measured. Values outside the customary range will generate warnings.

Distances

All distances, both input and output, are in kilometers.

TERMINOLOGY

Forecasting satellite visibility is an activity on the border between aeronautics and astronomy. It needs technical words, and borrows from both these disciplines, tending to prefer the aeronautical term when there is conflict. There is a fairly exhaustive TERMINOLOGY AND CONVENTIONS section in the documentation for Astro::Coord::ECI, but a few key terms will be covered here:

Body

Short for 'orbiting body', this is the satellite, spent booster, dropped hammer, or other orbiting item that you are trying to observe. Bodies of all sorts are identified by an OID. Several models have been published to predict the position of such an item at a given body.

Orbiting bodies are represented in this package by an Astro::Coord::ECI::TLE object. Before this object can be used, it needs to be initialized with data for the specific satellite of interest. The standard representation of this data is called TLE, and is explained below.

Epoch

In general and in astronomical calculations, the epoch is a date and time to which time-dependent calculations are referred. For example, the position of a star or planet may be given in epoch J2000, meaning the coordinates for Julian year 2000.

But in orbital calculations it refers to the 'as-of' date of the orbital data, and that is the meaning used most often in this documentation.

The epoch is important for TLE data because this data has a limited 'shelf life', and the farther from the epoch you are the worse the predictions are. In extreme cases the model itself fails because it cannot handle the type of orbit predicted.

Typically the 'shelf life' of a TLE is a couple weeks for casual use, though data for satellites in near-Earth orbits (defined as a period of less than two and a half hours) are usually updated every couple days. In extreme cases (e.g. the first arc of a Space Shuttle flight) the model may fail within a couple days of the epoch.

OID

Short for 'Object ID', this is a unique number assigned to an object by NORAD or its successors when the orbiting body is detected. The OID may also be called the 'Satellite ID', the 'Satellite Number', or simply the 'ID'.

Station

Short for 'observing station', this is the location of the observer. This package only supports observers on the surface of the Earth, so the observer will be represented by an Astro::Coord::ECI object.

This object will need to be initialized by calling its geodetic() method, passing the observer's latitude and longitude in radians and height above sea level in kilometers. Latitude is negative south of the Equator, and longitude negative west of Greenwich, England. The Astro::Coord::ECI::Utils packages exports deg2rad() to do the angle conversion.

TLE

Short for 'Two line elements', this is the standard representation of the data used to initialize any of the usual models for the positions of orbiting bodies. It is basically two lines of text, and owes a lot to the days when computers were fed data by making holes in pieces of cardboard.

A common variant of this format is sometimes called 'NASA TLE'. The format is the same, but the two lines of model data are preceded by a line containing the common name of the body being modeled.

The TLE data has a 'shelf-life', measured from its epoch. For casual use week-old data are usually fine, but in extreme cases (e.g. a Space Shuttle launch) the orbit models can fail completely within a couple days of the epoch.

Given a chunk of TLE data, the Astro::Coord::ECI::TLE parse() method can be used to turn it into Astro::Coord::ECI::TLE or Astro::Coord::ECI::TLE::Iridium objects.

This package does not deal with the acquisition of TLE data. See "WHERE TO GET TLE DATA", below, for that.

STRUCTURE

The modules in this package are organized functionally for the most part, with utility functions separate. The following list names the modules, and briefly states their function.

Astro::Coord::ECI

The Astro::Coord::ECI module is the base for the inheritance tree. It provides position and time transformations, and doubles as the object used to represent a location fixed to the surface of the Earth.

For the latter use you probably would construct the object by calling Astro::Coord::ECI->geodetic() method, passing it the latitude and longitude in radians, and the height above sea level in meters. The Astro::Coord::ECI::Utils module exports a deg2rad function to convert degrees to radians. Remember that latitude is negative south of the equator, and longitude is negative west of the Prime Meridian in Greenwich, England. Other prime meridians are not supported.

Astro::Coord::ECI::Moon

The Astro::Coord::ECI::Moon module is a subclass of Astro::Coord::ECI which represents the Moon. All you have to do to use it is to instantiate it (say, with my $moon = Astro::Coord::ECI::Moon->new()), and then set the time with something like $moon->universal($time), where the $time is a Perl time, such as is returned by the time() built-in. Then you can retrieve the position using one of the methods inherited from Astro::Coord::ECI.

You can pass an Astro::Coord::ECI::Moon object to the Astro::Coord::ECI::TLE pass() method, and it will report on close approaches to the Moon. How close depends on the setting of the Astro::Coord::ECI::TLE object's 'appulse' attribute. This defaults to 0, which means no appulse calculations are done.

Astro::Coord::ECI::Star

The Astro::Coord::ECI::Star module is a subclass of Astro::Coord::ECI which represents a star. It is initialized by calling the position() method to set the star's position in right ascension and declination in radians, and optionally its distance and proper motion. After this, simply setting the time of the object (e.g. by $star->universal($time), $time being a Perl time) will cause its position to be calculated. The position can be retrieved using one of the methods inherited from Astro::Coord::ECI.

You can pass an Astro::Coord::ECI::Star object to the and it will report on close approaches to the star. How close depends on the setting of the Astro::Coord::ECI::TLE object's 'appulse' attribute. This defaults to 0, which means no appulse calculations are done.

Astro::Coord::ECI::Sun

The Astro::Coord::ECI::Sun module is a subclass of Astro::Coord::ECI which represents the Sun. All you have to do to use it is to instantiate it (say, with my $moon = Astro::Coord::ECI::Sun->new()), and then set the time with something like $moon->universal($time), where the $time is a Perl time, such as is returned by the time() built-in. Then you can retrieve the position using one of the methods inherited from Astro::Coord::ECI.

This object is implicitly used by the Astro::Coord::ECI::TLE pass() method to calculate whether the satellite is illuminated, and whether it is day, dusk, or night at the observing station.

You can pass an Astro::Coord::ECI::Sun object to the Astro::Coord::ECI::TLE pass() method, and it will report on close approaches to the Sun. How close depends on the setting of the Astro::Coord::ECI::TLE object's 'appulse' attribute. This defaults to 0, which means no appulse calculations are done.

Astro::Coord::ECI::TLE

The Astro::Coord::ECI::TLE module is a subclass of Astro::Coord::ECI which represents a satellite or other body in orbit around the Earth. This representation is in terms of one of a number of related computational models, defined in Space Track Report Number 3 and Revisiting Spacetrack Report #3, both of which are available at http://celestrak.com/NORAD/documentation/.

It is possible to construct an Astro::Coord::ECI::TLE object by setting the requisite attributes directly, but it is probably more convenient to do so using the Astro::Coord::ECI::TLE->parse() method. This method accepts TLE data, and returns an array of Astro::Coord::ECI::TLE objects parsed from the data.

The position of a satellite is computed by setting the time represented by the object. This is typically done using the universal() method (inherited from Astro::Coord::ECI), by passing it a Perl time (i.e. the kind returned by the time() built-in. Once the position is computed, it can be retrieved by using any of the positional methods defined on Astro::Coord::ECI.

This module also offers the pass() method, which calculates visible passes over an observer's location during a given time interval.

One of the complications of using this module is that the TLE data are only good for a limited amount of time around the epoch of the data. In most cases this just results in a loss of precision, but in extreme cases (such as the first predicted element of a Space Shuttle launch) use of the data by as little as a day or so before its epoch can cause the model computations to fail. For cases like this there is a 'backdate' attribute, which tells the pass method whether it should consider times before the epoch of the data. It defaults to true because that represents the general case. But you may wish to set it false (e.g. by something like $tle->set(backdate => 0);) if you are using the predicted data downloaded from the "NASA Human Space Flight" web site.

Astro::Coord::ECI::TLE::Iridium

This module is a subclass of Astro::Coord::ECI::TLE representing an Iridium satellite. The Astro::Coord::ECI::TLE parse() method produces these automatically when fed TLE data representing Iridium satellites.

This module adds to the Astro::Coord::ECI::TLE functionality the ability to calculate Iridium flares. The flare() method is passed the observers' location and the desired time range for the prediction. It returns a list of hashes representing the predicted flares. This prediction is modified by attributes giving limiting magnitudes for daytime and nighttime flares, and whether you want predictions for am (between midnight and sunrise), day (between sunrise and sunset), and/or pm (between sunset and midnight) flares.

Astro::Coord::ECI::TLE::Set

This module is not a member of the Astro::Coord::ECI inheritance tree. It is a container for one or more Astro::Coord::ECI::TLE objects representing the same OID, and is usable pretty much anywhere an Astro::Coord::ECI::TLE object is.

The Astro::Coord::ECI::TLE::Set object exposes all the methods of its contained objects, but overrides some of them to work its magic. Astro::Coord::ECI::TLE::Set works on the principle that one of its contained objects is the current object, which is used to satisfy data requests. So the most important override is of the universal() method, which selects as the current object the one best representing the given time. In this context, 'best' means the object having the most recent epoch before the given time. If there is no such object, the object having the earliest epoch is used.

There are a couple other small magics involved in Astro::Coord::ECI::TLE::Set:

* The can() method is overridden, so that an Astro::Coord::ECI::TLE::Set object appears to implement the methods of whatever class it was populated with.

* The set() method is overridden so that attributes characteristic of the OID (such as 'name', 'backdate', and so on) being represented are set on all contained objects, but attributes characteristic of a specific TLE data set are set only on the selected object.

* For select methods, such as pass() and flare, the Astro::Coord::ECI::TLE::Set object passes itself to to the method in the role of $self, rather than passing the current object. This way such methods transparently switch TLE data sets whenever appropriate.

Astro::Coord::ECI::Utils

The Astro::Coord::ECI::Utils module is not a member of the Astro::Coord::ECI inheritance hierarchy, but is a container for all those utility subroutines that are not intrinsically object-oriented. These are generally conversion routines of some sort, such as the previously-mentioned deg2rad() and its inverse rad2deg, and conversions among the various time representations used in the various models.

WHERE TO GET TLE DATA

There are a number of places to get the TLE data on line. Some of these are accessible through the Astro::SpaceTrack Perl module (not included in this package, but available from CPAN), but you can always simply download the data and then read the file and pass its contents to Astro::Coord::ECI::TLE->parse().

Please note that anything specific said here about the functionality of Astro::SpaceTrack is not definitive. You should consult Astro::SpaceTrack for the latest.

Space Track

The 'most official' source of TLE data is http://www.space-track.org/, which requires you to register and use a username and password. Other sources may get their data from here, which means their data are hours to days older. Astro::SpaceTrack will retrieve data from this site, but of course you have to give it a username and password before it will do so.

Celestrak

Dr. T. S. Kelso's http://celestrak.com/ is a good source for the more popular satellites. It redistributes data from "Space Track", but you can get Dr. Kelso's data without registering. Astro::SpaceTrack will retrieve data from this site, but by default is simply gets the OID from Dr. Kelso, and then retrieves the data from Space Track, so you will need a username and password. If you don't have them, you can configure Astro::SpaceTrack to work for this site without them.

NASA Human Space Flight

NASA makes International Space Station and space shuttle data available at http://spaceflight.nasa.gov/realdata/elements/, but the TLEs have to be dug out of the data. Unlike the other sources, these data include predictions of future data, so that you can (for example) get data for a Space Shuttle flight that has not yet launched. If you're more than a day or so before the lunch, at least some of this data will be too far from its 'as-of' date to be useful. Astro::SpaceTrack will dig out the data for you, and you do not need a username or password.

Amateur Radio Satellite Corporation

The Amateur Radio Satellite Corporation (AMSAT) keeps orbital elements at http://www.amsat.org/amsat-new/tools/keps.php. They appear to get the data from Dr. Kelso. Astro::SpaceTrack will get this data for you, and you need no username or password.

Heavens Above

Heavens Above at http://www.heavens-above.com/ does visibility predictions, and will give you TLE data if you drill down far enough on an individual satellite. I do not know where they get their data. I have observed it to be a day or so behind Space Track, but they also carry data from classified satellites (which Space Track does not), so I don't know where they get their data. You can create an account for yourself, but this is not necessary to use the site. Astro::SpaceTrack does not retrieve data from this site.