Last modified: 15 Feb 2022

URL: https://cxc.cfa.harvard.edu/ciao/threads/true_color_ds9/

True Color Images in ds9

CIAO 4.16 Science Threads


Overview

Synopsis:

Most astronomical images map color to intensity level, e.g. lighter tones may correspond to a brighter intensity level in a greyscale image. An alternative way of presenting data is via an image that correllates color and energy.

SAOImage ds9, the imaging application distributed with CIAO, has the capability for users to create an RGB image and interactively adjust many of its parameters to achieve optimal results.

There are several output options, such as JPEG and PS, which are useful when producing images for the web and publication.

Purpose:

To apply a specific color table in ds9 to filtered files in order to create a true color image.

Related Links:

Last Update: 15 Feb 2022 - Review for CIAO 4.14. Updated for Repro-5 and CALDB 4.9.6


Contents


Get Started

Download the sample data: 198 (ACIS-S, CAS A (CHIP S3))

unix% download_chandra_obsid 198 evt2

Create Input Files

In this example, the following energy bands are used for the input event files:

  • soft: 0.2-1.5 keV
  • medium: 1.5-2.5 keV
  • hard: 2.5-8.0 keV

dmcopy is used to create three filtered event files:

unix% punlearn dmcopy

unix% dmcopy infile="acisf00198N005_evt2.fits[energy=200:1500]" \
      outfile="red_198.fits"

unix% dmcopy infile="acisf00198N005_evt2.fits[energy=1500:2500]" \
      outfile="green_198.fits"

unix% dmcopy infile="acisf00198N005_evt2.fits[energy=2500:8000]" \
      outfile="blue_198.fits"

Since ds9 automatically bins the event file into an image for display, it is not necessary to apply any binning beforehand. This provides for further flexibility in manipulating the data in ds9.

Creating Fluxed Input

If there is significant exposure variation across your data, e.g. you are using both front- and back-illuminated ACIS chips or are working with a mosaic, consider creating fluxed FITS images as input for the true-color image.

To create fluxed input images:

  1. Filter the event list into three energy bands.

  2. Create an exposure map for each filtered event file by running the fluximage script, as described in the Single-Chip or Multiple-Chip ACIS Exposure Map thread.

    After completing the thread, you will have three normalized images, one for each energy band.

  3. Use these fluxed images as input to this thread.

While creating exposure maps adds a non-trivial amount of time to the analysis, the image results can be significantly improved.


Creating an RGB Frame in ds9

To use the three-color capabilities of ds9, the data must be loaded into a special RGB frame. This frame will contain all three files, stacked together.

A. From the command line

The ds9 command-line syntax can be used to create the RGB frame and load the three filess in the correct bands:

unix% ds9 -rgb -red red_198.fits \
               -green green_198.fits \
	       -blue blue_198.fits &

ds9 will open with the three files in one frame, as shown in Figure 1; the "Scale" is set to "log: minmax". The RGB window (Figure 2) should open as well. If it doesn't, open it from the "Frame → RGB..." menu.

Use the binning and zoom options in ds9 to adjust the image so that the full region of interest is visible. This is similar to applying a spatial filter and binning specification when creating an image with dmcopy.

Figure 1: RGB frame with three files loaded

[Thumbnail image: The data is loaded into one ds9 frame; the RGB window indicates the current layer is Blue.]

[Version: full-size]

[Print media version: The data is loaded into one ds9 frame; the RGB window indicates the current layer is Blue.]

Figure 1: RGB frame with three files loaded

Figure 2: ds9 RGB window

[The RGB window indicates that all three layers are visible and Blue is selected as the current one.]
[Print media version: The RGB window indicates that all three layers are visible and Blue is selected as the current one.]

Figure 2: ds9 RGB window

If this window doesn't open automatically, launch it from the "Frame → RGB..." menu.

More information on the RGB command-line options is available from the ds9 Manual.


B. From the ds9 GUI

To load the files from the ds9 GUI:

  1. Launch ds9

  2. Choose "New Frame RGB" from the "Frame" menu.

    When the new frame is created, the RGB window (Figure 2) should open as well. If it doesn't, open it from the "Frame → RGB..." menu.

  3. Make sure the "Red" band is selected in the "Current" column of the RGB window, then choose "File → Open..." in the main ds9 window and select the red (soft-band) file, red_198.fits.

  4. Change the current band to "Green" in the RGB window. Open the green (medium-band) file, green_198.fits, as you did for the red.

  5. Change the current band to "Blue" in the RGB window. Open the blue (hard-band) file, blue_198.fits, as you did for the red and green.

The resulting ds9 display is shown in Figure 1. The "Scale" is set to "log: minmax".

Use the binning and zoom options in ds9 to adjust the image so that the full region of interest is visible. This is similar to applying a spatial filter and binning specification when creating an image with dmcopy.


C. Locking frames

Each frame of the RGB image may have different binning, scaling, smoothing, and colorbars applied to it. You can "lock" the frames together, so that all the setting is applied to all three frames at once. This is done with the Lock menu in the RGB window (Figure 3); all five options are checked in this thread.

Figure 3: Lock menu in the RGB window

[The lock menu is expanded and all four options are checked.]
[Print media version: The lock menu is expanded and all four options are checked.]

Figure 3: Lock menu in the RGB window


Smoothing the Data (optional)

Smoothing can help bring out finer features in the data by removing statistical noise. It is an optional step; experiment with smoothing to see if it improves the appearance of your data.

The smoothing capability in ds9 lets you interactively smooth the data, as opposed to running the CIAO tools aconvolve or csmooth. For quantitative data analysis, the configurable CIAO tools are more appropriate, but ds9 does a nice job for publication purposes.

Choose "Smooth" from the "Analysis" menu and the ds9 display is updated with the results of smoothing. The "Smooth" option can be toggled on and off during your ds9 session.

Open the "Smoothing Parameters..." dialog box from the same menu to adjust the function and kernel radius of the smoothing. The default smoothing is a Gaussian function with radius of three, which is fine for this data. The results are shown in Figure 4.

Figure 4: Data smoothed with a Gaussian of radius three

[Thumbnail image: The smoothed data are displayed in ds9.]

[Version: full-size]

[Print media version: The smoothed data are displayed in ds9.]

Figure 4: Data smoothed with a Gaussian of radius three


Adjusting the Scale Parameters

This data is being displayed with a "log: minmax" scale. That means that ds9 stretches the scale to encompass the range of pixel values in the file. Adjusting the minimum and maximum scale values sets a threshold for the background data and brings out features.

To change the minimum and maximum values, open the "Scale → Scale Parameters" dialog box. The pixel distribution shown is for the band selected as "Current" in the RGB window; change the current band selected and the histogram of pixel values is updated to match.

To adjust the values, use the cursor to grab the red (minimum) or green (maximum) vertical lines on the plot and drag them to the desired location. You can type a value in to the "Low" or "High" field and hit "Apply" to set the limits.

A basic guideline for setting the low value is to minimize the contribution of the background. That is, adjust the minimum of each band until the background of the image is flat (i.e. solid black). For the maximum value, bringing it in to the last data point in the pixel distribution is usually sufficient.

For ObsID 198 with the smoothing applied, the following limits were chosen:

Band Low High
Red 0.255 10
Green 0.255 18
Blue 0.0779 5

Figure 5 shows the image with the new pixel value limits set.

Figure 5: The adjusted pixel distribution for scaling

[Thumbnail image: The background of the image is almost completely flat (black) after changing the scaling values.]

[Version: full-size]

[Print media version: The background of the image is almost completely flat (black) after changing the scaling values.]

Figure 5: The adjusted pixel distribution for scaling


More Display Options

There are a number of other options that can be added to the image display. The two most popular are overlaying a source list and including a coordinate grid.

Overlaying a Source List

To overlay a source list on a ds9 image:

  • ASCII files: load the region file from the ds9 menu "Regions" → "Load Regions..." → ascii_file.reg.

  • FITS files load the region file from the ds9 menu "Regions" → "Load Regions..." → fits_file.fits.

    The region definition is saved in the REGION or SRCLIST extension of the FITS file. ds9 should automatically find the correct extension.

Read the Using CIAO Region Files thread for more information on working with regions in ds9.


Adding a Coordinate Grid

To add a coordinate grid to the image, choose the "Coordinate Grid" option from the "Analysis" menu. Then choose "Coordinate Grid Parameters" from the same menu to open the preferences dialog (Figure 6).

Figure 6: Coordinate Grid parameters dialog box

[The parameter box contains fields to set the plot title and axis labels and to change the axis spacing and numbering.]
[Print media version: The parameter box contains fields to set the plot title and axis labels and to change the axis spacing and numbering.]

Figure 6: Coordinate Grid parameters dialog box

From the preferences box, you can change the color, font, line style (solid or dash), and line thickness for all elements of the grid. The font style, size, and color can be edited, and you can add titles. It is also possible to turn off the display of individual items via the "View" menu.

In Figure 7, we have turned off the grid lines and border. The axes have been changed to "Exterior Axes" (from the "Type" menu). The ds9 "Edit → Preferences → View → Background Color" menu was used to make the background of the ds9 window black instead of the default white; this provides a better display for the axes on the image.

Figure 7: Final three-color image with coordinate grid overlaid

[Thumbnail image: The three-color image is displayed in ds9.]

[Version: full-size]

[Print media version: The three-color image is displayed in ds9.]

Figure 7: Final three-color image with coordinate grid overlaid


Saving the Output

Once you are happy with your true color image, there are a number of output options in ds9.

  • Image formats: from the "File → Save Image..." menu, you can choose JPG, PNG, or TIFF file formats.

  • Postscript: to create a postscript file, go to "File → Print..." and select "Print To: File".

Currently it is not possible to save the state of the ds9 imager. This means that you cannot save the composite RGB frame and reopen later for further analysis. This functionality is expected to be added in a future version of ds9.


The Equivalent dmimg2jpg Command

There is another CIAO thread, True Color Images, which uses the dmimg2jpg tool to create a three-color image. This method would be preferable for users looking to script the analysis.

Note that the data needs to be smoothed prior to running dmimg2jpg. The tool does not have an option to apply it. This can be done with aconvolve.

Since the tool requires images as input, a binning specification has been added to the filenames. The spatial filter is used to constrain the size of the output image.

The dmimg2jpg equivalent to running this thread (without smoothing) is:

unix% punlearn dmimg2jpg

unix% dmimg2jpg infile="red_198.fits[bin x=3650:4550:1,y=3450:4350:1]" \
      greenfile="green_198.fits[bin x=3650:4550:1,y=3450:4350:1]" \
      bluefile="blue_198.fits[bin x=3650:4550:1,y=3450:4350:1]" \
      scalefunction="log" scaleparam="1" \
      minred="0.255" mingreen="0.255" minblue="0.0779" \
      maxred="10" maxgreen="18" maxblue="5" \
      showaimpoint="no" showlabel="no" showgrid="yes" fontsize="1" \
      outfile="dmimg2jpg.jpg" psfile="dmimg2jpg.ps" 

Figure 8 shows the dmimg2jpg output.

Figure 8: Three-color image created with dmimg2jpg

[Thumbnail image: The image has a coordinate grid overlaid.]

[Version: full-size]

[Print media version: The image has a coordinate grid overlaid.]

Figure 8: Three-color image created with dmimg2jpg


History

02 Feb 2007 new for CIAO 3.4: original version
16 Jan 2008 updated for CIAO 4.0: ds9 now automatically looks for the "[REGION]" or "[SRCLIST]" extension in the region file, so it doesn't have to be specified; new Locking frames section
04 Feb 2009 updated for CIAO 4.1: images converted to inline
28 Jan 2010 updated for CIAO 4.2: changed 'lock' RGB menu figure
13 Jan 2011 reviewed for CIAO 4.3: no changes
08 Jul 2011 added a link to fluximage in the Creating Fluxed Input section
10 Jan 2012 reviewed for CIAO 4.4: no changes
03 Dec 2012 Review for CIAO 4.5; no changes
11 Dec 2013 Review for CIAO 4.6; minor edits.
23 Dec 2013 Review for CIAO 4.7; no changes.
01 Feb 2016 Update ds9 links.
15 Feb 2022 Review for CIAO 4.14. Updated for Repro-5 and CALDB 4.9.6