; TVHUI
;---------------------------------------------------------------
;! make TV image from images of intensity, hue, saturation
;# Task TV
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2002-2003
;;  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
;-----------------------------------------------------------------------
TVHUI     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
TVHUI:  Make TV image from images of intensity, hue, saturation
USERID     -32000.0     32000.0    User ID. 0 => current user,
                                     32000 => any user.
INNAME                             Intensity image name
INCLASS                            Intensity image class
INSEQ           0.0      9999.0    Intensity image seq. #
INDISK                             Intensity disk drive #
IN2NAME                            Hue image name
IN2CLASS                           Hue image class
IN2SEQ          0.0      9999.0    Hue image seq. #
IN2DISK                            Hue image disk drive #
IN3NAME                            Saturation image name
IN3CLASS                           Saturation image class
IN3SEQ          0.0      9999.0    Saturation image seq. #
IN3DISK                            Saturation image disk drive #
DOOUTPUT       -1.0         1.0    > 0 => write RGB output cube
OUTNAME                            Output RGB cube name
OUTCLASS                           Output RGB cube class
OUTSEQ          0.0      9999.0    Output RGB cube sequence #
                                     0 => highest unique
OUTDISK                            Output RGB cube disk drive #
                                     0 => highest with space
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!
TXINC           0.0      1000.0    Increment in pixels on X axis
TYINC           0.0      1000.0    Increment in pixels on y axis
DOALIGN        -2.0         1.0    > 0 => images must line up
                                      (see HELP DOALIGN)
TVCHAN          0.0        15.0    TV channel to use
OPTYPE                             'LUT' else 'S=1' method used
DOWEDGE        -1.0         3.0    > 0 => plot a wedge on top.
                                   > 1.5 => wedge on right edge
                                   > 2.5 => both wedges
DOCIRCLE       -1.0         1.0    > 0 => plot hues through a
                                   full circle, else only blue
                                   through red.
PIXRANGE                           Min,Max of image intensity
                                     0 => entire range.
DPARM                              (1,2) pixrange for hue image
                                   (3,4) pixrange for saturation
                                   (5) ratio # intensity / # hue
                                      levels.  0 -> 1.5
                                   (6) # saturation levels 3 - 4
                                   (7) # total pixels to use in
                                      subimage <= 86000.
                                   (8) use 1-channel method even
                                      on TVs capable of full RGB
                                   (9) > 0 => include wedges in
                                      optimizations
----------------------------------------------------------------
TVHUI
Type: Task
Use:  TVHUI will construct a TV image based on two or three AIPS
      images, one representing intensity, one representing hue, and,
      optionally, one representing saturation.  Two methods of
      converting HSI to RGB are offered.  The program then enters an
      interactive mode in which the user selects options from a menu
      shown on a graphics overlay plane.  Options are to enhance each
      of the images individually , to select logarithmic or linear
      transfer functions for intensity, to select the window
      specifying the sub-image which is used during interactive
      enhancements, to repaint the full image on the TV with a simple
      color scheme or an optimized scheme, and to exit with or without
      final updates and an output file. On-line help for the options
      is available by positioning the cursor to the option and pushing
      button D.  Pushing buttons A, B, or C selects the option.

      Note that this task was constructed in part to deal with
      pseudo-color displays incapable of true 3 color functions.  It
      has the concept of working on a smaller sub-image to enhance the
      coloring and then repainting the full image.  It does a look-up
      table optimized to represent the full colors in the image using
      the limited pseudo-color table available.  On those displays
      which do true color in 3 separate image memories, TVHUI can do a
      much better job representing the image in its full colors.
      Nonetheless, it may be slow because the RGB images must be
      computed at each change and re-loaded to the TV.  This slowness
      takes some adjustment on the users' part - be patient, the
      results are worth it.
Adverbs:
  USERID......The ID of the owner of the image.  0 => current
              user.  32000 => any user.
  INNAME......Image name for intensity.    Standard defaults.
  INCLASS.....Image class for intensity.   Standard defaults.
  INSEQ.......Image seq. # for intensity.  0 => highest.
  INDISK......Disk unit # for intensity.   0 => any.
  IN2NAME.....Image name for hue.          Standard defaults.
  IN2CLASS....Image class for hue.         Standard defaults.
  IN2SEQ......Image seq. # for hue.        0 => highest.
  IN2DISK.....Disk unit # for hue.         0 => any.
     If any of 3rd name non-blank/zero, then do saturation
  IN3NAME.....Image name for saturation.   Standard defaults.
  IN3CLASS....Image class for saturation.  Standard defaults.
  IN3SEQ......Image seq. # for saturation. 0 => highest.
  IN3DISK.....Disk unit # for saturation.  0 => any.
  DOOUTPUT....> 0 => write an output image with the 3rd axis being
              RGB.  The full range of input intensities are carried
              along (i.e. PIXRANGE is ignored in this phase).  The
              display intensity transfer function is also ignored.
              However, the scaling and clipping of the hue and
              saturation images done from DPARM(1,2) plus any
              interactive enhancement is used to set the color
              translation.  <= 0 -> skip output file.
              The full size of the input images is used for the output
              and the pixel increments are ignored.
              The effective PIXRANGE of the final display for each of
              the images is shown.  Use the one shown for Intensity
              when you TVLOD the output RGB cube to get the same
              display you saw inside TVHUI.
  OUTNAME.....Output name for RGB cube.     Standard defaults.
  OUTCLASS....Output class for RGB cube.    Standard defaults.
  OUTSEQ......Output seq. # for RGB cube.   0 => highest unique
  OUTDISK.....Disk drive # of RGB cube.     0 => highest with
              space.
  TBLC........Bottom Left Corner of intensity image.  (0,0) means
              (1,1).  The hue image window is the same size as the
              intensity image window, but a smaller window will be
              selected if needed to overlap the images.  See DOALIGN.
              The image size is also limited by the size of the TV.
              TBLC is ignored on writing the output image except for
              any alignment adjustments.
  TTRC........Top Right Corner of grey-scale image: (0,0) means top
              right corner of map.  NOTE: for the intensity image
              TTRC(3-7) is set to TBLC(3-7) since only one plane is
              shown.  If the hue image is a cube, TTRC(3) is taken to
              select the plane of that cube to be used for hue.  This
              allows a hue image of one plane to color am intensity
              image of another plane of the same cube.  TTRC is
              ignored on writing the output image except for any
              alignment adjustments.
  TXINC.......Increment in pixels between displayed pixels along
              the X axis.  0 => 1.  Ignored while doing output.
  TYINC.......Increment in pixels between displayed pixels along
              the X axis.  0 => 1.  Ignored while doing output.
  DOALIGN.....Controls how the intensity, hue, and saturation images
              are to be aligned (see HELP DOALIGN).  True (>.1) means
              that the images must agree in their coordinates, though
              not necessarily in the reference pixel position.
              Alignment is by coordinate values (if DOALIGN > -0.1) or
              by offsets from the reference pixel positions (if
              DOALIGN <= -0.1).  If DOALIGN < -1.5, alignment is at
              pixels (1,1,...) ignoring the headers.
  TVCHAN......TV channel to use: 0 => 1.  Two channels are used,
              TVCHAN for the unoptimized picture and TVCHAN+1 for the
              optimized picture.  Optimization is not available in
              TVHUI when there is only 1 channel; use DOOUT = 1 and
              task TVRGB.  Three channels are used on true-color TVs.
  OPTYPE......Determines algorithm used:
              'LUT' TVHUEINT verb method.
              Otherwise, Gonzales and Woods, p 236 with S = 1 or
              S determined by the saturation image.
  DOWEDGE.....If false (<= 0.0), do not plot a step wedge.  If
              If 1.5 >= DOWEDGE > 0.0, then plot a wedge along the top
              of the image.  If > 1.5, plot a wedge along the
              right-hand edge of the image.  If > 2.5, plot wedges
              along both the top and the right-hand side.  Each wedge
              is a wedge in intensity along the longer side of the
              wedge and in hue along the shorter side of the wedge.
              Multiple wedges are drawn for each saturation level.
  DOCIRCLE....False (<= 0) means that colors range from red to green
              to blue only.  This is appropriate for 0th and 1st
              moment images for example.  True means that colors range
              from red to green to blue and back to red (through
              purple).  This is appropriate to polarization intensity
              and angle images, for example.
  PIXRANGE....Min,Max of Image intensity.  0 => entire range
  DPARM.......(1,2) pixrange for HUE image.  0,0 => full range
              (3,4) pixrange for saturation image.  0,0 => full range.
              (5) The ratio of the number of intensity levels to the
                 number of hue levels.  Allowed values 1.0 - 2.5..
                 default 1.5.  The number of grey levels is divided
                 into Nint * Nhue <= Ngrey levels and the lookup table
                 is set to translate these intensities and hues to
                 RGB.
              (6) Number of saturation levels to use.  Default is 3
                 and only 3 or 4 is allowed.
              (7) Maximum number of pixels in the interactive
                 sub-image.  0 => 86000, the upper limit.
                 Interactivity is with a sub-image of the displayed
                 image.  Initially, this is taken as a decimated
                 sub-image.  Interactively, one may specify a smaller
                 area with correspondingly less extreme decimation.
                 DPARM(7) is used to speed interactivity by giving up
                 display area.
              (8) Some TV devices (e.g. IIS Model 70 and XAS on some
                 computers) can display 3 separate images in separate
                 colors.  TVHUI will use this where possible unless
                 DPARM(6) > 0, in which case it uses its "standard"
                 1-channel methods.
              (9) > 0 => to include the step wedges when optimizing
                 colors.  If one does, then the wedge will be seen
                 fully but the presence of all colors in the wedge
                 will probably degrade the optimization of the images.
                 If one does not, (<= 0) then those colors in the
                 wedges which are not present in the images will
                 appear black in the display.  This is distracting but
                 very informative.
              (10) not used yet
----------------------------------------------------------------

