; CNTR
;---------------------------------------------------------------
;! generate a contour plot file or TV plot from an image
;# Task Plot TV
;-----------------------------------------------------------------------
;;  Copyright (C) 1995, 2002, 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
;-----------------------------------------------------------------------
CNTR      LLLLLLLLLLLLUUUUUUUUUUUU CCCCCCCCCCCCCCCCCCCCCCCCCCCCC
CNTR:  Task to generate a contour plot as TV image or plot file
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                             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         -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
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
INVERS          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
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.
----------------------------------------------------------------
CNTR
Type: Task
Use:  CNTR will write commands to a plot file for the execution
      of a contour plot for an image.  CNTR supports TELL
      operations QUIT and ABOR only.
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: 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.
  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.
  INVERS......Version number of ST (star position) file to be
              used to plot star positions as plus signs.
              0 => highest.
  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
  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.
----------------------------------------------------------------
CNTR: Task to create a contour-plot extension file for an image
RELATED PROGRAMS: PCNTR, KNTR, PRTPL, TKPL, TVPL, TVWIN

                           PURPOSE

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

                          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.

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

