NAME

Astro::Coord::ECI::TLE::Set - Represent a set of data for the same ID.

SYNOPSIS

my @sats = Astro::Coord::ECI::TLE::Set->aggregate (
    Astro::Coord::ECI::TLE->parse ($tle_data));
my $now = time ();
foreach my $tle (@sats) {
   print join ("\t",
      $tle->get ('id'),
      $tle->universal ($now)->geodetic ()),
      "\n";
}

DESCRIPTION

This module is intended to represent a set of orbital elements, representing the same NORAD ID at different points in time. It can contain any number of objects of class Astro::Coord::ECI::TLE (or any subclass thereof) provided all contents are of the same class and represent the same NORAD ID.

In addition to the methods documented here, an Astro::Coord::ECI::TLE::Set supports all methods provided by the currently-selected member object, through Perl's AUTOLOAD mechanism. In this way, the object is almost a plug-compatible replacement for an Astro::Coord::ECI::TLE object, but it uses the orbital elements appropriate to the time given. The weasel word 'almost' is expanded on in the "Incompatibilities with Astro::Coord::ECI::TLE" section, below.

When the first member object is added via the add() method, it becomes the currently-selected object. The select() method can be used to select the member that best represents the time passed to the select method. In addition, certain method calls that are delegated to the currently-selected member object can cause a new member to be selected before the delegation is done. These include 'universal', 'dynamical', and any Astro::Coord::ECI::TLE orbital propagation model.

There may be cases where the member class does not want to use the normal delegation mechanism. In this case, it needs to define a _nodelegate_xxxx method, where xxxx is the name of the method that is not to be delegated to. The _nodelegate method is called with the same calling sequence as the original method, but the first argument is a reference to the Astro::Coord::ECI::TLE::Set object, not the member object. Use of this mechanism constitutes a pledge that the _nodelegate method does not make use of any private interfaces to the member objects.

Incompatibilities with Astro::Coord::ECI::TLE

Inheritance

Astro::Coord::ECI::TLE::Set is not a member of the Astro::Coord::ECI inheritance hierarchy, so $set->isa ('Astro::Coord::ECI') is false.

Calling semantics for delegated behaviors

In general, when Astro::Coord::ECI::TLE::Set delegates functionality to a member object, that object's method receives a reference to the member object as its first argument. That is, if $set is the Astro::Coord::ECI::TLE::Set object and $tle is the relevant member object, $set->method (...) becomes $tle->method (...) from the point of view of the called method.

If the member class wishes to see the Astro::Coord::ECI::TLE::Set object as the first argument of method xxxx, it defines method _nodelegate_xxxx, which is called as though by $set->_nodelegate_xxx (...). The _nodelegate_xxx method must use only the public interface to the $tle object (whatever its class). A cheap way to get this method is

*_nodelegate_xxxx = \&xxxx;

but nothing says the _nodelegate_xxxx method must be defined this way.

Calling semantics for static behaviors

Some Astro::Coord::ECI methods (e.g. universal()) will instantiate an object for you if you call them statically. This will not work with Astro::Coord:ECI::TLE::Set; that is, Astro::Coord::ECI::TLE::Set->universal () is an error.

Return semantics for delegated behaviors

In general, when behavior is delegated to a member object, the return is whatever the delegated method returns. This means that, for methods that return the object they are called on (e.g. universal()) you get back a reference to the member object, not a reference to the containing Astro::Coord::ECI::TLE::Set object.

Methods

The following methods should be considered public:

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

This method instantiates a new set. Any arguments are passed to the add() method.

$set->add ($member ...);

This method adds members to the set. The initial member may be any initialized member of the Astro::Coord::ECI::TLE class, or any subclass thereof. Subsequent members must be the same class as the initial member, and represent the same NORAD ID. If not, an exception is thrown. If a prospective member has the same epoch as a current member, the prospective member is silently ignored.

The first member added becomes the current member for the purpose of delegating method calls. Adding subsequent members does not change the current member, though it may be appropriate to call select() after adding.

@sets = Astro::Coord::ECI::TLE::Set->aggregate ($tle ...);

This method aggregates the given Astro::Coord::ECI::TLE objects into sets by NORAD ID. If there is only one object with a given NORAD ID, it is simply returned intact, not made into a set with one member.

If you should for some reason want sets with one member, do

$Astro::Coord::ECI::TLE::Set::Singleton = 1;

before you call aggregate(). Actually, any value that Perl will interpret as true will work. You might want a 'local' in front of all this.

$set->can ($method);

This method checks to see if the object can execute the given method. If so, it returns a code reference to the subroutine; otherwise it returns undef.

This override to UNIVERSAL::can is necessary because we want to return true for member class methods, but we execute them by autoloading, so they are not in our namespace.

$set->clear ();

This method removes all members from the set, allowing it to be reloaded with a different NORAD ID.

@tles = $set->members ();

This method returns all members of the set, in ascending order by epoch.

$set->select ($time);

This method selects the member object that best represents the given time, and returns that member. If called without an argument or with an undefined argument, it simply returns the currently-selected member.

The 'best representative' member for a given time is chosen by considering all members in the set, ordered by ascending epoch. If all epochs are after the given time, the earliest epoch is chosen. If some epochs are on or before the given time, the latest epoch that is not after the given time is chosen.

The 'best representative' algorithm tries select the element set that would actually be current at the given time. If no element set is current (i.e. all are in the future at the given time) we take the earliest, to minimize peeking into the future.

$set->set ($name => $value ...);

This method iterates over the individual name-value pairs. If the name is an attribute of Astro::Coord::ECI::TLE and is not 'debug' or 'model', it calls set_selected($name, $value). Otherwise, it calls set_all($name, $value). If the set has no members, this method simply returns.

$set->set_all ($name => $value ...);

This method sets the given attribute values on all members of the set. It is not an error to call this on an object with no members, but neither does it accomplish anything useful.

$set->set_selected ($name => $value ...);

This method sets the given attribute values on the currently-selected member of the set. It is an error to call this on an object with no members.