; GREYS
;---------------------------------------------------------------
;! plots images as contours over multi-level grey
;# TASK PLOT
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2002-2004, 2006, 2008, 2011-2012
;;  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
;-----------------------------------------------------------------------
GREYS     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
GREYS:  Task to do  grey-scale plot with optional contours.
DOCONT         -1.0         1.0    > 0 => do contours
DOCOLOR        -1.0         1.0    Plot image(s) as true color
INNAME                             Grey scale image name
INCLASS                            Grey scale image class
INSEQ           0.0      9999.0    Grey scale image seq. #
INDISK                             Grey scale disk drive #
IN2NAME                            Contour image name
IN2CLASS                           Contour image class
IN2SEQ          0.0      9999.0    Contour image seq. #
IN2DISK                            Contour image disk drive #
IN3NAME                            Green image name
IN3CLASS                           Green image class
IN3SEQ          0.0      9999.0    Green image seq. #
IN3DISK                            Green image disk drive #
IN4NAME                            Blue image name
IN4CLASS                           Blue image class
IN4SEQ          0.0      9999.0    Blue image seq. #
IN4DISK                            Blue image disk drive #
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!
XYRATIO         0.0        10.0    X to Y axis plot ratio. 0 =>
                                   header inc or window ratio.
PIXRANGE                           Min,Max of image intensity
                                     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
APARM                              1,2 pixrange of green image
                                   3,4 pixrange of red image
                                   5 FUNCTYPE code number green
                                   6 FUNCTYPE code number red
LTYPE         -10.0        10.0    Type of labeling: 1 border,
                                   2 no ticks, 3 standard, 4 rel
                                   to center, 5 rel to subim cen
                                   6 pixels, 7-10 as 3-6 with
                                   only tick labels
                                   <0 -> no date/time
DOALIGN        -2.0         1.0    > 0 => images must line up
                                      (see HELP DOALIGN)
PLEV          -99.0       100.0    Percent of peak for levs.
CLEV                               Absolute value for levs
                                      (used only if PLEV = 0).
LEVS        -9999.0     99999.0    Contour levels (up to 30).
DOWEDGE        -1.0         4.0    > 0 => plot a wedge also.
                                   = 2 => put on the right edge.
                                   = 3 => put on top using full
                                          range of image values
                                   = 4 => put on right w full
                                          range of image values
DOCIRCLE       -1.0         1.0    > 0 => extend ticks to form
                                   coordinate grid
STVERS         -1.0     46655.0    STar file version number.
STFACTOR    -9999.0      9999.0    Scale star sizes: 0 => none.
                                   > 0 crosses with no labels
                                   < 0 crosses with labels
CBPLOT        -20.0        20.0    Position for beam plot:
                                     0: don't plot beam
                                     1: lower left (default)
                                     2: lower right
                                     3: upper right
                                     4: upper left
                                     5: plot in separate pane
                                     6-10 as 1-5 but filled in
                                    11-15 as 1-5 more filled
                                    16-20 as 1-5 scribbled on
                                    -n < 0 => n, but no other
                                       drawing in beam-plot area
IN2VERS         0.0       999.0    Start slice to overlay
IN3VERS         0.0       999.0    End slice to overlay
NBOXES          0.0        50.0    Number of boxes to overlay
CLBOX                              Boxes to overlay
DOTV           -1.0         1.0    > 0 Do plot on the TV, else
                                   make a plot file
GRCHAN          0.0         8.0    Graphics channel 0 => 1.
TVCHAN          0.0        16.0    Grey-scale display channel
DODARK         -1.0         1.0    Plot dark vectors as black?
DARKLINE        0.0         1.0    Switch to dark lines when
                                   grey-scale > DARKLINE 0-1
TVCORN          0.0      2048.0    TV pixel location of bottom
                                   left corner of image
                                   0 => centered
OFMFILE
                                   ' ' => do black & white
                                   'TV' => use TV OFM
                                   else read file for OFM
INFILE
                                   Holography layout/bolts files
----------------------------------------------------------------
GREYS
Type: Task
Use:  GREYS will write commands to a plot file for the execution of a
      grey-scale plot for an image.  Optionally a second image can be
      represented as contours superimposed on the grey scale.  The
      images are assumed to be of type MA.  Optionally, the locations
      of slices (taken from SLICE files) and windows (given by
      CLBOXes) may be overlaid.
Adverbs:
  DOCONT......IF > 0 requests that contour overlays be done.  At least
              one of IN2NAME, IN2CLASS, IN2SEQ, and IN2DISK must also
              be specified.
  DOCOLOR.....If > 0, do a true-color picture using INNAME if it is an
              RGB cube to give all three colors or using INNAME,
              IN3NAME, and IN4NAME as the red, green, and blue images
              respectively.  RGB cubes are made by RGBMP, TVHUI, MCUBE
              (with PUTHEAD), and LAYER.  If <= 0, take one plane of
              INNAME as a grey-scale image.
  INNAME......Image name for grey scale.    Standard defaults.
  INCLASS.....Image class for grey scale.   Standard defaults.
  INSEQ.......Image seq. # for grey scale.  0 => highest.
  INDISK......Disk unit # for grey scale.   0 => any.
        Optional contour image: may be same image as grey scale
        All blank or DOCONT <= 0. -> no contours
  IN2NAME.....Image name for contours.      Standard defaults.
  IN2CLASS....Image class for contours.     Standard defaults.
  IN2SEQ......Image seq. # for contours.    0 => highest.
  IN2DISK.....Disk unit # for contours.     0 => any.
        Optional green and blue images.  They are used only if DOCOLOR
        > 0 and the INNAME file does not have RGB as its third axis.
  IN3NAME.....Image name for green.         Standard defaults.
  IN3CLASS....Image class for green.        Standard defaults.
  IN3SEQ......Image seq. # for green.       0 => highest.
  IN3DISK.....Disk unit # for green.        0 => any.
  IN4NAME.....Image name for blue.          Standard defaults.
  IN4CLASS....Image class for blue.         Standard defaults.
  IN4SEQ......Image seq. # for blue         0 => highest.
  IN4DISK.....Disk unit # for blue.         0 => any.
  BLC.........Bottom Left Corner of grey-scale image  (0,0) means
              (1,1).  The contour image window is the same size as the
              grey image window, but a smaller window will be selected
              if needed to overlap the images.  See DOALIGN.
  TRC.........Top Right Corner of grey-scale image: (0,0) means top
              right corner of map.  NOTE: for the grey-scale image
              TRC(3-7) is set to BLC(3-7) since only one plane is
              shown.  If the contour image is a cube, TRC(3) is taken
              to select the plane of that cube to be used for
              contouring.  This allows a contour image of one plane to
              overlay a grey image of anther plane of the same cube.
  XYRATIO.....The ratio of the X-axis to Y-axis pixel separations.
              0  => use ratio of axis increments or Y to X windows
  PIXRANGE....Min,Max of Image intensity.  0 => entire range
  FUNCTYPE....Image intensity transfer function
              'LN' => linear = 1;
              'LG' => log = 2;
              'L2' => extreme log = 3;
              'SQ' => square root = 4;
              'NE' => negative linear = 5.
              'NG' => negative log = 6;
              'N2' => negative extra log = 7;
              'NQ' => negative square root = 8;
              others => linear.
  APARM.......(1,2) PIXRANGE for green image 0 -> green image entire
                    range.  Can also be used for green pixrange when
                    plotting an RGB image - default is PIXRANGE.
              (3,4) PIXRANGE for blue image 0 -> blue image entire
                    range.  Can also be used for blue pixrange when
                    plotting an RGB image - default is PIXRANGE.
              (5) code number for FUNCTYPE of green image;
                  0 -> FUNCTYPE
              (6) code number for FUNCTYPE of blue image;
                  0 -> FUNCTYPE
              These are used when building an RGB truecolor image from
              three independent images with DOCOLOR > 0.
  LTYPE.......Labelling type: 1 = border, 2 = no ticks, 3 or 7 =
              standard, 4 or 8 = relative to ref. pixel, 5 or 9 =
              relative to subimage (BLC, TRC) center, 6 or 10 =
              pixels.  7-10 all labels other than tick numbers and
              axis type are omitted.  Less than 0 is the same except
              that the plot file version number and create time are
              omitted.
  DOALIGN.....Controls how the grey and contour 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, alignement is at pixels
              (1,1,...) ignoring the headers.
  PLEV........Percent of peak for the contour increment.  If PLEV and
              CLEV are zero, 10 is used.
  CLEV........Image intensity value for the contour increment.
              Used only if PLEV = 0.
  LEVS........Contour levels in units of the increment.  The levels
              must be in ascending order and a maximum of 30 levels
              are permitted.     0 => -10,-9,-8,-7,-6,-5,-4,-3,-2,-1,
              1,2,3,4,5,6,7,8,9,10,0
  DOWEDGE.....If false (<= 0.0), do not plot a step wedge.  If 1.5 >=
              DOWEDGE > 0.0, then plot a wedge along the top of the
              image using PIXRANGE range of values.  If between 1.5 and
              2.5, plot a wedge along the right-hand edge of the image
              using PIXRANGE range of image values.  If between 2.5 and
              3.5, plot a wedge along the top with the full range of
              image values.  If between 3.5 and 4.5, plot a wedge along
              the right hand edge with the full range of image values.
              If LTYPE >= 3, ticks and tick labels are drawn for the
              wedge.  In true-color plots, the labeling is done for
              the red image.  DOWEDGE=3 or 4 is recommended in that
              case.
  DOCIRCLE....False (<= 0) means that tick marks are short lines
              extending inward from the plot borders.  True (>0)
              requests that a full coordinate grid be drawn.
  INVERS......Version number of ST (star position) file to be
              used to plot star positions as plus signs.
              0 => highest, < 0 => no star positions plotted
  STFACTOR....Scale factor used to multiply star sizes in file
              for plotting. = 0 => don't plot stars, < 0 also
              plot any labels.
  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
                  5: plots the beam in a separate pane
                  6 - 10: as 1-5 but slightly filled in
                 11 - 15: as 1-5 more filled in
                 16 - 20: as 1-5 scribbled over
              CBPLOT = -n  < 0 => use CBPLOT=n but do not plot any
              contours, grey scale, or vectors in the Clean Beam area.
  IN2VERS.....Start slice file version to overlay location
  IN3VERS.....End slice file version to overlay location
  NBOXES......Number of boxes to overlay
  CLBOX.......Boxes to overlay
  DOTV........> 0 => plot directly on the TV device, otherwise
              make a plot file for later display on one or
              more devices (including the TV if desired).
  GRCHAN......Graphics channel (1 - 7) to use for line drawing.
              0 => use multiple graphics planes for the various parts
              of the graphical drawing.
  TVCHAN......TV channel to display gray-scale portion of plot.
              0 -> 1.
  DODARK......When plotting on the TV (only), DODARK controls whether
              contours, polarization lines, and stars are drawn as
              black overlay lines when the grey-scale image is bright
              (>0) or in the same color as used for the lines when the
              image is not bright (<= 0).
  DARKLINE....When the grey-scale image after FUNCTYPE and other
              scaling (values 0 to 1) is > DARKLINE, dark lines are
              used to draw polarization lines, stars, and contours.
              <= 0, > 1 => 0.33.
  TVCORN......TV pixel location (X,Y) where the bottom left corner of
              the plot is to be placed. If either is zero, center the
              plot.  Pixel scaling is always used in GREYS.
  OFMFILE.....' ' => plot in black and white
              'TV' => read the TV OFM (before initializing it)
              other => read a text file giving the OFM to use (as in
              OFMDIR, OFMGET, OFMLIST, OFMSAVE).
              OFMFILE may be of the form 'Logical:File' where Logical
              is an logical (environment) name for a directory and
              File is a file name.  It may also be of the form
              'Stdfile' which is either a file $OFMFIL/Stdfile.uuu
              where uuu is the login user number or a file
              $AIPSOFM/Stdfile.001 in the OFM area distributed with
              AIPS.  Use verb OFMDIR to show what is available in the
              AIPSOFM and OFMFIL directories.  There is a web site
                 http://www.nro.nao.ac.jp/~sawada/aipscb/
              with color images of all standard AIPS OFMFILEs.
  INFILE......If not blank, look for text files of name INFILE.layout
              and INFILE.bolts to generate a line type 4 overplot
              showing the panel and bolt configuration.  The panel
              layout file has format
                 n              ! card 1 gives number of circles
                 j   Rin   Rout ! n cards give number panels and their
                                  inner and outer radii in units of
                                  image
              any number of cards may follow and are ignored.  The
              bolts file has format
                 n  r           ! card 1 gives number of bolt circles
                                  and size of x mark
                 R  j  Theta0   ! n cards give bolt radius, number of
                                  bolts and starting angle (CW, 0 up)
              any number of cards may follow and are ignored.  The
              number of values shown above are read with free format
              and anything following on the card is ignored.  Values
              must be separated by blanks not TAB characters.
----------------------------------------------------------------

