; TVIEW
;---------------------------------------------------------------
;! Display image cube in all 3 transpositions with rotation & reference
;# Task TV ANALYSIS IMAGE-UTIL INTERACTIVE
;-----------------------------------------------------------------------
;;  Copyright (C) 2018-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
;-----------------------------------------------------------------------
TVIEW     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
TVIEW:  Interactive display of image cube in 3 transpositions
INNAME                             Image cube: name
INCLASS                            Image cube: class
INSEQ           0.0      9999.0    Image cube: seq #
INDISK                             Image cube: disk
BLC             0.0      4096.0    Bottom left corner of cube
                                     0=>entire image
TRC             0.0      4096.0    Top right corner of cube
                                     0=>entire image. See HELP!
IN2NAME                            Reference image: name
IN2CLASS                           Reference image: class
IN2SEQ          0.0      9999.0    Reference image: seq #
IN2DISK                            Reference image: disk
TBLC            0.0                Bottom left corner reference
                                      image  0=>entire image
TTRC            0.0                Top right corner reference
                                      image  0=>entire image
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
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
REWEIGHT        0.0         4.0    (1) Interpolation halfwidth
                                   (2) Minimum fraction of good
                                       pixels required (0->1/3)
----------------------------------------------------------------
TVIEW
Type: Task
Use:  TVIEW is similar to TVSPC and is used to view an image cube in
      its 3 transpositions.  It may also load a reference image in the
      remaining quadrant of the screen or use that quadrant to display
      line plots of spectra from the cube..  It begins by displaying the
      3 transpositions at the central pixel of the 3rd axis of that
      transposition and the reference image, if any, or a central pixel
      spectrum.  It then displays a menu which includes manipulations of
      the TV display and modes in which the locations in the cube are
      interactively changed.  To have spectra rather than a reference
      image, leave IN2NAME blank.

      Details of the interactive operation and options are described
      in the EXPLAIN file.  See also AIPS Memo 124, "Further
      Exploration of Image Cubes in AIPS", October 2019 revision for a
      more detailed description of the use of this task.

Adverbs:
  INNAME......Image name for image cube.    Standard defaults.
  INCLASS.....Image class for image cube.   Standard defaults.
  INSEQ.......Image seq. # for image cube.  0 => highest.
  INDISK......Disk unit # for image cube.   0 => any.
  BLC.........The bottom left-hand pixel of the input image cube which
              becomes the bottom left corner of the input sub-image.
              The value (0,0,0) means (1,1,1).
  TRC.........The top right-hand pixel of the input image cube which
              becomes the top right corner of the sub-image.  The value
              (0,0) means take the top right hand corner of the cube.
  IN2NAME.....Image name for reference image.      Standard defaults.
              Leave IN2NAME blank to have a spectral display instead of
              the reference image.
  IN2CLASS....Image class for reference image.     Standard defaults.
  IN2SEQ......Image seq. # for reference image.    0 => highest.
  IN2DISK.....Disk unit # for reference image.     0 => any.
  TBLC........Bottom Left Corner of reference 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 reference image: (0,0) means top
              right corner of image.
  TVCHAN......TV channel to use: 0 => 1.
  PIXRANGE....Min,Max of displayed intensity on TV.  0 => entire range
              of reference 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.
  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
  REWEIGHT....Interpolation kernel parameters:
              (1) Half width of the interpolating kernel
                  (1 - 4).  Default = 1
                  Larger support sizes should produce more accurate
                  results at the cost of increased computation.
              (2) Minimum fraction of pixels in interpolation kernel
                  area required for non-blanked output.
                  <= 0 or >= 1  => 0.333
----------------------------------------------------------------
TVIEW :  Interactive display of image cube in 3 transpositions
Documenter:  E. W. Greisen NRAO
Related Programs: TVSPC, SLFIT, ZEMAN, XGAUS, ZAMAN, AGAUS

See AIPS Memo 124 for full details on TVIEW and AIPS Memo 120 for full
details on TVSPC - 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.

TVIEW is similar to TVSPC but is designed to show the data cube in all
3 transpositions as well as a "reference" image or the spectrum at the
selected pixel.  The reference image is any image that is useful for
defining locations in the RA-Dec plane, especially a line sum (moment 0)
image.  The INNAME adverbs define the cube and BLC and TRC define the
portion of the cube that will appear.  The IN2NAME adverbs define the
reference image with TBLC and TTRC defining the portion of that image
that will appear.  Note that the reference image is a single plane with
RA-Dec axes, but it does not need to be on the same coordinate system as
the cube.

The task begins by reading the reference image (if any) into memory,
followed by the image cube.  It is stored in three large arrays, one
for each transposition.  Independent of the transposition of INNAME,
the Ra-Dec-Freq cube is displayed in the lower left of the TV screen,
the Freq-Ra-Dec cube is displayed in the upper right, and the
Freq-Dec-Ra cube is displayed in the lower right.  The reference image,
if any, appears in the upper left.  Each of these images appears in the
largest form that will fit in the current TV's quadrant.  Pixels may
be interpolated or only every n'ht pixel shown depending on image size
and TV size.  When the images are loaded, information on the
interpolations or decrements is displayed in the message window.  The
plane pixel number and approximate coordinate are displayed above the
images of the 3 transpositions.  If there is no reference image, the
spectrum at the X, Y pixel selected in the two right-hand display is
plotted.

A menu will then appear on the screen.  Move the cursor to a menu
option which will change color as you point at it.  To select the
option, press buttons A, B, or C.  Press button D for a short
description of the option, displayed on the message window.  The pixel
display range of the reference image is initially set by adverb
PIXRANGE, but may be reset with option SET REF RANGE.  If there is no
reference image, SET SPEC RANGE is used to set the intensity range for
plots of spectra.  The pixel display range of the cube is initially set
by the image header range, but may be reset with option SET CUBE RANGE.
Adverb TVTRANSF sets the transfer function type for both images.  The
SET WINDOW option allows you to display a smaller region of the
reference or cube images which are then computed to fill as large an
area as possible.  You must select an image with the cursor and a TV
button and then set the window in the usual way.  Windows set in cube
images affect all 3 images.  RESET WINDOW allows you to select one of
the images with the cursor and a TV button and reset the window applying
to that image.  The usual display options are present: OFF TRANS, OFF
PSEUDO, TVTRANSF, and TVFLAME.  The LABEL IMAGES? option circles from
simple image labels to image labels with lines drawn across the full
image to no axis labeling.

The option ROAM allows you to roam in any displayed images, changing
the corresponding displays.  The plane number and its approximate
coordinate of each cube image are shown above that image at the right
and will change as you roam.  Note that only 2 of the displays change
at any one time.  If there is no reference image, the plotted spectrum
will also change as you roam.  CURVALUE allows you the usual pixel value
under the cursor display in any of the four images.  ROTATE asks you for
a rotation angle (clockwise in degrees) and then rotates each Ra-Dec
plane in the images accordingly.  If there is a reference image, TV
ROTATE will display the reference image on the full screen and allow
you to set the end points of a slice.  if there is no reference image,
the currect plane of the position-position-velocity transposition is
used instead.  Buttons A, B, and C switch between end points, button D
sets the points.  An angle is then determined from the slice and the
images rotated.  The interpolation of the images during the rotation is
determined with the aid of the REWEIGHT adverbs.

Since rotations will blank those pixels in the rotated image that do
not occur in the input image, areas of the image will become blanked
even if one reverses the rotation.  RELOAD IMAGES allows you to return
to the pre-rotation state of the images.

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
| LABEL IMAGES?   |   Cycle through no image label, image label,
                      label with ticks drawn across the image
| SET REF RANGE   |   Set pixel range of reference image
| SET SPEC RANGE  |   Set pixel range of spectrum plot
| SET CUBE RANGE  |   Set pixel range of cube images.
| CURVALUE        |   Display intensity under the cursor in any of
                      the images displayed
|                 |
| ROAM            |   Interactively select the planes to be displayed
| SET WINDOW      |   Select a sub-image for more detailed viewing
| RESET WINDOW    |   Return to viewing full image
| ROTATE          |   Enter rotation angle, rotate images
| TV ROTATE       |   Mark slice on ref image, rotate images
| RELOAD IMAGES   |   Reread the images from disk
|                 |
| EXIT            |   Exit the task
-------------------
