; HLPTVSPC
;---------------------------------------------------------------
;! Interactive display of spectra from a cube - run-time help
;# Task TV ANALYSIS IMAGE-UTIL INTERACTIVE
;-----------------------------------------------------------------------
;;  Copyright (C) 2016-2017
;;  Associated Universities, Inc. Washington DC, USA.
;;
;;  This program is free software; you can redistribute it and/or
;;  modify it under the terms of the GNU General Public License as
;;  published by the Free Software Foundation; either version 2 of
;;  the License, or (at your option) any later version.
;;
;;  This program is distributed in the hope that it will be useful,
;;  but WITHOUT ANY WARRANTY; without even the implied warranty of
;;  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
;;  GNU General Public License for more details.
;;
;;  You should have received a copy of the GNU General Public
;;  License along with this program; if not, write to the Free
;;  Software Foundation, Inc., 675 Massachusetts Ave, Cambridge,
;;  MA 02139, USA.
;;
;;  Correspondence concerning AIPS should be addressed as follows:
;;         Internet email: aipsmail@nrao.edu.
;;         Postal address: AIPS Project Office
;;                         National Radio Astronomy Observatory
;;                         520 Edgemont Road
;;                         Charlottesville, VA 22903-2475 USA
;-----------------------------------------------------------------------
C-----------------------------------------------------------------------
OFF TRANS
This option turns off any black-and-white enhancements done in TVTRANSF.
C-----------------------------------------------------------------------
OFF PSEUDO
This options turns of any color enhancements done in TVPSEUDO or
TVFLAME.  Has no effect if the image is in black and white.
C-----------------------------------------------------------------------
TVTRANSF
This option allows you to set the black-and-white transfer function
using the TV cursor to control intercept and slope.  Buttons A and B
turn a plot of the LUT on and off, button C reverses the sign of the
slope, and button D ends the enhancement and returns to the menu.
C-----------------------------------------------------------------------
TVPSEUDO
This option allows you to set the color transfer function using the TV
cursor.  Button A loops through all possible RGB triangles, button B
selects a circle in hue (which is very useful for phase displays),
button C selects several color contours, and button D ends the
enhancement and returns to the menu.  As in AIPS, the TV cursor is used
to adjust the colors within the selected function.  Instructions appear
on the message screen.
C-----------------------------------------------------------------------
TVFLAME
This option allows you to set the color transfer function using the TV
cursor and a flame-like color scheme.  Buttons A and B cycle through the
sequence of all possible color combinations, while buttons C and D end
the enhancement and return to the menu.  The TV cursor X position
adjusts the image intensity at which the color turns more white, while
the Y position adjusts the way colors add (the gamma).  Instructions
appear on the message screen.
C-----------------------------------------------------------------------
SET APARM
This option allows you to change all of the APARM and SAMPTYPE control
adverbs.  The task prompts with "Spectral plot range min and max".
Enter 2 values: if A(1) < A(2) the spectral plots are done from A(1)
to A(2), if A(2) < A(1) the spectral plots are done over the full
image range, and if A(1) = A(2) the spectral plots are all self-scaling.
The the task prompts "Spectral averaging radius in YZ pixels"; enter 1
value >= 0 to set the spatial averaging radius.  Then the task prompts
"Split screen: < 0 vertical, > 0 horizontal, 0 none" to set the split
of the screen between the area for the INNAME image and the area for
the spectral plot(s).  If split screen is selected, the prompt
"Fraction of split screen for spectra" requests a value from 0.1 to
0.9 and will default to 0,5.  If IN3NAME was specified, you are asked
"Split spectra: <= 0 no, > 0 yes" to control whether the two spectra
over-plot each other or plot in separate windows.  Then you are asked
"Label spectra in channels: > 0 -> yes" to select channel labeling or
phyical parameter labeling.  Then "Baseline fit order: > 0 -> yes" asks
the polynomial level for baselines in Gaussians fits.  Zero means no
baseline, 1 for constant, 2 to add a slope, and 3 to add a curvature.
The prompt "Spectral smoothing function type (4 characters)" requests
a string to do spectral smoothing with BOX, MWF, HANN, GAUS, and EXP
as known values.  Any other means do not smooth.  If smoothing with
BOX or MWF, you are prompted for "Spectral smoothing support in
channels" or, if smoothing with HANN, GAUS, or EXP you are prompted
with "Spectral smoothing FWHM in channels".  Enter one number Greater
than zero for the full support or FWHM in channels.
C-----------------------------------------------------------------------
LABEL IMAGES?
This option lets you cycle from no axis labels on the gray-scale images
to labeling the gray scale images (at adverb LTYPE=7), to labeling the
grey-scale images with tickes extended to form a coordinate grid, and
back to no label.  The labels are updated whenever windows or planes
are changed.
C-----------------------------------------------------------------------
SET WINDOW
This option allows you to set the window into the TV image that you wish
to view.  That sub-image will be blown up to fill as much of the area
reserved for the grey-scale (INNAME) image as possible.  This option is
similar to TVWINDOW in AIPS.  Any button marks the BLC on the image,
switching you to setting TRC. Thereafter, buttons A and B switch between
setting BLC and TRC and buttons C and D set the window, reload the image
and return to the menu.  Instructions appear on the message screen.
Note that the cursor position cannot be moved off the currently visible
image window.
C-----------------------------------------------------------------------
RESET WINDOW
This option lets you set the visible window into the grey-scale image
to include the whole field.  The image will be redisplayed using pixel
increments large enough to fit the full image into the part of the
screen reserved for the grey-scale image.  Note that the image is
interpolated if possible and sub-sampled if necessary to fit the
available area.
C-----------------------------------------------------------------------
SET CHANNELS
This option lets you restrict the range of spectral channels plot by
PLOT SPECTRA and fit by FIT SPECTRUM.  You must first plot soem
spectrum.  Then this option starts with vertical lines drawn at the
left and right edges of the spectrum.  Move the mouse to set the upper
channel (:ECHAN"), then hit button A or B to set the lower channel
("BCHAN").  Hitting buttons A or B switches between the two limits, the
values of which are displayed at the upper left of the screen.  Hit
buttons C or D to exit setting the channel range for the next PLOT
SPECTRA operation.
C-----------------------------------------------------------------------
RESET CHANS
This option resets the displayed spectral channel range to the full
range available in the transposed image cubes.  If you want to expand
the current channel range, you must first RESET CHANS, PLOT SPECTRA, and
then do SET CHANNELS since the last can only reduce the channel range.
C-----------------------------------------------------------------------
CURVALUE
This option lets you examine the intesnities as a function of pixel
number in any of the grey-scale images and spectral plots.  Move the
cursor to select the image pixel desired or the spectral channel.  You
may move the cursor freely between the images and spectra on display.
HIt button C or D to exit.
C-----------------------------------------------------------------------
PLOT SPECTRA
This option lets you plot spectra from the IN2NAME cube and, if
specified, the IN3NAME cube interactively.  Position the cursor inside
the current grey-scale (INNAME) image.  The selected coordinate in
INNAME will be translated to a pixel value in the cube(s) and the
spectrum from each read and plotted.  The spectrum may be averaged over
a radius of APARM(3) pixels and may be smoothed spectrally.  The
spectral plot(s) will overlap the grey-scale image or will appear to
the right and below the grey-scale image depending on APARM(4).  The
spectra, if there are two of them, will overlap or appear in separate
panels depending on APARM(6) and will be in different colors.  Hit
buttons C or D to stop plotting.  The spectrum that is left on the
screen at this point may be fit with Gaussians and may be saved as a
slice.
C-----------------------------------------------------------------------
FIT SPECTRUM
This option lets you fit up to 4 Gaussians to the spectrum plotted from
the first transposed cube (IN2NAME).  The task prompts you to position
the cursor at the peak of the first component and hit button A or B.
This sets the initial guess of the peak and center channel.  Then the
task asks you to position the cursor at the half-power point and hit
button A or B.  This sets the width (so the vertical position does not
matter).  Then you are prompted for the next component similarly.  Hit
buttons C or D to exit the initial guess phase at any time.  The task
then does the non-linear least-squares fit and displays the results
with uncertainties on the message screen.
C-----------------------------------------------------------------------
SAVE SPECTRUM
This option lets you save the plotted spectrum from the first cube as
a slice (SL) file attached to that cube.  Any Gaussian fit is also
saved in the SL file.  You may then do more PLOT SPECTRA, FIT SPECTRUM,
and SAVE SPECTRUM sequences to save additional SL files.
C-----------------------------------------------------------------------
VERBOSE?
This option lets you choose whether you want to see a message giving
the pixel position in the cube for every spectrum or whether you would
rather not be bothered with that verbose output.  You will still see
messages when the position in the grey-scale image cannot be found in
the cube.  Select this option to switch verbosity on and off.
C-----------------------------------------------------------------------
EXIT
This option allows you to exit the task.
C-----------------------------------------------------------------------