10.7.1 Invoking astscript-color-faint-gray ¶

This installed script will consider several images to combine them into a single color image to visualize the full dynamic range. The executable name is astscript-color-faint-gray, with the following general template:

$ astscript-color-faint-gray [OPTION...] r.fits g.fits b.fits

Examples (for a tutorial, see Color images with full dynamic range):

## Generate a color image from three images with default options.
$ astscript-color-faint-gray r.fits g.fits b.fits -g1 --output color.pdf

## Generate a color image, consider the minimum value to be zero.
$ astscript-color-faint-gray r.fits g.fits b.fits -g1 \
                           --minimum=0.0 --output=color.jpg

## Generate a color image considering different zero points, minimum
## values, weights, and also increasing the contrast.
$ astscript-color-faint-gray r.fits g.fits b.fits -g1 \
                      -z=22.4 -z=25.5 -z=24.6 \
                      -m=-0.1 -m=0.0 -m=0.1 \
                      -w=1 -w=2 -w=3 \
                      --contrast=3 \
                      --output=color.tiff

This script takes three inputs images to generate a RGB color image as the output. The order of the images matters, reddest (longest wavelength) filter (R), green (an intermediate wavelength) filter (G) and bluest (shortest wavelength). In astronomy, these can be any filter (for example from infra-red, radio, optical or x-ray); the “RGB” designation is from the general definition of colors (see https://en.wikipedia.org/wiki/RGB_color_spaces) These images are internally manipulated by a series of non-linear transformations and normalized to homogenize and finally combine them into a color image. In general, for typical astronomical images, the default output is an image with bright pixels in color and noise pixels in black.

The option --minimum sets the minimum value to be shown and it is a key parameter, it uses to be a value close to the sky background level. The current non-linear transformation is from Lupton et al. 2004, which we call the “asinh” transformation. The two important parameters that control this transformation are --qthresh and --stretch. With the option --coloronly, it is possible to generate a color image with the background in black: bright pixels in color and the sky background (or noise) values in black. It is possible to provide a fourth image (K) that will be used for showing the gray region: R, G, B, K

The generation of a good color image is something that requires several trials, so we encourage the user to play with the different parameters cleverly. After some testing, we find it useful to follow the steps. For a more complete description of the logic of the process, see the dedicated tutorial in Color images with full dynamic range.

1. Use the default options to estimate the parameters. By running the script with no options at all, it will estimate the parameters and they will be printed on the command-line.
2. Select a good sky background value of the images. If the sky background has been subtracted, a minimum value of zero could be a good option: --minimum=0.0.
3. Focus on the bright regions to tweak --qbright and --stretch. First, try low values of --qbright to show the bright parts. Then, adjust --stretch to show the fainter regions around bright parts. Overall, play with these two parameters to show the color regions appropriately.
4. Change --colorval to separate the color and black regions. This is the lowest value of the threshold image that is shown in color.
5. Change --grayval to separate the black and gray regions. This is highest value of the threshold image that is shown in gray.
6. Use --checkparams to check the pixel value distributions.
7. Use --keeptmp to not remove the threshold image and check it.

A full description of each option is given below:

-h

--hdu=STR/INT

Input HDU name or counter (counting from 0) for each input FITS file. If the same HDU should be used from all the FITS files, you can use the --globalhdu option described below to avoid repeating this option.

-g

--globalhdu=STR/INT

Use the value given to this option (a HDU name or a counter, starting from 0) for the HDU identifier of all the input FITS files. This is useful when all the inputs are distributed in different files, but have the same HDU in those files.

-o

--output

Output color image name. The output can be in any of the recognized output formats of ConvertType (including PDF, JPEG and TIFF).

-m

--minimum=FLT

Minimum value to be mapped for each R, G, B, and K FITS images. If a single value is given to this option it will be used for all the input images.

This parameter controls the smallest visualized pixel value. In general, it is a good decision to set this value close to the sky background level. This value can dramatically change the output color image (especially when there are large negative values in the image that you do not intend to visualize).

-Z

--zeropoint=FLT

Zero point value for each R, G, B, and K FITS images. If a single value is given, it is used for all the input images.

Internally, the zero point values are used to transform the pixel values in units of Janskys. The units are not important for a color image, but the fact that the images are photometrically calibrated is important for obtaining an output color image whose color distribution is realistic.

-w

--weight=FLT

Relative weight for each R, G, B channel. With this parameter, it is possible to change the importance of each channel to modify the color balance of the image.

For example, -w=1 -w=2 -w=5 indicates that the B band will be 5 times more important than the R band, and that the G band is 2 times more important than the R channel. In this particular example, the combination will be done as \(\rm{colored}=(1{\times}\rm{R}+2{\times}\rm{G}+5{\times}\rm{B})/(1 + 2 + 5)=0.125{\times}\rm{R} + 0.250{\times}\rm{G} + 0.625{\times}\rm{B}\).

In principle, a color image should recreate “real” colors, but “real” is a very subjective matter and with this option, it is possible to change the color balance and make it more aesthetically interesting. However, be careful to avoid confusing the viewers of your image and report the weights with the filters you used for each channel. It is up to the user to use this parameter carefully.

-Q

--qbright=FLT

It is one of the parameters that control the asinh transformation. It should be used in combination with --stretch. In general, it has to be set to low values to better show the brightest regions. Afterwards, adjust --stretch to set the linear stretch (show the intermediate/faint structures).

-s

--stretch=FLT

It is one of the parameters that control the asinh transformation. It should be used in combination with --qbright. It is used for bringing out the faint/intermediate bright structures of the image that are shown linearly. In general, this parameter is chosen after setting --qbright to a low value.

The asinh transformation. The asinh transformation is done on the stacked R, G, B image. It consists in the modification of the stacked image (I) in order to show the entire dynamical range appropriately following the expression: \(f(I) = asinh(\) qbright \(\cdot\) stretch \(\cdot I) /\) qbright. See Color images with full dynamic range for a complete tutorial that shows the intricacies of this transformation with step-by-step examples.

--coloronly

By default, the fainter parts of the image are shown in grayscale (not color, since colored noise is not too informative). With this option, the output image will be fully in color with the background (noise pixels) in black.

--colorval=FLT

The value that separates the color and black regions. By default, it ranges from 100 (all pixels becoming in color) to 0 (all pixels becoming black). Check the histogram FOR COLOR and GRAY THRESHOLDS with the option --checkparams for selecting a good value.

--grayval=FLT

This parameter defines the value that separates the black and gray regions. It ranges from 100 (all pixels becoming black) to 0 (all pixels becoming white). Check the histogram FOR COLOR and GRAY THRESHOLDS with the option --checkparams to select the value.

--regions=STR

Labeled image, identifying the pixels to use for color (value 2), those to use for black (value 1) and those to use for gray (value 0). When this option is given the --colorval and --grayval options will be ignored. This gives you the freedom to select the pixels to show in color, black or gray based on any criteria that is relevant for your purpose. For an example of using this option to get a physically motivated threshold, see Manually setting color-black-gray regions.

IMPORTANT NOTE. The options --colorval and --grayval are related one to each other. They are defined from the threshold image (an image generated in the temporary directory) named colorgray_threshold.fits. By default, this image is computed from the stack and later asinh-transformation of the three R, G, B channels. Its pixel values range between 100 (brightest) to 0 (faintest). The --colorval value computed by default is the median of this image. Pixels above this value are shown in color. Pixels below this value are shown in gray. Regions of pure black color can be defined with the --grayval option if this value is between 0 and --colorval. In other words. Color region are defined by those pixels between 100 and --colorval. Pure black region are defined by those pixels between --colorval to grayval. Gray region are defined by those pixels between --grayval to 0. If a fourth image is provided as the “K” channel, then this image is used as the threshold image. See Color images with full dynamic range for a complete tutorial.

--colorkernelfwhm=FLT

Gaussian kernel FWHM (in pixels) for convolving the color regions. Sometimes, a convolution of the color regions (bright pixels) is desired to further increase their signal-to-noise ratio (but make them look smoother). With this option, the kernel will be created internally and convolved with the colored regions.

--graykernelfwhm=FLT

Gaussian kernel FWHM (in pixels) for convolving the background image. Sometimes, a convolution of the background image is necessary to smooth the noisier regions and increase their signal-to-noise ratios. With this option, the kernel will be created internally and convolved with the colored regions.

-b

--bias=FLT

Change the brightness of the final image. By increasing this value, a pedestal value will be added to the color image. This option is rarely useful, it is most common to use --contrast, see below.

-c

--contrast=FLT

Change the contrast of the final image. The transformation is: \(\rm{output}=\rm{contrast}\times{image}+brightness\).

-G

--gamma=FLT

Gamma exponent value for a gamma transformation. This transformation is not linear: \(\rm{output}=\rm{image}^{gamma}\). This option overrides --bias or --contrast.

--markoptions=STR

Options to draw marks on the final output image. Anything given to this option is passed directly to ConvertType in order to draw marks on the output image. For example, if you construct a table named marks.txt that contains the column names: x, y, shape, size, axis ratio, angle, color; you will execute the script with the following option: --markoptions="--marks=markers.txt --markcoords=x,y --markshape=shape --marksize=size,axisratio --markrotate=angle --markcolor=color". See Drawing with vector graphics for more information on how to draw markers and Weights, contrast, markers and other customizations for a tutorial.

--checkparams

Print the statistics of intermediate images that are used for estimating the parameters. This option is useful to decide the optimum set of parameters.

--keeptmp

Do not remove the temporary directory. This is useful for debugging and checking the outputs of internal steps.

--cite

Give BibTeX and acknowledgment information for citing this script within your paper. For more, see Operating mode options.

-q

--quiet

Do not print the series of commands or their outputs in the terminal. For more, see Operating mode options.

-V

--version

Print the version of the running Gnuastro along with a copyright notice and list of authors that contributed to this script. For more, see Operating mode options.