/ ciao4.16 / ahelp / energy_hue_map.html

Jump to: Description · Examples · Parameters · About Contributed Software · Bugs · See Also

AHELP for CIAO 4.16

energy_hue_map

Synopsis

Creates a true color image using median-energy map and counts image.

Syntax

energy_hue_map  infile energymap outroot [colorsys] [min_energy]
[max_energy] [min_counts] [max_counts] [energy_scale] [counts_scale]
[min_hue] [max_hue] [min_sat] [max_sat] [contrast] [bias] [show_plot]
[clobber] [verbose]

Description

`energy_hue_map' creates a true color image by using the energy of the events as the color hue (red through purple) and the counts/flux image as the saturation and "value" values. This creates an image in the "HSV" (Hue Saturation Value) color system. To display the image, the HSV values are converted to RGB (Red Green Blue) color system. The result is an image where the pixel color maps to continuous color spectrum and the intensity maps to the counts/flux in each pixel.

Tri-Color vs. True Color

Traditional RGB tri-color images start by creating 3 images in separate energy bands. One example could be 3 X-ray energy bands such as the Chandra Source Catalog 'soft' (0.5 to 1.2kev), 'medium' (1.2 to 2keV), and 'hard' (2.0 to 7.0 keV) bands. However, the energy bands do not need to continuous, and in fact could cover different parts of the EM spectrum: for example Optical, Radio, and X-ray. Each image is represented by a single color channel that is independently scaled. The combination of primary colors (RGB) leads to the visual interpretation of secondary colors: eg pixels with both red and green counts will appear yellow, and pixels with both green and blue counts will appear cyan. Applications such as ds9, matplotlib, and dmimg2jpg can be used to visualize these RGB datasets.

True color images are created from a continuous energy range. The color hue represents the energy of each individual pixel, eg the median or mean energy value of the individual events. This provides an increase in the coverage of the color gamut. Consider the color purple/violet. In the optical color range, violet represents the highest energies. However, in traditional tri-color images, the only way to see violet is to have a combination of pixels in the blue and red color channel images, where red usually represents the lowest energies. This is unlikely to occur when using a continuous energy range. Using this true color energy hue mapping, the highest energy events get assigned the highest hue.

Examples

Example 1

unix% energy_hue_map acis_broad_thresh.img median_energy.map my_output

Using all the default values, this will take the counts image in the input file: acis_broad_thresh.img, and will apply color hues based on the median energy values stored in the image: median_energy.map. There will be two output files: my_output.fits and my_output.jpg. The JPEG file shows the true color image. The .fits file contains separate extensions corresponding the reg, green, and blue color channels. The default verbose=1 terminal output looks like

energy_hue_map
          infile = acis_broad_thresh.img
       energymap = median_energy.map
         outroot = my_output
        colorsys = hsv
      min_energy = INDEF
      max_energy = INDEF
      min_counts = INDEF
      max_counts = INDEF
    energy_scale = linear
    counts_scale = asinh
         min_hue = 0
         max_hue = 0.833
         min_sat = 0
         max_sat = 1
        contrast = 1
            bias = 0.5
       show_plot = no
         clobber = no
         verbose = 1
            mode = ql

To display the data correctly in ds9 use the following command:

ds9 -rgb -red 'my_output.fits' -linear -scale limits 0 255 \
    -green 'my_output.fits[GREEN]' -linear -scale limits 0 255 \
    -blue 'my_output.fits[BLUE]' -linear -scale limits 0 255

Users will typically want to tweak some of the min/max parameters to improve the image.

Example 2

unix% energy_hue_map acis_broad_thresh.img median_energy.map my_output \
min_counts=0 max_counts=10 min_energy=1000 max_energy=3000
counts_scale=log

This is similar to the previous example, but with the min and max counts and energy values specified, and the counts scaling changed to log scale.

Example 3

unix% energy_hue_map acis_broad_thresh.img median_energy.map my_output \
min_counts=0 max_counts=10 min_energy=1000 max_energy=3000
counts_scale=log \
contrast=0.7 bias=0.35

Experiments have shown that sometimes the colors become fully saturated causing a loss of spatial details. Users can adjust the contrast and bias settings akin to ds9 to try to recover some of those details.

Example 4

unix% merge_obs '*/repro/*evt2.fits' outroot=acis
unix% dmnautilus acis_broad_thresh.img img.abin snr=5 method=3
outmask=img.map
unix% statmap acis_merged_evt.fits"[energy=500:7000]" img.map
out=median_energy.map col=energy stat=median
unix% energy_hue_map acis_broad_thresh.img median_energy.map my_output

This is one possible example of the processing steps to create the image and the median energy map which are input to the energy_hue_map script.

Users could choose to (adaptively) smooth the counts image and the exposure map to create a smoothed, fluxed image. CIAO 4.15 provides two adaptive binning tools: dmnautilus and dmradar; however any tool that produces a "map" file (pixel values provide a grouping of neighboring pixels according to some algorithm) could be used. Also, the energy=500:7000 filter could also be adjusted based the spectrum of the object(s).

Parameters

name	type	ftype	def	min	max	reqd
infile	file	input				yes
energymap	file	input				yes
outroot	file	output				yes
colorsys	file		hsv
min_energy	real		INDEF
max_energy	real		INDEF
min_counts	real		INDEF
max_counts	real		INDEF
energy_scale	string		linear
counts_scale	string		asinh
min_hue	real		0	0	1
max_hue	real		0.833	0	1
min_sat	real		0	0	1
max_sat	real		1	0	1
contrast	real		1.0	0.0	10.0
bias	real		0.5	0.0	1.0
show_plot	boolean		no
clobber	boolean		no			no
verbose	integer		0	0	5	no

Detailed Parameter Descriptions

Parameter=infile (file required filetype=input)

Input counts (or flux) file name.

The input image is the equivalent of the counts image integrated over the same energy range as the energymap. It can have additional processing done such as exposure correcting, smoothing, and possibly background subtraction.

The input image is used to set the output pixel color saturation and "value".

Parameter=energymap (file required filetype=input)

The energy map file name.

The energy map provides an estimate of the energy for each pixel. This estimate may be based on the mean or median of all the events in a single pixel or could be computed over some local area to gather enough events to get a statistically meaningful sample.

The energy map can be created in several ways. One option is to use the statmap tool; it computes the median (or mean) energy value using an adaptive binning map (eg created by dmnautilus.) If the source has a large number of counts, then it can also be as simple as computing the mean energy using dmimgcalc and using the ";weight" syntax when binning

% dmimgcalc "evt.fits[bin sky=1;energy]" "evt.fits[bin sky=1]" mean_energy.map div

The energy map file must have same axis lengths as the input image.

Parameter=outroot (file required filetype=output)

Output directory and filename root.

The tool produces two output files.

${root}.fits - is a FITS file with three (3) separate extensions for the red, green, and blue images used for display (eg by ds9, matplotlib, or dmimg2jpg).
${root}.jpg - is a JPEG file showing the combined image.

Parameter=colorsys (file default=hsv)

Which color system to use to process the data: hsv or hls?

A detailed description of the differences between the HSV (Hue Saturation and Value) and HLS (Hue Lightness Saturation) color systems is deferred to wikipedia. The practical take away for how it affects this script is in how the lightest colors are represented, in particular the color "white". Comparing to an optical system: white light represents all energies -- which then is uninformative as to what is the actual mean/median energy. The HSV color system tends to preserve the visual color hue whereas the HLS color system tends to emphasize the pixel intensity.

Parameter=min_energy (real default=INDEF)

The minimum energy. This value maps to the min_hue.

Pixels with energies at and below the minimum energy are set to the min_hue value (default is 0, ie the color red). The default value of 'INDEF' lets the tool compute the minimum from all the pixels in the energymap input file.

The units of this parameter are the same as the units of the energymap input file.

Parameter=max_energy (real default=INDEF)

The maximum energy. This value maps to the max_hue.

Pixels with energies at and above the maximum energy are set to the max_hue value (default is 0.833, ie the color purple). The default value of 'INDEF' lets the tool compute the maximum from all the pixels in the energymap input file.

The units of this parameter are the same as the units of the energymap input file.

Parameter=min_counts (real default=INDEF)

The minimum counts. This value maps to the min_sat.

Pixels with counts at and less than the minimum counts value are set to the min_sat (minimum saturation) value. The default value of 'INDEF' lets the tool compute the minimum from all the pixels in the infile input image.

The units of this parameter as the same as the units of the infile input image.

Parameter=max_counts (real default=INDEF)

The maximum counts. This value maps to the max_sat.

Pixels with counts at and above than the maximum counts value are set to the max_sat (maximum saturation) value. The default value of 'INDEF' lets the tool compute the maximum from all the pixels in the infile input image.

The units of this parameter as the same as the units of the infile input image.

Parameter=energy_scale (string default=linear)

Scaling applied to the energy values

The choices are: linear, log, asinh (hyperbolic arcsine), sqrt (square root), and square.

Parameter=counts_scale (string default=asinh)

Scaling applied to the counts values.

The choices are: linear, log, asinh (hyperbolic arcsine), sqrt (square root), and square.

Parameter=min_hue (real default=0 min=0 max=1)

The minimum color hue.

Color hues are cyclical starting from 0 (red) and going to 1, which is also red.

Parameter=max_hue (real default=0.833 min=0 max=1)

Color hues are cyclical starting from 0 (red) and going to 1, which is also red. The default value of 0.833 is the hue for the color purple/violet.

Parameter=min_sat (real default=0 min=0 max=1)

Minimum saturation

The minimum allowed saturation value.

Parameter=max_sat (real default=1 min=0 max=1)

Maximum saturation

The maximum allowed saturation value.

Parameter=contrast (real default=1.0 min=0.0 max=10.0)

Adjust the contrast in the pixel intensity (brightness)

This is equivalent to adjusting the contrast in ds9. The contrast controls the how much the pixel brightness is compressed (contrast values greater than 1.0) or stretched (contrast values less than 1.0). This may needed when the range of the pixel values is especially large and usually used in conjunction with adjusting the bias parameter.

Parameter=bias (real default=0.5 min=0.0 max=1.0)

Adjust the bias in the pixel intensity (brightness)

This is equivalent to adjust the color bias in ds9. The bias controls the center of the intensity range. Setting the bias less than the default of 0.5 will brighten darker pixels, and setting the bias greater than 0.5 will darken lighter pixels. This may needed when the range of the pixel values is especially large and usually used in conjunction with adjusting the contrast parameter.

Parameter=show_plot (boolean default=no)

Display a plot of the image?

If set to "yes", the tool will display the image. Users must close the display window for the tool to finish.

Parameter=clobber (boolean not required default=no)

Remove files if they already exist?

Clobber will remove the output files if they already exist before creating the new files.

Parameter=verbose (integer not required default=0 min=0 max=5)

Report information to the user.

This parameter defines how much information is passed to the user. A level of 0 reports nothing, a level of 5 reports the most. Level 1 will report the input parameters.

About Contributed Software

This script is not an official part of the CIAO release but is made available as "contributed" software via the CIAO scripts page. Please see this page for installation instructions.

Bugs

There are no known bugs for this tool.