AIPS HELP file for PCNTR in 31DEC25
As of Wed Dec 11 9:06:56 2024
PCNTR: Task to generate plot file for contour plus pol. vectors
INPUTS
DOCONT -1.0 4.0 Draw contours? select image
DOVECT -1.0 4.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 -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
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.
DOFRACT -1.0 1.0 > 0 -> convert polarization
to fractional pol.
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
PVPLOT 0.0 4.0 Position for polarization
vector scale plot as CBPLOT
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.
HELP SECTION
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, 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.
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.
DOFRACT.....If > 0, convert P image to fractional polarization
before plotting but only when I > ICUT and P > PCUT in
the input units of those images. Note - if your input P
image is already fractional polarization, do not set
DOFRACT > 0. FACTOR applies to fractional polarization
when selected while PCUT applies to real units (Jy/beam
usually).
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
PVPLOT......Selects the corner in which a plot of the polarization
vector scale appears. 0: no vector plot
1: lower left 2: lower right
3: upper right 4: upper left
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.
EXPLAIN SECTION
PCNTR: Task to create contour and/or polarization plot file
DOCUMENTOR: J. J. Condon NRAO/CV
RELATED PROGRAMS: CNTR; TKPL, TXPL, TVPL, 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 TXPL,
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.