\documentclass[preprint]{aastex}
\usepackage{graphicx}

\begin{document}

%\title{\bf MAKING ANNOTATED IMAGES IN IDL \\ (WITH COLORBARS TOO!) \\ \today} 
\title{\bf IMAGE DISPLAY, ANNOTATION, AND EXAMINATION WITH TIM
  ROBISHAW'S {\tt display.pro} AND RELATED PROCEDURES \\ \today} 

\author{Carl Heiles, Tim Robishaw}

\tableofcontents

\section{INTRODUCTION}

Tim Robishaw's {\tt display.pro} does most of what we cover in other
handouts\footnote{Particularly the three handouts ``IDIDL---Image
Display and Manipulation in IDL'' (ididl.ps) ``1d2d3d: One, Two, and
Three Dimensional Color Images'' (newdimensionalcolor.ps).  ''IACIDL:
Image Annotation and Colorbars in IDL'' (annotated\_images.ps).}, but
much more simply. Here's an introduction to this and related
programs. We emphasize that this is an {\it introduction} to those
programs; for more details, look at their documentation (in IDL, that's
{\tt doc, 'display'} for {\tt display.pro}). One more thing: while {\tt
display.pro} does things more simply, those handouts describe how to
things more flexibly (e.g., sizing and placement of display windows and
colorbars)---and less simply. 

{\it Important!} There are various authors who wrote different versions
of {\tt display} and {\tt colorbar}; we treat, and recommend, {\it
Robishaw's} versions. The Robishaw procedures we cover here include:
\begin{enumerate}

\item {\tt display.pro} . This displays 1d or 3d images, draws axes,
labels axes, properly bytescales the images (either automatically or
according to user specs), changes contrast\dots

\item {\tt trc.pro} . Shorthand for trcursor, this slaps a nice crosshairs
  on the screen and, when you push the mouse button, records the image
  value and the x/y positions. {\tt trc} works for ordinary graphs, too,
  for which it is very handy!

\item {\tt trp.pro} . Shorthand for trprofiles, this plots image profiles
  (the image intensity versus the x or y coordinate).

\item {\tt colorbar.pro} . Puts a colorbar near your displayed
image. 

\item {\it Important!} If you are making a postscript file output, then
see \S \ref{ps} below!

\end{enumerate}

In short, the first three of these Robishaw procedures do what the
  native IDL procedures {\tt tv}, {\tt rdpix}, and {\tt profiles} do,
  except that they can give the x/y values in designated coordinate
  values instead of pixels, do a few other nice things, and work better.

Let's get started at the same place as in \S 3 of IDIDL. Specifically,
we'll start with 1-d images, like a greyscale or false-color image, which
means you are using a 256-entry color table, i.e.\ you have turned color
decomposition off\footnote{You do this by typing {\tt device,
    decomposed=0} .}. (If this is Greek to you, read the first two sections of
IDIDL.)

\section{USING TIM ROBISHAW'S {\tt display} TO MAKE AND EXAMINE 1D OR 3D IMAGES}

Here we assume you are writing to the terminal window, not postscript;
see \S \ref{ps} for postscript. Before starting, set {\tt ps=0}; this
tells the {\tt display} and {\tt colorbar} programs what you're doing.

\subsection{ 1d Images} \label{display}

First, generate an image\footnote{There's a nice 1d image of the X-ray sky,
  obtained by the ROSAT satellite, in {\tt
    http://astro.berkeley.edu/$\sim$heiles/handouts/rass\_c.fits} .  Copy
  this file to the disk area where you are running IDL. To accomplish this,
  type {\tt wget
    http://astro.berkeley.edu/$\sim$heiles/handouts/rass\_c.fits} .  This
  file is in a format called ``FITS'' format, which is the standard format
  of most astronomical images.  To read the data file into an array called
  {\tt img}, it is easiest to use the IDL procedure called ``readfits'',
  which resides in the Goddard IDL library, which, in turn, is already in
  your IDL path.  All you have to do is type {\tt img =
    readfits('rass\_c.fits', headerinfo)} .  This returns two arrays: the
  image array ({\tt img}) and information about the image ({\tt
    headerinfo}); type {\tt print, headerinfo} to see the header
  information.  Now type {\tt help, img} and IDL will tell you that it is a
  $480 \times 240$ FLOAT array.}.  In IDIDL, we matched the window size to
the image size. When using {\tt display}, you don't need to do that; it's
done automatically, and it will even generate a window for you if you don't
have one open. If you want a larger image on your screen, you can define a
window of your desired size and {\tt display} will fill it. You have to be
careful, though, about the effects of reducing the size (number of
  pixels) of an image because the interpolation process can lose
  information, depending on how it's done. The discussion of {\tt
  congrid} in IDIDL explains these concerns, which apply to {\tt
  display} even though it doesn't use {\tt congrid}. 

A good way to use {\tt display} for this particular image:

\begin{verbatim}
x=findgen(480)* (360./480.) 
y=findgen(240)* (180./240.) - 90.
ps=0

display, img, x, y, min=0, max=2000, out=out, ps=ps, $
xtit='Galactic Longitude', ytit='Galactic latitude', title= 'C-Band ROSAT Sky'
\end{verbatim}

Some explanation: \begin{enumerate}

\item {\tt x} and {\tt y} are the axes values. The angles run from 0 to 360
  in {\tt x} and from --90 to 90 in {\tt y}. The first dimension of {\tt
    img} must have the same number of elements as {\tt x} while the second
  dimension of {\tt img} must have the same number of elements as {\tt y}.

\item {\tt min} and {\tt max} say that the minimum data value will be
  converted to 0 (the minimum intensity, black for a greyscale image) and
  the maximum to 255 (white).

\item If you wanted to make a false-color image instead of greyscale, load
  in your desired color table. For example, if you want to use a native IDL
  color table, e.g.\ number 5, then before calling {\tt display} type {\tt
    loadct, 5}.

\item The x, y, and image titles speak for themselves.

\item {\tt out} is an output structure that contains information used
  for examining and manipulating the image; check it out. It is used
  directly as an input to {\tt trp} .

\end{enumerate}

In addition, there are some useful additional keywords or optional
inputs for {\tt display}. Some of the more useful include: \begin{enumerate}

\item {\tt aspect} allows you to change the shape of the image. {\tt
  aspect} is the ratio of the x to the  y dimensions of the output
  image.

\item {\tt negative}: if  you set this keyword, then the color table is
  reversed. That is, instead of black/white being min/max, black/white
  is max/min. For greyscale images to be printed on paper, or
  projected in a powerpoint presentation, you {\it almost always}
  want to set {\tt negative}!

\item If you want to change the contrast of the image, you must do it
  yourself before calling display. For example, to increase the
  contrast so that weak features are highlighted, one often raises the
  image values to a power less than one. This power is usually called
  {\tt gamma}. 

\item If you want to write the image to a postscript file, see \S
  \ref{ps}. 

\end{enumerate}

\subsection{ 3d Images}

Everything here is exactly as above, except that {\bf (1)} your image
must be a truecolor image of dimension (3, nx, ny) [i.e., 3 colors by
(nx/ny) (horizontal/vertical) pixels]; and {\bf (2)} you need to set
  the {\tt true} keyword when calling {\tt display}. 


\subsection{Examine the 1d Image on Your Terminal}
\subsubsection{Interactively Locate Points Using {\tt trc}}

{\tt trc} is just a wrapper that calls {\tt tr\_rdplot} with useful
settings. Type

\noindent {\tt trc, x, y}

\noindent Then move the cursor inside the plot window. Left clicks write
and record the {\tt (x,y)} values in the coordinate system you select
(i.e., {\tt data, device, normal}; default is {\tt data}). A middle or left
click will exit the program.  Notice that the crosshairs are clipped at
the axes: it's often useful to make the crosshairs extend to the edges of
the window.  This is accomplished by passing the {\tt /noclip} keyword, and
since we can use minimum matching in IDL, {\tt /noc} will be good enough:

\noindent {\tt trc, x, y, /noc}

\noindent If you don't want to store the positions of your left-clicks
in {\tt x} and {\tt y}, then you don't need to include them in the
procedure call. For more details, see the
documentation of {\tt trc} and {\tt tr\_rdplot}.

\subsubsection{Interactively Plot 1d Image Intensities Versus x or y
  Using {\tt trp}}

{\tt trp} is just a wrapper that calls {\tt tr\_profiles} with useful
settings. Type

\noindent {\tt trp, out}

\noindent Notice that a new window has been created.  Move the cursor
inside the plot window containing the displayed image. You now see the
profiles in the newly created window (labeled {\it Profiles}).  Initially,
you see intensity versus the {\tt x} data coordinates. Left click gives
intensity versus the {\tt y} data coordinates. Middle click prints the x/y
values.  Right click exits the program and closes the profiles window. For
more, see the documentation for {\tt trp} and {\tt tr\_profiles}.

Normally {\tt trp} plots profiles of the original, unscaled image.
However, if you have scaled the displayed image using {\tt min} and/or {\tt
  max}, and if you want to get profiles of this scaled image, type

\noindent {\tt trp, out, /scaled}

\noindent Obviously, in order for all this to work, you need to have used
the {\tt OUT} keyword for {\tt display} prior to calling {\tt trp}.

\section{ADD A COLORBAR! USING TIM ROBISHAW'S {\tt colorbar}}

Displaying an image without a colorbar is like displaying a graph with
axes that have no numbers or labels. It's easy to add a colorbar with
Tim's {\tt colorbar}. This procedure does either 1d or 2d colorbars; see
the images in in the handout ``1d2d3d: One, Two, and Three
Dimensional Color Images''. Here we first describe what to do for a 1d
colorbar; next we describe the 2d case. 

In either case, the first job is to decide where to put the
colorbaar. Decide if you want a horizontal colorbar (usually on the top) or a
  vertical one (usually on the right hand side). There's a keyword {\tt
  vertical}; set it appropriately.

You need enough space for the colorbar. To make enough space on the
  terminal, use a bigger x-window; to make enough on the postscript
  window, see \S \ref{ps}.

Then define {\tt position}, a 4-element vector that specifies the
normalized coordinates\footnote{Normalized coordinates range from 0 to 1
  and are the fraction
  of the size of the window.} of the corners of the colorbar. The 4
elements are in order (lowleftx, lowlefty, uprgtx, uprgty). For example,
for a horizontal colorbar on the top you might choose something like
{\tt position = [ 0.1, 0.8, 0.9, 0.9]} .

The remaining jobs depend on whether you are making a 1d or 2d
colorbar. 

\subsection{ A 1d Colorbar} \label{colorbar}

\begin{enumerate}
\item Define the data values that correspond to the min and max of the
  image brightness; for the description of {\tt display} above, these
  would be {\tt min} and {\tt max}. Set {\tt crange=[min, max]}. 

\item If you raised the data to a power ({\tt gamma}) to change the
  contrast, then set {\tt cgamma = gamma}. If not, set {\tt cgamma=1} or
  leave it undefined.

\item Define the name of the displayed quantity, e.g.\ {\tt
  xtitle='Xray intensity'}. 

\item Then make the colorbar:
\begin{verbatim}
colorbar, POSITION=position, ps=ps, CRANGE=crange, CGAMMA=cgamma, $
        NEGATIVE=negative, VERTICAL=vertical, XTITLE=xtitle
\end{verbatim}

\noindent For more info on colorbar parameters, see its documentation.
\end{enumerate}


\subsection{ A 2d Colorbar}

\begin{enumerate}
\item For a 2d image you need to specify the min and max for both 
the color image ({\tt cmin,
  cmax}) and the intensity image ({\tt imin, imax}). These min,
  max values are specified as 2-element vectors. So for the color image,
  it's {\tt crange= [cmin, cmax]} and for the intensity image it's {\tt
  irange= [imin, imax]}. Similarly, each image  has its own gamma (the
  power to which the data numbers are raised): {\tt cgamma} and {\tt
  igamma}. It should be obvious that these gamma values should
  correspond to what you used when you displayed the image. The titles
  on the colorbar are {\tt xtitle} (the name of the variable that
  represents color, e.g. velocity) and {\tt ytitle}. 

\item Finally, for 2d color image and colorbar you are using a 256-entry
  colortable to define the colors. The 256 (r,g,b) intensities are
  represented with a $256 \times 3$ array called {\tt colr}. If you use
  the physiologically-correct colortable discussed in the handout
  ``1d2d3d: One, Two, and Three Dimensional Color Images'', then you get
  this array from the procedure {\tt pseudo\_ch, colr}. We assume this
  in our example just below; if you get {\tt colr} in another way, you
  still need to {\tt loadct,0} before calling {\tt colorbar}. 

\item Finally, invoke the colorbar procedure:

\begin{verbatim}
pseudo_ch, colr
loadct,0
colorbar, POSITION=position, RGB=colr, ps=ps, $
	CRANGE=crange, IRANGE=irange, CGAMMA=cgamma, IGAMMA=igamma, $
        NEGATIVE=negative, VERTICAL=vertical, $
        XTITLE=xtitle, YTITLE=ytitle
\end{verbatim}
\end{enumerate}
 
\section{IF YOU WANT AN IMAGE AND COLORBAR ON POSTSCRIPT\dots} \label{ps}

If you want a
nice image/colorbar in postscript, then do the following (We're
repeating the individual contents of \S \ref{display} and \S
\ref{colorbar}, just so you see how easy it is)\footnote{ If
you don't want it on postscript, don't do the first two steps---i.e.,
set {\tt ps=0} and don't invoke {\tt psopen} .}:
\begin{enumerate}

\item You must tell {\tt display} and {\tt colorbar} that  you're writing
to postscript, so 

\noindent {\tt ps=1}

\item Open the postscript device, making sure to specify the size; the
  size must be big enough to accommodate both the image and the colorbar. For
  example: 

\noindent {\tt psopen, 'xray.ps', /times, /bold, /isolatin1, /color,
    xsize=8, ysize=8, /inch }

\noindent which writes to the file {\tt xray.ps}, uses the Times/Bold
  font, allows color in the image, and sets the x and y sizes to 8 and 8
  inches.  

\item Display the image  using {\tt display}, setting ps. You need to specify the
  size of the image and, in particular, you need to make it smaller than
  the postscript window size; this leaves room for the colorbar. So you
  might say

\begin{verbatim}
x=findgen(480)* (360./480.) 
y=findgen(240)* (180./240.) - 90.
xsize=8
ysize=5
min=0
max=2000
display, img, x, y, ps=ps, min=min, max=max, out=out, $
xsize=xsize, ysize=ysize, /inch, $
xtit='Galactic Longitude', ytit='Galactic latitude', title= 'C-Band ROSAT Sky'
\end{verbatim}

\noindent {\it Notes:} {\bf (1)} With a ps window ysize of 8 inches and an
image ysize of 5 inches, you have 3 vertical inches left for the
colorbar. {\bf (2)} If you want to annotate the image, do so here using
{\tt xyouts} . 

\item Now we display the colorbar, as above, setting ps. Manipulate the
  {\tt position} coordinates, using trial and error, to make it look
  visually good. And if we're in postscript, we close the file and
  properly return to x windows.

\begin{verbatim}
position = [0.15, 0.79, 0.85, 0.88]
xtitle=  'ROSAT counts'
colorbar, POSITION=position, ps=ps, CRANGE=crange, CGAMMA=cgamma, $
        NEGATIVE=negative, VERTICAL=vertical, XTITLE=xtitle
if ps then psclose
if ps then setcolors, /sys
\end{verbatim}

\end{enumerate}


\section{USING {\tt dsply2d} FOR 2D IMAGES}

This poorly-documented procedure is quick and automatically gives you a
nice colorbar. However, it requires your images to be $541 \times 541$
pixels. If they are not this size, the procedure resizes them using {\tt
congrid}; the image always comes out square. A more flexible alternative
is the 2d example in the handout ``1d2d3d: One, Two, and Three
Dimensional Color Images''.

2d images synthesize color and intensity, so
these plots explicitly require information for the two
dimensions---i.e., the two images. Define
\begin{enumerate} 

\item {\tt c\_img} and {\tt i\_img} as the color image and intensity
  image, respectively.

\item {\tt xaxis, yaxis} as the (x,y) pixel values (like {\tt x,y} for
  {\tt display}).

\item {\tt c\_title} and {\tt y\_title} as the titles for the two
images

\item Keyword {\tt c\_range}: a 2-element vector specifying the max and
  min of color used for labeling (e.g., if colors correspond to a
  velocity range of -10 to 10 km/s, then {\tt c\_range = [-10,10]}).

\item Keywords {\tt intmin, intmax} as the minimum/maximum intensity values for
  the intensity images (like {\tt min,max} for {\tt display}).

\item Keyword {\tt gamma} as the contrast parameter (the intensity image is
  raised to this power).

\item Keywords {\tt xaxlbl, yaxlbl} as the x- and y-axis labels.

\item For postscript, set keywords {\tt ps}, {\tt filename} and, if
  you want encapsulated postscript, {\tt encapsulated}.  

\end{enumerate}

\noindent There are some other keywords; you can look at the code and
experiment. As I said above, for more flexibility look at the 2d example
in the handout ``1d2d3d: One, Two, and Three Dimensional Color Images''.

\section{USING {\tt rgbimg} FOR 3D COLOR IMAGES}

We have a clumsily-written but reliable procedure to produce a 3d image
with a fancy colorbar like those of Figure 6 in the handout ``1d2d3d:
One, Two, and Three Dimensional Color Images''. A severe restriction is
that the image must have dimensions $541 \times 541$; you can use {\tt
congrid} to convert your image to this size (but see the cautions about
{\tt congrid} in in the handout ``1d2d3d: One, Two, and Three
Dimensional Color Images''). The procedure is called {\tt rgbimg.pro} and
it is reasonably well-documented.

To see what kind of image and colorbar this produces, see the handout
``1d2d3d: One, Two, and Three Dimensional Color Images''.

\end{document}

