%-----------------------------------------------------------------------
%;  Copyright (C) 1995, 1998, 2000-2025
%;  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
%-----------------------------------------------------------------------
\chapts{Displaying Your Data}{plot}

\renewcommand{\titlea}{31-December-2025 (revised 26-November-2025)}
\renewcommand{\Rheading}{\AIPS\ \cookbook:~\titlea\hfill}
\renewcommand{\Lheading}{\hfill \AIPS\ \cookbook:~\titlea}
\markboth{\Lheading}{\Rheading}

     This chapter is concerned with the ways in which you may display
your data.  There are a number of tasks for generating ``plot files''
which contain graphics commands for the making of various displays of
your \uv\ and image data.  All of these now offer a ``preview'' option
to draw the plot directly on the \AIPS\ TV, rather than putting the
commands into a file.  Once the files are created, a variety of tasks
may be used to translate them into displays on various devices, such
as the \AIPS\ TV and graphics windows and PostScript printers.  There
are also verbs to display and manipulate your images on the \AIPS\ TV
and a single task {\tt TVCPS} to capture that display, if desired,
into a PostScript file for printing, recording on film, or even
including in your scientific papers.

     Several indices of the \AIPS\ software are relevant to this
discussion.  To generate current lists of \AIPS\ functions on your
workstation window (or terminal) use {\us ABOUT HARDCOPY \CR}, {\us
ABOUT INTERACT \CR}, {\us ABOUT PLOT \CR}, {\us ABOUT TV-APPL \CR},
and {\us ABOUT TV \CR}\@.  Recent versions of these indices are
reproduced in \Rchap{list} of this \Cookbook.

\Sects{Getting data into your \AIPS\ catalog}{displtape}

     By the time you reach this chapter, most of your data will
probably already be loaded into your \AIPS\ catalog either by reading
an external tape or disk or by being generated by some \AIPS\ task.
Visibility data which are not presently on disk may be read by the
\AIPS\ tasks {\tt FILLM}, {\tt UVLOD} and {\tt FITLD}; see
\Sec{uvtape} and \Sec{imagtape} for details.  Images that are
generated by other imaging systems, (\eg\ images from non-NRAO radio
telescopes or non-radio images) can be transported to \AIPS\ by
writing them out of the other imaging system on tape or disk in the
standard FITS format.  The tasks {\tt IMLOD} and {\tt FITLD} can then
be used to read them into \AIPS\@.  These tasks are also used to
read images saved with {\tt FITTP} and {\tt FITAB} from previous
\AIPS\ sessions.

\subsections{{\tt IMLOD} and {\tt FITLD} from FITS-disk}

     {\tt FITLD} and {\tt IMLOD} can read FITS-format images from
external disk files or magnetic tape into your \AIPS\ catalog.  The
disk-file option is indicated by setting the adverb {\tt DATAIN} to a
non-blank value.  Disk image files must be read in only one at a time
per execution of {\tt IMLOD}, but {\tt FITLD} can read more than one
FITS-disk file if the file names are identical except for sequential
post-pended numbers beginning with 1.  {\tt DATAIN} is a string of up
to 48 characters that must completely specify the disk, directory, and
name of the input disk file to your computer's operating system.  See
\Sec{fitsdisk} for a discussion of \indx{FITS-disk} files.

        One ``feature" of \AIPS\ complicates this otherwise
straightforward disk analog of FITS tape reading.  {\tt AIPS}
translates all of your alphabetic inputs to upper case (this was
demanded by users who otherwise became confused between upper and
lower cases).\footnote{If you omit the close quote on the character
string, it is not converted to upper case, allowing you to circumvent
this \AIPS\ limitation.  The string without a close quote must, of
course, be the last thing on the line.}  So if your computer
distinguishes upper and lower cases for disk, directory, or file
names, you probably should do two things to prepare for this before
running \AIPS\@.  First, restrict your external disk file names
to upper-case characters and numbers.  Second, set an upper-case
``environment variable'' or ``logical'' to point to the disk and
directory where your \indx{FITS-disk} images are stored before you run
{\tt AIPS}\@.  You may need help from your System Manager when doing
this for the first time.  A common strategy on UNIX machines is to
create an upper-case logical name after logging in but before starting
up {\tt AIPS}:
\dispx{{\tt \%\qs}setenv MYLOGICAL {\it myarea\/} \CR}{if using
              C-shell, or}
\dispx{{\tt \$\qs}export MYLOGICAL={\it myarea\/} \CR}{if using korn,
              bourne, or bash shells,}
\dispe{where {\us MYLOGICAL} is an all-upper-case string of your
choice and {\it myarea\/} is the full path name of the disk directory
that contains your FITS-disk data.  \AIPS\ usually provides a public
disk area known as {\tt FITS} which you may use.}

      Then, once inside {\tt AIPS}, tell {\tt \tndx{FITLD}} or {\tt
\tndx{IMLOD}}:
\dispt{DATAIN\qs 'MYLOGICAL:IMAGE.DAT' \CR}{to read in the FITS-disk
      file {\it myarea\/}{\tt :IMAGE.DAT}.}
\dispe{To check that the file name is correct, type:}
\dispt{\tndx{TPHEAD} \CR}{ }
\dispe{Your terminal will then list information about the image header
of the disk file.}
\dispt{OUTDI\qs {\it n\/} \CR}{to specify writing the image to your
             \AIPS\ catalog on disk {\it n\/}.}
\dispt{OUTNAME\qs '{\it your-chosen-name\/}' \CR}{to specify the
             output disk file name in \AIPS; the default is the image
             name on tape if {\tt FITTP} was used to write the image
             to tape.}
\dispe{The string {\it your-chosen-name\/} can be any ($\le$
12-character) title that you want to use as the image name within
\AIPS\ and should be specified for images from other image-processing
software systems.  {\tt \tndx{FITLD}} also allows you to specify the
6-character image ``class'' parameter.  Use {\us OUTCLASS '{\it
abcdef\/}' \CR}, if you wish to change the class from that in your
input file as the image is read or if the image comes from a
``foreign'' system.}
\dispt{OUTS\qs -1 \CR}{to keep the sequence number the same as that
          in the file; the default is the highest unique number
          for images with this name and class in your current
          \AIPS\ catalog.}
\dispt{NCOUNT\qs {\it m\/} \CR}{in {\tt FITLD} only, to load {\it m}
          images consecutively starting with the file specified by
          {\tt DATAIN} with a 1 post pended.  The other files must be
          the same name but with sequential numbers post pended.  If
          you use this option, do {\it not\/} specify the {\tt
          OUTNAME} unless you want the same name for all the new
          images in your catalog.}
\dispt{GO\qs FITLD \CR}{or {\tt \tndx{IMLOD}}, to run the task.}
\dispe{If {\tt OUTNAME} is left unspecified, it defaults to the
``name'' of the image read from the FITS header --- either the name
previously used in earlier image processing or the source name.  If
{\tt OUTCLASS} is unspecified, it defaults to the Class previously
used in earlier image processing or to a compound name (\eg\ {\tt
IMAP}, {\tt IBEM}, {\tt QMAP}, {\tt ICLN}) which attempts to describe
the image.  These defaults are frequently good ones when you are
loading multiple consecutive images with {\tt NCOUNT} $>0$. You may of
course change the \AIPS\ image and class names later by using {\tt
RENAME} (see \Sec{rename} of this \Cookbook).}

{\tt IMLOD} and {\tt FITLD} can also read images from magnetic tape;
see the instructions in \Sec{magtape}.  Use the verbs {\tt MOUNT} to
mount the tape, {\tt AVFILE} to advance the tape to the desired file,
and {\tt TPHEAD} to check that the tape is correctly positioned.  Set
{\tt NFILES=0}, {\tt NCOUNT} to the number of consecutive tape files
you wish to load, and the say {\tt GO} to either {\tt FITLD} or {\tt
IMLOD}\@.

\Subsections{Image coordinates}{coordinates}

Images of the celestial sphere must be rendered with some sort of
coordinate ``projection.''  \AIPS\ pioneered the handling of such
coordinates, supporting true projective \indx{coordinates} called {\tt
SIN} (orthographic),  {\tt TAN} (gnomic), {\tt ARC} (zenithal
equidistant), and {\tt STG} (stereographic) as well as a special
version of orthographic suited for East-West interferometers ({\tt
NCP})\@.  \AIPS\ also supports modern\footnote{Calabretta, M. R. and
Greisen, E. W. 2002, ``Representations of celestial coordinates in
FITS,'' {\it Astr. \&\ Ap.}, 395, 1077.} interpretations of {\tt GLS}
({\tt SFL} Sanson-Flamsteed), {\tt MER} (Mercator), {\tt AIT}
(Hammer-Aitoff), {\tt CAR} (Plate carr\'{e}e). {\tt MOL} (Molweide), and
{\tt PAR} (parabolic) ``projections.''  These are normally used to
represent large sections of the celestial sphere.  Users should be
warned that reference pixel values other than zero lead to {\it oblique}
projections.

Fits to the coordinates on optical images often lead to a modest
amount of skew in the image.  This is represented in the {\tt PC{\it
i}\_{\it j}} or {\tt CD{\it i}\_{\it j}} FITS header cards.  If these
cards contain any significant skew, {\tt IMLOD} and {\tt FITLD} will
tell you about it.  In such cases, run {\tt \tndx{DSKEW}} on the images
after they have been loaded into \AIPS\@.  This is the only task that
understands coordinate skew and it will re-grid the images for use by
all other \AIPS\ tasks.

\sects{Printer displays of your data}

     The most old fashioned way to look at your data --- and the most
exact --- is simply to print it out and read the numbers.  \AIPS\
provides a variety of tasks and verbs to print visibility data, image
data, tabular data, and miscellaneous other information.  All of these
tasks and verbs allow you to specify where the printed output goes
using two adverbs, {\tt \tndx{DOCRT}} and {\tt \tndx{OUTPRINT}}\@.  If
{\tt DOCRT} $\le 0$ and {\tt OUTPRINT} is blank, then the output is
placed in a temporary file and queued to the \indx{printer} you
selected when starting {\tt AIPS}; see \Sec{stAIPS}.  If printing
directly to the printer is requested, most tasks and verbs count the
number of lines of print and request permission to proceed if the count
is large.  (Type {\us PRINTER {\it n\/} \CR} to change the line printer
selection to that numbered {\it n\/}; type {\us PRINTER 999 \CR} to see
the devices available to you and their assigned numbers.)  If {\tt
DOCRT} $\le 0$, a non-blank {\tt OUTPRINT} specifies a text file into
which the output is to be written; see \Sec{textfile}.  The current
output is appended to the file if it already exists.  Thus, you can
combine a number of printed outputs for later editing and/or printing.
When {\tt DOCRT = -1}, the output print file will contain full paging
commands and headers.  To suppress some of this, use {\tt DOCRT = -2} or
to suppress almost all of it, use {\tt DOCRT = -3}.  This last is
especially helpful when writing programs to read the text file.  If {\tt
DOCRT} $> 0$, the output is directed to your workstation window or
terminal.  All printer verbs and tasks are able to respond to both the
width and height of your workstation window.  Set {\tt DOCRT = 1} to use
the current width; set {\tt DOCRT} $= n \ge 72$, to use {\it n\/} as the
width of the display window.  Since most print tasks display more
information on wider windows, we recommend widening your window to 132
characters and specifying {\tt DOCRT = 1}.  The print routines will
pause whenever the screen is full and offer you the choice of
continuing or quitting.  Thus, you can start what might be a very long
print job, find out what you wanted to know after a few screens full,
and quit without using up any trees.

\Subsections{Printing your visibility data}{printuv}

     Before beginning calibration, it is a very good idea to make a
-summary list of the contents of your data set.  {\tt \tndx{LISTR}}
with {\tt OPTYPE = 'SCAN'} will list the contents of each scan in the
data set.  {\tt \tndx{LISUN}} produces the same output with the addition
of the angle between each scan and the Sun.  It also honors {\tt
TIMERANG} and {\tt SOURCES} unlike {\tt LISTR} in its {\tt SCAN} mode.
{\tt \tndx{DTSUM}} also produces a listing summarizing the
data set in either a condensed or full form.

     The most basic display of your visibility data is provided by
{\tt \tndx{PRTUV}} which lists selected correlators in the order they
occur in the data set:
\dispt{TASK\qs'PRTUV' ; INP \CR}{to review the inputs.}
\dispt{INDI\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to select the disk
         and data set to print.}
\dispt{CHANNEL\qs {\it c\/} ; BIF\qs 1 \CR}{to print starting with
         channel {\it c\/} from IF 1.}
\dispt{BPRINT\qs {\it m\/}; XINC\qs {\it i\/} \CR}{to print every
         $i^{\uth}$ visibility starting with the $m^{\uth}$ visibility

         in the data set.}
\dispt{DOCRT\qs 1 ; GO \CR}{to run the task with display on the
         terminal.}
\dispe{When you have seen enough, enter {\us q \CR} or {\us Q \CR} at
the page-full prompt.}

\noindent You may limit the sources, range of projected baselines, and
times displayed and may select only one baseline or one antenna.  {\tt
PRTUV} does not apply calibration or flagging tables.  To get a
similar display with all ``standard'' calibration, flagging, and data
selection (optionally) applied, use the task {\tt \tndx{UVPRT}}\@.
{\tt \tndx{LISTR}} also uses all of the calibration options to list
the data in simple lists or in a display showing all the baselines at
each time in a matrix form.  {\tt \tndx{SHOUV}} also lists calibrated
visibility data with options to average all channels in each IF and to
display closure rather than observed phases.  {\tt \tndx{ANBPL}}
converts baseline-based amplitudes, phases, or weights into
antenna-based values and prints and/or plots them.  The display of
antenna-based weights before and after amplitude self-calibration is a
particularly useful tool for spotting calibration/instrumental
problems.

     There are a number of tasks used to diagnose possible problems in
your data and to print information about them.  {\tt \tndx{UVFND}}
examines a data set for excess fluxes, excess apparent V-polarization,
or simply any data with a specified fringe spacing and position angle
or a specified range in {\it u\/} and {\it v\/}. As it does this, it
also checks for bad antenna numbers, bad times, and (optionally) bad
data weights. {\tt \tndx{CORER}} examines a data set for excessive
mean values and rms in each correlator (after applying calibration and
flagging and then subtracting a point source at the origin).  {\tt
\tndx{RFI}} examines the rms fluctuations in the real and imaginary
visibilities of each correlator looking for (and reporting) periods of
apparent RF interference.  {\tt \tndx{UVDIF}} directly compares two
data sets reporting any excess differences.  It is useful for
determining whether your latest operations (flagging, self-cal) have
made a significant (or any) difference.

\Subsections{Printing your image data}{printim}

     The most basic display of an image is a print out of the numbers
it contains.  Such a display is provided by {\tt \tndx{PRTIM}}:
\dispt{TASK\qs 'PRTIM' ; INP \CR}{to review the inputs.}
\dispt{INDI\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to select the disk
         and image to print.}
\dispt{NDIG\qs 3 \CR}{to use 3 digits, printing numbers between -99
         and 999 with appropriate power of 10 scaling.}
\dispt{FACTOR\qs 10 \CR}{to raise the default scaling by a factor of
         10, overflowing regions of high values to see low valued
         regions better.}
\dispt{BLC\qs 0 ; TRC\qs 0 \CR}{to see the whole image.}
\dispt{XINC\qs 2 ; YINC\qs 2 \CR}{to see every other column and every
         other row.}
\dispt{DOCRT FALSE ; GO \CR}{to print the image on the selected
         \indx{printer}.}
\pd

     Other imaging tasks which can use the printer are {\tt
\tndx{BLSUM}} and {\tt \tndx{ISPEC}}, which compute and print spectra
by summing over regions of each plane in a data cube (see
\Sec{lineanal}), and {\tt \tndx{IMFIT}}, {\tt \tndx{JMFIT}}, and {\tt
\tndx{SAD}}, which fit one or more Gaussians to an image (see
\Sec{analfit}).  {\tt \tndx{IMTXT}} writes an ASCII-formatted file
containing an image.

\subsections{Printing your table data}

     If you have any doubts about the contents of tables in \AIPS, it
is best to resolve them by looking at the contents of the tables
involved.  {\tt \tndx{PRTAB}} is a very general task which will print
the contents of any \AIPS\ table file.  For example, to print flag
table version 1:
\dispt{TASK\qs 'PRTAB' ; INP \CR}{to review the inputs.}
\dispt{INDI\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to select the disk
         and catalog entry to print.}
\dispt{INEXT\qs 'FG' ; INVERS\qs 1 \CR}{to select flag table version
         1.}
\dispt{BPRINT\qs 0 ; EPRINT\qs 0 ; XINC\qs 1 \CR}{to print everything.}
\dispt{DOHMS\qs TRUE \CR}{to print times in sexagesimal notation.}
\dispt{DOCRT\qs 1 ; GO}{to print the flag table on the terminal.}
\dispe{When you have seen enough, enter {\us q \CR} or {\us Q \CR} at
the page-full prompt.  For a table with a significant number of
columns, {\tt PRTAB} shows all rows for the first columns and then
loops for the next set of columns.  To see all columns for some rows,
set a low {\tt EPRINT} value or be very patient.  Enter a list of
column numbers in {\tt BOX} to see only some of the columns.  {\tt
NCOUNT}, {\tt BDROP} and {\tt EDROP} control which values are
displayed in those columns having more than 1 value per row.  Adverb
{\tt RPARM} lets you limit the display to rows having specific column
values within specified ranges, while {\tt NDIG} controls the format
and accuracy used to display floating-point columns.}

     Some of the tables have specialized printing programs.  These
include {\tt \tndx{PRTAN}} for antenna tables, {\tt \tndx{PRTCC}} for
Clean component tables, {\tt SLPRT} for slice files, and {\tt
\tndx{LISTR}} with {\tt OPTYPE = 'GAIN'} for calibration, solution,
and system temperature tables.  The verb {\tt \tndx{EXTLIST}} will
list information about various extension files, particularly slice and
plot files (see below), which may be printed with {\tt
\tndx{PRTMSG}}\@.  {\tt \tndx{OFMLIST}} is a verb to print the
contents of an \AIPS\ TV color table.  Finally, task {\tt
\tndx{TBDIF}} will compare columns of two tables and print information
about their differences.  {\tt \tndx{PRTSY}} and {\tt \tndx{SYPRT}}
offer differeing views od the contents of EVLA SysPower tables.

\subsections{Printing miscellaneous information}

     There is a variety of miscellaneous information which may also be
sent to the \indx{printer} in the same way.  Verb {\tt PRTMSG} prints
selected contents of the \AIPS\ message file; see \Sec{message}.  Verb
{\tt \tndx{PRTHI}} prints selected lines from a history file; see
\Sec{history}.  Pseudo-verb {\tt \tndx{ABOUT}} prints lists of \AIPS\
symbols by category while pseudo-verbs {\tt \tndx{HELP}} and {\tt
\tndx{EXPLAIN}} print information about a selected symbol; see
\Sec{help}.  Task {\tt \tndx{PRTTP}} prints the contents of magnetic
tape volumes and pseudo-tape disk files; see \Sec{prttp} and
\Sec{tapeuse}.  Task {\tt \tndx{PRTAC}}, which may also be run in a
stand-alone mode, prints information selected from the \AIPS\
accounting file.

     Task {\tt \tndx{TXPL}} will attempt to represent an \AIPS\ plot
file (see below) on the printer.  This will not work well for
complicated plots, but, for simple plots, it may be the only way
someone running over a slow telephone line can see his/her data in
plot form.

\Sects{Plotting your data}{plot}

     The basic concept in \AIPS' plotting is to use some task to
create and write a device-independent \Indx{plot file} as a PL
extension file to a cataloged image or visibility data set and then to
use some device-dependent task to interpret that file for the desired
output device.  Plot files are not overwritten by subsequent plot
tasks. Instead they make new plot files with higher ``version''
numbers.  The device-dependent tasks include {\tt \tndx{TVPL}} (\AIPS\
TV devices including {\tt \tndx{XAS}}), {\tt \tndx{TKPL}} (Tektronix
graphics devices including \AIPS' {\tt \tndx{TEKSRV}} server), {\tt
\tndx{TXPL}} (line printers), and {\tt \tndx{LWPLA}}
(\indx{PostScript} printer/plotters).  Tasks called {\tt PRTPL}, {\tt
QMSPL}, and {\tt CANPL} support antique Versatec, QMS, and Canon
printer/plotters.  To plot on a PostScript printer/plotter:
\dispt{TASK\qs 'LWPLA' ; INP \CR}{to review the inputs.}
\dispt{INDI\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to select the disk
         and catalog entry to print.}
\dispt{PLVER\qs {\it m\/} ; INVERS\qs 0 \CR}{to plot the $m^{\uth}$
         plot file only.}
\dispt{OUTFILE\qs ' ' ; GO \CR}{to do the plot immediately.}
\dispe{{\tt LWPLA} offers the option to save the file for later
plotting or inclusion as encapsulated PostScript in other documents.
It also has options to control scaling, output paper size, width and
darkness of lines, and transformation of grey-scale intensities.  It
can write more than one plot file at a time and can append new plots
to existing output files.  Multi-plot files are not ``encapsulated''
but may be printed and viewed with tools such as {\tt gv} or {\tt
ghostview}.  Note that PostScript files are text files and \AIPS\
writes particularly simple PostScript so that it can be modified by
the users.  See {\us HELP POSTSCRIPT} for suggestions including
information on deleting and adding labels and arrows and on converting
the PostScript to other formats like jpg without loss of resolution.
\Todx{PostScript}}

{\tt LWPLA} and all plot tasks offer some ``coloring'' options.  These
are illustrated in the color pages at the end of this chapter.  The
grey-scale plotting tasks, including {\tt GREYS}, {\tt PCNTR}, and
{\tt KNTR}, can now enhance the grey-scales with a transfer function
and then pseudo-color them with a color table.  See \Sec{tvofmlut} for
a short discussion of ``output-function memory'' tables which may be
read into the above tasks or to {\tt LWPLA} using the adverb {\tt
OFMFILE}\@.  Lines plotted on top of grey scales (\eg\ contours,
polarization vectors, stars) may be ``dark'' when the grey scale
intensity is high.  {\tt LWPLA} may be instructed to plot these as
bright if adverb {\tt DODARK} is false.  All plot programs can draw
lines of different types in both bright and dark forms.  In {\tt
LWPLA}, if {\tt DOCOLOR} is true, the array adverb {\tt
\tndx{PLCOLORS}($i,j$)} controls the red, green, and blue colors ($i =
1,2,3$, resp.) of line types $j= 1$ -- 10.  The normal meanings of
these types are:
\begin{enumerate}
\item\ Bright labeling, tick marks, surrounding lines
\item\ Bright lines, usually contours or model curves
\item\ Bright lines, usually polarization vectors
\item\ Bright lines, usually symbols such as stars, visibility samples
\item\ Dark labeling text inside plot area
\item\ Dark lines, usually contours
\item\ Dark lines, usually polarization vectors
\item\ Dark lines, usually symbols such as stars
\item\ Bright labeling outside the main plot area, e.g. titles, tick
      values and types, documentation
\item\ Background for the full plot
\end{enumerate}
Some plot tasks have the ability to control the colors of their line
drawing independent of these line types.  These colors may be
controlled only when making the plot file with the particular task.
{\tt PCNTR} and {\tt KNTR} have acquired the ability to color each
contour level under control of the adverb {\tt RGBLEVS}\@.  Using
system {\tt RUN} file {\tt \tndx{SETRGBL}}, procedures {\tt
\tndx{CIRCLEVS}}, {\tt \tndx{RAINLEVS}}, {\tt \tndx{FLAMLEVS}}, and
{\tt \tndx{STEPLEVS}} are available to help you set the values of {\tt
RGBLEVS}\@.  Examples are shown on the color pages at the end of this
chapter.  With {\tt \Tndx{LWPLA}} and these options one may prepare
extremely effective displays --- or hopelessly bad ones --- for use in
talks and, since the prices have become reasonable, even in journals.
Note that most journals want color images in CMYK
(cyan-magenta-yellow-black) rather than RGB; use {\tt DPARM(9) = 1} in
{\tt LWPLA} to get PostScript files with this color convention.  Note
that these two color representations usually require different
``gamma'' corrections; the adverb {\tt RGBGAMMA} allows this control
in {\tt LWPLA}\@.

\Iodx{TV functions}
     All \AIPS\ plot tasks now offer a ``preview'' option.  If you set
{\tt \tndx{DOTV} = TRUE} when running any plot task, then the plot
appears immediately on the \AIPS\ TV display and no plot file is
generated. This option allows you to make sure that the parameters of
the plot are reasonable and lets you avoid making files and wasting
paper for quick-look plots.  Additional options allow you to control
which graphics channel is used for the line drawing ({\tt GRCHAN}) and
to select pixel scaling of the plot at your specified location on the
TV screen ({\tt TVCORN})\@.  These two options allow you to view
more than one plot at a time on the TV, usually for purposes of
comparison.  Each graphics channel on the TV has a different color and
a complementary color is used when two or more channels are on at the
same point.  This allows for a fairly detailed and effective
comparison of plots, all of which may be captured with task {\tt
\tndx{TVCPS}} (see below).  Be aware that most tasks now interpret
{\tt GRCHAN = 0} as an instruction to use graphics channels 1 through
4 for line types 1 through 4 and graphics channel 8 for dark vectors.
The comparison function is only achieved by specifying {\tt GRCHAN};
see {\us HELP GRCHAN} for more information\@.  Tasks that produce
multiple plot files pause for 30 seconds at the end of each plot when
{\tt DOTV = TRUE}\@.  This allows you to stop the task (TV button {\tt
D}), hurry it along (TV buttons {\tt B} or {\tt C}), or make it pause
indefinitely (TV button {\tt A}) until another TV button is pressed.

     You can review the parameters of the plot files associated with a
given image or visibility data set by typing:
\dispt{INDI\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to select the disk
         and catalog entry to print.}
\dispt{INEXT\qs 'PL' ; \tndx{EXTLIST} \CR}{to list summaries of the
         plot file contents.}
\dispt{PLVER\qs{\it m\/} ; \Tndx{PLGET} \CR}{to recover all adverb
         values used when making the specified plot file.}
\dispe{Plot files (and other ``extension files'') are automatically
deleted when an image is deleted by {\tt ZAP}\@.  However, large
plot files should be deleted as soon as they are no longer needed:}
\dispt{INP\qs \tndx{EXTDEST} \CR}{to review the inputs required.}
\dispt{INEXT\qs 'PL' ; INVERS\qs {\it m\/} \CR}{to set the type to
         {\tt PL} (plot) and the version number to be deleted to {\it
         m\/}.  $m = -1$ means all and $ m = 0$ means the most recent
         (highest numbered).}
\dispt{EXTDEST \CR}{to do the deletion.}
\dispt{INVERS\qs 0 \CR}{to reset the version number to its default ---
         usually advisable.}
\dispe{Plot files are not amenable to the FITS format and so are not
written by {\tt \tndx{FITTP}} and {\tt \tndx{FITAB}}\@.  They may be
copied from one catalog entry to another with {\tt \tndx{TACOP}}\@.}

\Subsections{Plotting your visibility data}{plotuv}

\begin{figure}
\centering
%\resizebox{!}{3.4in}{\gname{uvpltuv}\hspace{0.1cm}\gname{uvpltbf}}
\resizebox{!}{3.4in}{\gbb{516,541}{uvpltuv}\hspace{0.1cm}\gbb{524,550}{uvpltbf}}
\caption[{\tt UVPLT} displays]{{\tt \tndx{UVPLT}} displays of where
the data were observed in the \uv\ plane (left) and of the visibility
amplitudes as a function of baseline length (right).  The data on
3C336 were provided by Alan Bridle from observations made with the VLA
on 6 December 1987.\Iodx{plot file}}
\label{fig:uvplt}
\end{figure}

     The most basic plot program for visibility data is called {\tt
\tndx{UVPLT}}\@.  It allows you to select the {\it x\/} and {\it y\/}
axes of the plot from real, imaginary, amplitude, log of amplitude,
phase and weight of the visibility, time, hour angle, elevation,
azimuth, and parallactic angle, and projected baseline length,
position angle, {\it u\/}, {\it v\/}, {\it w\/}, frequency, spectral
channel number, and baseline number.  It offers all of the usual
calibration and data selection options and it plots the selected
points individually and/or in a controlled number of bins along the
{\it x\/} axis.  It can display multiple IFs and spectral channels
at once, including averaging groups of spectral channels.  It can also
time average the data ({\tt SOLINT} minutes) prior to plotting.  For
example, to plot calibrator phases as a function of time for all
baselines to one antenna:
\dispt{TASK\qs 'UVPLT' ; INP \CR}{to review the inputs.}
\dispt{INDI\qs{\it n\/} ; GETN\qs {\it ctn\/} \CR}{to select the disk
         and catalog entry of the data set.}
\dispt{BPARM = 11 , 2 \CR}{to plot time in hours on the {\it x\/} axis
         and phase in degrees on the {\it y\/} axis.}
\dispt{SOURCES\qs ' ' ; CALCODE\qs '*' \CR}{to select all calibrator
         sources.}
\dispt{XINC\qs 4 \CR}{to plot only every fourth selected sample.}
\dispt{ANTENNA\qs 2,0 ; BASELINE\qs 0 \CR}{to do all baselines with
         antenna 2.}
\dispt{DOTV = -1 ; GO \CR}{to make a \Indx{plot file} of these data.}
\dispe{After {\tt UVPLT} is running, or better, after it has
finished:}
\dispt{PLVER\qs 0 ; GO\qs LWPLA \CR}{to plot the latest version on a
         PostScript printer/plotter.}
\pd

     There are several other tasks to plot your visibility data.  {\tt
\tndx{VPLOT}} plots all of the parameters offered by {\tt UVPLT}, but
one baseline at a time with multiple baselines per page (\ie\ per plot
file) and multiple pages per execution.  {\tt \tndx{CLPLT}} is a
similar task but restricted to plotting closure phases around baselines
involving 3 antennas as a function of time.  {\tt \tndx{CAPLT}} is a
similar task but restricted to plotting closure amplitudes around
groups of 4 baselines as a function of time.  All three of these
can also plot a source model (based on Clean components) as well as
the observations.  In {\tt 31DEC22}, task {\tt \Tndx{CLOSE}} can plot
the rms of closure phase or amplitude as a function of spectral
channel.  {\tt \Tndx{ANBPL}} can create plots of amplitudes, phases, or
weights converted to antenna-based quantities; this function is helpful
in diagnosing problems with your data.  For spectral-line users, {\tt
\tndx{POSSM}} plots visibility spectra averaged over selected baselines
and time intervals.  It can also plot various spectral tables (bandpass
and others), as well as the Fourier transform of visibility spectra (the
auto- and cross-correlation functions).  {\tt POSSM} can also plot other
spectral tables ({\tt BD}, {\tt PD}, {\tt CP}, {\tt PC}, and {\tt PP}).
For VLBI users (primarily), {\tt \tndx{FRPLT}} plots visibilities versus
time or, more importantly, the fringe rate spectrum.  To examine the
statistical distribution of your data, try {\tt \tndx{UVHGM}} which
plots histograms showing the number of samples or weights versus a
wide variety of parameters. Optionally, it will fit a Gaussian to the
histogram and plot the result.  The task {\tt \tndx{UVIMG}} will grid
visibility data into an image on a variety of axes, while the task
{\tt \Tndx{UVHIM}} will make an image of a two-dimensional histogram
of your \uv\ data.  All image display functions below may then be used
to view the results.  For example, if the axes of the histogram image
are the real and imaginary parts of your data, then the image will
demonstrate the amplitude and phase stability present (or missing) in
your data.

     Two tasks, new in {\tt 31DEC21}, compute and then plot statistical
information from calibrated autocorrelation data.  {\tt \Tndx{VBRFI}}
computes the statistics as a function of frequency and antenna and
then prints them to a text file and, optionally, plots them.  {\tt
\Tndx{PLRFI}} can plot one or more of the text files written by
{\tt VBRFI}\@.  As the names suggest, these are intended to describe
the RFI environment of the antennas.

     A number of visibility plotting and editing tasks offer the {\tt
DO3COLOR} option to separate multiple IFs, spectral channels, sources,
times, and the like when plotted in the same plot area.  Task
{\tt \Tndx{PLOTC}} will make plots showing the colors used by such tasks
with labels to assist in identifying which color goes with which data
parameter.  These plots may be saved as plot files and shown directly on
the TV just as with all other plot tasks.

     Three tasks allow you to examine selected portions of a $uv$ data
set statistically.  {\tt \Tndx{UVRMS}} averages the selected data in
{\tt SOLINT} time intervals and then can plot the average values as a
function of time and as a histogram.  A variety of statistical
parameters are computed and printed.  {\tt \Tndx{SPRMS}} determines and
plots the mean and standard deviation of the selected data as a
function of spectral channel.  Note that both tasks will combine data
from multiple sources, baselines, etc.~if so instructed.  {\tt
\Tndx{RIRMS}} computes statistics over the included visibility data
and then prints a matrix over baselines of the real and imaginary
parts separately.  Histogram plots and plots over time may be generated.

     Two plot programs actually convert visibility data to the image
plane for plotting.   Observers of point objects which might vary with
time either intrinsically or by scintillation (\eg\ stars, masers)
might wish to try {\tt \tndx{DFTPL}}, which plots the Fourier
transform of the data shifted to a selected position as a function of
time.  Control over Stokes including polarization amplitude and
popsition angle are available in {\tt 31DEC24}\@.  Tasks which save an
image for later plotting include {\tt \tndx{DFTIM}} which makes an image
of such data as a function of frequency and time and {\tt \tndx{ACIMG}}
which makes a time and frequency image of autocorrelation data by
antenna.  VLBI spectral-line observers may need to use
{\tt \tndx{FRMAP}}, which performs imaging via fringe-rate inversion and
plots the loci of possible source positions.

%\vfill\eject
\Subsections{Plotting your image data}{plotimag}

     Image data may be drawn in a variety of ways including contours,
grey or color levels, row tracing, and statistical.  All plots are
drawn with labeled tick marks although these may be suppressed with
the {\tt LTYPE} parameter.  This {\tt \tndx{LTYPE}} parameter is used
to control the type of axis labels, the degree of extra labeling, the
presence of the line giving the plot time and version, and also how
metric scaling is done on the axis units.  Read {\tt HELP LTYPE} for
details.  For plots having significantly non-linear coordinate axes,
\eg\ wide-field images, it is sometimes useful to draw a full,
non-linear coordinate grid rather than just short lines at the edges
of the plot.  Tasks like {\tt CNTR} and even the verb {\tt
\tndx{TVLABEL}} offer this option; enter {\us DOCIRC\qs TRUE \CR}\@.

     Plot symbols (\eg\ plus signs) may be drawn on the plots produced
by {\tt \tndx{CNTR}}, {\tt \tndx{PCNTR}}, {\tt \tndx{GREYS}}, {\tt
\tndx{KNTR}} and several of the other tasks mentioned below.  In these
tasks, the parameters which controls the plotting are {\tt STFACTOR}, a
scale factor for the symbols, and {\tt STVERS}, a choice of the
desired stars extension file.  When using this option, there must be
a table of ``star'' positions associated with the image being plotted.
To create one, enter {\us EXPLAIN\qs \tndx{STARS} \CR} to learn the
format of the input data file and the parameters for the task.  See
also \Rappen{sys} or your local equivalent for instructions on editing
text files.  A star file may also be created by {\tt \tndx{MF2ST}}
from a model fit file produced by task {\tt \tndx{SAD}} (see \Sec{sad}
and \Sec{sdmodel}).  Tasks {\tt IMFIT}, {\tt JMFIT}, and {\tt SAD} may
now also produce ``star'' extension files directly.

     Example outputs of the following three tasks are given in
\Rfig{imageplot}.

\Subsubsections{Contour and grey-scale plots}{plotcntr}

     The most basic contour drawing task is {\tt \tndx{CNTR}}\@.
In addition to the usual image selection parameters, you may specify:
\dispt{TASK\qs 'CNTR' ; INP \CR}{to tell you what you may specify.}
\dispt{BLC 250 , 230 \CR}{to set the bottom left corner of plot
               at 250, 230 (in pixels with 1,1 at extreme bottom left
               of the image).}
\dispt{TRC 300, 330 \CR}{to set the top right corner of plot at
               300, 330.}
\dispt{CLEV\qs 0 ; PLEV\qs 1 \CR}{to get contour levels at 1$\%$ of
               the peak image value.}
\dispt{PLEV\qs 0 ; CLEV\qs .003 \CR}{to get contour levels at 3 mJy.}
\dispt{LEVS\qs -1, 1, 2, 4, 6 \CR}{to get actual contours at -1, 1,
               2, 4, and 6 times the basic level set by {\tt PLEV} or
               {\tt CLEV}\@.  {\tt LEVS} need not be integers,
               but very fine subdivisions cannot be represented
               accurately on the plot.}
\dispe{{\it N.B.,\/} if you request more than one negative level with
the {\tt LEVS} input, you {\it must\/} use commas between the negative
levels.  Otherwise the minus sign(s) will be treated as subtraction
symbols and the desired levels will be combined into a single negative
level by the {\tt AIPS} language processor.  {\tt BLC} and {\tt TRC}
can be initialized conveniently from the TV display using the cursor
with the {\tt TVWIN} instruction (see \Sec{TVparm}).  Then check:}
\dispt{INP \CR}{to review what you have specified.}
\dispt{GO \CR}{to run the task when you're satisfied with the inputs.}
\dispe{This generates a \Indx{plot file} as an extension to your image
file, with the parameters you have just specified.  Watch the \AIPS\
monitor (which, on some systems, is your terminal) to see the progress
of this task.  If the ``number of records used'' in the plot file is
over 200, the contour plot will be messy (unless the field is also
large).  In this case, check that you have not inadvertently set {\tt
PLEV} or {\tt CLEV}, for example, to unrealistically low values.
Printing a large, messy plot file on the printer can take a
considerable length of time and will inconvenience other users.
Consider plotting directly on the TV first ({\tt DOTV = TRUE}) to
check on your selection of contours.}

     {\tt \tndx{PCNTR}} plots \indx{polarization} vectors on top of
contours and/or grey-scales.  You may make a polarized-intensity image
and a polarization position-angle image from the Q and U images (see
\Sec{analpoli}) or use the Q and U images themselves.  Then:
\dispt{TASK\qs 'PCNTR' ; INP \CR}{to review the input parameters.}
\dispt{INDI\qs{\it n1\/} ; GETN\qs {\it ctn1\/} \CR}{where {\it n1\/}
               and {\it ctn1\/} select the disk and catalog numbers of
               the image to be contoured.}
\dispt{IN2DI\qs {\it n2\/} ; GET2N\qs {\it ctn2\/} \CR}{where {\it
               n2\/} and {\it ctn2\/} select the Q or polarized
               intensity image.}
\dispt{IN3DI\qs{\it n3\/} ; GET3N\qs {\it ctn3\/} \CR}{where {\it
               n3\/} and {\it ctn3\/} select the U or position-angle
               image.}
\dispt{IN4DI\qs{\it n4\/} ; GET4N\qs {\it ctn4\/} \CR}{where {\it
               n4\/} and {\it ctn4\/} select the grey-scale image.}
\dispt{PCUT\qs {\it nn\/} \CR}{to blank out vectors less than {\it
               nn\/} in the units of polarized intensity.}
\dispt{ICUT\qs {\it mm\/} \CR}{to blank out vectors at pixels where
               the total intensity (image 1) is less than {\it mm\/}
               in the units of image 1.}
\dispt{DOFRACT\qs 1 \CR}{to convert the polarization lines to
               fractional polarization, dividing by the I image,
               before plotting.}
\dispt{FACTOR\qs {\it xx\/} \CR}{to set the length of a vector of 1
               (in units of total or fractional polarization) to {\it
               xx\/} cell widths.}
\dispt{DOCONT\qs 1 ; DOVECT\qs 1 ; DOGREY\qs 4\CR}{to request
               vectors plus contours of image 1 and grey scale of
               image 4.}
\dispt{PIXRAN\qs $T_{min}, T_{max}$ ; FUNCTYP\qs ' ' \CR}{to scale
               linearly the grey-scale values from $T_{min}$ to
               $T_{max}$.}
\dispt{OFMFILE\qs 'RAINBOW' \CR}{to use the standard rainbow-colored
               OFM table to pseudo-color the grey scales.}
\dispt{CBPLOT\qs 1 \CR}{to plot the Clean beam in the lower left
               corner.  See {\tt HELP CBPLOT} for numerous options.}
\dispt{PVPLOT\qs 4 \CR}{to plot a polarization vector of stated
              length in Jy/beam in a box in the upper left corner.}
\dispt{INP \CR}{to review your inputs and remind you of others.  Most
               are similar to those in {\tt CNTR} and sensibly
               defaulted.}
\dispt{GO \CR}{to generate the plot file, which can then be routed to
               output devices via {\tt TKPL}, {\tt TVPL}, {\tt LWPLA}
               etc.}
\dispe{Unless images 2 and 3 are of Q and U polarization, the lengths
of the vectors are controlled by image 2 while the directions of them
are controlled by image 3.  Clearly this program can also be used for
other combinations of images, so long as one of them represents an
angle. {\tt PCNTR} and following tasks have the option to draw an
image of the Clean beam under control of adverb {\tt CBPLOT}\@.
Polarization vectors may be plotted with the color representing the
angle.  The value of {\tt POL3COL}, if greater than zero, is that
angle represented in pure red from 0 to 180 degrees.  A color
``spray'' is plotted to calibrate the eye.  To clarify the length
scale of polarization vectors, a vector may be drawn in a box in an
image corner under control of {\tt PVPLOT} with the length of that
vector in Jy/beam shown in a text line below the plot.  The ability
to plot multiple spectral planes in colored contour or polarization
vectors was also added.  The adverb {\tt CON3COL} controls this
function.  The ability to select the colors of each contour level with
{\tt RGBLEVS} has been added.  These color functions are displayed at
the end of this chapter in the color pages.}

\begin{figure}
\centering
%\resizebox{\hsize}{!}{\gname{cntr}\hspace{0.3cm}\gname{pcntr}}
\resizebox{\hsize}{!}{\gbb{528,537}{cntr}\hspace{0.3cm}\gbb{536,545}{pcntr}}
\vfill
\vspace{6pt}
\hbox to \hsize{\hss {\tt \tndx{CNTR}} \hss \hss {\tt \tndx{PCNTR}}
          \hss}
\vspace{27pt}
%\resizebox{\hsize}{3.6in}{\gname{greys}\hspace{0.5cm}\gname{greysc}}
\resizebox{\hsize}{3.6in}{\gbb{537,562}{greys}\hspace{0.5cm}\gbb{536,600}{greysc}}
\vspace{6pt}
\hbox to \hsize{\hbox to 0.5\hsize{\hss{\tt \tndx{GREYS}}\hss}\hss
\hbox to 0.5\hsize{\hss{\tt GREYS} with contours \hss}}
\caption[Contour and grey-scale plots of an image]{Contour,
polarization, and grey-scale plots of an image}
\label{fig:imageplot}
\end{figure}

\begin{figure}
\centering
\resizebox{!}{3.6in}{\gbb{522,340}{greyspr}}
\caption[{\tt GREYS} with profiles]{{\tt \tndx{GREYS}} plot of the
output of {\tt \tndx{DFTIM}} with profiles at top and right-hand side
({\tt DOPROFIL = 3}).}
\label{fig:greyspr}
\end{figure}

     {\tt \Tndx{GREYS}} creates a \Indx{plot file} of the grey-scale
intensities in the first input image plane and, optionally, a contour
representation of a second input image plane.  Like the other
grey-scale plotting tasks, {\tt GREYS} can interpret a true-color
(RGB) image cube in its ``true'' colors.  Unlike the others, it can
construct the true-color image from 3 separate image planes.  A sample
set of inputs could be:
\dispt{TASK\qs 'GREYS' ; INP \CR}{to review the inputs.}
\dispt{DOCOLOR\qs 1 \CR}{to specify that a ``true-color'' image is to
       be plotted.}
\dispt{INDISK\qs {\it n1\/} ; GETN\qs {\it ctn1\/} \CR}{to select the
               red image.}
\dispt{IN3DISK\qs {\it n3\/} ; GET3N\qs {\it ctn3\/} \CR}{to select the
               green image.}
\dispt{IN4DISK\qs {\it n4\/} ; GET4N\qs {\it ctn4\/} \CR}{to select the
               blue image.}
\dispt{PIXRAN\qs $T_{minr}, T_{maxr}$ ; FUNCTYP\qs 'SQ' \CR}{to scale
               by a square-root function red values from $T_{minr}$ to
               $T_{maxr}$.}
\dispt{APARM\qs $T_{ming}, T_{maxg}, T_{minb}, T_{maxb}$ \CR}{to scale
               green and blue values similarly over ranges $T_{ming}$
               to $T_{maxg}$ and $T_{minb}$ to $T_{maxb}$,
               respectively.}
\dispt{BLC\qs 250 , 250 , 3 \CR}{to select the lower left corner and
               the plane in the first image.}
\dispt{TRC\qs 320 , 310 , 12 \CR}{to select the upper right corner in
               the first image and, with {\tt TRC(3)}, the plane in
               the second image.}
\dispt{DOCONT\qs TRUE \CR}{to specify that contours are to be drawn.}
\dispt{IN2D\qs {\it n2\/} ; GET2N\qs {\it ctn2\/} \CR}{to select the
               contour image.}
\dispt{PLEV\qs 0 ; CLEV\qs 0.005 \CR}{to select 5 mJy/beam contour
               increments.}
\dispt{LEVS\qs -3 , -1 , 1 3 10 30 100 \CR}{to plot contours at -15,
               -5, 5, 15, 50, 150, and 500 mJy/beam.}
\dispt{DOWEDGE\qs 2 \CR}{to plot a 3-color step-wedge along the
               right-hand edge; 1 for along the top and 0 for no
               wedge.}
\dispt{DOPROFIL\qs 1 \CR}{to plot a ``profile'' of the average of
               each column of the image.}
\dispt{DOTV\qs FALSE ; GO \CR}{to make the plot file.}
\dispe{In {\tt 31DEC25}, {\tt GREYS} has the added option of plotting a
``profile'' at the top averaging all values in each column of the image
and/or at the right averaging all values in each row of the image.  This
is illustrated in \Rfig{greyspl}.  New task {\tt \Tndx{PRPLT}} will plot
up to 3 profiles generated by averaging an image cube along 2 axes as a
function of the third axis.}

When {\tt GREYS} has finished, run {\tt LWPLA} to view the plot
file.  Note that {\tt LWPLA} has a variety of options which control
the plotting and scaling of the grey-scale images without having to
rerun {\tt GREYS}\@.  In this example case, you should remember to set
{\tt FUNCTYPE = ' '} and {\tt DPARM = 0} (or at least the first 4
values to 0) in {\tt LWPLA} to avoid additional scaling.  You may wish
to color the labeling, contours, and background with {\tt DOCOLOR=1}
and {\tt PLCOLORS} with {\tt LWPLA}.  The procedure {\tt
\tndx{TVCOLORS}} will set {\tt \tndx{PLCOLORS}} to match the TV
graphics-plane colors, {\tt \tndx{DEFCOLOR}} will set {\tt PLCOLORS}
to the standard TV colors even in the absence of a TV display and
{\tt \tndx{OKCOLORS}} will set colors which work well with a white
background, using less printer ink.  See examples on the color pages
at the end of this chapter.

     There are two other contour drawing tasks which offer additional
options.  {\tt \tndx{KNTR}} is able to draw multiple contour,
polarization, and/or grey-scale images in a single plot file,
primarily to show multiple planes of a spectral-line cube; see
\Sec{dispcube}.  {\tt KNTR} uses a different, and probably superior,
method of drawing the contour lines.  It also can use color to
represent different spectral channels and/or polarization angles or
simply different colors for the different contour levels.  {\tt
\tndx{CCNTR}} is virtually identical to {\tt CNTR} except that it can
draw extra symbols on the plot representing the locations and
intensities of source model components found in {\tt CC} (Clean
component) or {\tt MF} (model fit Gaussians from {\tt \tndx{SAD}}, see
\Sec{sad} and \Sec{sdmodel}).

\Subsubsections{Row tracing plots}{plotrow}

\begin{figure}
\centering
%\resizebox{!}{3.7in}{\gname{plrow}}
\resizebox{!}{3.7in}{\gbb{537,620}{plrow}}
\vfill
%\resizebox{!}{4.7in}{\gname{profl}}
\resizebox{!}{4.7in}{\gbb{548,445}{profl}}
\label{fig:rowplot}
\caption[Row plots of an image]{Row plots of an image with (bottom,
   {\tt PROFL}) and without (top, {\tt PLROW}) perspective}
\end{figure}

     There are a number of tasks which plot rows directly.  Two of
these are for use with single image planes while others are more
intended for use with, \eg\ spectral-line data cubes transposed into
velocity-ra-dec order.  Of the former, {\tt \tndx{PLROW}} is the
simpler.  It makes a plot file of all selected rows in an image plane.
Each row is plotted as a slice offset a bit from the previous row.
Low intensities which are ``obscured'' by foreground (\ie\ lower row
number) bright features are blanked to keep the plot readable.
Example inputs would be:
\dispt{TASK\qs 'PLROW' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to select the
               image on disk {\it n} catalog slot {\it ctn\/}.}
\dispt{BLC\qs 100 ; TRC 300 \CR}{to select the sub-image from (100, 100)
               to (300, 300).}
\dispt{YINC\qs 3 \CR}{to plot only every $3^{\urd}$ row.}
\dispt{PIXRANGE\qs -0.001 0.050 \CR}{to clip intensities outside the
               range $-1$ to 50 mJy.}
\dispt{OFFSET\qs 0.002 \CR}{to set the intensity scaling such that 2
               mJy separates rows of equal intensity.}
\dispt{INP \CR}{to check the inputs.}
\dispt{GO \CR}{to run {\tt PLROW}.}
\dispt{GO\qs LWPLA \CR}{to display the plot file on the laser printer
               after {\tt PLROW} has finished.}
\dispe{The plot files produced by {\tt PLROW} are a simple, special
case of those produced by {\tt \tndx{PROFL}}\@.  This task makes
a plot file of a ``wire-mesh'' representation of an image plane
complete with user-controlled viewing angles and correct perspective.
Enter {\us EXPLAIN PROFL \CR} for a full description.  Both of these
tasks are especially useful where the signal-to-noise ratio is high
and examples of them are given in \Rfig{rowplot}.\Iodx{plot file}}

     In \Rchap{line} we discuss the computation and use of ``slices,''
one-dimensional profiles interpolated along any line in an image
plane.  Once a slice has been computed, it may be plotted by {\tt
\tndx{SL2PL}} on the TV or into a device-independent \Indx{plot file}.

     Three other row-plotting tasks, {\tt \tndx{PLCUB}}, {\tt
\tndx{ISPEC}}, and {\tt\tndx{BLSUM}}, are designed primarily for
spectral-line and other data ``cubes'' (see \Sec{dispcube} and
\Sec{lineanal}).  {\tt PLCUB} makes one or more plot files showing the
intensities in each selected row.  The row subplots are positioned in
a matrix in the coordinates of the $2^{\und}$ and $3^{\urd}$ axes of
the cube.  {\tt ISPEC} averages circular or rectangular areas in each
plane of a cube and plots the resulting spectrum.  It can also save the
output in a {\tt SL}ice file.  {\tt \tndx{RSPEC}} does the same except
that it plots the robust or median absolute deviation (``MAD'') rms in
each plane rather than the data.  {\tt RSPEC} has options to write out a
signal-to-noise image and/or a text file of channel weights as well.
{\tt BLSUM} can plot spectra from irregular regions selected on the TV
with a ``blotch'' algorithm.

\Subsubsections{Miscellaneous image plots}{plotmisc}

\begin{figure}
\centering
%\resizebox{\hsize}{!}{\gname{imvim}\hspace{0.25cm}\gname{imean}}
\resizebox{\hsize}{!}{\gbb{496,518}{imvim}\hspace{0.25cm}\gbb{522,567}{imean}}
\vspace{12pt}
\hbox to \hsize{\hss {\tt \tndx{IMVIM}} (binned) \hss \hss {\tt
         \tndx{IMEAN}} \hss\Iodx{plot file}}
\caption[Statistical plots of an image]{Plots of statistical
   parameters of an image.}
\label{fig:miscplot}
\end{figure}

     {\tt \tndx{IMVIM}} allows a variety of image comparisons by
plotting the pixel values of one image against the pixel values of
another image. The special options include binning the values (and
plotting symbols proportional to the number of samples in a bin) and
shifting one of the images in {\it x\/} and/or {\it y\/} with respect
to the other.  The former reduces large scatter diagrams to more
manageable sets of numbers while the latter allows cross-correlation
functions to be developed.

     {\tt \tndx{IMEAN}} prints the mean, rms, and extrema inside or
OUTSIDE a user-specified window in an image.  It also prints the
intensity at, and rms of, the noise peak in the histogram and
returns these values as adverbs to {\tt AIPS}\@.  It also returns an
array in which {\tt TRIANGLE($i$)} is the brightness level above which
there are $i$ per cent of the image pixels.  This is often useful in
setting {\tt PIXRANGE} for \indx{optical} images.  Optionally, {\tt
IMEAN} plots histograms of image intensities over the window using a
user-specified number of summing cells over a user-specified range of
intensities.  Optionally, it also plots the fit to the noise peak on the
user-specified histogram.  An example of this is also shown
in \Rfig{miscplot}.

\subsections{Plotting your table data}

\begin{figure}
\centering
%\resizebox{\hsize}{!}{\gname{sl2pl}\hspace{0.5cm}\gname{taplt}}
\resizebox{\hsize}{!}{\gbb{537,572}{sl2pl}\hspace{0.5cm}\gbb{518,562}{taplt}}
\vspace{12pt}
\hbox to \hsize{\hss {\tt \tndx{SL2PL}} \hss \hss {\tt \tndx{TAPLT}}
    \hss}
\caption[Slice and table plots]{Slice and table plots.}
\label{fig:plotslta}
\end{figure}

     {\tt \tndx{TAPLT}} is a very general task to plot information
from \AIPS\ table extension files.  It can plot a histogram of a
function of the values in one or two columns of the table and it can
plot a function of one or two columns against another function of
another one or two columns.  The latter can be summed or averaged in
bins or have every point plotted.  At first blush, the inputs seem
rather complicated, but the results may well justify some effort to
understand them. For example, to plot Clean component fluxes as a
function of radius from the image center:
\dispt{TASK\qs 'TAPLT' ; INP \CR}{to review the inputs.}
\dispt{INDISK\qs {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to select the
               image on disk {\it n\/} catalog slot {\it ctn\/}.}
\dispt{INEXT\qs 'CC' ; XINC\qs 1 \CR}{to select every row in the Clean
               components file.}
\dispt{BCOUNT\qs 1 ; ECOUNT\qs 0 \CR}{to select all rows in the
               table.}
\dispt{APARM = 2 , 1, 3 , 1 , 16 , 1 , 1 \CR}{to plot the modulus of
               columns 2 and 3 on the {\it x\/} axis (\ie\
               $\sqrt{\Delta_x^2 + \Delta_y^2}\,$) and column 1 on the
               {\it y\/} axis (\ie\ component flux).}
\dispt{BPARM = 0 ; CPARM = 0 \CR}{to use self-scaling of the plot and
               no scaling of the column values.}
\dispt{DOTV\qs TRUE ; GO}{to plot the fluxes on the TV screen.}
\dispe{You may need to set the scaling with {\tt BPARM} after seeing
the preview plot in order, for example, to bring out the details in
the low-level components.}

     There are a few tasks intended to make plotting specific kinds of
tables rather easier.  {\tt \tndx{SNPLT}} plots calibration, solution,
system temperature and EVLA SysPower tables for selected antennas as a
function of time, antenna elevation, hour angle, azimuth, or sidereal
time.  It will make several plots per page (one antenna per plot) and
multiple pages if needed, or you can plot the most discrepant value
over all antennas in a single plot.  In one execution, polarizations
and IFs may be plotted on separate plots or together on the same plots,
optionally separated by color.  {\tt SNPLT} also has the option to
separate sources by color instead.  You can also plot multiple parameter
types in the same execution.  {\tt \Tndx{SNBLP}} plots calibration
solutions much like {\tt SNPLT}, but on a baseline basis, to investigate
exactly how the solutions affect the visibility data.
{\tt \tndx{SNIFS}} is similar to {\tt SNPLT} but is intended to compare
solutions at different IFs, plotting the IF on the $x$ axis with a
variety of binning options.

{\tt \tndx{POSSM}} will plot bandpass tables when {\tt APARM(8)} is
set to 2.  Values 3 -- 10 plot bandpass-like tables from {\tt BLCHN}
({\tt BD}), {\tt PCAL} ({\tt PD} antenna polarization and {\tt CP}
source polarization), VLB pulse-cal ({\tt PC}), and {\tt RLDIF} ({\tt
PP} phase difference).  {\tt POSSM} can also do multiple plots per page
with all the usual data selection adverbs.  {\tt \tndx{BPLOT}} also
plots {\tt BP} and the other similar tables, with multiple times for one
antenna or multiple antennae for one time on each plot.  Combined with
difference and coloring options, this allows close comparison of
bandpasses as functions of time or antenna.  {\tt \Tndx{BLPLT}} makes
a similar plot of the {\tt BL} table written by {\tt BLCAL}\@.
{\tt \tndx{BPEPL}} overplots multiple times within a {\tt BP} table
using color to separate times.  It is similar to {\tt BPEDT} without
the interactivity.  In {\tt 31DEC23}, {\tt \tndx{BPPLT}} plots selected
portions of bandpass tables as a function of time in a manner similar to
{\tt SNPLT}\@.  It is particularly useful when {\tt BPASS} is used
instead of {\tt CALIB} to provide the gain calibration.  {\tt
\tndx{WETHR}} plots the data in a {\tt WX} weather table including
parameters computed from those data such as relative humidity.  {\tt
\tndx{FGPLT}} plots the times of selected flags from a flag table.
{\tt \tndx{PRTAN}} can plot antenna locations.  Task {\tt TEPLT} may
be used to plot the ionospheric Faraday rotation and other parameters
used by {\tt TECOR} and written in a {\tt TE} table.  New tasks
{\tt ALBUS} and {\tt RIFRM} also write the {\tt TE} table filling in
some of the columns.

\subsections{Plotting miscellaneous information}

     There are a few other tasks which create \Indx{plot file}s, but
which do not fit into the categories above.  The most general of these
is {\tt \tndx{PLOTR}} which can plot up to 30 sets of {\it (x,y)\/}
points input from a text file with coloring options.  In {\tt
31DEC25}. {\tt PLOTR} can also read and plot a column of error bars if
desired.  Task {\tt \tndx{PCHIS}} also reads a text file to produce a
histogram plot of the values in any selected column of the file.
{\tt \tndx{CONPL}} is a task which plots \AIPS\ convolving functions
(used by various \uv-data gridding tasks such as {\tt \tndx{IMAGR}}) and
their Fourier transform, expected signal-to-noise ratio, or convolution
with a user-specified Gaussian.  {\tt \tndx{IRING}} integrates an image
in concentric annuli about the user-specified object center with
specified major axis position angle and inclination.  The results may
be placed in a plot file for later display.  {\tt \tndx{GAL}}
calculates the orientation and rotation curve parameters of a galaxy
from an image of the predominant velocities.  The observed rotation
curve is plotted together with the fitted model curve.  {\tt
\tndx{LOCIT}} fits antenna location corrections to {\tt SN} tables;
the residual phases may be plotted as a function of sample number.

There are several tasks which create RGB cubes for later display by
tasks such as {\tt GREYS} and {\tt KNTR}\@.  These include {\tt
\tndx{RGBMP}} which does a weighted sum of the planes of a data cube,
{\tt \tndx{HUINT}} which uses two images as hue and intensity to
construct an RGB cube, and {\tt \tndx{TVHUI}} which interactively uses
three images as intensity, hue, and saturation to construct an RGB
cube by a different algorithm.  Task {\tt \tndx{SCLIM}} will scale and
clip image planes to be used as inputs to {\tt \tndx{LAYER}}, which
produces an RGB cube from the colored sum of up to 10 input image
planes using a complicated and general algorithm.

%\vfill\eject
\Sects{Interactive TV displays of your data}{TVinter}

     The \AIPS\ TV display allows you to look at your image data in
detail and to set parameters by pointing at interesting features
visible on the screen.  Although \AIPS\ will run on a variety of
hardware display devices (\eg\ \IIS\ Models 70, 75 and IVAS and
DeAnza), it is now used almost exclusively with the X-Windows
TV-simulation program called {\tt \tndx{XAS}}\@.  See \Sec{xas}
for information on using this basic \AIPS\ tool.  If the {\tt XAS}
window has closed for any reason, you may restart it without exiting
{\tt AIPS} with the verb {\tt \Tndx{STARTTV}} or
{\tt \Tndx{TVRESTOR}}\@.  Information on TV verbs and tasks may be found
by entering {\us ABOUT TV \CR}, {\us ABOUT INTERACT \CR}, and {\us ABOUT
TV-APPL \CR}, or by consulting the corresponding sections
of \Rchap{list} of this \Cookbook. \Iodx{TV functions}

\Subsections{Loading an image to the TV}{TVload}

     The simplest way to load an image from your catalog to the TV and
then to manipulate the display is with the procedure called {\tt
\tndx{TVALL}}:
\dispt{INP\qs TVALL \CR}{to review the input parameters.}
\dispt{INDI\qs {\it n\/} ; GETN\qs {\it ctn\/} \CR}{to select the disk
             and image name parameters from the catalog.}
\dispe{Use one of the following commands to specify the initial
transfer function that converts your image file intensities to display
pixel intensities:}
\dispt{FUNC\qs 'LN' \CR}{linear---this is the default.}
\dispt{FUNC\qs 'LG' \CR}{logarithmic.}
\dispt{FUNC\qs 'L2' \CR}{``extra'' logarithmic.}
\dispt{FUNC\qs 'SQ' \CR}{square-root, often a good compromise}
\dispt{FUNC\qs 'NE' \CR}{negative linear.}
\dispt{FUNC\qs 'NG' \CR}{inverse logarithmic.}
\dispt{FUNC\qs 'N2' \CR}{inverse ``extra'' logarithmic.}
\dispt{FUNC\qs 'NQ' \CR}{negative square root.}
\dispt{PIXRA\qs {\it x1\/}, {\it x2\/} \CR}{to load only image
             intensities {\it x1\/} to {\it x2\/} in the units of the
             image.  The default is to load the full range of
             intensities in the image.}
\dispe{(The slopes and intercepts of the display transfer functions
can be modified later, but the above options let you choose initially
between linear, square-root, logarithmic, and  negative displays and
restrict the range of intensities that is loaded).  Then:}
\dispt{TVALL \CR}{to load the selected image.}
\dispe{The image should appear on the TV screen in black-and-white.
If you see a new image but it is not what you expected, hit button
{\tt D} to end {\tt TVALL} and then review your inputs with:}
\dispt{INP\qs TVALL \CR}{ }
\dispe{If no image appears, make sure that {\tt AIPS} started up with
your workstation assigned as the display; see \Sec{stAIPS} for
information on starting up {\tt AIPS} and assigning the TV display.}

     After your image has been displayed on the TV by {\tt TVALL},
your trackball with its buttons (which should be labeled {\tt A}, {\tt
B}, {\tt C}, and {\tt D}) --- or your workstation mouse with keyboard
buttons {\tt A}, {\tt B}, {\tt C}, and {\tt D}) --- can be used to
modify the display transfer functions, coloring and zoom.  Pressing
button {\tt A} alone enables black-and-white and color-contour coding
of the image intensities, successively.  Adjust the cursor position on
the TV (using the trackball or mouse) to vary the slope and intercept
of the display transfer function.  {\tt TVALL} will superpose a
calibrated horizontal wedge on the image.  This should help you to
choose the optimum cursor setting for the display.  Black-and-white
displays are generally much more suitable than color for
high-dynamic-range images, while color contouring may be used to
accentuate interesting features.  (Note also that a much wider range of
image-coloring options is available outside {\tt TVALL} by invoking
{\tt \tndx{TVPSEUDO}}, {\tt \tndx{TVPHLAME}}, and {\tt
\tndx{TVHELIX}}\@.)  Pressing buttons {\tt B} and {\tt C} adjusts the
zoom of the display: {\tt B} to increase the magnification and {\tt C}
to decrease it.  When these buttons are enabled, the cursor controls
the position of the center of the zoomed field of view.  Magnification
factors of 1 through 16 are available on most workstations.  Note that
your terminal issues instructions when buttons are pressed, but that
it is in the death-like grip of {\tt TVALL} otherwise until you press
button {\tt D} to exit from it.

     The size of the image which can be displayed depends on the size
(in pixels) of your workstation screen or TV display and some other
parameters which can vary from site to site.  A typical Sun
workstation can display up to 1024 by 900 pixels.  Then, if the image
is larger than about 800 pixels or so in the {\it y\/}-direction,
portions of the labeling of the wedge (the units) will be omitted or
superposed on top of the wedge (the tick numeric values).  A useful
technique for displaying large images is to load only alternate
pixels.  The command:
\dispt{TXINC\qs 2 ; TYINC\qs 2 \CR}{to load every other {\it x\/} and
          {\it y\/} pixel.}
\dispe{before {\tt \tndx{TVALL}} would do this.  Also use:}
\dispt{TBLC = {\it n1\/}, {\it n2\/}, {\it n3\/}, $\ldots$ \CR}{bottom
          left pixel to load.}
\dispt{TTRC = {\it m1\/}, {\it m2\/}, {\it n3\/}, $\ldots$ \CR}{top
          right pixel to load.}
\dispe{to limit the displayed field.  A small image may be interpolated
to fill the TV screen by setting {\us TXINC = -1 ; TYINC = -1 \CR}.
Recent versions of {\tt XAS} allow the verb {\tt \tndx{TVROAM}} to
function again.  This verb loads adjacent portions of an image to as
many as 16 memories and then ``roams'' with a split screen to allow
you to view any contiguous portion of the loaded image.  {\tt
\tndx{REROAM}} resumes roaming an already loaded roam-mode image,
perhaps after adjustment of the transfer function of all channels with
{\tt TVTRANSF} and {\tt TVCHAN = 0}.  The verb {\tt \tndx{ROAMOFF}}
allows you to convert the final split-screen image into a normal, more
useful single-plane image.}

     {\tt TVALL} is a procedure that insures that the desired graphics
and TV channels are on and cleared and the others off, then loads the
image with verb {\tt \tndx{TVLOD}}, loads a wedge with {\tt
\tndx{TVWEDGE}}, and labels the wedge with {\tt \tndx{TVWLABEL}}\@.
You do not have to use {\tt TVALL}, which can be rather slow, simply
to load a new image on the TV\@.  Use {\tt TVLOD} instead.  {\tt
TVWEDGE} has a variety of options concerning the width of the wedge
and its position and direction; type {\us HELP TVWED \CR} for details.
\Iodx{TV functions}

     The task {\tt \Tndx{TVHLD}} was completely revised to load images
to the TV with histogram equalization.  The task has interactive
controls over the intensity range and method of computing the histogram
and can write out a histogram-equalized image in arbitrary, non-physical
units for display by the various plotting tasks.

%\vfill\eject
\subsections{Manipulating the TV display}

      There are a number of verbs which allow you to manipulate the
display, including:
\dispt{\Tndx{STARTTV} \CR}{to start the TV, message, and Tektronix
         servers when one or more of them have exited.}
\dispt{\tndx{TVINIT} \CR}{to initialize the entire TV and TV image
         catalog.  The image catalog is now kept in {\tt XAS} and so
         is always current.}
\dispt{\tndx{TVON} {\it n\/} \CR}{to turn on TV grey channel(s) with
        {\it n\/} being a bit pattern of the desired channels:
        $2^{(i-1)}$.  Thus {\tt TVON 4} turns on channel 3.  You may
        have to turn off other channels to see the desired channel,
        since the sum of two images may be rather odd.}
\dispt{\tndx{TVOFF} {\it m\/} \CR}{to turn off channel {\it m\/},
         where {\it m\/} is a bit pattern as with {\tt TVON}\@.}
\dispt{\tndx{GRON} {\it n\/} \CR}{to turn on one or more of the 8
         graphics channels, where {\it n\/} is a bit pattern.}
\dispt{\tndx{GROFF} {\it m\/} \CR}{to turn off one or more graphics
          channels.}
\dispt{TVCHAN\qs {\it n\/} ; \tndx{TVCLEAR} \CR}{to zero a TV
         channel.}
\dispt{GRCHAN\qs {\it m\/} ; \tndx{GRCLEAR} \CR}{to zero a graphics
         channel.}
\dispt{\tndx{TVZOOM} \CR}{to set the zoom magnification and center
          interactively, follow instructions on the screen.}
\dispt{\tndx{OFFZOOM} \CR}{to reset the zoom and zoom center to null.}
\dispt{\tndx{GREAD} \CR}{to read the current color of a specified
              graphics overlay channel into {\tt RGBCOLOR}\@.}
\dispt{\tndx{GWRITE} \CR}{to change the color of a graphics overlay
              channel to that specified by  {\tt RGBCOLOR}\@.  This
              may be done for aesthetic reasons or because the default
              colors may not show up well when captured by {\tt TVCPS}
              and printed on a color printer.}
\dispt{\tndx{TVPOS} \CR}{to read the TV cursor position, returning
          adverbs for use in procedures or other verbs.}
\dispt{\tndx{IM2TV} \CR}{to convert an image pixel in {\tt PIXXY} to
          the corresponding TV pixel.}
\dispt{\tndx{TVDATA} \CR}{to display lots of information about your
          current TV display.}
\dispt{\tndx{TVFACTS} \CR}{to display lots of information about your
          current TV display.}
\pd

\Subsections{Intensity and color transfer functions}{tvofmlut}

     The \AIPS\ model of a TV postulates two intensity transfer
functions, called the LUT and the OFM, which are basically
multiplicative.  In most circumstances, the LUT is used for
black-and-white enhancements and the OFM for coloring, but both can be
used for either.  To manipulate the LUT interactively, while leaving
the pseudo-coloring alone, use the {\tt \tndx{TVTRANSF}} verb.  The
cursor position controls the slope and intercept of the transfer
function, buttons {\tt A} and {\tt B} switch a plot of the transfer
function on and off, button {\tt C} switches the sign of the slope,
and button {\tt D} (as always) exits.  In {\tt 31DEC21}, verb
{\tt \Tndx{TVBANDW}} implements 3 types of black-and-white modifications
of the LUT: a series of step wedges, sine waves, or stairs in intensity.
To turn the LUT back to normal, enter {\tt \tndx{OFFTRAN}}\@.

     A rich zoo of color coding is available with {\tt
\tndx{TVPSEUDO}}, which alters the OFM while leaving the LUT alone.
Repeated hits on button {\tt A} select a variety of color triangles,
button {\tt B} selects a circle on hue, and repeated hits on button
{\tt C} select a variety of color contours.  First-time users should
experiment with the \AIPS\ coloring options until they develop an
intuitive feel for the effects of cursor settings on the image
appearance.  The wedge displayed by {\tt \tndx{TVALL}} adjusts to the
alternative colorations selected with {\tt TVPSEUDO}, and it is
helpful to watch changes in both the wedge and the image.  A
flame-like coloring is available with {\tt \tndx{TVPHLAME}}, or
variations on the scheme with repeated hits on buttons {\tt A} or
{\tt B}\@.  {\tt \tndx{TVHELIX}} does a helix in color space
attempting to make a monotonic increase in perceived intensity.  The
buttons change direction, number of rotations, and saturation.
For images that have significant negative and positive values,
{\tt \Tndx{TV2COLOR}} uses two color wedges increasing away from
the user-adjusted central value.  In these verbs the cursor position
controls aspects of the coloring such as enhancements, richness, or
cycles of hue.  To turn off pseudo-coloring, enter
{\tt \tndx{OFFPSEUD}}\@.

     A set of less well-known verbs is available to allow you to
create, manipulate, and save desirable versions of the OFM table.
{\tt \tndx{OFMSAVE}} allows you to save a named OFM, {\tt
\tndx{OFMDIR}} lists all saved OFMs belonging to you or generally
available from the \AIPS\ distribution, {\tt \tndx{OFMGET}} loads a
named OFM, {\tt OFMZAP} deletes a named OFM, and {\tt OFMLIST} prints
the current OFM\@.  {\tt \tndx{OFMCONT}} is an elaborate interactive
verb which allows you to set the hue, intensity, and saturation of the
OFM divided up into a number of color contours. Each of these contours
can be a constant level or a step wedge.  {\tt OFMADJUS} is another
elaborate interactive verb to alter pieces of the OFM, while {\tt
\tndx{OFMTWEAK}} is a simpler verb to stretch the OFM\@.\Iodx{TV
functions}

\begin{figure}
\centering
\resizebox{!}{3.75in}{\gbb{550,343}{ofmpl}}
\label{fig:ofmpl}
\caption[{\tt OFMPL} step wedge display]{Example step wedge display
   from {\tt OFMPL}}
\end{figure}

The OFM received particular attention in {\tt 31DEC25}\@.  A
significant number of OFM tables described on the Internet were
adapted and added to the \AIPS\ distribution.  A new pseudo-coloring
verb {\tt \Tndx{OFMCOLOR}} was added to {\tt AIPS} and to the menus of
multiple image-display tasks such as {\tt TVSPC} and {\tt XGAUS}\@.
This function begins by loading one of the new OFMs.  You may then
select different OFMs by hitting buttons A, B, or C.  Each button
selects from a list of 10 of the new OFMs.  Having selected an OFM, you
may then shift the center of the function using the horizontal position
of the cursor.  Another new verb {\tt \Tndx{OFMSTRCH}} does this
stetching of the current OFM outside of {\tt OFMCOLOR}\@.  To view the
available OFMs distributed with \AIPS\ plus any that you may have
developed, the new task {\tt \Tndx{OFMPL}} was developed.  It has three
displays: up to 4 step wedges, a plot of the red, green, and blue parts
of the OFM, and an optional image colored by the OFM\@.  All three of
these show a menu at the top of the TV listing all available OFMs plus
items to select the desired display.  See an example in \Rfig{ofmpl}.

%\vfill\eject
\Subsections{Setting parameters with the TV}{TVparm}

     One reason to load the image to the TV is to set adverbs for use
by other verbs and tasks.  Verbs which use the TV cursor to set
adverbs include:
\dispt{\tndx{TVNAME} \CR}{to set {\tt INDISK}, {\tt INNAME}, etc.~to
            the name parameters of the image currently visible.  If
            there is an ambiguity, you will be asked to move the
            cursor to the desired image and press a button.}
\dispt{\tndx{MFITSET} \CR}{allows you to set the adverbs for {\tt
            \tndx{IMFIT}} and {\tt \tndx{JMFIT}}, namely the image
            name parameters, window, and initial guesses for the
            Gaussians from the image on the TV.}
\dispt{\tndx{SETXWIN} ({\it dx\/},{\it dy\/}) \CR}{reads pixel
            coordinate of the center of a {\it dx\/}-pixel by {\it
            dy\/}-pixel window and sets the adverbs {\tt BLC} and {\tt
            TRC}.}
\dispt{\tndx{TVWIN} \CR}{reads pixel coordinates from the next two
            cursor positions at which a trackball button is depressed.
            The TV graphics shows the current shape and position of
            the window.  Button A allows you to switch to (re)setting
            the other corner while the other buttons exit after both
            corners have been set. {\tt TVWIN} uses the pixel
            coordinates to set up the bottom left ({\tt BLC}) and top
            right ({\tt TRC}) corners of an image subsection, \eg\ for
            input to the contouring programs {\tt CNTR} and {\tt
            PCNTR}, to the mean/rms calculator {\tt IMEAN}, and to
            many other tasks.}
\dispt{\tndx{SETSLICE} \CR}{works like {\tt TVWIN} above to set {\tt
            BLC} and {\tt TRC}\@.  Instead of a rectangle however, the
            display shows a diagonal line which is useful for setting
            the ends of slices.}
\dispt{\tndx{TVBOX} \CR}{is similar to {\tt TVWIN} above except that
            it is used to set up pixel coordinates to define
            rectangular {\it or circular\/} Cleaning areas for the
            \AIPS\ Clean tasks.  The adverbs {\tt NBOXES} and {\tt
            CLBOX} are set. The circular option appeared in the {\tt
            15JUL95} release and is not supported by {\tt
           \tndx{APCLN}}\@.}
\dispt{\tndx{REBOX} \CR}{allows revision using the TV of the Cleaning
            areas set previously with {\tt TVBOX}.  Revises {\tt
            NBOXES} too.}
\dispt{\tndx{DELBOX} \CR}{allows deletion using the TV of the Cleaning
            areas set previously with {\tt TVBOX}.  Revises {\tt
            NBOXES} too.}
\dispt{\tndx{FILEBOX} \CR}{is {\tt REBOX} for boxes in the text file
            used with {\tt \tndx{IMAGR}}; multiple fields and many
            more boxes are allowed.}
\dispt{\tndx{DFILEBOX} \CR}{is {\tt DELBOX} for boxes in the text file
            used with {\tt \tndx{IMAGR}}; multiple fields and many
            more boxes are allowed.}
\pd

Task {\tt \tndx{FILIT}} performs {\tt FILEBOX} and much more on a set
of images, usually the multiple facets of a wide-field imaging.  It
offers a wide range of image display options including handling images
larger than the TV, allows editing of the box information, creates
boxes via the auto-boxing algorithm, and checks the multiple facets
for overlapping boxes.  This new task may be the quickest and easiest
way to review a set of facet images.

%\eject
\Subsections{Reading image values from the TV}{TVvalue}

     There are several facilities for reading out intensity and
position information from displayed images using the TV cursor:
\dispt{\tndx{IMPOS} \CR}{displays the two coordinate values (\eg\ RA
              and Dec) from the cursor position when any button is
              depressed.  Adverbs {\tt TVBUT} and {\tt COORDINA} are
              returned.}
\dispt{\tndx{IMXY ; IMVAL} \CR}{displays the image intensity and the
              two coordinate values (\eg\ RA and Dec) from the cursor
              position when any button is depressed.  Adverbs {\tt
              PIXXY}, {\tt TVBUT}, {\tt PIXVAL}, and {\tt COORDINA}
              are set.}
\dispt{\tndx{CURVALUE} \CR}{continuously displays (in the upper-left
              corner of the TV) the pixel coordinates and the image
              intensity in user-recognizable units at the position
              selected by the TV cursor.}
\dispt{\tndx{TVFLUX} \CR}{displays image intensities and coordinates
              whenever a TV button is pressed, looping until button
              {\tt D} is pressed.  Adverbs for the first image name
              are set as well as {\tt PIXXY}, {\tt TVBUT}, {\tt
              PIXVAL}, and {\tt COORDINA} for the last pixel
              selected.}
\dispt{\tndx{TVDIST} \CR}{displays the angular length and position
              angle of the spherical vector between two pixels in one
              or two images shown on the TV\@.  Name adverbs for input
              files 1 and 2 are set as well as adverbs {\tt PIXXY},
              {\tt PIX2XY} and {\tt DIST}.}
\dispt{\tndx{TVMAXFIT} \CR}{whenever a TV button is pressed, fits a
              quadratic function to the image to find the position and
              strength of an extremum, looping until button D is
              pressed.  Adverbs for the first image name are set as
              well as {\tt PIXXY}, {\tt TVBUT}, {\tt PIXVAL}, and {\tt
              COORDINA} for the last object selected.}
\dispt{\tndx{TVSTAT} \CR}{determines the mean, rms, extrema and
              integrated intensity (if appropriate) in user-defined
              ``blotch'' regions within the image currently displayed
              on the TV\@. The regions are irregular polygons
              selected with the TV cursor.  Type {\us EXPLAIN\qs
              TVSTAT \CR} for details.  Adverbs {\tt PIXAVG}, {\tt
              PIXSTD}, {\tt PIXVAL}, {\tt PIXXY}, {\tt PIX2VAL}, and
              {\tt PIX2XY} are set.}
\dispt{\tndx{COPIXEL} \CR}{to convert between pixel and astronomical
              coordinates for an image; allows determination that a
              coordinate is not inside an image.}
\pd

\subsections{Labeling images on the TV}

     There are a number of facilities for labeling images on the TV
including:\Iodx{TV functions}
\dispt{\tndx{CHARMULT} /CR}{to scale the character size used by the TV
              by 1 through 5 times the standard size which is 7 by 9
              pixels.  Many menu-driven interactive tasks include this
              option when run on larger TV displays.}
\dispt{\tndx{TVLABEL} \CR}{to draw standard axis labels around the
              visible image.  You may control the type of labeling and
              whether coordinates are shown as a grid or short tick
              marks.  A Clean beam may be plotted.  If more than one
              image is visible, you will be asked to indicate which one
              you want with the cursor and any button.}
\dispt{\tndx{TVWLABEL} \CR}{to draw axis labels around the visible
              intensity wedge.}
\dispt{\tndx{TVANOT} \CR}{to draw a text string into a grey-scale
              channel or a graphics plane at a location specified via
              an adverb or via the TV cursor.}
\dispt{\tndx{TVLINE} \CR}{to draw a straight line into a grey-scale
              channel or a graphics plane at locations specified in
              part or in whole via adverbs or via the TV cursor.}
\dispt{\tndx{TVILINE} \CR}{to draw a straight line into a grey-scale
              channel or a graphics plane between two image pixel
              coordinates.}
\dispt{\tndx{COSTAR} \CR}{to plot a ``star'' positions at a
              user-specified coordinate on the TV image.}
\dispt{\tndx{TVSTAR} \CR}{to plot ``star'' positions from an {\tt ST}
              file on top of the visible image; see \Sec{plotimag}.}
\pd

\vfill\eject
\Subsections{Comparing images on the TV}{TVcompare}

     It is often useful to compare two images, \eg\ to decide whether
one contains artifacts that are not present in another at the same
frequency, or to look for frequency-dependent features at constant
resolution.  \AIPS\ provides several tools for such image comparisons.
\Iodx{TV functions}

      The first tool is a capability for loading multiple images to
the same plane (or channel) of the TV device.  The parameter {\tt
TVCORN} specifies where the bottom left corner of the image or image
subsection will be positioned in the TV frame by {\tt \tndx{TVLOD}} or
{\tt TVALL}\@.  If {\tt TVCORN} is left at zero, {\tt TVLOD} and
{\tt TVALL} adjust it to center the displayed image.  You may however
use {\tt TVCORN} to control loading successive images to different
regions of the display with successive executions of {\tt TVLOD}\@.
For example, the following commands would load two 512 by 512 pixel
images from slots 1 and 2 on disk 1 {\it side-by-side\/} on channel 1
of a 1024 by 900 TV display:
\dispt{INDI\qs 1; GETN\qs 1 \CR}{to select the input disk and the
            first image.}
\dispt{TVCH\qs 1 \CR}{to select TV channel 1 for the loading.}
\dispt{TVCORN\qs 1 193 ; TVLOD \CR}{to load the first image.}
\dispt{GETN\qs 2 \CR}{to select the second image.}
\dispt{TVCORN\qs 513 193; TVLOD \CR}{to load the second beside the
            first.}
\dispe{You could then adjust the color coding, transfer function,
etc.~for both images simultaneously with {\tt TVFIDDLE} or {\tt
\tndx{TVTRAN}}\@. You may load as many as 256 images to a single TV
plane with this technique, which is therefore a powerful method for
making ``montages.''  The number of simultaneous images is limited
mostly by your image sizes, the need to avoid overlaps (which are
allowed if you want) --- and your ability to do the arithmetic for
appropriate {\tt TVCORN} settings!  You are also limited by the need
for all the images in one plane to share that plane's transfer
function. Judicious use of the {\tt PIXRANGE} and {\tt FUNC} inputs to
{\tt TVLOD} permits making useful montages of disparate images,
however.}

     A second tool is the classic ``blink" technique from optical
astronomy.  {\tt \tndx{TVBLINK}} allows you to load images to two
different planes of the TV memory and then to alternate the display
rapidly between the two.  The two images described above could
be ``blinked'' against each other by the following command sequence:
\dispt{INDI 1; GETN 1 \CR}{to select the input disk and first image.}
\dispt{TVINIT; TVCORN 0}{to clear the TV and restore the default
               positioning.}
\dispt{TVCH 1; TVLOD \CR}{to load the first image on plane 1.}
\dispt{GETN 2 \CR}{to select the second image.}
\dispt{TVCH 2 ; TVLOD \CR}{to load the second image on plane 2.}
\dispt{TV2CH 1 ; TVBLINK \CR}{to blink planes 1 and 2.}
\dispe{The rate and duty cycle of the blinking, and the transfer
functions applied to the planes, are controlled interactively with the
TV cursor.  Instructions for these operations appear on your terminal
while {\tt TVBLINK} is running.}

     The task {\tt \tndx{PLAYR}} provides a menu-driven method to
enhance and blink two images and to develop and save TV color tables
(``OFMs'').

     For data cubes (\eg\ frequency or time sequences of images), the
verbs {\tt \tndx{TVMOVIE}} and {\tt \tndx{TVCUBE}} combine the two
previous techniques.  These are described in more detail in
\Sec{dispcube}.  Both verbs load one or more image planes with as many
planes from the cube as possible (and as requested).  Then they
display each frame in sequence with interactive controls over the
frame rate in movie mode, the chosen frame in single-frame mode, and
the brightness, contrast, and color of the displayed images.  {\tt
TVMOVIE} makes a somewhat more efficient movie sequence, but {\tt
TVCUBE} makes a better montage by using a more normal arrangement of
the image planes.  The {\tt DOALL} adverb allows these verbs to loop
over more than just the third axis if the ``cube'' has more than three
multi-pixel dimensions.

     Certain real TV displays used to provide powerful tools to
compare images using color as well as intensity to represent real
information.  {\tt XAS} implements some of these tools on workstations
capable of displaying a virtually unlimited number of colors.  Perhaps
the most powerful of these is the ``hue-intensity'' display in which
one image controls the intensity of the displayed image and the other
controls the hue.    A number of uses for this algorithm are obvious,
including spectral-line moment images (intensity from total line
integral and velocity setting color), polarization images (intensity
from the total or polarized intensity image and polarization angle
setting color in a circular scheme), and depolarization observations
(color set by a two-frequency depolarization image).   The best
implementation of this algorithm has been in the interactive verb {\tt
\Tndx{TVHUEINT}}:
\dispt{INDI {\it d1\/}; GETN {\it ctn1\/} \CR}{to select the intensity
          image.}
\dispt{TVINIT; TVCORN 0}{to clear the TV and restore the default
           positioning.}
\dispt{TVCH 1; TVLOD \CR}{to load the first image on plane 1.}
\dispt{INDI {\it d2\/}; GETN {\it ctn2\/} \CR}{to select the hue
           image.}
\dispt{TVCH 2 ; TVLOD \CR}{to load the second image on plane 2.}
\dispt{TVCH 1 ; TV2CH 2 ; TVHUEINT \CR}{to display a full-color view
          where the intensity is controlled by image 1 and the hue by
          image 2 and to interactively adjust that display.}
\dispe{Instructions for altering transfer functions and reversing the
roles of the two images appear on your terminal while {\tt TVHUEINT}
is running.  You may create a labeled two-direction step wedge to
accompany the hue-intensity display with the verb {\tt HUEWEDGE}\@.}
\Iodx{TV functions}

Until the {\tt 31DEC14} release, the only way to capture this image
was with {\tt TVCPS}, which is fundamentally limited by the size and
resolution of the TV display.  Control over labeling, character font,
number of pixels, and the like is severely limited.  To overcome these
limitations, a new task called {\tt \Tndx{HUINT}} was written.  It
performs the functions of {\tt TVHUEINT} with the option of saving the
resulting image and a two-dimensional step wedge as \AIPS\ cataloged
images.  The task enters an interactive mode in which the user selects
options from a menu shown on a graphics overlay plane.  Options are to
enhance each of the images individually, to select linear,
square-root, or one of 2 logarithmic transfer functions for intensity
or hue, and to exit with or without final updates and an output file.
The output image(s) can then be made into plot files with standard
plot tasks like {\tt GREYS} and {\tt KNTR} and then converted into
PostScript by {\tt LWPLA}\@.  {\tt HELP POSTSCRIPT} contains some
guidance on how to combine PostScript renderings of the color image
and the color step wedge into a single file.  Note that the images
saved by {\tt HUINT} are not in any recognizable physical units.  Also
note that {\tt KNTR} should be run with {\tt DOCOLOR=1; DOWEDGE=0
FUNCTYPE=' '} and {\tt LWPLA} should be run with {\tt RGBGAMMA=1} and
no extra enhancements.

The two functions above require a display that can do an almost
unlimited number of colors.  Unfortunately, some older workstations
can display only 256 simultaneous colors (or even fewer).  {\tt
\tndx{XAS}} supports both kinds of workstation.  For these limited
workstations, there are two tasks, also discussed in \Sec{lineanal},
which attempt to recover much of this capability by trying to optimize
color assignments over the limited range available.  The first of
these, {\tt \tndx{TVHUI}} produces a composite display in which the
intensity is set by one image, the hue is derived from another image,
and the saturation is optionally derived from a third image.  An
interactive menu allows you to enhance each of the images
individually, to select linear, square-root, or logarithmic transfer
functions for the intensity and hue images, to select the sub-image
used during interactive enhancements, to repaint the full image, and
to exit with or without writing out the final three-color image.  The
task has the option of writing an image of a hue-intensity step-wedge
as well.  A number of uses for the saturation portion of this task are
obvious, including spectral-line moment images (line width setting
saturation) and polarization images (polarization intensity setting
saturation).  {\tt TVHUI} is also useful on full-color displays, but
for such displays, you may do much of the work of this task in {\tt
HUINT}\@.  {\tt TVHUI} attempts to write out the full range of input
intensities scaled by the selected transfer functions.  Thus, its
output images are different from those of {\tt HUINT} and may, or may
not, be preferable in particular cases.

There is also an \AIPS\ task called {\tt \tndx{RGBMP}} which writes
three-color cubes using weighted sums over a data cube.  Three-color
cubes also arise when digitizing color photographs of real scenes.
The second task, {\tt \tndx{TVRGB}}, can be used to display these
three-color cubes or to generate a three-color display from any three
\AIPS\ image planes. Common examples of the latter are the
superposition of radio continuum and/or line data on optical or X-ray
images, and color-coding of effective temperatures or spectral indices
from 3-channel continuum data.  {\tt TVRGB} can also be used to
color-code different types of depolarization effects from
multi-frequency polarimetry.  Like {\tt TVHUI}, {\tt TVRGB} offers a
simple menu to enhance each of the images individually or all
together, to select the window specifying the sub-image which is used
during interactive enhancements, to repaint the full image on the TV,
and to exit.  {\tt TVRGB} does not write an output image per se, but
it can be instructed to write out a full 24-bit color
\indx{PostScript} plot file to be sent to a color printer.  Its
display (or any other TV display including that of {\tt TVHUI}) can be
captured and sent to a \indx{color printer}; see \Sec{TVcapture}
below.

      On full-color workstations, three-color images may be displayed
by loading each color plane to a separate TV memory.  Then each memory
is turned on in the desired color only using {\tt TVON} with the
usually ignored {\tt COLORS} adverb.  If the red image is in TV
channel 1, the green in 2 and the blue in 3, the verb {\tt
\tndx{TV3COLOR}} is a short-cut for all the parameter setting.
\displ{FOR TVCH=1:3; TBLC(3)=TVCH; TVLOD; END; TV3COLOR \CR}{}
\dispe{In {\tt 31DEC25}, the procedure {\tt \tndx{TV3LOD}} was added to
make this type of display even more convenient.}
\pd

%\vfill\eject
\Subsections{Slice files and the TV display}{TVslice}

     In \Rchap{line} we discuss the computation and use of ``slices,''
one-dimensional profiles interpolated along any line in an image
plane.  Once a slice has been computed, it may be plotted by {\tt
\tndx{TVSLICE}} on the TV display in your choice of graphics channel.
A second slice may be plotted on top of the first with {\tt
\tndx{TVASLICE}}\@.  The TV graphics display is used to prepare
initial guesses for {\tt SLFIT}, which fits Gaussians to slices.  The
verbs involved are:
\dispt{NGAUS\qs {\it n\/} ; \tndx{TVSET} \CR}{to set the number of
           Gaussians to be fitted to {\it n\/} and then to prepare an
           initial guess at the parameters by pointing at the peaks
           and half width points on a graphics plot of the slice.}
\dispt{TV1SET\qs {\it j\/} \CR}{to revise the initial guess for the
             $j^{\uth}$ Gaussian.}
\dispt{\tndx{TVGUESS} \CR}{to plot the initial guess of the model on
             the TV graphics, erasing any previous plot.}
\dispt{TVAGUESS \CR}{to add a plot of the initial guess of the model
             to the current slice plot on the TV graphics.}
\dispt{\tndx{TVMODEL} \CR}{to plot the fit model on the graphics
             device, erasing any previous plot.}
\dispt{TVAMODEL \CR}{to add a plot of the fit model to the current
             slice plot on the TV graphics.}
\dispt{\tndx{TVRESID} \CR}{to plot the data minus the fit model on
             the TV graphics, erasing any previous plot.}
\dispt{TVARESID \CR}{to add a plot of the residuals (data minus model)
             to the current slice plot on the TV graphics.}
\dispt{\tndx{TVCOMPS} \CR}{to plot the individual components including
             baseline of the fit model on the TV graphics, erasing
             any previous plot.}
\dispt{TVACOMPS \CR}{to add a plot of the individual components
             including baseline of the fit model to the current
             slice plot on the TV graphics.}
\dispe{The units for slice model parameters are those of the plot,
so it is convenient to set them with these verbs.  These same
operations may also be done on the Tek graphics device
(\Sec{TKslice}), but modern X-Windows emulations of such devices seem
to have problems with cursor reading.  The TV verbs allow multiple
colors for plot comparisons using different {\tt GRCHAN}s.}

\subsections{Other functions using the TV}

     There are a number of tasks which use the TV to give the user
real interactive input to the operation based on the images displayed
by the task on the TV\@.  These include {\tt \tndx{BLANK}}
(\Sec{lineanal}) to blank out non-signal portions of an image, {\tt
\tndx{BLSUM}} (\Sec{lineanal}) to sum images over irregular blotch
regions plotting or printing out summed spectra (and saving {\tt SL}ice
files), {\tt \tndx{TVFLG}} (\Sec{tvflg}) to edit visibility data based
on grey-scale displays of some function of the visibility with baseline
on the {\it x\/} axis and time on the {\it y\/} axis, {\tt \tndx{SPFLG}}
(\Sec{lineasses}, \Sec{spflg}) to edit visibility data based on
grey-scale displays of some function of the visibility with spectral
channel for all IFs on the {\it x\/} axis and time on the {\it y\/}
axis, {\tt \tndx{EDITR}} (\Sec{editr}) to edit visibility data based on
plots of visibility versus time, 1--11 baselines at a time,
{\tt \tndx{EDITA}} (\Sec{edita}) to edit visibility data based on plots
of system temperature ({\tt TY} or {\tt SY} tables) or antenna gains
({\tt SN} or {\tt CL} tables), {\tt \tndx{WIPER}} to edit visibility
data using {\tt UVPLT}-like displays, and {\tt \tndx{SNEDT}} to edit
{\tt TY}, {\tt SY}, {\tt SN}, and {\tt CL} tables themselves.  TV-based
tasks have appeared to edit visibility data displayed on a $u-v$ grid
({\tt \tndx{UFLAG}}), to edit visibility or bandpass data based on
graphical displays of bandpass solutions ({\tt \tndx{BPEDT}}), and two
tasks to edit pulse-cal tables ({\tt PCFLG}, {\tt PCEDT})\@.

     The imaging tasks, {\tt \tndx{IMAGR}}, {\tt \tndx{SCIMG}}, and
{\tt \tndx{SCMAP}} display the results of the computation at its
current stage on the TV and provide a menu of interactive options to
the user.  The menu includes the usual display enhancements, the
ability to choose among the images being computed, the ability to set
Clean windows in those images, and the ability to end the computation
at its current stage.  The computation will resume when instructed via
the menu or after a period of inactivity.  A number of older iterative
tasks use the TV to display the results of the computation so far and
then prompt the user to hit button {\tt D} within some number of
seconds to stop the computation.  Tasks that do this include {\tt
\tndx{APCLN}}, {\tt \tndx{SDCLN}}, {\tt \tndx{VTESS}}, and several
less significant tasks. {\tt \tndx{UVMAP}} uses the TV simply to draw
a picture indicating which cells are sampled in the \uv\ plane.  All
of these tasks are described in \Rchap{image}.

     The multi-source fitting task {\tt \tndx{SAD}} was provided with a
companion task {\tt \Tndx{TVSAD}} which allows interactive setting of
the initial guess parameters for each island being fit.  It allows
re-trying the fits and adjusting the island boundaries, and can be run
non-interactively until the fit finds a problem, after which the
interactive mode resumes.  \AIPS\ Memo 119\footnote{Greisen, E. W. 2014,
``TVSAD: interactive search and destroy'' AIPS Memo 119, {\tt
https://www.aips.nrao.edu/aipsdoc.html}} describes the operation of this
task in detail.

     There is a set of related tasks for analysis of data cubes
transposed so that the first axis is the one on which baselines or
Gaussians are to be fit.  In the case of a spectral-line cube, the
image would be transposed so that velocity is the first axis.
{\tt \tndx{TVSPC}} is an interactive task which displays spectra from
one or two transposed cubes at pixels chosen on the TV from some image
of the overall field.  A third cube may also be displayed with the
spectral plane chosen by the cursor on the displayed spectra.  See the
associated \AIPS\ Memo\footnote{Greisen, E. W. 2025, ``Exploring Image
Cubes in \AIPS,'' AIPS Memo 120 revised, {\tt
https://www.aips.nrao.edu/aipsdoc.html}}.  There is now an additional
task {\tt \Tndx{TVIEW}} which does an interactive display of an image
cube in all three tranpostions; it also has an \AIPS\
Memo\footnote{Greisen, E. W. 2025, ``Further Exploration of Image Cubes
in \AIPS,'' AIPS Memo 124 revised,\\   {\tt
https://www.aips.nrao.edu/aipsdoc.html}}.  One can also use
{\tt \tndx{XPLOT}} (with {\tt DOTV 1}) first to get an idea of what
the profiles really look like.  It uses a flux cutoff to determine
which profiles to display and prompts you for permission to continue
after each plot.  {\tt \tndx{XBASL}} is used to remove
$n^{\uth}$-order polynomial baselines from each spectrum.  It has a
batch mode of operation and an interactive mode which uses the
graphics display to plot each spectrum and to accept guidance on
which channels to use in determining the baselines.

{\tt \tndx{XGAUS}} fits up to 8 Gaussians plus a linear baseline to
each spectral profile.  It builds a table of solutions at each pixel and
may be re-started until you are satisfied, after which images of the fit
Gaussian parameters and their uncertainties may be written to disk.  In
its interactive mode, it plots each selected spectrum on the TV graphics
planes and accepts guidance on the initial guesses for the Gaussians.
After all pixels have been done, it displays images of the fit
parameters and offers a variety of options for editing and correcting
the results.  Tasks similar to {\tt XGAUS} have been written to fit
polarization spectra ({\tt \tndx{RMFIT}}) and to fit for Zeeman
splitting ({\tt \tndx{ZEMAN}}) of the line viewed simply or as a set
of Gaussians found by {\tt XGAUS}\@.  Plot tasks {\tt \Tndx{XG2PL}}
and {\tt \Tndx{RM2PL}} have been written to display these spectral
fits in standard \AIPS\ plot files.  See \AIPS\ Memo
118.\footnote{Greisen, E. W. 2025, ``Modeling Spectral Cubes in
\AIPS,'' AIPS Memo 118 revised, {\tt
https://www.aips.nrao.edu/aipsdoc.html}}  Corresponding tasks
{\tt \tndx{AGAUS}} and {\tt \tndx{ZAMAN}} are available to perform
similar analysis of absorption-line image cubes.  See \AIPS\ Memo
122.\footnote{Greisen, E. W. 2025, ``Modeling Absorption-line Cubes
in \AIPS,'' AIPS Memo 122 revised, {\tt
https://www.aips.nrao.edu/aipsdoc.html}}  In {\tt 31DEC24}, a similar
task called {\tt \tndx{TVSPX}} has appeared to assist in fitting
spectral indexes to image cubes.  In {\tt 31DEC25}, another similar task
{\tt \tndx{LISPX}} fits spectral indices to spectra in text files.
See \AIPS\ Memo 126.\footnote{Greisen, E. W. 2025, ``Spectral index
fitting in \AIPS,'' AIPS Memo 126, {\tt
https://www.aips.nrao.edu/aipsdoc.html}}

\Subsections{Capturing the TV}{TVcapture}

     Having done all the work to prepare the absolutely perfect
display on your TV screen, it would be a good idea to capture it
before someone, such as the local power company, does a {\tt
TVINIT}\@.  See \Sec{copyscreen} for a discussion of Unix tools to do
this.  We recommend, however, {\tt \tndx{TVCPS}} to capture the image
on your TV, including graphics overlay channels if they are on, and to
write the result to an encapsulated \indx{PostScript} file. This file
can be printed immediately on a black-and-white or \indx{color
printer} or on any other device which understands PostScript.  It can
also be saved for later printing or inclusion in other documents.
{\tt TVCPS} was used to make the picture on the title page of this
\Cookbook, the picture of {\tt TVFLG}'s display in \Rchap{cal}, and
the picture of a right ascension - velocity - declination data cube in
\Rchap{vlbi}.  {\tt TVCPS} bases its picture on the current size of
your TV display.  If you are using a  workstation with {\tt XAS}, be
sure to adjust the size of the display window to encompass all of your
image plus a modest border. If you leave a large border, you will get
a large border in your output.  {\tt TVCPS} understands both pseudo-
and full-color {\tt XAS} displays.  Your {\tt TVCPS} session could
look like:
\dispt{TASK\qs 'TVCPS' ; INP \CR}{to review the inputs.}
\dispt{OUTFILE\qs 'MYAREA:TV.PIX \CR}{to save the output in a file
           called {\tt TV.PIX} in an area defined by the logical {\tt
           MYAREA}; see \Sec{textfile}.}
\dispt{OPCODE\qs 'COL' \CR}{to make a color picture.}
\dispt{APARM\qs 8.5 , 11 \CR}{to set the output device size to 8.5 by
           11 inches, appropriate to standard quarto paper.}
\dispt{GO \CR}{to run the task when the inputs are set.}
\dispe{{\tt TVCPS} has an option to add a character string below the
image with adverb {\tt REASON}\@.  If your image is too large to fit
on the TV, you can instruct {\tt TVCPS} to read the image from disk
with {\us DOTV = -2 \CR}, using adverbs {\tt TBLC}, {\tt TTRC}, {\tt
TXINC}, and {\tt TYINC}\@.  When doing this, you should turn off
the graphics display ({\us GROFF 32767 \CR}) since it is not aligned
properly.  This option works when multiple images are visible at the
same time, but only when they are in separate TV planes as fully
overlapped 3-color images.  Some color printers and recorders have
rather different transfer characteristics than the workstation screen.
{\tt TVCPS} offers the option to remove the ``gamma correction'' used
for your workstation and to apply a different one appropriate to your
color recorder.  {\tt TVCPS} now offers the option to represent colors
using the CMYK (cyan-magenta-yellow-black) used in printing rather
than the familiar RGB colors system.  CMYK displays often require
different gamma corrections from those used for RGB\@.  To see the
effects of the gamma correction, try the verb {\tt \tndx{GAMMASET}} in
{\tt AIPS}\@.  You may need to use {\tt \tndx{GWRITE}} to select
better colors for the graphics overlay planes as well.  The default
black background may be set to and color with adverb {\tt
RGBCOLOR}\@.}\Iodx{TV functions}

\Sec{copyscreen} contains a discussion of Unix tools to capture the TV
screen which work even when the \AIPS\ display task has control of the
display.  The {\tt import} program is perhaps the more useful of
these.

\vfill\eject
\sects{Graphics displays of your data}

\Iodx{graphics functions}
     In the dim dark past, Tektronix invented some nice graphical
display devices and an inconvenient but functional way to talk to
them.  This communication language became so embedded in software that
workstation vendors now provide X-Windows windows that understand it.
\AIPS\ also arose from this dim dark past and once upon a time talked
to those lovely green screens.  To retain the graphics capability, we
now provide a {\tt \tndx{TEKSRV}} server which will provide a
Tektronix-like graphics screen on which certain \AIPS\ tasks and verbs
plot.  When {\tt AIPS} starts up on workstations, it brings up a
window called {\tt TEKSRV}\@.  Leave this window in its iconic state;
it is only a marker for the presence of the server.  The first time
you write to {\tt TEKSRV}, it will create and open a window called
{\tt TEKSRV (Tek)} in which the plot is done.  You can re-size this
window within some limits and the plot will automatically re-size
itself. When the workstation cursor is in the Tek window, it changes
to a diagonal arrow pointer.  When an \AIPS\ task or verb tries to
read from the Tek window, this pointer becomes a plus sign.  You
should position the pointer to the desired location {\it without\/}
touching the keyboard or the mouse buttons.  When the pointer is
exactly where you want it, press any mouse button or any key ({\it
except\/} {\tt RETURN}) to return the pointer position to the program.
Note that the functions using the graphics display are not quite as
friendly as those on the TV\@.  This is due to the inability to erase
a piece of a plot without erasing all of it.  You can erase the full
screen with {\tt \tndx{TKERASE}}, which will keep the window from
redrawing a big plot on every expose event.  In recent years, we have
found unfortunately that cursor reading from Tektronix emulation
screens can be unreliable.  Therefore, every {\tt TK} function
described below also has a {\tt TV} version, described in a previous
subsection.  The TV has many other advantages over the Tektronix
emulator and now is nearly as fast.  The verb {\tt \tndx{STARTTV}} will
restart this server if it has, for some reason, exited.

\subsections{Plotting data and setting values with the graphics
    display}

     {\tt \tndx{TKPL}} interprets \AIPS\ plot files to the graphics
window or device.  The graphics screen can be used to read back data
values and set adverbs, much like the TV:\Iodx{graphics functions}
\dispt{TKXY \CR}{to read the graphics cursor position, setting adverb
             {\tt PIXXY}; requires a contour or comparable image to be
             shown on the screen.}
\dispt{\tndx{TKXY ; IMVAL} \CR}{to read the graphics cursor position and
             return the image value and coordinates of the selected
             position.}
\dispt{\tndx{TKPOS} \CR}{to read the graphics cursor position and
             return the image coordinates of the selected position.}
\dispt{\tndx{TKWIN} \CR}{to read the graphics cursor position twice,
             first setting {\tt BLC} and then setting {\tt TRC}.}
\dispt{TKBOX({\it i\/}) \CR}{to read the graphics cursor position
             twice, first setting the lower left and then the upper
             right of Clean box {\it i\/}.}
\dispt{TKNBOXS({\it n\/}) \CR}{to set {\tt NBOXES} to {\it n\/} and
             then set all {\it n\/} Clean boxes using the graphics
             cursor.}
\dispe{All of these verbs require a graphics display of a plot file
produced by {\tt CNTR}, {\tt PCNTR}, {\tt GREYS}, or {\tt SL2PL}\@.
The window procedures don't make much sense with a slice plot, but
they will work.}

\vfill\eject
\Subsections{Slice files and the graphics display}{TKslice}

     In \Rchap{line} we discuss the computation and use of ``slices,''
one-dimensional profiles interpolated along any line in an image
plane.  Once a slice has been computed, it may be plotted by {\tt
\tndx{TKSLICE}} on the graphics display.  A second slice may be plotted on
top of the first with {\tt \tndx{TKASLICE}}\@.  The graphics
display is used to prepare initial guesses for {\tt SLFIT}, which fits
Gaussians to slices.  The verbs involved are:
\dispt{\tndx{TKVAL} \CR}{to return the flux level pointed at by the
             graphics cursor.}
\dispt{NGAUS\qs {\it n\/} ; \tndx{TKSET} \CR}{to set the number of
           Gaussians to be fitted to {\it n\/} and then to prepare an
           initial guess at the parameters by pointing at the peaks
           and half width points on a graphics plot of the slice.}
\dispt{TK1SET\qs {\it j\/} \CR}{to revise the initial guess for the
             $j^{\uth}$ Gaussian.}
\dispt{\tndx{TKGUESS} \CR}{to plot the initial guess of the model on
             the graphics device, erasing any previous plot.}
\dispt{TKAGUESS \CR}{to add a plot of the initial guess of the model
             to the current slice plot on the graphics device.}
\dispt{\tndx{TKMODEL} \CR}{to plot the fit model on the graphics
             device, erasing any previous plot.}
\dispt{TKAMODEL \CR}{to add a plot of the fit model to the current
             slice plot on the graphics device.}
\dispt{\tndx{TKRESID} \CR}{to plot the data minus the fit model on
             the graphics device, erasing any previous plot.}
\dispt{TKARESID \CR}{to add a plot of the residuals (data minus model)
             to the current slice plot on the graphics device.}
\dispe{The units for the slice model parameters are fairly
problematic, so we recommend using these graphical input and output
functions.  At least, they all have the same strange ideas. See
\Sec{TVslice} for the verbs that allow this same processing using the
TV display.}

\subsections{Data analysis with the graphics display}

     Tasks {\tt \tndx{XPLOT}} and  {\tt \tndx{XBASL}} have modes which
use the graphics display.  They also can use the TV display which is
now as fast as the graphics and more reliable.
\Iodx{graphics functions}
%\vfill\eject

\sects{Examples of color plotting}

The following six pages are in color and should be printed on a color
PostScript printer if possible.  They will also print on a black and
white printer but will then not show what they are supposed to
illustrate.
\vfill\eject

\gdef\titlec{6.7 Examples of color plotting}

%\sections {Examples of color plotting}
%
%
\begin{figure}
\centering
%\centerline{\resizebox{\hsize}{!}{\gname{kntr1}}}
\centerline{\resizebox{\hsize}{!}{\gbb{702,374}{kntr1}}}
\vspace{12pt}
%\centerline{\resizebox{\hsize}{!}{\gname{pr1}}}
\centerline{\resizebox{\hsize}{!}{\gbb{697,407}{pr1}}}
\caption[{\tt KNTR} with pseudo-coloring, contours and polarization
vectors in bright and dark lines]{{\tt KNTR} does polarization lines,
contours, and grey-scale.  Then {\tt LWPLA} converts the grey-scale to
pseudo-color and colors the lines making dark contours dark but dark
polarization lines and stars bright.  Data courtesy of Greg Taylor.}
\end{figure}

\begin{figure}
\centering
%\centerline{\resizebox{!}{5.0in}{\gname{kntr2}}}
\centerline{\resizebox{!}{5.0in}{\gbb{557,530}{kntr2}}}
\vspace{12pt}
%\centerline{\resizebox{\hsize}{!}{\gname{pr2}}}
\centerline{\resizebox{\hsize}{!}{\gbb{692,315}{pr2}}}
\caption[{\tt KNTR} shows true-color image]{{\tt KNTR} interprets the
output of {\tt TVHUI} as a three-color RGB image and overlays moment-0
contours. {\tt LWPLA} adds coloring to the lines, using a less than
pure white for both bright and dark contours so that they are not so
dominant. Data courtesy of Eric Greisen, Kristine Spekkens, and
Gustaaf van Moorsel.}
\end{figure}

\begin{figure}
\centering
%\centerline{\resizebox{!}{4.75in}{\gname{pcntr3}}}
\centerline{\resizebox{!}{4.75in}{\gbb{637,502}{pcntr3}}}
\vspace{12pt}
%\centerline{\resizebox{\hsize}{!}{\gname{pr3}}}
\centerline{\resizebox{\hsize}{!}{\gbb{692,327}{pr3}}}
\caption[{\tt PCNTR} with polarization position angle shown with
color]{{\tt PCNTR} plots contours and polarization vectors of
Centaurus A\@.  Color is used to show the complex changes in
polarization position angle since the angles of short lines cannot be
seen accurately.  Data courtesy of Greg Taylor.  For a discussion of
this amazing pattern see Taylor, G.B., Fabian, A.C., \&\ Allen, S.W.
2002, MNRAS, 334, 769, astro-ph/0109337 ``Magnetic Fields in the
Centaurus Cluster.''}
\end{figure}

\begin{figure}
\centering
%\centerline{\resizebox{\hsize}{!}{\gname{pcntr4}}}
\centerline{\resizebox{\hsize}{!}{\gbb{701,497}{pcntr4}}}
\vspace{12pt}
\centerline{\resizebox{\hsize}{!}{\gbb{688,195}{pr4}}}
\caption[{\tt PCNTR} with contours colored by velocity]{{\tt PCNTR}
plots contours every fifth plane from a data cube using colors related
to the velocity.  {\tt LWPLA} adds coloring to the labeling and
background and applies a gamma correction to blue. Data courtesy of
Eric Greisen, Kristine Spekkens, and Gustaaf van Moorsel.}
\end{figure}

\begin{figure}
\centering
%\centerline{\resizebox{!}{5.1in}{\gname{casa}}}
\centerline{\resizebox{!}{5.1in}{\gbb{522,525}{casa}}}
\vspace{12pt}
%\centerline{\resizebox{6.5in}{!}{\gname{pr6}}}
\centerline{\resizebox{6.5in}{!}{\gbb{687,288}{pr6}}}
\caption[{\tt KNTR} with contours colored with {\tt RGBLEVS}]{{\tt
KNTR} plots contours of Cassiopeia A with each contour level
separately colored under control of adverb {\tt RGBLEVS}\@.  The
values of {\tt RGBLEVS} were set by a procedure call {\tt
\tndx{STEPLEVS}(10)} made available by {\tt RUN \tndx{SETRGBL}}\@.
Image is from the {\it Images from the Radio Universe} CD, 1992, NRAO
with the particular image from Anderson M., Rudnick, L., Leppik, P,
Perley, R. \&\ Braun, R. 1991, ApJ, 373, 146.}
\end{figure}

\begin{figure}
\centering
%\centerline{\resizebox{!}{4.8in}{\gname{snplt}}}
\centerline{\resizebox{!}{4.8in}{\gbb{522,531}{snplt}}}
\vspace{12pt}
%\centerline{\resizebox{6.5in}{!}{\gname{pr5}}}
\centerline{\resizebox{6.5in}{!}{\gbb{698,325}{pr5}}}
\caption[{\tt SNPLT} with IFs/polarizations colored]{{\tt SNPLT} plots
phases for four antennas with color indicating polarization and IF
channel.  Stokes 1, IF {\tt BIF} is pure red changing through yellow,
green, and cyan to Stokes 2, IF {\tt EIF} as pure blue.  When all
symbols lie on top of each other, the last one (pure blue) will
dominate.}
\end{figure}
