HIGH-QUALITY 1d2d3d IMAGES USING ROBISHAW’S display.pro AND

RELATED PROCEDURES April 18, 2016

Carl Heiles, Tim Robishaw

Contents

1 INTRODUCTION 1 2 WRITING THE IMAGE 2

2.1 1d Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2 2.2 3d Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 3

3 NOW IS THE TO ANNOTATE THIS IMAGE 3 4 ADD A COLORBAR! USING TIM ROBISHAW’S colorbar 3 5 SUMMARY: MAKING AN IMAGE AND ITS COLORBAR 4 6 CREATING A 2d IMAGE AND COLORBAR 5

6.1 Using display2d for 2d Images . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 5 6.2 The Alternative: Do It All Yourself . . . . . . . . . . . . . . . . . . . . . . . . . . . . 6

7 USING rgbimg FOR 3D COLOR IMAGES 7

1. INTRODUCTION Tim Robishaw’s combination of display.pro and colorbar.pro is excellent for creating

publication-quality images^{1}. Here’s an introduction; for more details, look at the documentation. Important! There are various authors who wrote different versions of display and colorbar; here we treat Robishaw’s versions.

1trc.pro (gives a mouse-controlled cursor) and trp.pro (plots profiles of the image) work here.

If you want PostScript output, precede all of the commands below by opening the ps file. We recommend using ps ch.pro .

2. WRITING THE IMAGE

2.1. 1d Images

As an example, here we use the 1d image of the X-ray sky rass c.fits obtained by the ROSAT satellite^{2}; the image is a 480 × 240 FLOAT array. 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 display will fill it.

A good way to use display for this particular image:

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'

Some explanation:

1. x and y are the axes values. The angles run from 0 to 360 in x and from –90 to 90 in y. The first dimension of img must have the same number of elements as x while the second dimension of img must have the same number of elements as y.

2. min and 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).

3. 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 display type loadct, 5.

4. The x, y, and image titles speak for themselves.

5. 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 trp .

2http://astro.berkeley.edu/∼heiles/handouts/handouts images.html or http://ugastro.berkeley.edu/radio/2016/index.html .

In addition, there are some useful additional keywords or optional inputs for display. Some of the more useful include:

1. aspect allows you to change the shape of the image. aspect is the ratio of the x to the y dimensions of the output image.

2. 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 almost always want to set negative!

3. 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 gamma.

2.2. 3d Images

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

3. 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 xyouts .

4. ADD A COLORBAR! USING TIM ROBISHAW’S 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 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:

1. 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 vertical; set it appropriately.

2. Define position, a 4-element vector that specifies the normalized coordinates^{3} 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 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:

3Normalized coordinates range from 0 to 1 and are the fraction of the size of the window.

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 colorbar it will spill over the edge of the window, in which case you might get an error like this:

% DISPLAY: Normalized POSITION[2:3] must be less than 1.
% Execution halted at: DISPLAY           731

3. Define the data values that correspond to the min and max of the image brightness; for the description of display above, these would be min and max. Set crange=[min, max].

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

5. Define the name of the displayed quantity, e.g. xtitle='Xray intensity'.

6. Define position as above.

7. Then make the colorbar:

colorbar, POSITION=position, CRANGE=crange, CGAMMA=cgamma, $
        NEGATIVE=negative, VERTICAL=vertical, XTITLE=xtitle

For more info on colorbar parameters, see its documentation.

5. SUMMARY: MAKING AN IMAGE AND ITS COLORBAR

If you want a nice image/colorbar pair, then do the following:

1. Display the image using 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

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'

2. If you want to annotate or make other additions to the image, do so here using xyouts or any other routines .

3. Now we display the colorbar. Manipulate the position coordinates, using trial and error, to make it look visually good.

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

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

ps ch, 'filename.ps', /defaults, /color, xsize=8, ysize=8, /inch

(or you can use psopen). Then, at the end, close the PS file with

ps ch, /close

6. CREATING A 2d IMAGE AND COLORBAR

6.1. Using display2d for 2d Images

The easiest way to make a 2d image with its colorbar is with our 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

1. c img and i img as the color image and intensity image, respectively.

2. xaxis, yaxis as the (x,y) pixel values (like x,y for display).

3. c title and y title as the titles for the two images

4. Keyword 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 c range = [-10,10]).

5. Keywords intmin, intmax as the minimum/maximum intensity values for the intensity im-

ages (like min,max for display).

6. Keyword gamma as the contrast parameter (the intensity image is raised to this power).

7. Keywords xaxlbl, yaxlbl as the x- and y-axis labels.

8. For PostScript, set keywords ps, filename and, if you want encapsulated PostScript, encapsulated.

There are some other keywords; you can look at the code and experiment.

6.2. The Alternative: Do It All Yourself

1. For a 2d image you need to specify the min and max for both the color image (cmin, cmax) and the intensity image (imin, imax). These min/max values are specified as 2-element vectors. So for the color image, it’s crange= [cmin, cmax] and for the intensity image it’s irange= [imin, imax]. Similarly, each image has its own gamma (the power to which the data numbers are raised): cgamma and 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 xtitle (the name of the variable that represents color, e.g. velocity) and ytitle.

2. 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 × 3 array called 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 pseudo ch, colr. We assume this in our example just below; if you get colr in another way, you still need to loadct,0 before calling colorbar.

3. Finally, invoke the colorbar procedure:

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

N.B. Any of the keywords that you can send to plot are also accepted by display and 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 ticklen=-0.02 to both

display and colorbar.

7. USING rgbimg FOR 3D COLOR IMAGES

Tim’s 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 × 541; you can use congrid to convert your image to this size (but see the cautions about congrid in in the handout “1d2d3d: One, Two, and Three Dimensional Color Images”). The procedure is called rgbimg.pro and it is reasonably well-documented.