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

\begin{document}

\title{\bf HIGH-QUALITY 1d2d3d IMAGES USING 
ROBISHAW'S {\tt display.pro} AND RELATED PROCEDURES \\ \today} 

\author{Carl Heiles, Tim Robishaw}

\tableofcontents

\section{INTRODUCTION}

Tim Robishaw's combination of {\tt display.pro} and {\tt colorbar.pro}
is excellent for creating publication-quality images\footnote{{\tt
    trc.pro} (gives a mouse-controlled cursor) and {\tt trp.pro} (plots
  profiles of the image) work here.}.  Here's an introduction; for more
details, look at the documentation. {\it Important!} There are various
authors who wrote different versions of {\tt display} and {\tt
  colorbar}; here we treat {\it Robishaw's} versions. 

If you want PostScript output, precede all of the commands below by
opening the {\tt ps} file. We recommend using {\tt ps\_ch.pro} .

\section{WRITING THE IMAGE}
\subsection{ 1d Images}
As an example, here we use the 1d image of the X-ray sky {\tt
  rass\_c.fits} obtained by the ROSAT satellite\footnote{{\tt
    http://astro.berkeley.edu/$\sim$heiles/handouts/handouts\_images.html}
  or \\ {\tt http://ugastro.berkeley.edu/radio/2016/index.html} .}; the
image is a $480 \times 240$ FLOAT array. {\tt display} matches the image
size to the pre-existing window size, If you want a larger image on your
screen, you can define a window of your desired size and {\tt display}
will fill it.

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

\section {NOW IS THE TO ANNOTATE THIS IMAGE}
Having just written the image, it is now available for additions such as
annotations, plotted points, or a coordinate grid. For annotations, use
{\tt xyouts} .

\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 colorbar. 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 haven'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}

\item If you want to annotate or make other additions to the image, do
  so here using {\tt xyouts} or any other routines .

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

