view release on metacpan or  search on metacpan

lib/Astro/App/Satpass2/TUTORIAL.pod  view on Meta::CPAN

Latitude and longitude can be specified in either decimal degrees (e.g.
40.5) or degrees, minutes and seconds (e.g. 40d30m0s). B<South> latitude
and B<West> longitude are negative.

Height is assumed to be in meters, but you can be specify it in feet by
appending 'ft'. For example, '10' specifies 10 meters, as does '10m',
but '10ft' specifies 10 feet.

Because it would be painful to specify your position every time you use
it, C<Astro::App::Satpass2> allows a configuration file. The example
that follows will end by creating a configuration file and storing the
configuration in it.

And here, finally, is the example. We make the egregious assumption that
the President of the United States uses this software, so we use the
executive mansion as our location.

 $ satpass2
 ... front matter displayed ...
 satpass2>
 satpass2> # This is a comment, as is any line beginning
 satpass2> # with a hash mark ('#'). Comments and blank
 satpass2> # lines are ignored.
 satpass2>
 satpass2> # Enter the name of our location. This is for
 satpass2> # information only, and will be displayed by
 satpass2> # the location command. Command arguments that
 satpass2> # contain spaces need to be quoted.
 satpass2> set location '1600 Pennsylvania Ave, Washington DC'
 satpass2>
 satpass2> # Set our latitude and longitude.
 satpass2> set latitude 38d53m55.5s longitude -77d2m15.7s
 satpass2>
 satpass2> # Set our height above sea level.
 satpass2> set height 54.72ft
 satpass2>
 satpass2> # Some of our data sources will try to fetch
 satpass2> # their data from Space Track when we ask for
 satpass2> # it. We are assuming no Space Track username,
 satpass2> # so we tell them to just give us what they have.
 satpass2> spacetrack set direct 1
 satpass2>
 satpass2> # Some data sources come either with or without the
 satpass2> # actual name of the spacecraft. We want the name
 satpass2> # if it is available.
 satpass2> spacetrack set with_name 1
 satpass2>
 satpass2> # Save our configuration. All we really need to
 satpass2> # save are the changes from the default.
 satpass2> save -changes
 satpass2>
 satpass2> # We can now exit. When we restart, we will get
 satpass2> # the configuration we just set up.
 satpass2> exit

=head2 Geocoding the address

Looking up a latitude and longitude can be a bit of a pain. If you live
in the United States, C<Astro::App::Satpass2> can geocode your address,
and then query the U. S. Geological Survey for your height above sea
level.

This requires two more optional modules:
L<Geo::Coder::OSM|Geo::Coder::OSM> and
L<Geo::WebService::Elevation::USGS|Geo::WebService::Elevation::USGS>.
With these installed, the address entry in the previous example becomes

 satpass2> geocode '1600 Pennsylvania Ave NW, Washington DC USA'

When you issue this command, the geocoded location is displayed,
formatted as C<set> commands:

 set location '1600 Pennsylvania Avenue Northwest,
   Washington, District of Columbia USA'
 set latitude 38.8976989
 set longitude -77.036553192281
 set height 18.81

If more than one result is returned, all are displayed but no location
is set. If no result is returned, an exception is raised.

=head1 PREDICTING PASSES

The main use of this package is probably predicting when satellites are
going to pass over the observer.

=head2 Visible Passes

This is the functionality that tells you when you can go out and see a
satellite, assuming clear skies and a satellite large enough to be
visible. Visible passes require three things to happen:

* The satellite must be above the horizon (of course!),

* The Sun must be shining on the satellite (they do not have lights),
and

* The Sun must not be shining where you are (otherwise the sky is too
bright to see the satellite).

The example is for the International Space Station, and we will
use NASA's predictions of its orbit over the next week as a starting
point.

 $ satpass
 ... front matter ...
 satpass2>
 satpass2> # Tell the Astro::SpaceTrack object to fetch us
 satpass2> # all the predicted orbital elements from NASA's
 satpass2> # Human Space Flight web site. We include the
 satpass2> # effective date, since the data may include
 satpass2> # planned changes in orbit.
 satpass2> spacetrack spaceflight -all -effective
 satpass2>
 satpass2> # Make the default pass prediction, which is for
 satpass2> # seven days starting today at noon.
 satpass2> pass

You may want to print this information and stick it on your
refrigerator. C<Astro::App::Satpass2> has something a bit like Unix