AIPS NRAO AIPS HELP file for KNTR in 31DEC18



As of Sun Jul 22 0:35:29 2018


KNTR: Task to generate a plot file for a contour & grey plot

INPUTS

DOCONT         -1.0         2.0    > 0 => do contours
                                   (1 or 2 => which name)
DOGREY         -1.0         2.0    > 0 => do grey scale
                                   (1 pr 2 => which name)
DOVECT         -1.0         2.0    > => do polarization vectors
                                   (1 or 2 => which is IPOL)
                                   Contour or grey or IPOL
INNAME                             First image name (cube?)
INCLASS                            First image class
INSEQ           0.0      9999.0    First image seq. #
INDISK                             First image disk drive #
                                   Contour or grey or IPOL
IN2NAME                            Second image name
IN2CLASS                           Second image class
IN2SEQ          0.0      9999.0    Second image seq. #
IN2DISK                            Second disk drive #
                                   Polarization intensity image:
IN3NAME                              (name) blank => INNAME
IN3CLASS                             (class) blank => 'PPOL'
IN3SEQ          0.0      9999.0      (seq. #) 0 => high
IN3DISK         0.0         9.0      Disk drive #,  0 => any
                                   Polarization angle image:
IN4NAME                              (name) blank => INNAME
IN4CLASS                             (class) blank => 'PANG'
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 first
                                   image.  0 => 1
TRC             0.0      4096.0    Top right corner of first
                                   image;   0=>entire image
                                   Multiple planes of a cube
                                   will be plotted in panels.
ZINC        -1024.0      1024.0    Increment on 3rd axis of
                                   1st and possibly 2nd image
NY              0.0        32.0    Number of planes along
                                   vertical side of plot
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
OFMFILE
                                   ' ' => do black & white
                                   'TV' => use TV OFM
                                   else read file for OFM
DOCOLOR        -1.0         1.0    Do RGB images as 3-color?
LTYPE        -430.0       430.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
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).
CON3COL        -1.0         1.0    Color the contours by plane
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
DOBLANK        -1.0         1.0    Draw boundary between blanked
                                   areas and good areas?
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
LABEL          -1.0         2.0    0->label each pane with the
                                      pane number
                                   1->label each with coordinate
                                   2->label each with coordinate
                                      relative to reference
                                   -1->do not label each pane
INFILE
                                   Holography layout pattern
                                   text file or VLA or VLBA
DOTV           -1.0         1.0    > 0 Do plot on the TV, else
                                   make a plot file
TVCHAN          0.0        15.0    TV channel for grey plots
GRCHAN          0.0         8.0    Graphics channel 0 => 1.
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.

HELP SECTION

KNTR
Type: Task
Use:  KNTR will write commands to a plot file for the execution of a
      contour and/or grey-scale plot for one or 2 images.  The contour
      and/or grey-scale images can either be a single plane which is
      repeated in each pane or a data cube that matches the other image
      cube on the third axis.  If one image is a cube and the other a
      plane, then the cube must be the first image if multiple planes
      are to be plotted.
      Truecolor images and pseudo-coloring are available as are
      polarization vectors.
      Suggestion: when running LWPLA on the output, consider LPEN=2 or 1
      rather than the default (3).  If multiple planes are plotted,
      fatter pens cause dashed contours to merge into solid ones.
      Note that KNTR writes comments into the plot file (and hence the
      PostScript file written by LWPLA) whenever beginning a new
      contour level.  You can use these comments to guide you if you
      wish to change the intensity/color of a particular contour
      level.  Note that KNTR follows the levels in 129x129 pixel
      blocks and so visits a particular level once for each block.
Adverbs:
  DOCONT......If > 0 requests that contour overlays be done using INNAME
              image.  If > 1.5, use IN2NAME as the contour image.
  DOGREY......If > 0 requests that grey-scale images be included in each
              panel as well.  If > 1.5, use IN2NAME as the grey-scale
              image.  Both DOCONT and DOGREY > 1.5 causes INNAME et al.
              to be replaced with IN2NAME et al.
  DOVECT......If > 0, requests that the polarization images in the
              third and fourth images be used to plot polarization
              vectors.  DOVECT has value 1 or 2 in this case to select
              which of the first two images will be used as the IPOL
              image for doing the cutoff represented by ICUT.  If the
              polarization images are cubes matching the cube in the
              first image, then the polarization vectors plotted will
              come from the matching planes through the cubes.

  **** First image is used as the image for (1) cataloging the PLot
  file, (2) providing the STars file, (3) setting the basic BLC/TRC
  including allowing multiple planes to be plotted, (4) plotting the
  contours and/or grey scales, (5) providing the I values for ICUT use
  in polarization vector plotting.  If the first image is not
  referenced it will be replaced by the second image which may not be
  a good idea.
  INNAME......First image name.      Standard defaults.
              First image must be a cube if multiple planes are desired.
  INCLASS.....First image class.     Standard defaults.
  INSEQ.......First image seq. #.    0 => highest.
  INDISK......First disk unit #.     0 => any.
  **** Used optionally for contours, grey-scales, or the ICUT image.
  IN2NAME.....Second image name.    Standard defaults. May be a plane or
              a cube.
  IN2CLASS....Second image class.   Standard defaults.
  IN2SEQ......Second image seq. #.  0 => highest.
  IN2DISK.....Second image disk #.   0 => any.
  **** Used optionally as the total polarization or Q image when
              DOVECT > 0.
  IN3NAME.....Image name (name).  Standard behavior except all
              blank => use actual name of IPOL image
  IN3CLASS....Image name (class).  Standard behavior except all
              blank => use 'PPOL'
  IN3SEQ......Image name (seq. #) associated with pol. ang.
              0 => highest.
  IN3DISK.....Disk unit #.   0 => any.
  **** Used optionally as the polarization angle or Q image when
              DOVECT > 0.
  IN4NAME.....Image name (name).  Standard behavior except all
              blank => use actual name of IPOL image
  IN4CLASS....Image name (class).  Standard behavior except all
              blank => use 'PANG'
  IN4SEQ......Image name (seq. #) associated with pol. ang.
              0 => highest.
  IN4DISK.....Disk unit #.   0 => any.

  BLC.........Bottom Left Corner of first image.  0 => 1.
              Taken to apply to whichever image is plotted if only one
              image is plotted
  TRC.........Top Right Corner of first image.  0 => max.
  ZINC........Increment on 3rd axis of first, and possibly second,
              image;  0 -> 1.  ZINC < 0 => use abs (ZINC) but from
              TRC(3) to BLC(3).
  NY..........Number of panes on vertical side of plot.  The number on
              the horizontal will then be chosen so that all planes are
              plotted.  0 -> SQRT (# planes) rounded up.
  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.
              Setting XYRATIO > 1 stretches the X-axis.
  PIXRANGE....Min,Max of Image intensity.  0 => entire range when
              plotting grey scales.
  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.
  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 OFMFIL and AIPSOFM directories.  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, LAYER.
  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.
              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.
  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, alignment is at pixels (1,1,...) ignoring
              the headers.  Note that alignment of cubes must be one all
              three significant axes.  If the second image has only one
              plane then the alignment is checked only on the first two
              axes.
  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
  CON3COL.....> 0 => use a range of colors to draw the contours when a
              range of image planes are drawn.  <= 0 => use usual
              uncolored vectors.
  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).
  DOBLANK.....A contour is drawn between areas of good pixels and areas
              of magic-valued (blanked) pixels when DOBLANK is true (>
              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.
  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.
  STVERS......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 => 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
                  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.
  LABEL.......Determines the label in the upper right hand corner of
              each pane
              0->label each pane with the pane number
              1->label each with appropriate coordinate
              2->label each pane with coordinate wrt reference pixel
             -1->do not label each pane
  INFILE......If 'VLA' or 'VLBA' use layouts appropriate to those
              arrays.  Else 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.
  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).
  TVCHAN......TV channel for grey plots (0 -> 1).
  GRCHAN......Graphics channel (1 - 7) to use for line drawing.  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).
              If contours are colored (e.g.CON3COL or RGBLEVS), DODARK
              does not apply to the contours.
  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.

EXPLAIN SECTION

KNTR is a variant of task CNTR written by Mark Calabretta of the
Australia Telescope.  It uses a contour tracing algorithm rather
than CNTR's hybrid raster-vector algorithm which is unsuitable
for pen plotters.  KNTR can now plot grey-scales as well as, or
instead, of contours.

KNTR (unlike CNTR), can handle multiple planes of an image cube.
The sequence of planes to be plotted may be specified via BLC(3)
and TRC(3).  KNTR will arrange them on the page as efficiently
as possible.

KNTR also plots the boundary between blanked and unblanked
regions by delineating the pixel edges when DOBLANK > 0).  This
produces a characteristic angular type of contour.

The explanatory notes for KNTR follow.


KNTR: Task to create a contour-plot extension file for an image
RELATED PROGRAMS: PCNTR, PRTPL, TKPL, TVPL, TVWIN

                           PURPOSE

     KNTR generates a plot extension file containing an
intensity contour and/or grey-scale 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.  KNTR 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.  The plot can also be sent to the printer or
to a postscript file using LWPLA.

                          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 KNTR 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 KNTR, the messiness of the plot can be
judged by looking at the message on your monitor:

     GFINIS:  NUMBER OF RECORDS 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 or LWPLA, 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 positions of stars or other objects.
First you must read the positions 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 positing angle when
you create the ST table in STARS (see STARS for more
information).

EXECUTION TIMES:
Plotting 10 or so contours in a 100 by 100 window with a
straightforward source will take a few seconds.  Large, messy,
or noise-limited plots may take many minutes.  If KNTR seems
to be taking longer than expected, you may be plotting more
contours than you wanted.

AIPS