Last modified: 15 Feb 2022

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

True Color Images

CIAO 4.16 Science Threads


Overview

Synopsis:

Most astronomical images map color to intensity level, i.e. for a greyscale image, lighter tones correspond to a brighter intensity level or vice versa. An alternative way of presenting data is via an image that correllates color and energy or wavelength. The output may also be a postscript file.

Purpose:

Use the CIAO tool dmimg2jpg to create a true color image and (optionally) overlay a source list on that 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: 1838 (ACIS-S, G21.5-09)

unix% download_chandra_obsid 1838 evt2

Create Input Images

First we need to create the input image files for dmimg2jpg. In this example, we use dmcopy to create 3 image files corresponding to the soft, medium, and hard energy bands. For the soft band (energy = 0.2 to 1.5 keV):

unix% punlearn dmcopy
unix% pset dmcopy infile="acisf01838N004_evt2.fits[energy=200:1500][bin x=3773:4380,y=4006:4509]"
unix% pset dmcopy outfile=soft_img.fits
unix% dmcopy 
Input dataset/block specification (acisf01838N004_evt2.fits[energy=200:1500][bin x=3773:4380,y=4006:4509]): 
Output dataset name (soft_img.fits): 

This dmcopy command takes the events in the given energy range and bins them to create an image of the S3 chip only (specified by the coordinates in the bin option). Since we did not give a blocking factor, the image is binned to the default value of 1; see ahelp dmcopy for information on blocking.

The command may be condensed to a single line instead. For the medium band (energy = 1.5 to 2.5 keV):

unix% dmcopy "acisf01838N004_evt2.fits[energy=1500:2500][bin x=3773:4380,y=4006:4509]" med_img.fits

And, finally, for the hard band (energy = 2.5 to 8.0 keV):

unix% dmcopy "acisf01838N004_evt2.fits[energy=2500:8000][bin x=3773:4380,y=4006:4509]" hard_img.fits
[NOTE]
Energy Bands

The choice of energy bands is dependent on the type of source and specific types of analysis the user is doing. The energy bands in this thread are different than the energy bands used in the Chandra Source Catalog.


Create a True Color Image

Now we can use dmimg2jpg to combine the the soft, medium and hard images created in the previous section into a single RGB image:

unix% punlearn dmimg2jpg
unix% pset dmimg2jpg infile=soft_img.fits
unix% pset dmimg2jpg greenfile=med_img.fits
unix% pset dmimg2jpg bluefile=hard_img.fits
unix% pset dmimg2jpg outfile=truecolor_1838.jpg
unix% pset dmimg2jpg maxred=1 maxblue=1 maxgreen=1
unix% pset dmimg2jpg showgrid=yes
unix% pset dmimg2jpg gridsize=60
unix% pset dmimg2jpg fontsize=1
unix% dmimg2jpg
Input file name (red image if true color) (soft_img.fits): 
Green color channel file name (med_img.fits): 
Blue color channel file name (hard_img.fits): 
Output jpg file name (truecolor_1838.jpg): 

The resulting image looks like Figure 1. You can check the parameter file with plist dmimg2jpg.

Figure 1: X-ray true-color image of G21.5-09

[Thumbnail image: The image is displayed with a WCS grid showing the coordinates.]

[Version: full-size]

[Print media version: The image is displayed with a WCS grid showing the coordinates.]

Figure 1: X-ray true-color image of G21.5-09

A few notes on the parameters used above: maxred, maxblue, and maxgreen control the maximum pixel value to be used in the red, green, and blue files respectively. Experiment with these parameters to bring out the features in which you are interested. In general, lower maximum pixel values will bring out fainter features; for unsmoothed images, values near 1 may be necessary to display background noise.

The parameter showgrid controls whether a sky grid is overlayed on the image; gridsize=60 draws a grid line every 60 arcsecs. fontsize controls the size of font marking RA and Dec.

There is also a regionfile parameter that allows users to overlay a FITS formatted region (e.g. to mark the locations of sources). This option is discussed further in the Overlaying a Source List section.

[TIP]
Tip

Users may want to smooth their images before creating true color images. This can be done with several ciao tools: aconvolve, csmooth, or dmimgadapt.


Real vs. Virtual Image Files

It is also possible to use virtual files as input to dmimg2jpg, bypassing the dmcopy steps. To repeat the previous command with virtual file syntax:

unix% punlearn dmimg2jpg
unix% pset dmimg2jpg infile="acisf01838N004_evt2.fits[energy=200:1500][bin x=3773:4380,y=4006:4509]"
unix% pset dmimg2jpg greenfile="acisf01838N004_evt2.fits[energy=1500:2500][bin x=3773:4380,y=4006:4509]"
unix% pset dmimg2jpg bluefile="acisf01838N004_evt2.fits[energy=2500:8000][bin x=3773:4380,y=4006:4509]"
unix% pset dmimg2jpg outfile=virtual_1838.jpg
unix% pset dmimg2jpg maxred=1 maxblue=1 maxgreen=1
unix% pset dmimg2jpg showgrid=yes
unix% pset dmimg2jpg gridsize=60
unix% pset dmimg2jpg fontsize=1
unix% dmimg2jpg
Input file name (red image if true color) (acisf01838N004_evt2.fits[energy=200:1500][bin x=3773:4380,y=4006:4509]): 
Green color channel file name (acisf01838N004_evt2.fits[energy=1500:2500][bin x=3773:4380,y=4006:4509]): 
Blue color channel file name (acisf01838N004_evt2.fits[energy=2500:8000][bin x=3773:4380,y=4006:4509]): 
Output jpg file name (virtual_1838.jpg): 

Using this method is useful if disk space is an issue, since the intermediate files aren't written out.


Overlaying a Source List

A. On an X-ray Image

It is straightforward to overlay a source list from one of the detect tools, onto the x-ray image; the file may be either FITS or ASCII format. Using the regionfile parameter in dmimg2jpg:

unix%  cat sources.reg 
# Region file format: CIAO version 1.0
circle(4071,4247,75)
circle(4245,4092,20)

unix% punlearn dmimg2jpg
unix% pset dmimg2jpg infile=soft_img.fits
unix% pset dmimg2jpg greenfile=med_img.fits
unix% pset dmimg2jpg bluefile=hard_img.fits
unix% pset dmimg2jpg outfile=overlay_1838.jpg
unix% pset dmimg2jpg maxred=1 maxblue=1 maxgreen=1
unix% pset dmimg2jpg showgrid=yes
unix% pset dmimg2jpg gridsize=60
unix% pset dmimg2jpg fontsize=1
unix% pset dmimg2jpg regionfile="region(sources.reg)"
unix% pset dmimg2jpg regioncolor=")colors.red"
unix% dmimg2jpg
Input file name (red image if true color) (soft_img.fits): 
Green color channel file name (med_img.fits): 
Blue color channel file name (hard_img.fits): 
Output jpg file name (overlay_1838.jpg): 

The regions are shown in Figure 2. You can see a list of available colors by doing "plist colors"; note the close-parenthesis needed in the regioncolor syntax.

Figure 2: True-color image with source list overlaid

[Thumbnail image: The two sources in the field are outline with red circles.]

[Version: full-size]

[Print media version: The two sources in the field are outline with red circles.]

Figure 2: True-color image with source list overlaid


B. On an Optical Image

Adding a source list on top of an optical image requires the region file to be in WCS instead of Chandra physical coordinates.

  1. Convert the source list from Chandra physical pixels to WCS in ds9:

    • Load the x-ray image: unix% ds9 acisf01838N004_evt2.fits &
    • Region → Load Regions... → sources.reg
      unix% cat sources.reg
      # Region file format: CIAO version 1.0
      circle(4071,4247,75)
      circle(4245,4092,20)
      
    • Region → Save Regions... → sourcelist_J2000.reg
    • Format → ciao
    • Coordinate System →WCS → Equatorial J2000
      unix% cat sourcelist_J2000.reg
      # Region file format: CIAO version 1.0
      circle(18:33:33.627,-10:34:07.32,0.615')
      circle(18:33:27.821,-10:35:23.58,0.164')
      
  2. Load the optical image:

    • Frame → New Frame
    • Open... → optical.fits
    • Frame → Match Frames → WCS
  3. Make sure that the WCS axes are oriented the same for both images (e.g. North is "up"). Then load the region file onto the optical data.

    • Region → Load Regions... → sourcelist_J2000.reg → Format: ciao
  4. Convert the source list to the coordinates of the optical image:

    • Region → Save Regions → sourcelist_optical.reg → Format: ds9 → Coordinate System: Image
      unix% cat sourcelist_optical.reg
      # Region file format: DS9 version 4.0
      # Filename: /data/optical_image.fits
      global color=green font="helvetica 10 normal" select=1 highlite=1
      edit=1 move=1 delete=1 include=1 fixed=0 source 
      image
      circle(144.96674,195.67433,21.711926)
      circle(195.10976,150.535,5.7898468)
      

Now dmimg2jpg can be run with the optical image as input and the regions in optical coordinates (regionfile="region(sourcelist_optical.reg)").



Parameters for /home/username/cxcds_param/dmimg2jpg.par


#--------------------------------------------------------------------
# dmimg2jpg.par			Parameter file for dmimg2jpg tool
#--------------------------------------------------------------------
# Input files.  infile = redfile for true color output
#--------------------------------------------------------------------
        infile = soft_img.fits    Input file name (red image if true color)
     greenfile = med_img.fits     Green color channel file name
      bluefile = hard_img.fits    Blue color channel file name
#--------------------------------------------------------------------
# Output files.  Currently to get a postscript file you need
# to make the jpeg file.
#--------------------------------------------------------------------
       outfile = truecolor_1838.jpg Output jpg file name
#--------------------------------------------------------------------
# In greenfile == 'none'  use a lookup table
#--------------------------------------------------------------------
      (lutfile = )lut.grey -> /soft/ciao/data/grey.lut) Colormap file
 (colorstretch = 1)               Color lookup strech factor
   (colorshift = 0)               Color lookup table shift
       (invert = no)              Invert colors
#--------------------------------------------------------------------
# Scaling functions.  Use INDEF to get min and max of data
#--------------------------------------------------------------------
(scalefunction = log)             Scaling function(log|linear|power)
   (scaleparam = 3)               Scaling parameter (for non-linear scalefunction)
       (minred = INDEF)           Minimum value for the red color channel
     (mingreen = INDEF)           Minimum value for the green color channel
      (minblue = INDEF)           Minimum value for the blue color channel
       (maxred = 1)               Maximum value for the red color channel
     (maxgreen = 1)               Maximum value for the green color channel
      (maxblue = 1)               Maximum value for the blue color channel
#--------------------------------------------------------------------
# Regions, aimpoint and grid overlay
#--------------------------------------------------------------------
   (regionfile = )                Region overlay file
  (regioncolor = )colors.green -> 0 1 0) Region color triple
    (regionopt = individual)      Option of region shape drawing method (individal|combine)
 (showaimpoint = no)              Put crosshair at aimpoint
    (showlabel = no)              Label the contours?
     (showgrid = yes)             Show grid on image
    (gridcolor = )colors.white -> 1 1 1) Grid color triple
     (gridsize = 60)              Gridsize [arcsec]
     (fontsize = 1)               Font label size
       (psfile = )                Optional post script file name
      (verbose = 0)               Level of verbose output
      (clobber = no)              Clobber existing outputs?
         (mode = ql)              


    

History

16 Dec 2004 reviewed for CIAO 3.2: no changes
21 Dec 2005 reviewed for CIAO 3.3: no changes
01 Dec 2006 reviewed for CIAO 3.4: no changes
08 Mar 2007 added link to A True Color Images in ds9 thread
16 Jan 2008 updated for CIAO 4.0: color_image script removed from the CIAO scripts package (obsolete, use virtual file syntax instead); ds9 now automatically looks for the "[SRCLIST]" extension in the region file, so it doesn't have to be specified
30 Jan 2009 updated for CIAO 4.1: images are inline
20 Apr 2009 updated for CIAO 4.1.2: the showaimpoint and showgrid parameters in dmimg2jpg are set to "no" by default
27 Jan 2010 reviewed for CIAO 4.2: updated DS9 region file saving information
13 Jan 2011 reviewed for CIAO 4.3: no changes
10 Jan 2012 reviewed for CIAO 4.4: no changes
03 Dec 2012 Review for CIAO 4.5
11 Dec 2013 Review for CIAO 4.6; no changes.
23 Dec 2014 Review for CIAO 4.7; minor edits.
01 Feb 2016 Minor link and other updates.
15 Feb 2022 Review for CIAO 4.14. Updated for Repro-5 and CALDB 4.9.6