Improvements in FITSPNG.

With two appendixes.

Fitspng has been originally developed as an utility for a fast conversion of FITS images to PNG format. It is required for our Monteboo data archive for observed image display in an usual internet browser. The conversion can be also required for example for color imaging (look forward).

Some time ago, I did the conversion by two steps: to8bit utility converted normal (16-bit) FITS to 8-bit with an intensity scaling and convert (utility by Imagemagick) done FITS to PNG conversion. The way have been simple for me (I didn't have learn of libpng API) but one is slow due to high system load and storing of middle product on hard disk.

A long time (two years at least), the functionality satisfies of me, but now I have new ideas and I extended functionality of fitspng with respect on rawtran utility and some new knowledge.


Color images

If a multi-color FITS or tree normal (gray) FITSes is passed to fitspng as file to convert than 8-bit color png is created by the algorithm:

1. Fits is opened and recognized as multi-color FITS. All color bands are loaded.
2. The median and mean deviation of positive differences is computed on 10x10 grid (to speed-up the estimation) for every color band. The computation is abandoned when user specified the -fl switch.
3. These estimated parameters are merged with an user specification by -fr switch. Also white balance is setup via CBALANCE FITS keywords of every band or by -w switch.
4. Than every pixel is scaled by specified intensity profile, supplied parameters and white balance.
5. The file is saved as color PNG with RGB colors (without alpha channel). (May be useful add the alpha to image?)

There are two important requirements for the colorization. A simple way how to convert images from a digital camera processed to FITS by rawtran will be:

bash$ rawtran -t 2 IMG_666.CR2 > color.fits
bash$ fitspng color.fits > color.png

Of course, the direct way by ufraw or dcraw will be faster, but you can't apply some enhancing on images and mouse clicking may be really time consuming.

The most important application is on color composing of image data of CCD. The composition itself for tree images in R,V,B filters can be simple:

bash$ fitspng m1_R.fits,m1_V.fits,m1_B.fits > m1_color.png

The default setup of parameters will produce relative nice images but for more nicer images will be need some fine grained tuning via -fX, -w and by specifying of one from transformation functions: asinh, log (magnitude), error function, sqrt and linear transformation. The setup of various parameters by -fX is usually required when a histogram has and non-usual profile (always for non-stellar images).

If you requires nice publishable images, it is absolutely necessary to done basic processing like, dark and flat field correction and detailed photometric analysis. Ideal way is looking for A0 type (not saturated) star and balancing of the images by hand or by -w.

Note, that all single images has its own header with defined keywords which can/are be different. If any keyword is duplicated we get only the first match.

The multi-color FITS has structure:

FITS
+-----------------------------------+
| Primary array - dummy |
+-----------------------------------+
| Extended array - R image |
+-----------------------------------+
| Extended array - G image |
+-----------------------------------+
| Extended array - B image |
+-----------------------------------+


Intensity (flux) scaling

Inspired by Christian Buil, I had implemented asinh intensity profiles together with logarithmic, square root, error function and reimplemented the linear profile. Results are really nice. The profiles are presented on images. BTW, the intuitive color conversion curves which I used with ufraw are similar.

The conversion can be described as an function between output and input data. The input intensity I can be integer or real number without specified range. The output O level has integer range 0 .. 255. The I is transformed to O by

O = f0*f(x) + z0

where f0 is a scaling constant and z0 is black level. The function f(x) can be one from list:

asinh(x)
log(x)
erf(x)
sqrt(x)
x (f0 = 1)

The argument x is computed by a linear transformation

x = (I - t)/s

where t is a "mean" level and s is "mean" deviation. Values t are estimated by fitspng by median of grid pixels with separation of ten pixels (med). The s is determined by the same way on the same set but from positive deviations of t (not from absolute deviations as usually) (mad). Both parameters are corrected by constants u,v:

t = med - 3*mad
s = mad/15

The specified intensity transformation is a product of black magic on images and it can't be derived from an exact axioms. It empirically describes usual parameters of histograms of astronomical images.

The asinh magnitudes are used as photometric product of the Sloan sky survey. They recommends of use of the magnitudes in Lupton et al.(1999) and for color imaging in Lupton et al.(2004).


Working with full directory of images

Fitspng is ideal utility to done fully automatic conversion of fits images. It can be useful for fast look analysis in anyimage viewer or simple file browser. The thumbnails can be generated by command:

bash$ for A in *.fits; do fitspng -a -s 5 $A > ${A%fits}png; done

The switch -s resize the image 5 times.


How to create an animation

If we have images in png format, it is trivial to create an animated gif (with 50 milliseconds delay between images) via convert command of Imagemagic:

bash$ convert -delay 50 *.png animated_sky.gif

Larger animations is preferred to save to mpeg format. It can be created with small script:

---
#!/bin/bash

I=0
for A in *.png; do
for B in $(seq 1 25); do
I=$((I + 1))
N=$(printf "img%04d.png" $I)
ln -s $A $N
done
done
ffmpeg -f image2 -i img%04d.png animated_sky.mpg
---


The ffmepg requires 25 frames per second (at least 10 fps) so we create 25 times links on a single frame. The conversion requires relative small images with approximate size of a post stamp (about 800x600).


Notes.

I spend some time with optimizing of fitspng for speed because the conversion of normal size image gets a few seconds. Unfortunately, any hooks in main cycle are insignificant and, perhaps, the all actions consuming approximately the same part of execution time. The conclusion is that any (great) numerical operations has negligible fluency on execution duration. It is possible to visually inspect of the duration with setup of -v (verbose) switch.

I'm little bit confused about use of keywords of FITS files. They can be defined arbitrary and fitspng can produce fake outputs. I think that the most important is CBALANCE. Fortunately, the keyword can be replaced by -w switch. All others will only put wrong of description of image included in PNG file. The used keywords are listed in source fitspng.c.

The utility is coded in standard C but the coding style is old Fortran like without extensive usage of some user defined types and complicated structure of functions. I believe that the style is fine for coding and long time maintained of filter type utilities. I will not lost in function tree.

I'm expecting additional changes in future.


Examples of images

First image is composed exposition of field of NGC 7635 (Bubble nebula in Cas) acquired during summer 2006 by me and Exebece on MonteBoo Observatory (0.6m refl.) and HaP MK Brno (0.4m refl.) by non-enhanced cameras ST-8 and ST-7 in R filter. The image has been created by composition of 1084 images of total exposure time 95540(!) seconds. The images has intensity scaled by asinh and linear profiles. The differences are most remarkable at central part. The central star is saturated on linear scale, while faint details are visible.

Bubble nebula NGC 7635. Linear intensity profile.

Bubble nebula NGC 7635. Asinh intensity profile.

Second example shows Dumbell nebula (M27) exposed on MonteBoo (0.6m refl.) by Janapka two months ago. It is composition of 3x11 exposures (3x440 sec) in R,V,B filters by our enhanced ST-8 camera. The images has not flat-field corrected.

Dumbell nebula M27. Linear intensity profile.

Dumbell nebula M27. Asinh intensity profile.

So, I strongly recommends use of asinh intensity profiles.

Post scriptum. Scaling to preserve all colors

Dumbell nebula M27. Asinh intensity profile.
Scaled by intensity. Note better preserving of colors.

The paper Lupton et al.(2004) recommends as an optimal way to scale of output image by intensity rather than every single color. You can use the -f switch to invoke it. The key difference with respect to single color scaling is coloring of the saturated objects. The intensity scale algorithm preserves color ratio in (output) saturated regions. The saturated stars have approximate colors opposite with the white color of previous algorithm. Of course, really (on CCD chip) saturated stars are white again. Unfortunately, the saturated stars can create a strange color defect. To remove it, use another black magic.

Post scriptum. I forget attach a graph of all profiles. Please look on the linear (red) and the logarithmic (blue) and asinh (light green) profiles which ideally "interpolates" beween its.
SVG version.



Download of FITSPNG.

Improvements of RAWTRAN

While work on processing of set of images of Venus setting (I will it show soon), I found important bugs and revealed some possible improvements in rawtran utility. Moreover, I also found that only the type zero (default) conversion has worked correctly for all versions up to today. The default choice have composed four RGGB pixels of the Bayer color mosaic to one big grayscale pixel by use of unique weights for separate colors.

The Bayer mosaic is defined as red, blue and two green pixels arranged to rectangular matrix. It means that the number of different colors is tree but we have four pixels on detector matrix. Two green pixels are reserved for single color. Now, we have two choices for output intensities: sum of the pixels or their arithmetical mean. The sum gives precise value in integer numbers but one is two times greater than value of other colors. Opposite with this, the mean gives values of the same order as the red and blue pixels unfortunately with a rounding error as result of conversion between real and integer numbers. I think, the use of the mean and real numbers in FITS should be considered as a smooth alternative when a lot of disk space is available. Also sum of two greens and double values of red and blue can be a nice alternative for 12bit and 14bit A/D converters while we are storing data in 16bit FITSes. The arithmetical mean is the most simple alternative with small lost of precision. Please leave a comment about a preferred way to solve the controversial point.


Color weights

As the first noticeable change, I mention about the color balance (weights) used for conversion of a color based to a greyscale image. Generally, the conversion is done by the formula

I = w_R*R + w_G*G + w_B*B

where I is grayscale intensity, R,G,B are proper intensities in appropriate filters and w_i are a suitable weights. The choice of w_i depends on problem to solve. The setup of w_i is supplied by your camera according to spectral profiles of color device elements and to light conditions of an acquired scene. The photographers perhaps uses the term "white color balance" for the procedure, because it can be easy established by balancing of the coefficients on a white. Now, the camera setup is default. The previous versions used w_i = 1 without possibility to specify by hand. Note that both setups are useful in different situations. The camera supplied setup is ideal for images represents intensities close to reality. The 1's weighting can be useful for detailed spectral examination of images.

The color weights are derived from camera supplied data in field "Camera multipliers". The four numbers B1 B2 R1 R2 are used to estimate of color balance as:

w_R = R1/R2,
w_G = 1,
w_B = B1/B2.

The green band is supposed as basic unit and both remain are relatively scaled. The numerical values agrees with ufraw data. I don't know why also provided "Daylight multipliers" are not used for the reason.

For type zero the image is grayscale and the value is indicated by keyword FILTER which is set to GRAY. Weight factors are not directly included in keywords.


Multi-color fits

The most important change in the code is connected to multi-color (band) fits images. Previous versions has been badly decoding of Bayer's mask (the colors has been swapped). I corrected the bug and changed structure of resultant FITS files.

The effect of correct separation of colors can be easy showed on the image of the spectrum of a white source (data projector) observed through a rainbow glasses (famous paper - diffraction foil glasses). Look on included image for details. I'd correctly decoded the structure of image color mask on the image.

Color image and separated color bands.

Since recent issue, the multi-color FITS has following structure: the dummy primary image array (the header without any data) and tree color (band) extended images. Every header of the extended data contains a new keywords FILTER indicating one from set RED, GREEN, BLUE and appropriate color weight factor included as CBALANCE. Other new keyword EXTNAME is the same as FILTER and can be directly used to select the filter. For example, with ds9 you can directly select blue band by the command:

bash$ ds9 x.fits[BLUE]

The same selection can be done also as x.fits[3]. The file names uses the extended file name syntax introduced by cfitsio library.

Note, about multi-color (band) FITSes. The packaging of more images to one file is frequently used in space astronomy, where an experiment on a spacecraft records a radiation on many different wavelengths. The color mode is particular case of the gadget. The idea can be also extended for including of correction or calibration images or data.

Grid mode

The grid mode (type 1) simply arrange of pixels without collecting or space separating of pixels. I have no idea about any usefulness of the mode. Also I don't fully understand why noise (dark) level and white (saturated) regions are correctly displayed but the mid-level intensities produces grid structure.

8,16,32,-32 bits per pixel images

The output FITSes can have specified bitpix parameter (see man page). It can be very useful when you wanna save fine precision of intensities. The non-integer values are common product of white balancing when type zero conversion is selected. Also, the problem extensive discussed above is suppressed.

I suppose that the mode 16-bit is perfect for storing of raw data, the mode -32-bit for further processing and modes 8 and 32 are unusable. Images with 8-bit depth will usually white due to overflow of image's values over 255. The 32-bit mode only grows range of integer numbers and practically only occupied twice more disk space without any growing of stored information.


Examples of conversion

Basic run (equivalent commands):

bash$ rawtran IMG_666.CR2 > IMG_666.fits
bash$ rawtran -o IMG_666.fits IMG_666.CR2

The produced image IMG_666.fits contains grayscale image with half image dimensions of the original. Please, respect rule: first options than an image to convert.

Process all images in directory:

bash$ for A in *.CR2; do rawtran ${A} > ${A%CR2}fits; done

Process all images listed in a file l.lst:

bash$ for A in $(cat l.lst); do rawtran ${A} > ${A%CR2}fits; done

The file l.lst is usually created by command: bash$ ls > l.lst

Produce of multi-color image and show its green channel (band) in ds9:

bash$ rawtran -t 2 IMG_666.CR2 > IMG_666.fits
bash$ ds9 IMG_666.fits[GREEN]

Produce user's white-balanced multi-color image:

bash$ rawtran -t 2 -w 2.0,1.0,1.5 IMG_666.CR2 > IMG_666.fits

Separate blue color (band) from an image:

bash$ rawtran -t 3 -c B IMG_666.CR2 > IMG_666.fits

The output file roughly corresponds to a filtered CCD image with blue band.


Notes

Please, read source code of rawtran.c to get more detailed understanding of my ideas. I know that code is wrongly structured, it uses of poor data structures etc. but it isn't important for me. Valgrind shows defect free code.

I'm little bit confused about handling with output file. The default setup writes data on standard output which can be strangle for unexperinced users. The suffix swaping is not too elegant for C coding (shell replaces strings more effectively) and unique output filename like rawtran.png is confusing too.

All developing is proceed on images produced by Canon 30D. Be careful when your are working with another digital camera.

Download of RAWTRAN.
An older post about RAWTRAN.

Mandriva's repository of Munipack

Petoš is maintaing himself a repository with some useful software for Mandriva 2009.0. A presence of the current version of Munipack including dependencies (mostly cfitsio) is good news for us. The repository is easy available. Use the command

urpmi.addmedia "Petos" http://physics.muni.cz/~petos/mandriva/2009.0/i586 with media_info/hdlist.cz

to add it to your sources. The repository is for 32-bit branch (i586) . Packages doesn't contains any description and a digital sign. Ones are required to be used together as whole repository (not as independent entities).

BIG THX!

Note. The distribution of binary packages is generally a good idea. But the horrible fragmentation of unix world make me impossible to maintain (at least) some great Linux distribution (Debian, RedHat/Fedora, Mandriva, SuSE, Gentoo,..), *BSD (Free*, Net*, Open*) or Solaris. In despite of the worry, I speculate about this way.