
Notes about RAWTRAN.

http://monteboo.blogspot.com/

------------------------------------------------------------------------


Improvements of RAWTRAN.  (Dec. 2008)

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 0 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
images for details. I'd correctly decoded the structure of image color
mask on the image.

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:

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.


$Id$


************************************************************************


Recent progress in RAWTRAN (Mar. 2009)


There is a summary of last progress in rawtran (see previous posts: 
Dec 2008, Dec 2007). 

I precised definition of color format. By inspiration of PNG format 
(libpng), I introduced a new keyword to the first dummy header

COLORTYP

by PNG_COLOR_TYPE_* to be setup to (string) value RGB for color FITSes.
It will be useful for any software to easy recognize of the color format.
Also the definition also require additional condition on size of the
images that is required to be equal for all color bands.

Another change is replace of the CBALANCE header keyword in header by
the keyword COLORBAL with the same meaning. I think, it will be get
better understanding to users. The CBALANCE is now obsolete and
I don't expect any back-compatibility.

I added a new type of conversion. The type 4 produces multi-band
FITS file including of all four Bayer colors in separated FITS image
arrays. The type provides absolutely raw access to RAW data. 
It is another multi-band FITS than the color type. 

Some additional changes has been included to rawtran recently:

* Cleanup of code.
* CREATOR keyword.
* EXIF information by dcraw is written in the header block with 
  "begin" and "end" delimiters to be simple parsed.
* Update of man page.
* Run-time detection of dcraw.
* A switch to pass additional parameters to dcraw

It is still uncertain of the true meaning of Daylight and 
camera multipliers provided by camera and its meaning on a color 
white balance.


************************************************************************


A new fashion for RAWTRAN and FITSPNG (April 2010)


My recent development on understanding of black magic arts of 
the computer 
color imaging have inspired me to made new major revisions of RAWTRAN
and FITSPNG utilities. 
The crutial point is undersanding of representation of colors in
RAW images. I extensively working with CIE 1931 XYZ colorspace.

Every digital camera has its own color representation due to its 
instrumental characteristics. By another words, the spectral sensitivity
of color pixels differs from a camera to camera. To get a correct 
color representation, we need transform raw color data to a standard
color space. The transformation is provided by dcraw, which includes
color transformation 
matrixes for wide range of digital cameras. Dcraw facility can
produce output data in the exactly defined CIE 1931 XYZ color space.

That means that the ideal color representation of images will XYZ
colorspace which I included to Munipack graphical core. I rewroted
rawtran to create FITS files of tree types:

* grayscale of specified color channel
* instrumental (raw) values
* color images

The instrumental data are usually RAW and they can be interpreted by
any exact way with help of transformation matrixes included in source
file of dcraw.c or by a standard color system transformation known
in practical astronomy. Dcraw is using the matrixes and scales images
to cover all 16-bit color range. Our Canon EOS 30D is scaled by subtarcting
of 128 (black level) and multipliing a number to cover  (65536 - 128)/256.

By direct using of XYZ can be used to transform to another colorspace.
I selected BVR with similar filter sensitivities and great practical
importance.

All the changes in rawtran induces changes in fitspng. I canceled
support of coloring of images by compositiong of single filter images.
The coloring will be realised by coloring utility of Munipack. The
chnage imporantly simplify fitpng.

Another chnage is usage of different colorspaces. Up until now, I
scaled all the chanhes separatelly strongly affectinf colors of images.
So I implemented scaling by using of L component of Luv colosrpace.
It has benefits in no color changes by intensity scaling and offesr
possibility to simply change of color saturation.

The user visible changes are in more clearer command line interfaces.
I was cut-off some uselless parameters of both utilities. Theirs
behauviour is more deeply decribed in its webpages which I created.
A few parameters can help users because a mean person will remeber
maximaly up to five parameters. I also unified options for both utilities.




---

The time since last isue of stable Munipack, I spend with understanding
of colors in astronomy and computer graphics.


************************************************************************


New Format of Color FITS for RAWTRAN,FITSPNG and Munipack (May 2011)

Long-term experiences with processing of color FITSes has leaded
me to drastic change of color-storing format. The separation
of single-color bands to FITS image extension is really wrong way.
It is less natural
than storing in multi-dimensional single array. The data are
logically grouped together with meta (header) information.

However, main reason for the change has been simplifying
of manipulations with color images. The simplifying is really
drastic. I removed hundredth of code lines and a lot of
(potentially) buggy code.

Another important change is replacement of COLORTYP to CSPACE
describing of colorspace of stored color image. I suppose,
the new keyword is more mnemonics.

The exact structure of the changed color FITS format is
described on http://munipack.physics.muni.cz/colorfits.html

The changes are included since versions 0.3.0 of rawtran
and fitsng and 0.5.2 of Munipack.


$Id$

