view release on metacpan or  search on metacpan

lib/Astro/Coord/ECI/TLE.pm  view on Meta::CPAN

 # needed.
 
 my $st = Astro::SpaceTrack->new( direct => 1 );
 my $data = $st->celestrak( 'stations' );
 $data->is_success or die $data->status_line;
 
 # Parse the fetched data, yielding TLE objects. Aggregate
 # them into Set objects where this is warranted. We grep
 # the data because the Celestrak catalog we fetched
 # contains other stuff than the International Space
 # Station.
 
 my @sats = grep { '25544' eq $_->get( 'id' ) }
     Astro::Coord::ECI::TLE::Set->aggregate(
     Astro::Coord::ECI::TLE->parse( $data->content() ) );
 
 # We want passes for the next 7 days.
  
 my $start = time ();
 my $finish = $start + 7 * 86400;
 
 # Loop through our objects and predict passes. The
 # validate() step is usually not needed for data from
 # Space Track, but NASA's predicted elements for Space
 # Shuttle flights can be funky.
 
 my @passes;
 foreach my $tle (@sats) {
    $tle->validate($start, $finish) or next;
    push @passes, $tle->pass($loc, $start, $finish);
 }
 print <<eod;
      Date/Time          Satellite        Elevation  Azimuth Event
 eod
 foreach my $pass (sort {$a->{time} <=> $b->{time}} @passes) {
 
 #  The returned angles are in radians, so we need to
 #  convert back to degrees.
 #
 #  Note that unless Scalar::Util::dualvar works, the event output
 #  will be integers.
 
    print "\n";
 
    foreach my $event (@{$pass->{events}}) {
 	printf "%s %-15s %9.1f %9.1f %-5s\n",
 	    scalar localtime $event->{time},
 	    $event->{body}->get ('name'),
 	    rad2deg ($event->{elevation}),
 	    rad2deg ($event->{azimuth}),
 	    $event->{event};
    }
 }

=head1 NOTICE

Users of JSON functionality (if any!) should be aware of a potential
problem in the way L<JSON::XS|JSON::XS> encodes numbers. The problem
basically is that the locale leaks into the encoded JSON, and if the
locale uses commas for decimal points the encoded JSON can not be
decoded. As I understand the discussion on the associated Perl ticket
the problem has always been there, but changes introduced in Perl 5.19.8
made it more likely to manifest.

Unfortunately the nature of the JSON interface is such that I have no
control over the issue, since the workaround needs to be applied at the
point the JSON C<encode()> method is called. See test F<t/tle_json.t>
for the workaround that allows tests to pass in the affected locales.
The relevant L<JSON::XS|JSON::XS> ticket is
L<https://rt.cpan.org/Public/Bug/Display.html?id=93307>. The relevant Perl
ticket is L<https://github.com/perl/perl5/issues/13620>.

The C<pass_threshold> attribute has undergone a slight change in
functionality from version 0.046, in which it was introduced. In the new
functionality, if the C<visible> attribute is true, the satellite must
actually be visible above the threshold to be reported. This is actually
how the attribute would have worked when introduced if I had thought it
through clearly.

Use of the C<SATNAME> JSON attribute to represent the common name of the
satellite is deprecated in favor of the C<OBJECT_NAME> attribute, since
the latter is what Space Track uses in their TLE data. Beginning with
0.053_01, JSON output of TLEs will use the new name.

Beginning with release 0.056_01, loading JSON TLE data which specifies
C<SATNAME> produces a warning the first time it happens. As of version
0.061 there is a warning every time it happens. As of version 0.066
loading JSON TLE data which specifies C<SATNAME> is a fatal error. Six
months after this, all code referring to C<SATNAME> will be removed,
meaning that the key will be silently ignored.

=head1 DESCRIPTION

This module implements the orbital propagation models described in
"SPACETRACK REPORT NO. 3, Models for Propagation of NORAD Element Sets"
and "Revisiting Spacetrack Report #3." See the
L<ACKNOWLEDGMENTS|/ACKNOWLEDGMENTS> section for details on these
reports.

In other words, this module turns the two- or three-line element sets
available from such places as L<https://www.space-track.org/> or
L<http://celestrak.org/> into predictions of where the relevant orbiting
bodies will be. Additionally, the pass() method implements an actual
visibility prediction system.

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;
  SGP4R - updates and combines SGP4 and SDP4.

All the above models compute ECI coordinates in kilometers, and
velocities along the same axes in kilometers per second.

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:

lib/Astro/Coord/ECI/TLE.pm  view on Meta::CPAN

# $$ END

1;

__END__

=back

=head2 Attributes

This class has the following additional 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 as well as an object.

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.

=over

=item appulse (numeric, static)

This attribute contains the angle of the widest appulse to be reported
by the pass() method, in radians.

The default is equivalent to 10 degrees.

=item argumentofperigee (numeric, parse)

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

=item ascendingnode (numeric, parse)

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

=item backdate (boolean, static)

This attribute determines whether the pass() method will go back before
the epoch of the data. If false, the pass() method will silently adjust
its start time forward. If this places the start time after the end
time, an empty list is returned.

B<Note> that this is a change from the behavior of
Astro::Coord::ECI::TLE version 0.010, which threw an exception if the
backdate adjustment placed the start time after the end time.

The default is 1 (i.e. true).

=item bstardrag (numeric, parse)

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

=item classification (string, parse)

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

=item ds50 (numeric, readonly, parse)

This attribute contains the C<epoch>, in days since 1950.
Setting the C<epoch> also modifies this attribute.

=item eccentricity (numeric, parse)

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

=item effective (numeric, parse)

This attribute contains the effective date of the TLE, as a Perl time in
seconds since the epoch. As a convenience, it can be set in the format
used by NASA to specify this, as year/day/hour:minute:second, where all
fields are numeric, and the day is the day number of the year, January 1
being 1, and December 31 being either 365 or 366.

=item 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.

=item 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.

=item 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 epoch_dynamical and ds50 attributes.

=item epoch_dynamical (numeric, readonly, parse)

This attribute contains the dynamical time corresponding to the
C<epoch>. Setting the C<epoch> also modifies this attribute.

=item file (numeric)

This attribute contains the file number of the TLE data. It is typically
present only if the TLE object was parsed from a Space Track JSON file;
otherwise it is undefined.

=item firstderivative (numeric, parse)

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

=item geometric (boolean, static)

Tells the pass() method whether to calculate rise and set relative