view release on metacpan or  search on metacpan

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

 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:

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

In addition, I have on at least one occasion wanted to turn off the
automatic calculation of position when the time was set. That is
accomplished with this model:

  null - does nothing.

The models do not return the coordinates directly, they simply set the
coordinates represented by the object (by virtue of being a subclass of
L<Astro::Coord::ECI|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. 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 C<model> attribute is set the way you want
it, by

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

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

As of release 0.016, the recommended model to use is SGP4R, which was
added in that release. The SGP4R model, described in "Revisiting
Spacetrack Report #3"
(L<http://celestrak.org/publications/AIAA/2006-6753/>), combines SGP4
and SDP4, and updates them. For the details of the changes, see the
report.

Prior to release 0.016, the recommended model to use was 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. My understanding is that in general
(i.e. disregarding the characteristics of a particular implementation of
the models involved) the total error of the predictions (including error
in measuring the position of the satellite) runs from a few hundred
meters to as much as a kilometer.

I have no information on the accuracy claims of SGP4R.

This module is a computer-assisted translation of the FORTRAN reference
implementations in "SPACETRACK REPORT NO. 3" and "Revisiting Spacetrack
Report #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.

=head2 Methods

The following methods should be considered public:

=over 4

=cut

package Astro::Coord::ECI::TLE;

use strict;
use warnings;

our $VERSION = '0.134';

use base qw{ Astro::Coord::ECI Exporter };

use Astro::Coord::ECI::Utils qw{ :params :ref :greg_time deg2rad distsq
    dynamical_delta embodies find_first_true fold_case
    __format_epoch_time_usec
    format_space_track_json_time gm_strftime load_module local_strftime
    looks_like_number max min
    mod2pi PI PIOVER2 rad2deg SECSPERDAY TWOPI thetag
    __default_station
    @CARP_NOT
    };

use Carp qw{carp croak confess};
use Data::Dumper;
use IO::File;
use POSIX qw{ ceil floor fmod modf };
use Scalar::Util ();

BEGIN {
    local $@;
    eval {require Scalar::Util; Scalar::Util->import ('dualvar'); 1}
	or *dualvar = sub {$_[0]};
}

{	# Local symbol block.
    my @const = qw{
	PASS_EVENT_NONE
	PASS_EVENT_SHADOWED
	PASS_EVENT_LIT
	PASS_EVENT_DAY
	PASS_EVENT_RISE
	PASS_EVENT_MAX
	PASS_EVENT_SET
	PASS_EVENT_APPULSE
	PASS_EVENT_START
	PASS_EVENT_END
	PASS_EVENT_BRIGHTEST
	PASS_VARIANT_VISIBLE_EVENTS

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

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

=item revolutionsatepoch (numeric, parse)

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

=item secondderivative (numeric, parse)

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

=item pass_threshold (numeric or undef)

If defined, this attribute defines the elevation in radians that the
satellite must reach above the horizon for its passes to be reported. If
the C<visible> attribute is true, the satellite must be visible above
this elevation.

If undefined, any pass above the horizon will be reported (i.e. you get
the same behavior as before this attribute was introduced in version
0.046.)

B<Note> a slight change in the behavior of this attribute from version
0.046. In that version, it did not matter whether the satellite was
visible, even if the C<visible> attribute was true.

You might use this attribute if you want to use a nominal horizon of .35
radians (20 degrees), but are only interested in passes that reach an
elevation of .70 radians (40 degrees).

The default is C<undef>.

=item tle (string, readonly, parse)

This attribute contains the input data used by the parse() method to
generate this object. If the object was not created by the parse()
method, a (hopefully) equivalent TLE will be constructed and returned if
enough attributes have been set, otherwise an exception will be raised.

=item visible (boolean, static)

This attribute tells the pass() method whether to report only passes
which are illuminated (if true) or all passes (if false).

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

=back

=head1 ACKNOWLEDGMENTS

The author wishes to acknowledge the following individuals.

Dominik Brodowski (L<https://www.brodo.de/>), whose SGP C-lib
(available at L<https://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.

David A. Vallado, Paul Crawford, Richard Hujsak, and T. S. Kelso, the
authors of "Revisiting Spacetrack Report #3", presented at the 2006
AIAA/AAS Astrodynamics Specialist Conference.

Dr. T. S. Kelso, who made these two key reports available at
L<http://celestrak.org/NORAD/documentation/spacetrk.pdf> and
L<http://celestrak.org/publications/AIAA/2006-6753/> respectively. Dr.
Kelso's Two-Line Element Set Format FAQ
(L<http://celestrak.org/columns/v04n03/>) was also extremely helpful, as
was his discussion of the coordinate system used
(L<http://celestrak.org/columns/v02n01/>) and (indirectly) his Pascal
implementation of these models.

The TLE data used in testing the C<sgp4r> model are from "Revisiting
Spacetrack Report #3" (made available at the CelesTrak web site as cited
above), and are used with the kind permission of Dr. Kelso.

=head1 SEE ALSO

I am aware of no other modules that perform calculations with NORAD
orbital element sets. The L<Astro::Coords|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.

=head1 SUPPORT

Support is by the author. Please file bug reports at
L<https://rt.cpan.org/Public/Dist/Display.html?Name=Astro-satpass>,
L<https://github.com/trwyant/perl-Astro-Coord-ECI/issues>, or in
electronic mail to the author.

=head1 AUTHOR

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

=head1 COPYRIGHT AND LICENSE

Copyright (C) 2005-2025 by Thomas R. Wyant, III

This program is free software; you can redistribute it and/or modify it
under the same terms as Perl 5.10.0. For more details, see the full text
of the licenses in the directory LICENSES.

This program is distributed in the hope that it will be useful, but
without any warranty; without even the implied warranty of
merchantability or fitness for a particular purpose.

=cut

# ex: set textwidth=72 :