; CCNTR
;---------------------------------------------------------------
;! generate a contour plot file from an image
;# Task Plot
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 1999, 2002, 2009, 2011-2012, 2014
;;  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
;-----------------------------------------------------------------------
CCNTR      LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
CCNTR:  generate a contour plot with stars or fit sources marked
USERID     -32000.0     32000.0    User ID. ignored
INNAME                             Image name(name).
INCLASS                            Image name(class).
INSEQ           0.0      9999.0    Image name(seq. #). 0=>high
INDISK          0.0         9.0    Disk drive #. 0=>any
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
XYRATIO         0.0        10.0    X to Y axis plot ratio. 0=>
                                   header inc or window ratio
LTYPE        -410.0       410.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
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).
DOCIRCLE       -1.0         1.0    > 0 => extend ticks to form
                                   coordinate grid
INEXT                              'ST','CC','MF' to plot points
INVERS          0.0     46655.0    ST,CC,MF file version number
CTYPE           0.0                (1) Plot symbol # for CC, MF
                                   (2) Number components
                                   (3,4) Flux range for plot
                                   symbol range 0 - CTYPE(1)
CUTOFF                             Only plot CCs above this flux
FLUX            0.0                Scale CCs relative to FLUX
                                   0 -> no scaling
STFACTOR    -9999.0      9999.0    Scale star sizes: 0 => none.
                                   > 0 crosses with no labels
                                   < 0 crosses with labels
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.
TVCORN          0.0      2048.0    TV pixel location of bottom
                                   left corner of image 0=> self
                                   scale, non 0 => pixel scale.
----------------------------------------------------------------
CCNTR
Type: Task
Use:  CCNTR will write commands to a plot file for the execution of a
      contour plot for an image.  CCNTR supports TELL operations QUIT
      and ABOR only.  CCNTR is identical to CNTR, except that
      positions and sizes of ST, CC, or MF components can be plotted.
Adverbs:
  USERID......The ID of the owner of the image.  Ignored.
  INNAME......Image name (name).       Standard defaults.
  INCLASS.....Image name (class).      Standard defaults.
  INSEQ.......Image name (seq. #).     0 => highest.
  INDISK......Disk unit #.             0 => any.
  BLC.........Bottom Left Corner of image to contour.
              (0,0) means (1,1).
  TRC.........Top Right Corner of image to contour.
              (0,0) means top right corner of map.
  XYRATIO.....The ratio of the X-axis to Y-axis pixel
              separations. 0  =>  X to Y inc. in map header
              if related, else Y to X window
  LTYPE.......Labelling type, see HELP LTYPE for details:
              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.
              Add n * 100 to alter the metric scaling.
  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
  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.
  INEXT.......If 'CC' plot positions (and sizes if given) of
              clean components.  If 'ST' plot star positions
              as plus signs.  If 'MF' plot positions (and sizes
              if given) of model fit components.
  INVERS......Version number of CC, MF, or ST (star position).
              0 => highest.
  CTYPE.......(1) Plot symbol number to use when plotting CC
                  or MF points
              (2) Maximum number of CC or MF points to plot
              (3,4) If CTYPE(4) > CTYPE(3), then use plot
                  symbols 0 to CTYPE(1) over the component flux
                  range CTYPE(3) to CTYPE(4).  < CTYPE(3) use 0,
                  > CTYPE(4) use CTYPE(1).
              Types supported are
              0: Cross             10: Five pointed star
              1: Ellipse           11: Star of David
              2: Box               12: Seven pointed star
              3: Triangle          13: Eight pointed star
              4: Diamond           14: Nine  pointed star
              5: Pentagon          15: Ten   pointed star
              6: Hexagon           16: 11    pointed star
              7: Septagon          17: 12    pointed star
              8: Octagon           18: 13    pointed star
              9: Nine-gon          19: 14    pointed star
              20: Cross with gap   >20: Ellipse
  CUTOFF......Plot only components above cutoff Jy in absolute value.
  FLUX........If > 0, scale each plot symbol by the current value
              divided by FLUX and then multiply by STFACTOR.  Applies
              only to CCs.
  STFACTOR....Scale factor used to multiply star or component
              sizes in file for plotting.
                    > 0 => scale star size
                    = 0 => don't plot stars.
                    < 0 => scale by abs(STFACTOR) and show any
                           star label, component #.
  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.
  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.
----------------------------------------------------------------
CCNTR: Task to create a contour-plot extension file for an image
RELATED PROGRAMS: CNTR, KNTR, PCNTR, PRTPL, TKPL, TVPL, TVWIN

                           PURPOSE

     CCNTR generates a plot extension file containing an
intensity contour plot, its border, and labels.  The window
limits and contour levels are recorded in the header of the plot
file, and may be listed on your terminal with EXTLIST.  CCNTR
indicates positive and negative contour values by continuous and
broken lines, respectively.
     The plot itself may be displayed on a printer, TEK screen,
or TV graphics channel by the tasks PRTPL, TKPL, or TVPL
respectively.
     It differs from CNTR in the option to overplot symbols at
the location of components in the CC file.

                          COMMENTS

     Contour plots are often more useful for quantitative image
analysis than gray-scale or profile plots, and most maps are
published in the form of contour plots.  By suitable choice of
contour levels, a contour plot can give a quantitative display
of all features in an image with very large dynamic range.  The
contour plot of a map will be messy if contours are plotted at
levels below about 3 times the rms noise.
     Contour plots tend to emphasize gradients in intensity. The
contour plot of a complex image, especially one with local
minima, can therefore be confusing.  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 CNTR may produce jagged
"staircase" contours.  This problem can be minimized by
interpolating the image with the task GEOM.

BLC, TRC:
     A convenient way to select the plot corners is to display
the image on the 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
     If you request more than one negative level via a statement
of the form
        LEVS = a , b , c , d , e , f , g
you must use commas between the negative levels.  Otherwise, the
minus sign(s) will be treated as subtraction symbols by POPS and
the desired levels will be combined into a single negative
level.

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 that 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.

DISPLAYING THE PLOT:
     On termination of CNTR, the messiness of the plot can be
judged by looking at the message on your monitor:

     GFINIS:  NUMBER OF RECORDS GUESSED NNN    USED MMM

If MMM is much greater than 200, the plot will be complicated.
If this happens when you thought you were contouring a simple
small field, you have probably set the levels too low (or have
specified the contouring window incorrectly).  You may wish to
check your inputs before trying to display the plot.  It is
always worth using TKPL or TVPL to preview a new plot before
routing it to the slower PRTPL, unless you are very sure that
your input parameters were well chosen.

EXECUTION TIMES:
     In an otherwise empty VAX 11/780 a plot of 10 or so
contours in a 100 by 100 window with a straightforward source
takes about 20 seconds.  Large, messy, or noise-limited plots
may take many minutes.  If CNTR seems to be taking longer than
expected, you may be plotting more contours than you wanted.
