\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}

\tableofcontents

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

Tim Robishaw's {\tt display.pro} does most of what we cover in other
handouts, but much more simply. Here's an introduction to this and related
programs, namely \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.

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

\end{enumerate}

In short, these commands 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. (If this is Greek to you, read the first two sections of
IDIDL.)


\subsection{ 1d Images}

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 {\tt congrid} (namely: it can
interpolate over small features when you shrink an image---see IDIDL).

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 the image.

\end{enumerate}

In addition, there are some useful additional keywords or optional
inputs for {\tt display}: \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 write the image to a postscript file, you must
  first open it. Best is to use our {\tt psopen} procedure. For example, 

  \noindent {\tt psopen, 'xray.ps', /times, /bold, /isolatin1, /color,
    xsize=6, ysize=4, /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 6 and 4
  inches.  Then call {\tt display}. After that, close the ps file with {\tt
    psclose} .

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

\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 The positions of your left-clicks can be passed out in arrays in
addition to having them printed to the screen. For more details, see the
documentation of {\tt trc} and {\tt tr\_rdplot}.

\subsubsection{Interactively Plot the 1d Image Intensities Versus x or y As You Move Your Cursor}

{\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{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 an image
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. 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}

