%-----------------------------------------------------------------------
%;  Copyright (C) 2018-2019, 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
%-----------------------------------------------------------------------
\documentclass[twoside]{article}
\usepackage{palatino}
\renewcommand{\ttdefault}{cmtt}
% Highlight new text.
\usepackage{color}
\usepackage{alltt}
\usepackage{graphicx,xspace,wrapfig}
\usepackage{pstricks}  % added by Greisen
\definecolor{hicol}{rgb}{0.6,0.05,0.05}
\definecolor{mecol}{rgb}{0.1,0.1,0.6}
\definecolor{excol}{rgb}{0.05,0.5,0.05}
\newcommand{\Hi}[1]{\textcolor{hicol}{#1}}
%\newcommand{\Hi}[1]{\textcolor{black}{#1}}
\newcommand{\Me}[1]{\textcolor{mecol}{#1}}
%\newcommand{\Me}[1]{\textcolor{black}{#1}}
\newcommand{\Ex}[1]{\textcolor{excol}{#1}}
%\newcommand{\Ex}[1]{\textcolor{black}{#1}}
\newcommand{\No}[1]{\textcolor{black}{#1}}
\newcommand{\hicol}{\color{hicol}}
%\newcommand{\hicol}{\color{black}}
\newcommand{\mecol}{\color{mecol}}
%\newcommand{\mecol}{\color{black}}
\newcommand{\excol}{\color{excol}}
%\newcommand{\excol}{\color{black}}
\newcommand{\hblack}{\color{black}}
%
\newcommand{\AIPS}{{$\cal AIPS\/$}}
\newcommand{\eg}{{\it e.g.},}
\newcommand{\ie}{{\it i.e.},}
\newcommand{\etal}{{\it et al.}}
\newcommand{\tablerowgapbefore}{-1ex}
\newcommand{\tablerowgapafter}{1ex}
\newcommand{\keyw}[1]{\hbox{{\tt #1}}}
\newcommand{\sub}[1]{_\mathrm{#1}}
\newcommand{\degr}{^{\circ}}
\newcommand{\vv}{v}
%\newcommand{\vv}{\varv}
\newcommand{\eq}{\hbox{\hspace{0.6em}=\hspace{0.6em}}}
\newcommand{\newfig}[2]{\includegraphics[width=#1]{data.fig#2}}
%\newcommand{\putfig}[1]{\includegraphics{data.fig#1.eps}}
%\newcommand{\putfig}[1]{\includegraphics{#1.eps}}
\newcommand{\putfig}[1]{\includegraphics{#1}}
\newcommand{\whatmem}{\AIPS\ Memo \memnum}
\newcommand{\boxit}[3]{\vbox{\hrule height#1\hbox{\vrule width#1\kern#2%
\vbox{\kern#2{#3}\kern#2}\kern#2\vrule width#1}\hrule height#1}}
%
\newcommand{\memnum}{124 \Hi{Revised}}
\newcommand{\memtit}{Further Exploration of Image Cubes in \AIPS}
\title{
   \vskip -35pt
   \fbox{{\large\whatmem}} \\
   \vskip 28pt
%   \vskip 10pt
%   \fbox{{\Huge \Me{D R A F T}}}
%   \vskip 10pt
   \memtit \\}
\author{Eric W. Greisen}
%
\parskip 4mm
\linewidth 6.5in                     % was 6.5
\textwidth 6.5in                     % text width excluding margin 6.5
\textheight 9.0 in                  % was 8.81
\marginparsep 0in
\oddsidemargin .25in                 % EWG from -.25
\evensidemargin -.25in
\topmargin -0.4in
%\topmargin 0.2in
\headsep 0.25in
\headheight 0.25in
\parindent 0in
\newcommand{\normalstyle}{\baselineskip 4mm \parskip 2mm \normalsize}
\newcommand{\tablestyle}{\baselineskip 2mm \parskip 1mm \small }
%
%
\begin{document}

\pagestyle{myheadings}
\thispagestyle{empty}

\newcommand{\Rheading}{\whatmem \hfill \memtit \hfill Page~~}
\newcommand{\Lheading}{~~Page \hfill \memtit \hfill \whatmem}
\markboth{\Lheading}{\Rheading}
%
\vskip -.5cm
\pretolerance 10000
\listparindent 0cm
\labelsep 0cm
%
%

\vskip -30pt
\maketitle

\normalstyle
\begin{abstract}
  \AIPS\ has powerful tasks to fit models to the spectral axis of
  image cubes.  Tasks like {\tt XGAUS} and {\tt RMFIT} are easier to
  run if the user is already familiar with the general structure of
  the data cube.  Task {\tt TVSPC} was written to explore data cubes
  with emphasis on plots of spectra.  Now a new task {\tt TVIEW} has
  been written to explore data cubes with displays of
  position-velocity transpositions of the data cube.  This task
  provides an additional exploration tool within the \AIPS\
  environment, rather than requiring users to export their cubes to
  one or more of the many excellent visualization tools now available.
  {\tt TVIEW} offers the option of rotating the image in the celestial
  axes so that the position-velocity curves may be viewed along axes
  pertinent to the source, \eg\ the major axis.
  \footnote{The color \Hi{red} has been used for changes made to this
    memo in April 2025 while \Me{blue} is for changes in October 2019.}
\end{abstract}

\renewcommand{\floatpagefraction}{0.75}
\typeout{bottomnumber = \arabic{bottomnumber} \bottomfraction}
\typeout{topnumber = \arabic{topnumber} \topfraction}
\typeout{totalnumber = \arabic{totalnumber} \textfraction\ \floatpagefraction}

\section{Introduction}

\AIPS\ has a suite of tasks designed to fit models to the spectral
axis of image cubes.  Gaussians may be fit in emission or absorption,
Zeeman splitting may then be fit, and, in polarization, rotation
measures may be fit.    These tasks, along with display and modeling
tasks, are described in an \AIPS\ Memo\footnote{Greisen, E.W. 2015,
  \AIPS\ Memo 118 revised, ``Modeling Spectral Cubes in \AIPS,''
  March 2017.} which includes descriptions of the mathematics,
the input adverbs, and the flow of each program.  Similar tasks geared
for use with absorption-line spectral cubes have appeared and {\tt
  AGAUS} and {\tt ZAMAN} are described in an \AIPS\
Memo\footnote{Greisen, E.W. 2017, \AIPS\ Memo 122, ``Modeling
Absorption-line Cubes in \AIPS,'' March 2017.}.  {\tt TVSPC} is an
interactive data exploration task which assists users to become
familiar with the spectral content of their data cubes.  It is
described in yet another \AIPS\ Memo\footnote{Greisen, E.W. 2016,
  \AIPS\ Memo 120, ``Exploring Image Cubes in \AIPS,'' revised
  \Me{October 2019.}}

One can use the above tasks without being familiar with the contents
of the image cubes.  However, users who are familiar with the contents
of their data cubes will find the modeling tasks simpler to use.  {\tt
  TVSPC} emphasizes spectra at individual pixels on the celestial
axes.  A full understanding of the data cube however requires
examining the cube on planes with one spectral and one celestial axis
(the so-called ``position-velocity'' display).  There are two such
transpositions of the data cube in addition to the one having two
celestial axes on each plane.

\section{Image cube exploration: {\tt TVIEW}}

A new task, called {\tt TVIEW}, has now appeared in the {\tt 31DEC18}
version of \AIPS\@.  It presumes that the user has a ``spectral''
image cube in any transposition which has 2 celestial and one spectral
axes as the first 3 axes.  Optionally, the user may also have a second
``reference'' image, only one plane of which will be displayed.  It is
assumed that the two celestial axes are the first two axes of this
image.  The reference image can be any image that is meaningful to the
study of the data cube and is not required to be on a coordinate
system identical to the data cube.  An obvious example of a reference
image would be the zero-moment image (integral under the line) as
shown in the figures in this Memo.  Other possibilities would be a
continuum or rotation measure image.  \Hi{In {\tt 31DEC25}, {\tt TVIEW}
will offer the choice to display the reference image (if specified) or
the spectrum at the celestial pixel selected for the two
position-spectral displays.  Menu options now allow the user to switch
between the two displays.  The new pseudo-coloring scheme named {\tt
  OFMCOLOR} was also added.}

\subsection{Inputs}

The usual {\tt INNAME}  {\it et al.}~adverbs define the
three-dimensional image cube to be displayed in grey-scale on the
\AIPS\ TV\@.  Adverbs {\tt BLC} and {\tt TRC} may be used to limit the
extent of the cube that is displayed.  The usual {\tt IN2NAME} {\it et
  al.}~adverbs, if not blank, define the two-dimensional reference
image.  Adverbs {\tt TBLC} and {\tt TTRC} select the portion of this
image to appear on the TV including the plane if {\tt IN2NAME} points
at an image cube.  \Hi{If {\tt IN2NAME} is left blank, the upper left
portion of the screen will be used to display spectra.  If it is not
blank, the upper left portion of the screen will begin by displaying
the reference image.  A menu option will allow the user to switch
to the spectrum display and back again.}  {\tt TVCHAN} selects the TV
channel used for the gray-scale display. {\tt PIXRANGE} selects the
reference image intensity range while {\tt FUNCTYPE} selects the
transfer function used to load all images to the TV\@.  The image
intensity range for the reference image \Me{(or the spectra)} and,
separately, for the cube may be changed while running the task as well.
\Me{{\tt CBPLOT} controls the plotting of a Clean beam on
  position-position images when labeling is enabled.}  The {\tt
  REWEIGHT} adverb controls the accuracy and blanking parameters of the
interpolation used when rotating the images.  The larger {\tt
  REWEIGHT(1)}, the greater the accuracy and the greater the computation
time.  With the 952 x 538 data cube with 108 spectral planes used in the
figures of this memo, a rotation with {\tt REWEIGHT(1) = 1} required 7
seconds while {\tt REWEIGHT(1) = 4}, the upper limit required 37
seconds.  There are no other adverbs.

\subsection{Execution: the image}

When {\tt TVIEW} begins it reads the reference image, if any, into
dynamic memory and then reads the image cube into 3 different dynamic
memory segments, one for each transposition.  The reference image is
then displayed in the upper left quadrant of the TV screen.  \Me{If
there is no reference image, then the spectrum at the celestial
position used for the S-Y-X and S-X-Y displays is shown.}  The
X-Y-S cube (X is usually right ascension, Y declination, and S
frequency or velocity) is displayed in the lower left quadrant using
the central spectral plane.  The S-X-Y cube is displayed in the upper
right quadrant and the S-Y-X cube is displayed in the lower right
quadrant.  Each image is made as large as the available TV real estate
will allow.  If the image is small, pixels will be interpolated.  If
it is large, only every $n^{\rm th}$ pixel will be displayed.  In the
spatial displays (two left images), the X and Y increments are kept
the same.  In the other displays, the S increment and the X and Y
increments are allowed to differ.  Every time the images are loaded,
information on the increments of windows is given in the message
window.  The pixel number along the third axis of the displayed image
plane is shown at the upper right of the corresponding image \Me{along
  with the appropriate coordinate, usually right ascension and
  declination.}

The following menu appears in yellow at the left of the screen
whenever you need to select some operation.  (Graphics colors
mentioned in this Memo assume that the user has not changed the
default colors of the XAS graphics planes.)  When the TV cursor is
moved to an option, the color of the option changes to purple.  To
select the option, press buttons A, B, or C; button D will cause a
brief explanation of the option to appear in the command input window.

The gray-scale image(s) are displayed with a black-and-white
enhancement function followed by pseudo coloring, all with familiar
functions.  {\tt TVTRANSF} is an interactive alteration of the
black-and-white enhancement in which the TV cursor $x$ position
controls the intercept and the $y$ position controls the slope of a
linear transfer function.  Buttons A and B turn a plot of this
function on and off, button C changes the sign of the slope, and
button D exits.  {\tt OFF TRANS} resets the transfer function.  {\tt
  TVPSEUDO} is an interactive pseudo coloring.  Button A selects
triangles in the three colors with the cursor $x$ position controlling
the position separating the lowest color from the highest, the cursor
$y$ position controls the ``gamma'' correction affecting the intensity
of the colors, and repeated hits of button A cycling between all 6
possible color orders.  Button B selects circles in hue at maximum
saturation and intensity, with the cursor $x$ position controlling the
number of circles and the cursor $y$ position controlling the starting
hue.  Button C selects color contours with the cursor $x$ position
controlling the image intensity at which contours begin, the cursor
$y$ position sets the range of image intensities over which the
contours extend, and repeated hits of button C select between five
different contour designs.  Button D exits, returning to read the next
operation from the menu.  {\tt TVPHLAME} implements a flame-like
pseudo-coloring ranging initially from red through orange and yellow
to white.  The cursor $x$ position controls the intensity at which the
color transitions take place, the $y$ position controls the gamma
correction and repeated hits of buttons A or B will cycle between the
6 color sequences possible.  Buttons C and D return you to the main
menu.  \Hi{{\tt OFMCOLOR} allows you to choose any one of 10 ``output
function memory'' tables attached to each of buttons A, B, and C, 30
in all.  Having selected a color scale, it may be adjusted with the
horizontal position of the cursor.}  {\tt OFF PSEUDO} turns off all
  coloring.

\begin{center}
\begin{tabular}{|l|l|}\hline
 {\tt OFF TRANS      } & Initialize black-and-white transfer function \\
 {\tt OFF PSEUDO     } & Turn of any pseudo-coloring \\
 {\tt TVTRANSF       } & Adjust black-and-white transfer function \\
 {\tt TVPSEUDO       } & Color contours of a variety of types \\
 {\tt TVPHLAME       } & Flame-like pseudo-coloring \\
\Hi{{\tt OFMCOLOR   }} & \Hi{Many color tables available} \\
 {\tt LABEL IMAGES?  } & Cycle through image labeling options \\
 {\tt CURVALUE       } & Display intensity and pixel under the cursor\\
 {\tt SET CUBE RANGE } & Enter cube images intensity display range \\
 {\tt SET REF RANGE  } & Enter reference image intensity display range \\
\Me{{\tt SET SPEC RANGE}} & \Me{Enter spectrum plot intensity display range} \\
\Hi{{\tt SPECTRA    }} & \Hi{Display spectra in upper left} \\
\Hi{{\tt REFERENCE  }} & \Hi{Display reference image in upper left} \\
 {\tt                } & \\
 {\tt ROAM           } & Select planes to display in the cube images \\
 {\tt SET WINDOW     } & Select a sub-image for more detailed viewing \\
 {\tt RESET WINDOW   } & Return to viewing full image \\
 {\tt ROTATE         } & Enter angle to rotate all images \\
 {\tt TV ROTATE      } & Interactively set angle to rotate all images \\
 {\tt RELOAD IMAGES  } & Reread the images from disk undoing any
                         rotation \\
                         reference image  \\
 {\                  } & \\
 {\tt EXIT           } & Exit {\tt TVIEW}\\ \hline
\end{tabular}
\end{center}

The {\tt LABEL IMAGES?} option has three states: labels off, labels on
the gray-scale image(s), and labels on the image(s) with a full
coordinate grid.  Successive selection of this option cycles through
the three states.  The {\tt CURVALUE} option lets you display the
pixel numbers and intensity under the cursor when the cursor is placed
in any of the grey-scale images.  The {\tt SET REF RANGE} option lets
you set the intensity range displayed for the reference image.  \Hi{If
spectra are being displayed, this option is replaced with {\tt SET
  SPEC RANGE} which allows you to set the spectrum plot intensity range.
When the reference image (if any) is again displayed, this option
returns.}  {\tt TVIEW} will prompt you with a message indicating the
image intensity range.  Enter two numbers in the command input window.
If the first is less than the second, the two numbers define the desired
display range.  If the two numbers are the same, or the first is larger,
then the display reverts to the full image intensity range.  The {\tt
  SET CUBE RANGE} is similar but applies to the three displays of the
cube image.

{\tt SET WINDOW} is used to select a section of the reference image or
the cube images to be blown up for more detailed examination.  You
must first move the TV cursor to the image which you wish to examine
more closely and hit any button.  Then it behaves like verb {\tt
  TVWINDOW} and begins by setting the lower-left corner.  Hit buttons
A or B to switch to setting the upper right corner.  Buttons A and B
switch between the corners thereafter.  Buttons C and D exit with the
window set.  At this point, {\tt TVIEW} reloads the affected image(s)
with the selected corners, maximizing the size of the image on the TV
while keeping the X and Y pixel increments the same (in the reference
and X-Y-S images only).  A window in the reference image affects only
that image.  A window in the other three displays will affect the
appropriate axes in all displays.  Thus, a window in the X-Y-S display
will affect the vertical axes in the S-X-Y and S-Y-X displays.  A
window in the S-X-Y display will affect the horizontal axis of the
X-Y-S display and the S-Y-X display and a window in the S-Y-X display
will affect the vertical axis in the X-Y-S display and the horizontal
axis in the S-X-Y display.  All planes in each of the cube
transpositions remain available for display without regard for the
selected windows.

{\tt RESET WINDOW} requires you to position the cursor in the desired
gray-scale display and press any button.  Then the window in that
image will be reset to the initial corners ({\tt BLC} and {\tt TRC} of
the cube and {\tt TBLC} and {\tt TRC} of the reference image).  Note
that the reset window parameters affect the images as described above
for {\tt SET WINDOW}\@.

\subsection{Execution: examining the cube}

The {\tt ROAM} option allows you to choose which planes of the cubes
are displayed.  Position the cursor in one of the image windows and
move it around.  Two of the displayed windows will change.  If you are
in either of the left-hand (\Me{reference} X-Y and X-Y-S) windows, the
two right-hand windows will change as you select the Y and X planes.  If
you are in the top right window (S-X-Y), then the two lower windows will
change as you select S and X planes.  If you are in the lower right
window, the top right and lower left windows will change as you select S
and Y planes.  The plane number will appear at the top right of each
window along with an approximate coordinate for that plane.  The
spectral coordinate is assumed linear and the celestial coordinate in X
is computed at the reference pixel in Y and vice versa.  Since the
celestial coordinates are non-linear projections, these only approximate
the correct coordinate especially if there is rotation.  \Hi{If there is
no reference image or the spectrum plot has been selected, that plot
will change to that appropriate to the X and Y pixels selected.}

The user may wish to examine the cube after some rotation in the
celestial coordinates.  The example shown in the next section includes
a rotation to make the galaxy major axis horizontal.  Doing this
removes some of the projection affects in the apparent rotation curve.
There are two options to perform this rotation.  In the simple {\tt
  ROTATE} option, the user is prompted to enter an angle in the
command input window.  Units are degrees clockwise.  In the
interactive {\tt TV ROTATE} option, the reference image is shown using
the full screen.  \Me{If there is no reference image, the current plane
  of the X-Y-S image is shown.}  A short green line is overlaid.  Move
one end of the line to the end of a the desired slice and hit button A,
B, or C\@.  Then move the other end of the slice to the desired point.
Buttons A, B, and C switch ends of the slice.  Hit button D to determine
the angle subtended by the slice which will be used to rotate the
images.  Note that the rotation requires an interpolation operation
which is controlled by the {\tt REWEIGHT} adverb (see above).  After the
rotation has been computed, the altered images are displayed.

Note that pixels in the rotated image that do not occur in the previous
images must be blanked.  Each subsequent rotation will increase the
number of blanked pixels.  To start over with the initial, unrotated
images, select the {\tt RELOAD IMAGES} option.

\subsection{Examples}

The image used to illustrate {\tt TVIEW} is an HI spectral line cube
of NGC 6503.  The reference gray-scale image chosen is a moment-zero
image giving a wide-angle view of the total HI in the galaxy.  It
covers a larger spatial area than the cube which also has different
spatial pixel size and other different coordinate parameters.  In one of
the figures, the moment one image is shown giving a wide-angle view of
the predominant velocity of the HI\@.  An analysis of these data has
been published.\footnote{Greisen, E. W., Spekkens, K., van Moorsel,
  G. A. 2009, ``Aperture Synthesis Observations of the Nearby Spiral NGC
  6503: Modeling the Thin and Thick Disks'', AJ, 137, 4718-4733.}

Figure~\ref{fig:HIab} illustrates, in the upper portion, the screen at
the start of the program.  The reference image is at the top left,
the X-Y-S image central plane is at the lower left, the S-X-Y central
plane is at the upper right, and the S-Y-X central plane is at the
lower right.  The lower portion of the Figure shows the screen after a
{\tt LABEL IMAGES?}, a {\tt SET WINDOW} in the reference image, and a
{\tt ROAM} in which the cursor was only placed in the lower right
image.

Figure~\ref{fig:HIcd} also illustrates the {\tt TV ROTATE} option.
The upper portion shows the interactive setting of the desired
rotation angle and the lower portion shows the images after the
rotation.  The second invocation of {\tt LABEL IMAGES?} has been
invoked and {\tt TVPSEUDO} has been used to label fully and to color
the lower portion.

\Me{Figure~\ref{fig:HIfg} illustrates the screen when the spectral
  display has been selected (or there is no reference image).  It also
  illustrates use of sub-images, display of the Clean beam, use of
  rotation, and pseudo-coloring.}

\begin{figure}
\begin{center}
\resizebox{5.9in}{!}{\putfig{TVIEWa.eps}}
\centerline{\hphantom{MM}}
\resizebox{5.9in}{!}{\putfig{TVIEWb.eps}}
\caption{HI moment-zero reference image with image cube in 3
  transpositions.  Top: initial view, all at central planes.
  Bottom: images labeled, reference image has been sub-imaged, Y and S
  planes have been changed by {\tt ROAM} in lower right image.
  \Me{Clean beam is not plotted ({\tt CBPLOT = 0.})}}
\label{fig:HIab}
\end{center}
\end{figure}

\begin{figure}
\begin{center}
\resizebox{5.9in}{!}{\putfig{TVIEWc.eps}}
\centerline{\hphantom{MM}}
\resizebox{5.9in}{!}{\putfig{TVIEWe.eps}}
\caption{Top: HI moment-zero reference image with slice to set
  rotation angle.  Bottom: moment \Hi{one} image and image in 3
  transpositions after rotation.  \Hi{The {\tt CBPLOT=3} Clean beam is
    visible and a {\tt TVPSEUDO} coloring has been selected.}}
\label{fig:HIcd}
\end{center}
\end{figure}

\begin{figure}
\begin{center}
\resizebox{5.85in}{!}{\putfig{TVIEWf.eps}}
\centerline{\hphantom{MM}}
\resizebox{5.85in}{!}{\putfig{TVIEWg.eps}}
\caption{\Me{Top: display with \Hi{spectral plot selected}.  The X-Y-S
  image has been sub-imaged to make the {\tt CBPLOT=3} Clean beam more
  visible.  \Hi{An {\tt OFMCOLOR} has been selected.} Bottom: image in 3
  transpositions after a {\tt RESET WINDOW} and a rotation with the
  corresponding spectrum and a {\tt TVPHLAME} pseudo-coloring.}}
\label{fig:HIfg}
\end{center}
\end{figure}

\end{document}
