view release on metacpan or  search on metacpan

bin/sourceplot  view on Meta::CPAN

=head1 SYNOPSIS

    sourceplot [--help | --version] [--date YYYY-MM-DD] [--telposition TELESCOPE] [--samp]

=head1 PURPOSE

Source Plot was created to help observers decide which sources to observe
at particular times to optimise the observing time at the telescope.
The main purpose of this program is to plot the movement of a source
throughout the night.  The movement can be plotted by the source's
elevation, azimuth, parallactic angle, or by time.

=head1 DESCRIPTION

Source Plot is designed to display the path of a source throughout
a night.  This path can be displayed in several ways, using Time,
Elevation, Parallactic Angle, and Azimuth as the different axes.
The sources can either be taken from a catalog or manually inserted.
The first thing most observers will want to double click on is a source
in the Catalog Window, which will plot that source.  Currently the only
moving sources that can be plotted are planets, the Sun and the Moon,
which can be added via the 'Planets' button in the Edit Window.

=head2 Command Line Options

=over 4

=item --help | --man

Show this documentation.

=item --version

Show version information.

=item --date YYYY-MM-DD

Select initial date.

=item --telposition TELESCOPE

Indicate current pointing position of given telescope, if available.

=item --samp

Enable SAMP interface.  Will attempt to register with a SAMP hub and
listen for C<table.load.votable> messages.

=back

=head2 Plotting Window

The Plotting Window contains the actual plot and has control over the
other windows.  The display itself has several features.  Each colored
line in the Plotting Window is associated with the source with the same
color in the Edit Window.  In the event that two lines have the same or
similar color, moving the mouse over a plotted source will highlight the
source in the Edit Window.  The large dot along the plotted source is
the position of the source at the current time, called from here on a
'location dot'.  These dots are updated automatically as time passes.
Moving the mouse over a location dot will display the elevation and
azimuth for the source in respect to an RA-Dec graph, where Dec is
the y-axis.  This feature does not work in the
L<Azimuth-Elevation graph|/"Elevation vs Azimuth Mode">.  The small
dots along the plotted lines are 15 minutes apart, showing the precise
time the source will be at a given location.

There are several buttons in this window.  Starting from the left,
here's an explanation of each:

=over 4

=item B<Options>

Opens a window in which the relevant telescope, x-axis and y-axis can
be changed.  The time the plot is centred around can also be changed.
To apply these changes without closing the window, press the 'Apply'
button.

=item B<UT Date>

A window will appear with the current UT Date in it which can be modified
to see future or past dates.

=item B<Edit>

This button will open the Edit Window if it is closed.  This button
becomes disabled when the Edit Window is open.

=item B<Catalog>

Like the 'Edit' button, the button opens the Catalog Window if it is
closed.  This button will be disabled if the Catalog Window is open to
prevent more than one Catalog Window from being created.

=item B<Print>

See L</"Printing the Graph"> for a description of this button.

=item B<Exit>

Exits the program, closing all associated windows.

=back

=head2 Edit Window

This window contains the list of sources chosen by the observer.
Only the sources that are active will be shown in the plot.  The first
thing that should be known is how to select sources so they can be added,
deleted, or deactivated.  To select a source, single click on it in the
Edit Window.  The source will turn red indicating it has been selected.
Several sources can be selected by clicking on each one individually.
To deselect a source, single click on the source again.

There are several small features in this window.  Moving the mouse
over a source in the Edit Window will highlight its plotted line in
the Plot Window.  To edit a source's coordinates, double click on it.
A window will appear in which the source's information can be changed.
The final set of features require the use of the Edit Window Buttons.