view release on metacpan or  search on metacpan

lib/Astro/Coord/ECI/OVERVIEW.pod  view on Meta::CPAN

All angles, both input and output, are in radians. The
L<Astro::Coord::ECI::Utils> module exports functions
C<deg2rad()> and C<rad2deg()> to convert degrees to and from radians.
C<rad2dms()> and C<rad2hms()> are provided for radians to degrees,
minutes, and seconds or for hours, minutes, and seconds of right
ascension, but the user is on his or her own for input conversion of
these to radians.

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

=head2 Distances

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

=head2 Times

All times are seconds since the system's epoch. That is, the kind of
time returned by C<time()>.

=head1 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
L<TERMINOLOGY AND CONVENTIONS|Astro::Coord::ECI/TERMINOLOGY AND CONVENTIONS>
section in the documentation for L<Astro::Coord::ECI|Astro::Coord::ECI>,
but a few key terms will be covered here:

=head2 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 L<OID|/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
L<Astro::Coord::ECI::TLE|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 L<TLE|/TLE>, and is explained below.

=head2 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 can also be used as a proxy for the
'as-of' date of the orbital data. This is important for L<TLE|/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 L<TLE|/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. See the
L<TLE|/TLE> documentation for more information.

=head2 OID

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

=head2 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
L<Astro::Coord::ECI|Astro::Coord::ECI> object.

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

=head2 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
L<orbiting bodies|/Body>. 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 L<body|/Body> being modeled.

With the introduction of the REST (or Version 2) interface to the Space
Track web site, a third representation of TLE data, as JSON, has become
available.

Given a chunk of TLE data, the
L<Astro::Coord::ECI::TLE|Astro::Coord::ECI::TLE> C<parse()>
method can be used to turn it
into L<Astro::Coord::ECI::TLE|Astro::Coord::ECI::TLE> objects -- or
L<Astro::Coord::ECI::TLE::Iridium|Astro::Coord::ECI::TLE::Iridium>
objects if you have installed that module from its own distribution. If
your data are in JSON format, you will need the optional L<JSON|JSON>
module installed.

In practice, TLE data have an effective date, and a shelf life measured
from that effective date. Unfortunately, the TLE data do not contain
either of these.

For casual use, the 'shelf life' of a set of TLE data is a week or so.
But this can vary based on circumstances. For example, if the data
represent a coasting arc for a shuttle launch, the shelf life may be a
matter of minutes. For something like the International Space Station,
the shelf life is cut short when the station is boosted into a higher