; TVRGB
;---------------------------------------------------------------
;! make TV image from images of true color (RGB) images
;# Task TV
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-1996, 2003, 2006, 2009
;;  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
;-----------------------------------------------------------------------
TVRGB     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
TVRGB:  Task to make a TV image from true-color (RGB) image
INNAME                             RGB/red image name
INCLASS                            RGB/red image class
INSEQ           0.0      9999.0    RGB/red image seq. #
INDISK                             RGB/red disk drive #
IN2NAME                            Green image name IF needed
IN2CLASS                           Green image class
IN2SEQ          0.0      9999.0    Green image seq. #
IN2DISK                            Green image disk drive #
IN3NAME                            Blue image name IF needed
IN3CLASS                           Blue image class
IN3SEQ          0.0      9999.0    Blue image seq. #
IN3DISK                            Blue image disk drive #
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, 0 => 1
PIXRANGE                           Min,Max of red image display
                                       0 => entire range
DPARM                              (1,2) pixrange of green image
                                       default = PIXRANGE
                                   (3,4) pixrange for blue image
                                       default = PIXRANGE
                                   (5) # levels per R,G,B
                                       < 8 or > 40 => 32.
                                   (6) # pixels in subimage
                                       <= 86000.  0 => 86000.
                                   (7) # levels/r,g,b during
                                       interaction <= (5)
                                   (8) > 0 => use 1-channel
                                       method on TVs capable of
                                       full RGB
                                   (9) > 0 => do NOT place user
                                       number at bottom
DOOUTPUT       -1.          2.     > 0 => write RGB PostScript
                                   > 1.5 blanks -> white
BLC            0.0      4096.0     Bottom left corner of image
                                     0=>entire image
TRC            0.0      4096.0     Top right corner of image
                                     0=>entire image. See HELP!
OUTFILE
                                   Name of the output file.
                                    blank -> place in printer
                                             queue.
COPIES         0.0        50.0     Number of copies if going
                                   directly to a printer
RGBGAMMA        0.         10.     RGB Gamma corrections
REASON
                                   String to place at bottom
----------------------------------------------------------------
TVRGB
Type: Task
Use:  TVRGB will construct a TV image based on one AIPS image with an
      RGB axis, or three AIPS images representing red, green, and blue
      in that order.  On TV devices capable of displaying 3 images, one
      in each color, TVRGB simply uses this capability.  On those that
      can display only one image with pseudo-coloring, TVRGB first
      displays the image in a simple-minded coloring scheme and then
      uses a color optimization scheme.  The latter was adapted from
      ppmquant written and copyrighted (1989, 1991) by Jef Poskanzer.
      The program then enters an interactive mode in which the user
      selects options from a menu shown on a graphics overlay plane.
      Current options are to select the transfer function for each
      color, to enhance each of the images individually or all
      together, to select the window specifying the subimage which is
      used during interactive enhancements, to repaint the full image
      on the TV, and to exit.  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.

      When you are done and select EXIT rather than ABORT, the program
      will print (or save in a file) the resulting color image.  This is
      better than TVCPS because a full 24-bit image is saved rather than
      an 8-bit optimally pseudo-colored image.  DOOUTPUT must be true to
      select this option.
Adverbs:
  INNAME......Image name for RGB or red.    Standard defaults.
  INCLASS.....Image class for RGB or red.   Standard defaults.
  INSEQ.......Image seq. # for RGB or red.  0 => highest.
  INDISK......Disk unit # for RGB or red.   0 => any.
      Second and third image ignored if first has an RGB axis
  IN2NAME.....Image name for green.      Standard defaults.
  IN2CLASS....Image class for green.     Standard defaults.
  IN2SEQ......Image seq. # for green.    0 => highest.
  IN2DISK.....Disk unit # for green.     0 => any.
  IN3NAME.....Image name for blue.       Standard defaults.
  IN3CLASS....Image class for blue.      Standard defaults.
  IN3SEQ......Image seq. # for blue.     0 => highest.
  IN3DISK.....Disk unit # for blue.      0 => any.
  TBLC........Bottom Left Corner of RGB/red image  (0,0) means (1,1).
              The other image windows are the same size as the red 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.
  TTRC........Top Right Corner of red image: (0,0) means top right
              corner of map.  NOTE: for the red image TRC(3-7) is set to
              BLC(3-7) since only one plane is shown.  If the 2nd image
              is a cube, TRC(3) is taken to select the plane of that
              cube to be used for green.  This allows a green image of
              one plane to color a red image of another plane of the
              same cube.  Similarly, TRC(4) selects the blue plane.
  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 Y
              axis.  0 => 1.  Ignored while doing output.
  DOALIGN.....Controls how the red, green and blue 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.  Where possible, TVCHAN+1 is
              used for the interactive enhancement with sub-image.
  PIXRANGE....Min,Max of red intensity.  0 => entire range of 1st image.
              The PIXRANGEs are used to clip image intensities at all
              times.  No matter what scalings are chosen later,
              intensities outside the PIXRANGEs are unavailable.
  DPARM.......(1,2) pixrange for green image (even in RGB cube).
                    0,0 => actual PIXRANGE
              (3,4) pixrange for blue image (even in RGB cube).
                    0,0 => actual PIXRANGE
              (5) Number of levels used to evaluate R, G, and B for
                    optimizing.  The histogram is DPARM(5)**3 colors, so
                    smaller values should be faster but possibly less
                    pleasing.  DPARM(5) < 8 or > 40 => use 32.
              (6) Number of pixels in the sub-image used during
                    individual color enhancements; limit 86000.
                    < 860 => 86000.
              (7) Number of levels used to optimize during interactive
                    enhancement.  <= DPARM(5) = default.
              (8) > 0 => use 1-channel method even on TVs capable of
                    full 3-color displays.
              (9) > 0 => do not place user at bottom of picture.
              (10) not used yet
  DOOUTPUT....If true (> 0), write the final image (on EXIT but not
              ABORT) to a color PostScript printer or file.  If > 1.5,
              the black pixels from all 3 images blanked will be written
              as white (which is transparent on slides and transparency
              paper).  The image is actually read from disk to make
              the output file using BLC/TRC for corners and pixel
              increments of 1.
  BLC.........Bottom Left Corner of RGB/red image  (0,0) means (1,1).
              The other image windows are the same size as the red image
              window, but a smaller window will be selected if needed to
              overlap the images.  See DOALIGN.   The output image
              size is NOT limited by the size of the TV.  BLC(3-7) are
              set to TBLC(3-7).
  TRC.........Top Right Corner of red image: (0,0) means top right
              corner of map.  NOTE: for the red image TRC(3-7) is set to
              BLC(3-7) since only one plane is shown.  If the 2nd image
              is a cube, TRC(3) is taken to select the plane of that
              cube to be used for green.  This allows a green image of
              one plane to color a red image of another plane of the
              same cube.  Similarly, TRC(4) selects the blue plane.
              TRC(3-7) will be the same used for TTRC(3-7).
  OUTFILE.....The name of the PostScript file.  If this is left blank
              then the it is automatically placed in the current AIPS
              printer queue.  If a name is provided, the PostScript
              image file will be saved under this name and will not be
              placed in the printer queue.
  COPIES......Number of copies to print (0 => 1).  Set to 1 when OUTFILE
              is specified.
  RGBGAMMA...."Gamma" corrections to use for the red, green, and blue
              images.  RGBG(1) = 0 => use the TV gamma, RGBG(2) = 0 =>
              use RGBG(1), RGBG(3) = 0 => use RGBG(1).
  REASON......Text string to place at bottom of picture
----------------------------------------------------------------

