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

\begin{document}

%\title{\bf MAKING ANNOTATED IMAGES IN IDL \\ (WITH COLORBARS TOO!) \\ \today} 
\title{\bf TRDIDL: 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\_library,
  'display'} (or, if you use our startupfile, {\tt doc, 'display'})
for {\tt display.pro}). 

{\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. 

\end{enumerate}

\noindent 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.

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

\subsection{ Create the Image: the 1d Case} \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; {\tt display} matches the image size to the pre-exisging window
size, or 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.

display, img, x, y, min=0, max=2000, out=out, $
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}. 

\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}
\subsection{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 when calling keywords 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}.

\subsection{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 the handout ``1d2d3d: One, Two, and Three
Dimensional Color Images''. Here's what you do: 
\begin{enumerate}

\item 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.

\item 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]} .  If you have a
horizontal colorbar and you want it to extend the exact length of the
image, you can get the normalized position of the left and right edges of
the image from the system variable !x.window; similarly, the top and bottom
are stored in !y.window.  So if you wanted a colorbar that matched the
width of the image and you wanted it to have a height of 10\% of the height
of the window, then you could make the colorbar float 5\% above the top of
the image by providing a position vector of:

\noindent {\tt position = [!x.window[0],!y.window[1]+0.05,!x.window[1],!y.window[1]+0.05+0.10]}

You need enough space for the colorbar. If you havn't made a big enough
window, then when you run {\tt colorbar} it will spill over the edge of
the window, in which case you might get an error like this:

\begin{verbatim}
% DISPLAY: Normalized POSITION[2:3] must be less than 1.
% Execution halted at: DISPLAY           731
\end{verbatim}

\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 Define {\tt position} as above.

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

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

\section{SUMMARY: MAKING AN IMAGE AND ITS COLORBAR} \label{ps}

If you want a nice image/colorbar pair, then do the following:
\begin{enumerate}

\item Display the image using {\tt display}. 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.
min=0
max=2000
position= [.15, .15, .85, .85]
display, img, x, y, min=min, max=max, out=out, $
       xtit='Galactic Longitude', ytit='Galactic Latitude', $
       title= 'C-Band ROSAT Sky'
\end{verbatim}

\noindent {\it N.B.} If you want to annotate the image, do so here using
 {\tt xyouts} .

\item Now we display the colorbar. Manipulate the {\tt position}
  coordinates, using trial and error, to make it look visually good.

\begin{verbatim}
position = [0.15, 0.88, 0.85, 0.94]
xtitle=  'ROSAT counts'
colorbar, POSITION=position, CRANGE=crange, CGAMMA=cgamma, $
        NEGATIVE=negative, VERTICAL=vertical, XTITLE=xtitle
\end{verbatim}

\end{enumerate}

If you want all this on PostScript with an 8-inch square window, begin with 

\noindent {\tt ps\_ch, 'filename.ps', /defaults, /color, xsize=8, ysize=8, /inch}

\noindent (or you can use {\tt psopen}). Then, at the end, close the PS file with 

\noindent {\tt ps\_ch, /close}

\section{ CREATING A 2d IMAGE AND COLORBAR}

\subsection{Using {\tt display2d} for 2d Images}

The easiest way to make a 2d image with its colorbar is with our {\tt
  display\_2d.pro}; this does everything with one procedure call. For an
example showing how it's used, see the appendices in our tutorial
``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. 

\subsection{The Alternative: Do It All Yourself}

\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 a 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, $
        CRANGE=crange, IRANGE=irange, CGAMMA=cgamma, IGAMMA=igamma, $
        NEGATIVE=negative, VERTICAL=vertical, $
        XTITLE=xtitle, YTITLE=ytitle
\end{verbatim}
\end{enumerate}

\noindent N.B.\ Any of the keywords that you can send to {\tt plot} are
also accepted by {\tt display} and {\tt colorbar}.  As an example,
sometimes it's easier to see tickmarks on an image and on a colorbar if
they are pointing outwards; this could be accomplished by passing the
keyword {\tt ticklen=-0.02} to both {\tt display} and {\tt colorbar}.


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

Tim's {\tt dieplay} handles 3d images. But how do you make a colorbar
for 3d images? For our solution, see our handout ``1d2d3d: One, Two, and
Three Dimensional Color Images''
(newdimensionalcolor.ps). Unfortunately, however, we do not have a
colorbar procedure that produces our 3d colorbar.

What we can offer is 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.

\end{document}

