view release on metacpan or  search on metacpan

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

The author also recommends optional module L<Date::Manip|Date::Manip>,
but since the latest version of this module only installs under Perl
5.10 and above, this tutorial will not assume it is installed. When it
is not, C<Astro::App::Satpass2> uses a home-grown ISO-8601-ish date
parser. All dates specified in the examples will be compatible with both
date parsers.

It does not matter whether you install optional modules before or after
installing C<Astro::App::Satpass2>; it will use them if it finds them.

=head1 CONFIGURATION

There are several possibilities for configuring C<Astro::App::Satpass2>.
This tutorial will cover the following:

=head2 Configuring from a F<satpass> initialization file

If you already have configured the initialization file for the
F<satpass> script packaged in the C<Astro-satpass> distribution,
C<Astro::App::Satpass2> will read this script, making allowances for at
least some of the incompatibilities between the two tools.

Since the intent is to remove the F<satpass> compatibility when
F<satpass> is retired, you may at some time wish to convert your
F<satpass> initialization file to a C<Astro::App::Satpass2>
initialization file. To do this from inside the F<satpass2> script,
simply issue the command

 satpass2> save -changes

The name and location of the saved file depend on your operating system,
but will be reported when you issue this command. Once the file is
saved, you can display its location using

 satpass2> initfile

The configuration file's location is actually determined using
C<< File::HomeDir->my_dist_config( 'Astro-App-Satpass2' ) >>. See the
L<File::HomeDir|File::HomeDir> documentation for details.

Subsequent runs of the F<satpass2> script will initialize from the new
file. This form of the C<save> command just saves changes from the
default configuration. If you wish to save all configuration, omit the
C<-changes> option.

Be aware that C<save> only saves the configuration of the
C<Astro::App::Satpass2> object and its related helper objects. If your
initialization file does other things, like download data and make
predictions, these will not be written to the new file, and you must add
them back by hand.

=head2 Configuring manually

Before you do any predictions, C<Astro::App::Satpass2> needs to know
where you are. The embedded L<Astro::SpaceTrack|Astro::SpaceTrack>
object will also need some configuration so it knows how to fetch data
from its various sources.

Specifically, you need your latitude, longitude (from Greenwich
England), and height above sea level. The height is least critical, and
any reasonable guess will probably work.

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,