; PCNTR
;---------------------------------------------------------------
;! Generate plot file with contours plus polarization vectors
;# TASK PLOT TV POLARIZATION
;-----------------------------------------------------------------------
;;  Copyright (C) 1995-1996, 2002-2004, 2006, 2008-2009, 2011
;;  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
;-----------------------------------------------------------------------
PCNTR     LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
PCNTR:  Task to generate plot file for contour plus pol. vectors
DOCONT         -1.0         4.0    Draw contours? select image
DOVECT         -1.0         1.0    Draw pol. vectors? > 0 => yes
DOGREY         -1.0         4.0    Select grey-scale image?
USERID     -32000.0     32000.0    Image owner ID number ingored
                                   Total intensity image:
INNAME                               Image name (name)
INCLASS                              Image name (class)
INSEQ           0.0      9999.0      Image name (seq. #)
INDISK          0.0         9.0      Disk unit #
                                   Polarization intensity image:
IN2NAME                              (name) blank => INNAME
IN2CLASS                             (class) blank => 'PPOL'
IN2SEQ          0.0      9999.0      (seq. #) 0 => high
IN2DISK         0.0         9.0      Disk drive #, 0 => any
                                   Polarization angle image:
IN3NAME                              (name) blank => INNAME
IN3CLASS                             (class) blank => 'PANG'
IN3SEQ          0.0      9999.0      (seq. #) 0 => high
IN3DISK         0.0         9.0      Disk drive #,  0 => any
                                   Fourth image if needed
IN4NAME                              (name) blank => INNAME
IN4CLASS                             (class) blank => any
IN4SEQ          0.0      9999.0      (seq. #) 0 => high
IN4DISK         0.0         9.0      Disk drive #,  0 => any
BLC             0.0      4096.0    Bottom left corner of images
TRC             0.0      4096.0    Top right corner of images
CON3COL        -1.0                > 0 => overplot contours in
                                   color of multiple planes
                                   ZINC is CON3COL.
                                   See help for more.
XYRATIO         0.0        10.0    X to Y axis plot ratio. 0=>
                                   header inc or window ratio.
LTYPE         -30.0        30.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
                                   special values for RGBLEVS
PLEV          -99.9       100.0    Percent of peak for levs.
CLEV                               Absolute value for levs
                                     (used only if PLEV = 0).
                                     CLEV=PLEV=0 => PLEV=10
LEVS        -9999.0     99999.0    Contour levels (up to 30).
FACTOR          0.0    999999.9    Mult. factor for Pol vector
                                      (see HELP)
ROTATE                             Angle to rotate Pol vector
                                      (in degrees)
XINC            0.0        99.0    X-inc. of Pol vectors. 0=>1
YINC            0.0        99.0    Y-inc. of Pol vectors. 0=>1
PCUT                               Pol. vector cutoff. P units.
ICUT                               Int. vector cutoff. I units.
POL3COL        -1.0       180.0    Color polarization vectors
                                   value in degrees = red
DOALIGN        -2.0         1.0    Maps must align? > 0 => yes
                                   See HELP DOALIGN!
DOCIRCLE       -1.0         1.0    > 0 => extend ticks to form
                                   coordinate grid
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
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
OFMFILE
                                   ' ' => do black & white
                                   'TV' => use TV OFM
                                   else read file for OFM
DOCOLOR        -1.0         1.0    Plot RGB images as true color
STVERS          0.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
                                     6-9 : fill in a little
                                    11-14: more filled
                                    16-19: even more
                                    -n < 0 => n, but no other
                                       drawing in beam-plot area
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
RGBLEVS         0.0         1.0    Color each value of LEVS
TVCORN          0.0      2048.0    TV pixel location of bottom
                                   left corner of image 0=> self
                                   scale, non 0 => pixel scale.
----------------------------------------------------------------
PCNTR
Type: Task
Use:  PCNTR will write commands to a plot file for the execution
      of a grey-scale and/or contour plot and/or line vectors
      associated with a linear polarization image.  If DOCONT= 1 and
      DOVECT = -1, this task will do only a contour plot and is
      identical to task CNTR.  PCNTR now handles I-Pol-Angle sets of
      images, I-Q-U sets of images, or an image cube with IQU on the
      third axis.
      PCNTR supports TELL operations QUIT and ABOR only.
Adverbs:
  DOCONT......Should contours be plotted?  <= 0 => no, 1 - 4 selects
              which of the name sets will be contoured.
  DOVECT......Should line vectors whose lengths are associated
              with IN2NAME, etc; and whose orientations are
              associated with IN3NAME, etc. be derived.
              > 0 => yes
  DOGREY......Should a grey-scale, pseudo-color, or true-color image
              also be displayed?  <= 0 => no.  1 - 4 selects one of
              the 4 name sets for this display.
  USERID......The ID of the owner of the image.  Ignored.
  **** Main image - defines the I polarization for limiting the
  plotting of vectors and is the image to which the plot file is
  attached and which supplies the ST file if used.  It may be used for
  contouring if DOCONT=1 or grey scale if DOGREY=1.  If image 1 is a
  Stokes cubes with (at least) planes for I, Q, and U.  then the I
  plane is used for clipping and is contoured (DOCONT=1) or imaged
  (DOGREY=1), the Q and U converted to polarization and angle, and
  files 2 and 3 (below) ignored (for polarization vectors).  The
  contour image may be a non-polarization data cube with more than one
  plane plotted if CON3COL is set.  If DOCONT > 0 and CON3COL > 0,
  then the planes are separately colored contours.  If DOCONT <= 0 but
  DOVECT > 0 and CON3COL > 0, then the polarization planes will be
  colored by plane number.  Each polarization plane is blanked by the
  corresponding plane in the first image.
  INNAME......Image name (name).  Standard defaults.
  INCLASS.....Image name (class). Standard defaults.
  INSEQ.......Image name (seq. #). 0 => highest.
  INDISK......Disk unit #.  0 => any.
  **** Image to set the length of vectors.  Called the P image, it can
  really be of anything.  If its is an image plane of Stokes Q, it
  will be compbined with the third image of Stokes U to make
  polarization and angle images to be drawn.
  IN2NAME.....Image name (name). Standard behavior except all
              blank => use actual INNAME.
  IN2CLASS....Image name (class).  Standard behavior except all
              blank => use 'PPOL'
  IN2SEQ......Image name (seq. #).  0 => highest.
  IN2DISK.....Disk unit #.    0 => any.
              Image to set angles of vectors (or U image plane).
  IN3NAME.....Image name (name).  Standard behavior except all
              blank => use actual INNAME.
  IN3CLASS....Image name (class).  Standard behavior except all
              blank => use 'PANG'
  IN3SEQ......Image name (seq. #) associated with pol. ang.
              0 => highest.
  IN3DISK.....Disk unit #.   0 => any.
  **** Fourth image used when DOGREY = 4 or DOCONT = 4.
  IN4NAME.....Image name (name).  Standard behavior except all
              blank => use INNAME
  IN4CLASS....Image name (class).  Standard behavior except all
              blank => any
  IN4SEQ......Image name (seq. #) associated with pol. ang.
              0 => highest.
  IN4DISK.....Disk unit #.   0 => any.
  BLC.........Bottom Left Corner of image to contour. 0 -> 1.
              Images 2, 3, 4 use same size window, but a smaller
              window will be selected if needed to overlap the
              images.  See DOALIGN.
  TRC.........Top Right Corner of image to contour.
              (0,0) means top right hand corner of map.
              Normally, TRC(3-7) is set = BLC(3-7).  But, if CON3COL
              is > 0, then planes BLC(3) to TRC(3) by CON3COL will be
              plotted on top of each other in multiple colors.
              When DOCONT <= 0 and CON3COL > 0, multiple planes of the
              polarization vectors are separately colored.  If DOCONT
              > 0, then only the first plane of polarization is
              plotted and multiple planes of contours are plotted.
  CON3COL.....> 0 => plot multiple planes in color - see TRC above.
  XYRATIO.....The ratio of the X-axis to Y-axis pixel separation.
              0 => X to Y inc. in map header if related, else Y to X
              window ratio.
  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.
              When using RGBLEVS, LTYPE also controls whether a line
              in color appears in the plot at the bottom, the top, or
              not at all.  Values of LTYPE=-10 to 10 give a line
              inside the contour plot at the bottom; values from -20
              to -11 and 11 to 20 give the line inside the plot at the
              top, and values -30 to -21 and 21 to 30 omit the color
              listing of the LEVS. The units digit retains the same
              meaning for this extended range of LTYPE.
  PLEV........Percent of peak for the contour increment.  If CLEV and
              PLEV are both zero PLEV is set to 10.
  CLEV........Image intensity value for the contour increment.
              Used only if PLEV is zero.
  LEVS........Contour levels in units of the increment.  The levels
              must be in ascending order and a maximum  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
  FACTOR......Multiplication factor for polarization vectors.  A
              vector of 0.5 in the units of the P image (i.e. Jy/beam)
              will be this many pixel separations long.  Note that
              this may require rather large FACTORs to plot lines of a
              significant length for values of P around, say, a
              mJy/beam.              0 => 1.0
  ROTATE......Angle to rotate position angle vector in degrees.  This
              rotation is applied to all polarization vectors drawn.
  XINC........Separate pol. vectors in X by XINC pixels. 0 => 1
  YINC........Separate pol. vectors in Y by YINC pixels. 0 => 1
  PCUT........Do not plot polarization vectors if less than PCUT
              in the units of the P image.  No default.
  ICUT........Do not plot polarization vectors if less than ICUT
              in the units of the I image.  No default.
  POL3COL.....<= 0.0 => draw polarization vectors with usual uncolored
                     bright vectors.
              > 0 => use subtle colors to represent polarization
                     angle.  The value selects the polarization angle
                     that is pure red (eps to 180 degrees).
  DOALIGN.....Controls how the 4 input 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
              the headers are ignored and alignment is at pixels
              (1,1,...).
  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.
  PIXRANGE....Min,Max of Image intensity.  0 => entire range
  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.
  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.
  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.  There
              is a web site
                 http://www.nro.nao.ac.jp/~sawada/aipscb/
              with color images of all standard AIPS OFMFILEs.
  DOCOLOR.....If the grey-scale image has its 3rd axis type = 'RGB',
              then it can be displayed as true color if DOCOLOR > 0.
              RGB cubes are made by RGBMP, TVHUI, MCUBE (with
              PUTHEAD), and, soon, LAYER.
  STVERS......Version number of ST (star position) file to be used to
              plot star positions.  0 => highest, < 0 => no star
              positions plotted.
  STFACTOR....Scale factor used to multiply star sizes in file
              for plotting. > 0 => scale star size
                            = 0 => don't plot stars.
                            < 0 => scale by abs(STFACTOR) and
                                   show any star label
  CBPLOT......Selects the corner in which the half-power beam
              plot is placed (Clean images only)
                 -1: no beam plot
                  0, 5 => 1; 10 => 6, 15 => 11, 20 => 16.
                  1: lower left
                  2: lower right
                  3: upper right
                  4: upper left
                  6 - 10: as 1-5 but slightly filled in
                 11 - 15: as 1-5 more filled in
                 16 - 20: as 1-5 scribbled over
  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......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).
              DODARK does not apply to color contours (RGBLEVS or
              CON3COL).
  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.
  RGBLEVS.....Colors to be assigned to each of the LEVS:
              RGBLEVS(1,i) red color (0-1) assigned to LEVS(i)
              RGBLEVS(2,i) green color (0-1) assigned to LEVS(i)
              RGBLEVS(3,i) blue color (0-1) assigned to LEVS(i)
              If all are 0, do not do this.  RUN SETRGBL will compile
              procedures CIRCLEVS, RAINLEVS, FLAMLEVS, and STEPLEVS to
              help you set these values.
  TVCORN......TV pixel location (X,Y) where the bottom left-
              corner of the plot is to be placed. If either is
              zero, use the largest possible self scaling, else
              use pixel scaling with specified origin on the TV.
----------------------------------------------------------------
PCNTR: Task to create contour and/or polarization plot file
DOCUMENTOR: J. J. Condon  NRAO/CV
RELATED PROGRAMS: CNTR; PRTPL, TKPL, TVPL, QMSPL, TVWIN

                     PURPOSE

     PCNTR generates a plot extension file containing an inten-
sity contour plot and/ or a polarization vector plot, along
with the associated border and labels.  Such a plot may be
displayed on a printer, TEK screen, or TV by the tasks PRTPL,
TEKPL, or TVPL, respectively.
     Contour plots are generally more useful for quantitative
image analysis than gray-scale or profile plots, and most maps
are published in the form of contour plots.  Contour plots can
easily display all features in an image with a very large
dynamic range.  They tend to emphasize gradients in intensity.
The contour plot of a complex image, especially one with local
minima, can be confusing; and the contour plot of a noisy map
will be messy if contours below about 3 sigma are plotted.
     PCNTR indicates positive and negative contour values
by continuous and broken lines, respectively.  Note that a
local but non-negative minimum will be indicated by a closed
continuous contour, so that it is indistinguishable from a
maximum.  Also, the simple interpolation routine used by PCNTR
may produce jagged "staircase" contours.  This problem can be
minimized by interpolating the plotted images with the task
GEOM.  Alternatively, final contour plots may be produced
outside of AIPS.
     PCNTR indicates linear polarization by lines whose lengths
are proportional to the linearly polarized intensity and whose
directions are parallel to the E-vector.  These can be computed
in advance from Q and U images by COMB (OPCODEs POLI and POLA)
or "on-the-fly" in PCNTR.

                     COMMENTS

BLC, TRC:
     A convenient way to select the plot corners is to display
the image on a TV and set the rectangular boundary of the
subimage to be plotted with the verb TVWIN.

LEVS:
     Nonzero elements LEVS(I) in this 30-element vector
specify the contour levels LEVS(I)*PLEV or LEVS(I)*CLEV to be
plotted.  They must be specified in increasing order and lie
within the range -9999.0 to +99999.0.  It is easy to specify a
large number of LEVS values with a FOR loop.  For example,
the statement FOR I=1 TO 20;LEVS(I)=2**((I-1)/2.);END;LEVS(21)=0
yields successive contours separated by factors of 2**.5

LTYPE:
     1=> unlabeled rectangular border
     2=> rectangular border plus labels (image name, center
         position, etc.). Beware that the PEAK FLUX label
         gives the peak flux in the whole image, not just in
         the subimage plotted.
     3=> rectangular border, labels, and border tick marks
         indicating absolute coordinates (r.a., decl., etc.)
     4=> rectangular border, labels, and border tick marks
         indicating coordinates relative to the coordinates
         of the image reference pixel
     5=> rectangular border, labels, and border tick marks
         indicating coordinates relative to the center of
         the subimage plotted
     6=> rectangular border, labels, and border tick marks
         indicating image pixel numbers
     7-10 => like 3-6 but the extra labels are omitted.
     An LTYPE which is < 0 is used, in absolute value, to
     control the labeling as listed above and specifies that
     the "PLOT FILE VERSION n CREATED date time" string is
     not placed on the plot.

XYRATIO:
     XYRATIO can be used to change the plot aspect ratio.
Values >1 stretch the X-axis, values <1 compress it.

STFACTOR:
     You can use STarFACTOR to add crosses or other symbols to
your plot to denote the postions of stars or other objects.
First you must read the postions into a ST table using STARS.
Then set INVER to the table version number.  You can scale the
sizes of the crosses be setting STFACTOR > 0.  Set STFACTOR to
1.0 for no scaling (use the star sizes in the ST table).  You
can label the crosses with a character string to help identify
them by setting STFACTOR < 0.  The label is the text string
entered when creating the ST table.  The star sizes in this case
will be scaled by ABS(STFACTOR).  Note that you can also rotate
the crosses through an angle by specifying a positon angle when
you create the ST table in STARS (see STARS for more
information).

EXECUTION TIMES:
     In an otherwise empty VAX 11/780 a simple plot takes
about 20 seconds and a large messy plot can take several
minutes.  If PCNTR seems to be taking longer than expected,
you may be plotting more contours than you expected, or
you may have chosen PCUT or ICUT too low.
