; TVSPC
;---------------------------------------------------------------
;! Display images and spectra from a cube
;# Task TV ANALYSIS IMAGE-UTIL INTERACTIVE
;-----------------------------------------------------------------------
;;  Copyright (C) 2016-2017, 2019
;;  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
;-----------------------------------------------------------------------
TVSPC     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
TVSPC:  Interactive images and spectra and fitting from cube(s)
INNAME                             Image to put on TV: name
INCLASS                            Image to put on TV: class
INSEQ           0.0      9999.0    Image to put on TV: seq #
INDISK                             Image to put on TV: disk
TBLC            0.0      4096.0    Bottom left corner of image
                                     0=>entire image
TTRC            0.0      4096.0    Top right corner of image
                                     0=>entire image. See HELP!
TVCHAN          0.0        15.0    TV channel to use, 0 => 1
PIXRANGE                           Min,Max of TV image display
                                       0 => entire range
FUNCTYPE                           Image intensity transfer func
                                     'LN' Linear.  unknown=>'LN'
                                     'LG' Logarithmic
                                     'L2' More logarithmic
                                     'SQ' Square root
                                     'NE' Negative linear
                                     'NG' Negative logarithmic
                                     'N2' Negative more log.
                                     'NQ' Negative square root
IN2NAME                            Transposed cube: name
IN2CLASS                           Transposed cube: class
IN2SEQ          0.0      9999.0    Transposed cube: seq #
IN2DISK                            Transposed cube: disk
APARM                              (1,2) spectrum plot range
                                      (2) > (1) fixed scale
                                      (2) < (1) full image range
                                      (2) = (1) self-scale
                                   (3) radius in cube YZ to
                                      average spectra
                                   (4) split screen: <0 vertical
                                       > 0 horizontal
                                   (5) If split, fraction used
                                       for spectra
                                   (6) > 0 -> Separate the 2
                                       spectra plots
                                   (7) If smoothing, FWHM in
                                       X-axis pixels
                                   (8) > 0 -> label in channels
                                       else units of first axis
                                   (9) order of baseline in
                                       spectral fit + 1
                                       (0 => none)
SAMPTYPE                           Type of smoothing function
IN3NAME                            2nd Transposed cube: name
IN3CLASS                           2nd Transposed cube: class
IN3SEQ          0.0      9999.0    2nd Transposed cube: seq #
IN3DISK                            2nd Transposed cube: disk
IN4NAME                            Normal XYf cube: name
IN4CLASS                           Normal XYf cube: class
IN4SEQ          0.0      9999.0    Normal XYf cube: seq #
IN4DISK                            Normal XYf cube: disk
CBPLOT          0.0         4.0    Position for beam plot:
                                     0: don't plot beam
                                     1: lower left (default)
                                     2: lower right
                                     3: upper right
                                     4: upper left
----------------------------------------------------------------
TVSPC
Type: Task
Use:  TVSPC will load an image to the TV.  It then displays a menu
      which includes manipulations of the TV display and a mode in
      which the spectrum from a second, transposed image corresponding
      to the pixel under the cursor is displayed.  Optionally, the
      corresponding spectrum of a second cube is also drawn in a
      different color.  The second cube must match the first cube in
      size and coordinates.  The spectrum from the first cube may be
      fit with up to four Gaussians and may be saved (with the fit) as
      a slice file.

       Details of the interactive operation and options are described
       in the EXPLAIN file.  See also AIPS Memo 120, "Exploring Image
       Cubes in AIPS", July 2017 (revised) for a more detailed
       description of the use of this task.

Adverbs:
  INNAME......Image name for image on TV.    Standard defaults.
  INCLASS.....Image class for image on TV.   Standard defaults.
  INSEQ.......Image seq. # for image on TV.  0 => highest.
  INDISK......Disk unit # for image on TV.   0 => any.
  TBLC........Bottom Left Corner of image to be displayed on TV  (0,0)
              means (1,1).  The image size is also limited by the size
              of the TV.
  TTRC........Top Right Corner of the Tv image: (0,0) means top right
              corner of map.
  TVCHAN......TV channel to use: 0 => 1.
  PIXRANGE....Min,Max of displayed intensity on TV.  0 => entire range
              of 1st image.
  FUNCTYPE....Image intensity transfer function
              'LN' => linear;        'NE' => negative lin.
              'LG' => log;           'NG' => negative log;
              'L2' => extreme log;   'N2' => negative extra log;
              'SQ' => square root,;  'NQ' => negative square root;
              others => linear.
  IN2NAME.....Image name for transposed cube.      Standard defaults.
  IN2CLASS....Image class for transposed cube.     Standard defaults.
  IN2SEQ......Image seq. # for transposed cube.    0 => highest.
  IN2DISK.....Disk unit # for transposed cube.     0 => any.

  APARM.......Spectral plotting controls:
              (1,2) If APARM(2) > APARM(1), spectra are plotted from
                    APARM(1) to APARM(2)
                    If APARM(2) < APARM(1), spectra are plotted over
                    the range in the header of IN3NAME
                    If APARM(2) = APARM(1), each spectral plot is
                    done over its range of values.
              (3) Spectra are averaged over an area of radius APARM(3)
                  pixels (in IN3NAME pixels).
              (4) If < 0, screen is split with the lower half for
                  spectra plots and the upper for the image
                  If > 0, screen is split with the left for the image
                  and the right for spectral plots.
                  If = 0, the full screen is used for both, so they
                  overlap.
              (5) If split screen (APARM(4) not 0), fraction used by
                  spectra plots.  <= 0.1 or > 0.9 -> 0.5
              (6) If IN4NAME not blank, plot control for the spectra
                  of the 2nd cube:  <= 0, overlap the two spectra in
                  different colors, > 0 separate the two.
              (7) If SAMPTYPE not blank, the full support range (BOX,
                   MWF) or FWHM (HANN, GAUS, EXP) in IN3NAME X-axis
                   pixels used to smooth the spectra.
              (8) Spectra are labeled in the units of the first axis
                  of the (transposed) cubes unless APARM(8) > 0.  In
                  that case the labels are in channels.
              (9) When doing a Gaussian fit, APARM(9) controls the
                  order of the baseline fit: 1 -> constant, 2 adds a
                  slope, 3 adds a curvature.  0 -> no baseline
  SAMPTYPE....The type of smoothing:
                'BOX ' = boxcar smoothing
                'MWF ' = Median window filter
                'HANN' = Hanning
                'GAUS' = Gaussian
                'EXP ' = Exponential

     Optional 2nd cube.  Coordinates must match those of the first
     transposed cube but it cannot be the same file as the first
     transposed cube.
  IN3NAME.....Image name for 2nd transposed cube.      Standard defaults.
  IN3CLASS....Image class for 2nd transposed cube.     Standard defaults.
  IN3SEQ......Image seq. # for 2nd transposed cube.    0 => highest.
  IN3DISK.....Disk unit # for 2nd transposed cube.     0 => any.
     Optional 3rd cube, 1 plane at a time  displayed in grey-scale
  IN4NAME.....Image name for normal XYf cube.      Standard defaults.
  IN4CLASS....Image class for normal XYf cube.     Standard defaults.
  IN4SEQ......Image seq. # for normal XYf cube.    0 => highest.
  IN4DISK.....Disk unit # for normal XYf cube.     0 => any.
              Often IN2NAME is the transposition of IN4NAME.
  CBPLOT......Selects the corner in which the half-power beam plot is
              placed
                  0: no beam plot
                  1: lower left
                  2: lower right
                  3: upper right
                  4: upper left
----------------------------------------------------------------
TVSPC :  Interactive plotting of spectra from one or two cubes
Documenter:  E. W. Greisen NRAO
Related Programs: SLFIT, ZEMAN, XGAUS

See AIPS Memo 120 for full details - your $AIPS_ROOT/TEXT/PUBL area
contains the pdf and PostScript files or it can be found on the web at
http://www.aips.nrao.edu/aipsdoc.html.

TVSPC is an interactive task designed to let you look through spectra
from an image cube quickly and easily.  The task loads an image plane
in grey-scale using the full XAS screen area, the left half of the
screen, or the upper half of the screen, depending on the setting of
APARM(4).  (That setting, and all other APARM values, may be changed
while running the task.)  Images of the full source, such as
moment-zero images are probably best for this grey-scale image
specified by INNAME adverbs plus TBLC and TTRC.  The image is loaded
with interpolation between pixels, with every pixel, or with every
n'th pixel as needed to fill the display area as fully as possible.
The SET WINDOW option allows you to display a smaller region of the
grey-scale image, computed to fill as large an area as possible.
RESET WINDOW then lets you undo the SET WINDOW to view the full image
and perhaps set another window.  The usual image enhancement options
of TVTRANSF, TVPSEUDO, and TVFLAME are available.

Having selected a sub-image to view, you may now plot spectra from the
IN2NAME-specified, transposed cube.  In PLOT SPECTRA, move the TV
cursor over the grey-scale window selects a coordinate (RA and Dec) to
plot.  That coordinate is found in IN2NAME and the spectrum at that
pixel is plotted in a graphics overlay channel.  The plot may overlay
the grey-scale image, or lie below or to the right of the grey-scale
image, depending again on APARM(4).  The fraction of split screens
occupied by the spectra is controlled with APARM(5).  The spectrum may
represent the average over a circular region APARM(3) in radius and
may be smoothed in the spectral axis before plotting.  Hit buttons C
or D to exit back to the menu.

You may now fit up to 4 Gaussians to the spectrum that is displayed.
FIT SPECTRUM will prompt you for an initial guess, pointing at the
peaks and half-widths of some number of components.  Hit buttons A or
B to set the parameters and buttons C or D to set the number of
Gaussians in the guess and exit the setting of the guesses.  The task
then fits the Gaussians, giving the results in the message window.
It plots the fit and the residual (data-fit) in two more colors on top
of the spectrum plot.  The fit is done only over the currently
displayed channel ramge.

If a spectrum is displayed, it may be saved as a slice (SL) file
attached to the transposed cube (IN2NAME).  The full spectrum and any
Gaussian-fit results will be saved in the slice file.

You can examine two transposed cubes at the same time, so long as the
coordinates (number of pixels on first 3 axes, types and values of
the first 3 axes) match.  Set IN3NAME to ppint at the second
transposed cube.  Its spectra will be plotted on top of, or separated
from, the plots of the first cube depending on the setting of
APARM(6).  The two spectral plots will be in different colors in any
case.

Yet another image cube may also be viewed.  This cube needs tp be in
XYf sort order where X and Y are two celestial coordinates and f a
spectral coordinate.  IN2NAME and IN3NAME must match each other in
coordinates, but IN1NAME and IN4NAME need only have the same types of
axes and, to be useful, overlap the IN2NAME and IN3NAME cubes.  After
a spectum has been plotted, you may interactively select a plane from
IN4NAME to display to the right or above the display of IN1NAME using
LOAD PLANE.  That image may then be used to plot spectra (PLOT PL
SPECTRA).  Windows into this display and a display intensity range may
also be set and reset.  Menu items below marked with a * occur only
when IN4NAME is specified.

The images may be labelsd (LTYPE=7) with and without drawing the tick
marks all the way across (DOCIRCLE).  Consective selections of
LABEL IMAGES? cycles through the 3 possibilities.  CURVALUE does the
standard CURVALUE display of the pixel numbers and intensity under the
cursor.  It works in all possible images and spectral plots.

The menu is:
-------------------
| OFF TRANS       |   Initialize black-and-white transfer function
| OFF PSEUDO      |   Turn of any pseudo-coloring
| TVTRANSF        |   Adjust black-and-white transfer function
| TVPSEUDO        |   Color contours of a variety of types
| TVFLAME         |   Flame-like pseudo-coloring
| SET APARM       |   Change the plot and smoothing parameters
| LABEL IMAGES?   |   Cycle through no image label, image label,
                      label with ticks drawn across the image
|                 |
| SET WINDOW      |   Select a sub-image for more detailed viewing
| RESET WINDOW    |   Return to viewing full image
| SET CHANNELS    |   Interactively set channel ramge for spectra
| RESET CHANNELS  |   Plot spectra with all channels
| CURVALUE        |   Display intensity under the cursor in any of
                      the images and spectral plots
| PLOT SPECTRA    |   Plot spectra of cube(s) selected on grey-scale
                      image from IN1NAME
| FIT SPECTRUM    |   Gaussian fit the plotted spectrum
| SAVE SPECTRUM   |   Save the plotted spectrum as a slice
|                 | *
| LOAD PLANE      | * Select plane from IN4NAME to display
| PLOT PL SPECTRA | * Plot spectra of cube(s) selected on grey-scale
                      image plane from IN4NAME
| SET PL WINDOW   | * Select a sub-image in display of IN4NAME planes
| RESET PL WINDOW | * Return to viewing the full image planes of
                      IN4NAME
| SET PL RANGE    | * Enter intensity range for spatial cube display
|                 |
| EXIT            |   Exit the task
-------------------

APARM and SAMPTYPE control the arrangement of sub-windows on the XAS
TV screen and the averaging, smoothing, and plotting of spectra.

APARM(1 and 2) control the scaling of the spectral plots
    If APARM(2) > APARM(1), spectra are plotted from APARM(1) to
       APARM(2)
   If APARM(2) < APARM(1), spectra are plotted over the range in the
       header of IN3NAME
   If APARM(2) = APARM(1), each spectral plot is done over its range
       of values.

APARM(3) is the radius of the area over which spectra are averaged
   measured in IN3NAME pixels.

APARM(4) controls whether the XAS viewing area is split or not.
   If APARM(4) < 0, screen is split with the lower half for spectra
       plots and the upper for the image(s)
   If APARM(4) > 0, screen is split with the left for the image(s) and
       the right for spectral plots.
   If APARM(4) = 0, the full screen is used for both, so they
       overlap.

APARM(5) controls the fraction of split screens occupied by the
       spectra.  If APARM(5) < 0.1 or APARM(5) > 0.9, APARM(5) is
       forced to 0.5.

APARM(6) controls the plotting when there are two transposed cubes.
   If APARM(6) <= 0, the two spectra are plotted on top of each other
       using a single intensity range,
   If APARM(6) > 0, the two spectra are plotted in separate frames.
       If APARM(4) < 0, the two frames are separated horizontally.
       If APARM(4) >= 0, the two frames are separated vertically.
       In any case, the two frames are plotted in different colors.

SAMPTYPE controls the type of spectral smoothing:
                'BOX ' = boxcar smoothing
                'MWF ' = Median window filter
                'HANN' = Hanning
                'GAUS' = Gaussian
                'EXP ' = Exponential

APARM(7) is the full support size of BOX and MWF smoothing and the
   full-width at half-maximum for HANN, GAUS, and EXP.  Units are
   channels (x-axis pixels) in the transposed cube(s).

APARM(8) controls the labeling of the spectral axis with > 0 being
   channels and <= 0 being the units of the first axis of the
   transposed cube(s).

APARM(9) controls the fitting of a baseline when doing a FIT SPECTRA.
   0 -> none, 1 -> constant, 2 -> constant + slope, 3 -> constant +
   slope + curvature

CBPLOT   controls the plotting of a Clean beam (at half power) in a
   corner of the images.  Values include 0 (none), 1 lower left, 2
   lower right, 3, upper right, and 4 upper left.  The SET PARAM
   option allows you to change this.
