view release on metacpan or  search on metacpan

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

	    $ele{$_} *= SGP_DE2RA;
	}
	my $temp = SGP_TWOPI;
	foreach (qw{meanmotion firstderivative secondderivative}) {
	    $temp /= SGP_XMNPDA;
	    $ele{$_} *= $temp;
	}

	my $body = __PACKAGE__->new (%ele);	# Note that setting the
						# ID does the reblessing.
	$body->__parse_name( $name );
	$body->{tle} = $tle;
	push @rslt, $body;
    }

    if ( keys %magnitude_table ) {
	foreach my $tle ( @rslt ) {
	    defined( my $oid = $tle->get( 'id' ) )
		or next;
	    defined $tle->get( 'intrinsic_magnitude' )
		and next;
	    defined( my $std_mag = $magnitude_table{ _normalize_oid( $oid ) } )
		or next;
	    $tle->set( intrinsic_magnitude => $std_mag +
		$magnitude_adjust );
	}
    }
    return @rslt;
}

sub __parse_name {
    my ( $self, $name ) = @_;
    defined $name
	or return;
    $name =~ s{ \s* -- ( effective | rcs ) \s+ ( \S+ ) }{
	$self->set( $1 => $2 );
	''
    }smxge;
    $name ne ''
	and $self->set( name => $name );
    return;
}

# Parse information for the above from
# CelesTrak "FAQs: Two-Line Element Set Format", by Dr. T. S. Kelso,
# http://celestrak.org/columns/v04n03/
# Per this, all data are for the NORAD SGP4/SDP4 model, except for the
# first and second time derivative, which are for the simpler SGP model.
# The actual documentation of the algorithms, along with a reference
# implementation in FORTRAN, is available at
# http://celestrak.org/NORAD/documentation/spacetrk.pdf

=item @passes = $tle->pass ($station, $start, $end, \@sky)

This method returns passes of the body over the given station between
the given start end end times. The \@sky argument is background bodies
to compute appulses with (see note 3).

A pass is detected by this method when the body sets. Unless
C<PASS_VARIANT_TRUNCATE> (see below) is in effect, this means that
passes are not usefully detected for geosynchronous or
near-geosynchronous bodies, and that passes where the body sets after
the C<$end> time will not be detected.

All arguments are optional, the defaults being

 $station = the 'station' attribute of the invocant
 $start = time()
 $end = $start + 7 days
 \@sky = []

The return is a list of passes, which may be empty. Each pass is
represented by an anonymous hash containing the following keys:

  {body} => Reference to body making pass;
  {time} => Time of pass (culmination);
  {events} => [the individual events of the pass].

The individual events are also anonymous hashes, with each hash
containing the following keys:

  {azimuth} => Azimuth of event in radians (see note 1);
  {body} => Reference to body making pass (see note 2);
  {appulse} => {  # This is present only for PASS_EVENT_APPULSE;
      {angle} => minimum separation in radians;
      {body} => other body involved in appulse;
      }
  {elevation} => Elevation of event in radians (see note 1);
  {event} => Event code (PASS_EVENT_xxxx);
  {illumination} => Illumination at time of event (PASS_EVENT_xxxx);
  {range} => Distance to event in kilometers (see note 1);
  {station} => Reference to observing station (see note 2);
  {time} => Time of event;

The events are coded by the following manifest constants:

  PASS_EVENT_NONE => dualvar (0, '');
  PASS_EVENT_SHADOWED => dualvar (1, 'shdw');
  PASS_EVENT_LIT => dualvar (2, 'lit');
  PASS_EVENT_DAY => dualvar (3, 'day');
  PASS_EVENT_RISE => dualvar (4, 'rise');
  PASS_EVENT_MAX => dualvar (5, 'max');
  PASS_EVENT_SET => dualvar (6, 'set');
  PASS_EVENT_APPULSE => dualvar (7, 'apls');
  PASS_EVENT_START => dualvar( 11, 'start' );
  PASS_EVENT_END => dualvar( 12, 'end' );
  PASS_EVENT_BRIGHTEST => dualvar( 13, 'brgt' );

The C<PASS_EVENT_START> and C<PASS_EVENT_END> events are not normally
generated. You can get them in lieu of whatever events start and end the
pass by setting C<PASS_VARIANT_START_END> in the C<pass_variant>
attribute. Unless you are filtering out non-visible events, though, they
are just the rise and set events under different names.

The dualvar function comes from Scalar::Util, and generates values
which are numeric in numeric context and strings in string context. If
Scalar::Util cannot be loaded the numeric values are returned.

These manifest constants can be imported using the individual names, or
the tags ':constants' or ':all'. They can also be accessed as methods
using (e.g.) $tle->PASS_EVENT_LIT, or as static methods using (e.g.)
Astro::Coord::ECI::TLE->PASS_EVENT_LIT.

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

When setting this, possible values are those returned by C<body_type()>
-- either the dualvar constants themselves, or the numeric or
case-insensitive strings corresponding to them. Whatever is set, what is
stored and returned will be one of the C<BODY_TYPE_*> constants. Any
unrecognized value will be stored as C<BODY_TYPE_UNKNOWN>, with a warning.

=item ordinal (numeric)

This attribute contains the ordinal 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 originator (string)

This attribute contains the name of the originator 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 pass_variant (bits)

This attribute tweaks the pass output as specified by its value, which
should be the bitwise 'or' (i.e. C<|>) of the following values:

* C<PASS_VARIANT_VISIBLE_EVENTS> - Specifies that events which are not
visible (that is, which take place either during daylight or with the
body in shadow) are not reported. Illumination changes, however, are
always reported. This has no effect unless the C<visible> attribute is
true.

* C<PASS_VARIANT_FAKE_MAX> - Specifies that if
C<PASS_VARIANT_VISIBLE_EVENTS> filters out the max, a new max event, at
the same time as either the first or last reported event, will be
inserted. This has no effect unless C<PASS_VARIANT_VISIBLE_EVENTS> is
specified, and the C<visible> attribute is true.

* C<PASS_VARIANT_START_END> - Specifies that the first and last events
of the pass are to be identified as C<PASS_EVENT_START> and
C<PASS_EVENT_END> respectively. If the C<visible> attribute is true and
C<PASS_VARIANT_VISIBLE_EVENTS> is in effect, C<PASS_EVENT_START> will
replace either C<PASS_EVENT_RISE> or C<PASS_EVENT_LIT>, and
C<PASS_EVENT_END> will replace either C<PASS_EVENT_SET>,
C<PASS_EVENT_SHADOWED>, or C<PASS_EVENT_DAY>. Otherwise, they replace
C<PASS_EVENT_RISE> and C<PASS_EVENT_SET> respectively.

* C<PASS_VARIANT_NO_ILLUMINATION> - Specifies that no illumination
calculations are to be made at all. This means no C<PASS_EVENT_LIT>,
C<PASS_EVENT_SHADOWED>, or C<PASS_EVENT_DAY> events are generated, and
that the C<illumination> key on other events will not be present. I find
that setting this (with C<< visible => 0 >>) saves about 20% in wall
clock time versus not setting it. Your mileage may, of course, vary.
This has no effect unless the C<visible> attribute is false.

* C<PASS_VARIANT_TRUNCATE> - Specifies that any pass in progress at the
beginning or end of the calculation interval is to be truncated to the
interval. If the calculation interval starts with the body already above
the horizon, the initial event of that pass will be C<PASS_EVENT_START>
rather than C<PASS_EVENT_RISE>. Similarly, if the calculation interval
ends with the body still above the horizon, the final event of that pass
will be C<PASS_EVENT_END>. With this variant in effect, 'passes' will be
computed for synchronous satellites. This variant is to be considered
B<experimental.>

* C<PASS_VARIANT_BRIGHTEST> - Specifies that the the moment the
satellite is brightest be computed as part of the pass statistics. The
computation is to the nearest second, and is not done if
C<PASS_VARIANT_NO_ILLUMINATION> is set, the satellite has no intrinsic
magnitude set, or the satellite is not illuminated during the pass.

* C<PASS_VARIANT_NONE> - Specifies that no pass variant processing take
place.

The above constants are not exported by default, but are exported by the
C<:constants> tag.

The default is C<PASS_VARIANT_NONE>

=item rcs (string, parse)

This attribute represents the radar cross-section of the body, in square
meters.

=item reblessable (boolean)

This attribute says whether the rebless() method is allowed to rebless
this object. If false, the object will not be reblessed when its
id changes.

Note that if this attribute is false, setting it true will cause the
object to be reblessed.

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).