File: rawtran.html

package info (click to toggle)
rawtran 1.1-1
links: PTS, VCS
area: main
in suites: bookworm, bullseye, buster, forky, sid, trixie
size: 8,796 kB
sloc: sh: 1,232; ansic: 1,035; makefile: 18
file content (844 lines) | stat: -rw-r--r-- 26,465 bytes
<!DOCTYPE HTML>
<html lang="en">
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta name="description" content="RAW photo converter to FITS format">
<meta name="author" content="Filip Hroch">
<meta name="keywords" content="RAW, FITS, DSLR, digital, photography, astrophotography">
<title>Rawtran</title>
<style>
body { margin-left: auto; margin-right: auto; padding-top: 0em; padding-bottom: 0em; width: 50em;}
h1 { font-size: 140%; margin-left: 0%; margin-top: 1em; font-family: sans-serif; border-bottom: thin dotted #8AB8E6; color: #8AB8E6;}
h2 { font-size: 100%; font-family: sans-serif; margin-left: 0%; margin-top: 2em; border-bottom: thin dotted #8AB8E6; color: #8AB8E6;}
h3 { font-size: 100%; margin-left: auto; margin-right:0; width:45em;margin-top: 2em; color: #8AB8E6;}
pre { font-family: monospace; background: rgb(244,244,244); overflow: auto; width: 45em; margin-left: auto; margin-right: auto;}
p { width: 45em; margin-left: auto; margin-right: 0;}
p.indent:first-letter { padding-left: 2em; }
p.abstract { margin-top: 0em; margin-left: auto; margin-right: 0; margin-bottom:2em; text-align: right; font-style:italic;}
p.picture { font-size: 95%; text-align: center; margin-bottom: 2em; width: 352px;}
div.lp { float: left; }
div.rp { margin-left: 382px; }
div.pic { margin-left: auto; margin-right: 0; width: 750px;}
p.foot { font-size: 100%; margin-top: 5em; padding-top: 1em; margin-left: auto; margin-right: 0; border-top: thin dotted; text-align: center; width: 100%}
ul, dl { width: 45em; margin-left: auto; margin-right: 0;}
li { margin-top: 0.5em; }
dt { margin-top: 1em; }
dd { margin-top: 0.2em; }
dl { margin-bottom: 1em; }
span.par{ font-weight: bold; font-family: sans-serif; color: #8AB8E6; margin-right: 0.618em; }
</style>
</head>

<body>

<h1>Rawtran</h1>

<p class="abstract">
  Rawtran is a wrapper around <a href="http://www.cybercom.net/~dcoffin/dcraw/">
    dcraw</a> developed to produce images in the standard astronomical FITS
  format by processing of raw (CR2, CRW, MRW, etc.) photos.
</p>

<h2>Overview</h2>

<p>
Selected digital cameras offers possibility to save
<a href="http://en.wikipedia.org/wiki/Raw_image_format">raw photos</a> ‒
only slightly pre-processed photos intended for further image processing.
Rawtran is developed as a wrapper around <a href="http://www.cybercom.net/~dcoffin/dcraw/">dcraw</a>
 by D.Coffin to produce <a href="http://fits.gsfc.nasa.gov/">FITS</a> files
from the raw photos.
</p>

<p class="indent">
FITS files are basically used by astronomers.
Rawtran creates fully compatible FITS files which can be processed by
any standard astronomical software; the files are formally equivalent to ones,
which has been acquired by an ordinary scientific instrument.
FITS files created by Rawtran are suitable for all regular photometry,
spectroscopy or astrometry processing.
</p>

<h2>Data concern</h2>

<p>
  Data philosophy of Rawtran holds the key aspects:
</p>

<p>
  <span class="par">Image data</span>
  are processed by such way, to save any carried photometry information.
  The spectral bands  — colours —
  and the proper handling is important for a scientific
  interpretations. Rawtran implements the conversion
  from CIE 1931 XYZ colours, provided by dcraw itself,
  to BVR bands of Johnson photometry system.
</p>

<p>
<span class="par">Metadata</span>
or an exact description of actual exposure parameters,
including exposure data, used equipment etc., are considered
as the integral part of the image data, and becomes to be
the integral part of scientific data processig.
Rawtran extracts detailed EXIF information,
enclosed into every raw photo, and interprets
them in scope of common astronomical conventions.
</p>

<h2>Colour FITS</h2>

<p>
   Common use of a digital camera gives colour pictures.
   Unfortunately,
   there is no widely accepted convention, or definition, of the (natural)
   colour representation in the FITS world; Rawtran takes Munipack's
   specification:
</p>

<ul>
<li>
  The first FITS extension is a primary 3D array
  storing the image.
  CSPACE keyword should be presented; Rawtran always sets it
  to "CIE 1931 XYZ" which identifies
  <a href="http://en.wikipedia.org/wiki/CIE_1931_color_space">CIE 1931 XYZ
    colour-space.</a>
</li>
<li>
  Tree colour bands are stored in the array with the structure:
  width ⨉ height ⨉ 3; the bands are stored in short- to long- wavelength
  order: Z (blue) ‒ index 1, Y (green) ‒ index 2, X (red) ‒ index 3.
</li>
<li>
  The array values should be considered as a relative quantity
  linearly proportional to captured photon counts.
</li>
</ul>

<p>
  Colour FITS files can be correctly displayed only by
  <a href="http://munipack.physics.muni.cz">Munipack</a>
  or <a href="http://integral.physics.muni.cz/fitspng">Fitspng</a>.
</p>


<h2>Single bands</h2>

<p>Options: <samp>-c X,Y,Z,B,V,R,Ri,Gi,Gi1,Gi2,Bi,clear,scotopic</samp></p>

<p>
  The kind of conversion is intended for representation of
  detected counts in the colour band.
  The output is a grey-scale image, one is stored as two dimensional
  FITS primary array.
</p>

<p>
  <span class="par">Instrumental </span>
  bands by <samp>-c [Ri,Gi1,Gi2,Gi,Bi]</samp>
  are array elements under Bayer's mask.
  Gi is derived as the arithmetical mean Gi = (Gi1 + Gi2) / 2.
  These instrumental values are direct copy of on-chip counts
  specific for an unique camera model.
<p>

<p>
  <span class="par">CIE 1931 XYZ</span>
  bands by <samp>-c [X,Y,Z]</samp> are elements of the
  <a href="http://en.wikipedia.org/wiki/CIE_1931_color_space">colour</a>
  array derived by dcraw from the instrumental bands.
  Y component represents luminance: its spectral profile is similar
  to the spectral sensitivity of the human eye under well-light conditions
  (<a href="http://en.wikipedia.org/wiki/Photopic_vision">photopic vision</a>).
</p>

<p>
  <span class="par">Johnson's </span>
  bands by <samp>-c [B,V,R]</samp> are derived
  by Rawtran from CIE 1931 XYZ with help of a built-in colour
  transformation matrix  to
  <a href="http://en.wikipedia.org/wiki/UBV_photometric_system">Johnson
    UBVRI wide-band astronomical photometry system</a>.
</p>

<p class="indent">
  The data should be considered as an inaccurate approximation
  of photon rates in Johnson's filters.
  The exact transformation requires more detailed
  knowledge of full spectral sensitivity of a device, weather conditions,
  etc: determination of own transformation is highly recommended.
</p>

<p>
  <span class="par">Derived</span>
  bands by <samp>-c [scotopic, clear]</samp>
  simulates a wide-spectral band (like an unfiltered CCD image)
  or
  <a href="http://en.wikipedia.org/wiki/Scotopic_vision">scotopic
    vision</a> (like the human eye under low-light conditions).
  The visual difference between colour (or Y component) and
  the scotopic images illustrates
  <a href="http://en.wikipedia.org/wiki/Purkinje_effect">Purkyňův effect</a>.
</p>


<p class="indent">
  Note, that the data are slightly modified as result of
  a colour interpolation on Bayer's mask. Use -X "-h" to switch-off
  the interpolation.
  All the data should be supposed as <b>RELATIVE</b> counts only.
</p>


<h2>Instrumental (Bayer's) data</h2>

<p>Options: <samp>-c plain</samp>, <samp>-c all</samp></p>

<p>
  This operation modes provides the low-level raw access
  to the original data via FITS format. It is designed to
  offer a direct conversion between the file formats:
  the conversion rearranges bytes only and does NOT modify data itself.
</p>

<p class="indent">
  <span class="par">Plain</span> array by <samp>-c plain</samp>
  is a single large array of pixels without any photometric transformations.
  It represents an unmodified on-chip image covered by Bayer's mask.
  A grid appears due different sensitivity of R, G and B pixels.
  The actual pattern depends on a particular camera model.
</p>

<p class="indent">
  <span class="par">All</span> array by <samp>-c all</samp>
  is a single 4D primary array without any photometric transformations.
  Original bands are stored in the four dimensional structure:
  width ⨉ height ⨉ 4. The bands stores Bayer's colours in that order:
  B (blue), G1 (green1), G2 (green2), R (red).
  According to astronomical terminology, the single bands are in
  an instrumental colour photometry system.
</p>


<h2>Rawtran invocation</h2>

<h3>Synopsis</h3>

<p>
  <b>rawtran</b> [options] file(s)
</p>

<h3>Command line options</h3>

<dl>

  <dt><b>-c</b> [X|Y|Z|R|V|B|scotopic|clear] (derived bands)</dt>
  <dd>
    Transform input image data to the derived band:
    <dl>
      <dt><b>X,Y</b> or <b>Z</b></dt>
      <dd>
	Bands of
	<a href="http://en.wikipedia.org/wiki/CIE_1931_color_space">CIE XYZ
	  1931</a> colour-space.</dd>
      <dt><b>B,V</b> or <b>R</b></dt>
      <dd><a href="http://en.wikipedia.org/wiki/UBV_photometric_system">
	  Johnson</a> astronomical photometry system bands.</dd>
      <dt><b>scotopic</b></dt>
      <dd>Simulates human eye
	<a href="http://en.wikipedia.org/wiki/Purkinje_effect">sensitivity
	  under low-light conditions</a>,
	computed as (0.36169 Z + 1.18214 Y - 0.80498 X) for every pixel.</dd>
      <dt><b>clear</b></dt>
      <dd>or unfiltered: integrated over full camera spectral sensitivity,
	computed as (X + Y + Z) / 3 for every pixel.</dd>
    </dl>
  </dd>

  <dt><b>-c</b> [Ri|Gi|Gi1|Gi2|Bi] (instrumental bands)</dt>
  <dd>
    Transform input image data to the instrumental band:
    <dl>
	<dt><b>Ri,Gi,Gi1,Gi2</b> or <b>Bi</b></dt>
      <dd>Instrumental, camera specific, colour in Bayer's mask.
	The mean green is Gi = (Gi1 + Gi2) / 2.</dd>
    </dl>
  </dd>
  <dt><b>-c</b> [plain|all] (Bayer mask)</dt>
  <dd>
    Transform input image data to the machine representation:
    <dl>
      <dt><b>plain</b></dt>
      <dd>Plain data in
	<a href="https://en.wikipedia.org/wiki/Bayer_filter">Bayer mask</a></dd>
      <dt><b>all</b></dt>
      <dd>Data of Bayer's mask are separated on single channels.</dd>
    </dl>
  </dd>

<dt><b>-o</b> file</dt>
  <dd>
      Specify an output file name, a single file only.
  <p>
    Normally, the output filename is determined by the way:
    Suffixes of input filenames, like <samp>*.CR2</samp>,
    are replaced by <samp>*.fits</samp>, and a full directory
    path is removed. It is designed to leave original
    data untouched, and to keep results in current, working,
    directory (see <a href="#examples">Examples</a>).
  </p>
</dd>

<dt><b>--no-clobber</b></dt>
<dd>
  Do not overwrite an existing file.
  <p>
  In the FITS world, files can not be overwritten by default,
  except their filename is preceded with the exclamation point (!),
  like <samp>'!rawtran.fits'</samp>. Rawtran violates the rule by default;
  this options recovers the FITS world convention.
  </p>
</dd>

<dt><b>-eV</b></dt>
<dd>
  Store values of the output image as an energy-like quantity,
  proportional to [eV/s/m2/arcsec2], rather than photon-like
  quantity [counts/s/m2/arcsec2]. By physical terminology: the
  values will be stored in intensity (proportional to energy incoming from
  an unit cone per a time unit and an area).
  The values should be considered as non calibrated.
</dd>

<dt><b>-D</b> RAW dark filename</dt>
<dd>
Use the raw photo as a dark frame. Rawtran will try to convert the file to
PGM format by the recommended way <code>dcraw -D -4 -j -t 0 file.RAW</code>
and pass it to dcraw <code>-K file.pgm</code>.
Note that sometimes can be necessary to switch-off automatic frame
rotation using <code>-A "-t 0"</code>.
See <a href="#darkframe">Dark Frame</a> section for more info.
</dd>

<dt><b>-E</b> FITS dark filename</dt>
<dd>
Use the FITS file as a dark frame. The FITS file should be
previously converted as <code>dcraw -D -4 -j -t 0 dark.RAW</code>.
See <a href="#darkframe">Dark Frame</a> section for more info.
</dd>

<dt><b>-C</b> options</dt>
<dd>
  Core options for dcraw: default is <samp>"-4 -o 5"</samp>
  for standard photometry filters and <samp>"-4 -D"</samp>
  for instrumental bands. The defaults are usually satisfactory.
</dd>

<dt><b>-X</b> options</dt>
<dd>
Convenience options for dcraw; they represents
default parameters: <samp>"-q 3 -w"</samp> providing the best quality.
See also -A option.
</dd>

<dt><b>-A</b> options</dt>
<dd>
Additional options for fine tuning of dcraw; if you need pass
more options, enclose ones to quotes or apostrophes.
In doubts, use <samp>-A "-v"</samp> to show the detailed trace
of the conversion provided by dcraw.
</dd>

<dt><b>-h</b>, --help, --version</dt>
<dd>
Show summary of options or current versions.
</dd>
</dl>

<p>
  Splitting of the conversion parameters for dcraw
  onto <samp>-C, -X, -A</samp> groups is pure conventional;
  the core <samp>-C, -X</samp> and the tune <samp>-A</samp>
  options are separated to prevent potential mistakes.
  Setup of the core parameters is recommended only
  for users who know what they do.
</p>


<h2>Exit status</h2>
<p>
0 indicates successful run. A non-zero value is returned when
an error occurred during conversion: 1 means a general error,
2 indicates that conversion of any RAW file(s) has failed.
</p>

<p class="indent">
If the utility is launched without any options, or with -h switch:
zero means that Rawtran internal checker can run dcraw binary,
and non-zero value otherwise.
</p>


<h2 id="examples">Examples of usage</h2>

<p>
A raw photo converted to colour FITS (the result is displayed by xmunipack):
</p>
<pre>
$ rawtran IMG_0666.CR2
$ xmunipack IMG_0666.fits
</pre>

<p>
  A plenty of RAW files, by file-mask <samp>*.CR2</samp>,
  in directory <samp>/path/with/archive</samp>, are converted as
</p>
<pre>
$ cd workdir
$ rawtran /path/with/archive/*.CR2
</pre>
<p>
  All result, stored as *.fits, can be found in <samp>workdir</samp>.
</p>

<p>
  Simulates the seen of the human eye at good light conditions:
</p>
<pre>
$ rawtran -c Y -o IMG_0666_Y.fits IMG_0666.CR2
</pre>

<p>
An image is an equivalent of Johnson's B filter:
</p>
<pre>
$ rawtran -c B -o IMG_0666_B.fits IMG_0666.CR2
</pre>

<h2>Advanced usage</h2>

<p>
  The above commands can be flexible extended with help of command
  line shell functionality.
</p>

<p>
  An alternative of a plenty of files conversion:
</p>
<pre>
  $ for A in *.CR2; do
     rawtran -o ${A%CR2}fits ${A};
    done
</pre>

<p>
  A frame separation on standard Johnson single bands:
</p>
<pre>
  $ A=IMAGE_0666.CR2
  $ for F in B V R; do
     rawtran -c $F -o ${A%.CR2}_${F}.fits $A;
    done
</pre>

<p>
  An alternative to the common conversions,
  with results saved into a different directory, can be simulated by:
</p>
<pre>
  $ DATADIR=/path/with/input/raws
  $ DESTDIR=/path/for/output/fitses
  $ for A in ${DATADIR}/*.CR2; do
      B=$(basename $A)
      C="${DESTDIR}/${B%.CR2}.fits"
      rawtran -o $C $A;
    done
</pre>

<p>
  FITS files occupies a lot of storage volume. FITS compression
  can help to save some volume, but it may complicate of its usability:
</p>
<pre>
$ rawtran -o 'IMG_0666.fits[compress]' IMG_0666.CR2
</pre>

<h2>Gallery</h2>


<div style="padding:1em;"></div>

<div class="pic">
<div class="lp">
<img src="IMG_5952.png" width="352" height="234" alt="IMG_5952">
<p class="picture">
#1, Colour FITS
</p>
</div>

<div class="rp">
<img src="IMG_5952_X.png" width="352" height="234" alt="IMG_5952_X">
<p class="picture">
#2, X component
</p>
</div>
</div>

<div class="pic">
<div class="lp">
<img src="IMG_5952_Y.png" width="352" height="234" alt="IMG_5952_Y">
<p class="picture">
#3, Y component
</p>
</div>

<div class="rp">
<img src="IMG_5952_Z.png" width="352" height="234" alt="IMG_5952_Z">
<p class="picture">
#4, Z component
</p>
</div>
</div>

<div class="pic">
<div class="lp">
<img src="IMG_5952_R.png" width="352" height="234" alt="IMG_5952_R">
<p class="picture">
#5, R filter
</p>
</div>

<div class="rp">
<img src="IMG_5952_V.png" width="352" height="234" alt="IMG_5952_V">
<p class="picture">
#6, V filter
</p>
</div>
</div>

<div class="pic">
<div class="lp">
<img src="IMG_5952_B.png" width="352" height="234" alt="IMG_5952_B">
<p class="picture">
#7, B filter
</p>
</div>

<div class="rp">
<img src="IMG_5952_Ri.png" width="352" height="234" alt="IMG_5952_Ri">
<p class="picture">
#8, Ri Bayer instrumental
</p>
</div>
</div>

<div class="pic">
<div class="lp">
<img src="IMG_5952_Gi.png" width="352" height="234" alt="IMG_5952_Gi">
<p class="picture">
#9, Gi Bayer instrumental
</p>
</div>

<div class="rp">
<img src="IMG_5952_Bi.png" width="352" height="234" alt="IMG_5952_Bi">
<p class="picture">
#10, Bi Bayer instrumental
</p>
</div>
</div>

<div class="pic">
<div class="lp">
<img src="IMG_5952_u.png" width="352" height="234" alt="IMG_5952_u">
<p class="picture">
#11, Clear
</p>

</div>

<div class="rp">
<img src="IMG_5952_s.png" width="352" height="234" alt="IMG_5952_s">
<p class="picture">
#12, Night vision (scotopic)
</p>
</div>
</div>

<p>
  This gallery has been generated by the processing of the reference raw photo
  <a href="IMG_5952.CR2">IMG_5952.CR2</a>:
</p>
<pre>
$ rawtran -o IMG_5952.fits               IMG_5952.CR2             #1
$ rawtran -o IMG_5952_X.fits -c X        IMG_5952.CR2             #2
$ rawtran -o IMG_5952_Y.fits -c Y        IMG_5952.CR2             #3
$ rawtran -o IMG_5952_Z.fits -c Z	 IMG_5952.CR2             #4
$ rawtran -o IMG_5952_R.fits -c R	 IMG_5952.CR2             #5
$ rawtran -o IMG_5952_V.fits -c V	 IMG_5952.CR2             #6
$ rawtran -o IMG_5952_B.fits -c B	 IMG_5952.CR2             #7
$ rawtran -o IMG_5952_Ri.fits -c Ri	 IMG_5952.CR2             #8
$ rawtran -o IMG_5952_Gi.fits -c Vi	 IMG_5952.CR2             #9
$ rawtran -o IMG_5952_Bi.fits -c Bi	 IMG_5952.CR2             #10
$ rawtran -o IMG_5952_c.fits -c clear	 IMG_5952.CR2             #11
$ rawtran -o IMG_5952_s.fits -c scotopic IMG_5952.CR2             #12

$ fitspng -fl 0,20000  -o IMG_5952.png    -s 10 IMG_5952.fits     #1
$ fitspng -fl 0,20000  -o IMG_5952_X.png  -s 10	IMG_5952_X.fits   #2
$ fitspng -fl 0,20000  -o IMG_5952_Y.png  -s 10	IMG_5952_Y.fits   #3
$ fitspng -fl 0,20000  -o IMG_5952_Z.png  -s 10	IMG_5952_Z.fits   #4
$ fitspng -fl 0,20000  -o IMG_5952_R.png  -s 10	IMG_5952_R.fits   #5
$ fitspng -fl 0,20000  -o IMG_5952_V.png  -s 10	IMG_5952_V.fits   #6
$ fitspng -fl 0,20000  -o IMG_5952_B.png  -s 10	IMG_5952_B.fits   #7
$ fitspng -fl 128,1000 -o IMG_5952_Ri.png -s 10	IMG_5952_Ri.fits  #8
$ fitspng -fl 128,1000 -o IMG_5952_Gi.png -s 10	IMG_5952_Gi.fits  #9
$ fitspng -fl 128,1000 -o IMG_5952_Bi.png -s 10	IMG_5952_Bi.fits  #10
$ fitspng -fl 0,40000  -o IMG_5952_c.png  -s 10	IMG_5952_u.fits   #11
$ fitspng -fl 0,20000  -o IMG_5952_s.png  -s 10	IMG_5952_s.fits   #12
</pre>


<h2>Accuracy of colours </h2>

<p>
  The colour transformation between CIE 1931 XYZ and Johnson BVR,
  and vice versa, reduces accuracy of the colour reproduction.
</p>

<p class="indent">
  The comparison of original and reproduced colours can be
  visualised by the way: the original RAW is decomposed onto
  B,V,R channels, and again assembled to a colour frame.
</p>

<p class="indent">
  There are summarised commands to do the comparison.
  Both original and the final frames has set the white balance
  by a spot on coordinates 2370,1670 for FITS (origin in left
  bottom corner) and  2370,678 for PPM (origin in left top corner).
</p>

<pre>
  $ rawtran -c B -o IMG_5952_B.fits IMG_5952.CR2
  $ rawtran -c V -o IMG_5952_V.fits IMG_5952.CR2
  $ rawtran -c R -o IMG_5952_R.fits IMG_5952.CR2
  $ munipack colouring --disable-back --white-spot 2370,1670 \
             IMG_5952_B.fits IMG_5952_V.fits IMG_5952_R.fits
  $ dcraw -A 2370 678 10 10  IMG_5952.CR2
</pre>

<p class="indent">
  On the first sight the processed image has blended colours ‒ the ideal
  transformation should give images which can not be recognised each
  other.
</p>
<p class="indent">
  The colour transformations are computed by a matrix multiplication
  which approximates a single filter by another set of filters.
  The composition of forward and backward transformation matrix should
  be numerically close to unit matrix, which is not satisfied accurately.
  The reason for <a href="#johnson">above recommendation</a> has roots here.
</p>

<div style="padding:1em;"></div>

<div class="pic">
<div class="lp">
<img src="IMG_5952_orig.png" width="352" height="234" alt="IMG_5952_orig">
<p class="picture">
Processed by dcraw
</p>
</div>

<div class="rp">
<img src="IMG_5952_colouring.png" width="352" height="234" alt="IMG_5952_colouring">
<p class="picture">
Reconstructed colours
</p>
</div>
</div>


<h2 id="darkframe">Dark frame</h2>

<p>Rawtran provides convenience functions for handling of dark frames.
</p>

<p class="indent">
The basic way is use of <samp>-D</samp> option, which launch
dcraw to create PGM file representing of the dark:
</p>
<pre>
$ rawtran -D dark.CR2 -o light.fits light.CR2
</pre>
<p class="indent">
Note, dcraw sometimes saves results to PPM file, a transparent
conversion to PGM can be required. Therefore the time duration
of the procedure will depend on the conversion, and generally
one will be twice slower than passing a PGM file directly
by <samp>-A "-K file.pgm"</samp>.
An user is responsible to provide a correct dark frame,
a frame taken without light.
</p>

<p class="indent">
A little bit advanced way is to use a FITS file as dark frame which is
converted to PGM on the fly. Purpose of the option is to offer
a possibility for averaging of dark frames.
See, this hypothetical session:
</p>
<pre>
$ rawtran -c plain -A "-j -t 0" -o dark1.fits dark1.CR2
$ rawtran -c plain -A "-j -t 0" -o dark2.fits dark2.CR2
$ munipack dark -o dark.fits dark?.fits   # or equivalent
$ rawtran -E dark.fits -o light.fits light.CR2
</pre>
<p class="indent">
  Initially, as shows first two lines (or possible more),
  we converts dark frames
to FITS format by <samp>-c plain</samp> option,
the created FITS-es are averaged (munipack utility
is only an example), and finally,
the averaged file is passed as the dark frame.
</p>


<h2>Download and installation</h2>

<ul>
<li>
<a href="http://www.cybercom.net/~dcoffin/dcraw/">Dcraw</a> must be
available for proper function of Rawtran.
</li>
</ul>

<p>
  The <a href="ftp://integral.physics.muni.cz/pub/rawtran/">tar-ball</a>,
  or the <a href="http://integral.physics.muni.cz/hg/rawtran/">development
  repository</a>, is freely available under GPL3+ license.
  <a href="http://heasarc.gsfc.nasa.gov/docs/software/fitsio/fitsio.html">cfitsio</a> library including files required for development
  (headers, static libraries) is necessary for building.
  Building itself does not depends on dcraw.
</p>

<p class="indent">
Rawtran runs under any Unix-like operating system (all flavors
of GNU/Linux and BSD, Solaris, Mac OS X, etc). Usage under Windows
or DOS has not been reported yet. Portability is limited
by calling some particular functions (symlink, unlink) and
mainly by pthreads.
  Rawtran packages can be found in
  <a href="https://packages.debian.org/rawtran">GNU/Debian</a> and
  <a href="http://packages.ubuntu.com/rawtran">Ubuntu</a>.
</p>


<p><a href="http://en.wikipedia.org/wiki/Configure_script">
A recommended way</a> of local installation from the source code is:</p>

<pre>
$ tar zxf rawtran-X.Y.Z.tar.gz
$ cd rawtran-X.Y.Z/
$ autoreconf -i   # for Mercurial
$ ./configure CFLAGS="-O4 -DNDEBUG"
$ make
# make install
</pre>

<p class="indent">The last step should be executed under root account.
Both binary and
man page are installed under <code>/usr/local</code> tree. It would be
nice to keep the source directory for a case of later uninstall.</p>


<p class="indent">
Building under RPM-bases distributions (RHELL, Fedora) requires
place of Rawtran tarball to a directory
where RPM places sources (rpmbuild), unpack
the spec file and we can use the following commands
to build:
</p>
<pre>
$ rpmbuild -bb rawtran.spec
</pre>


<h2>Implementation details</h2>
<p>
  By design, Rawtran is a wrapper around dcraw. One internally launches
  dcraw as its sub-process and grabs an output data stream.
  Metadata (EXIF information) are obtained as:
</p>
<pre>
 dcraw -i -v -c
</pre>

<p>
The image data oneself are imported by one of the alternatives:
</p>
<pre>
 dcraw -4 -c -o 5    (standard bands)
 dcraw -4 -c -D      (instrumental bands)
</pre>
<p>
These parameters can be carefully modified by -C option (except -c).
</p>

<p class="indent">
  <span class="par">Data storage</span>
  Rawtran converts PGM/PPM images in 16-bit colour depth
  to an equivalent FITS format with BITXPIX=16; no values
  modification is done for these instrumental bands (<samp>-c</samp>):
  Bayer's mask elements, plain and all. Another conversions:
  Colour FITS, or any conversion onto Johnson BVR filters,
  clear and scotopic filters, are internally computed in 4-byte floats
  (with precision of 7 decimals and the maximum value 10<sup>33</sup>);
  their values are rounded to nearest integers, and stored as
  unsigned 16-bit numbers (range from 0 to 65535)
  in FITS files.
</p>

<p class="indent">
  <span class="par">Multi-threading</span>
  Rawtran is designed as a multi-threaded application: it launches
  as much as possible dcraw instances (up to available CPUs limit)
  simultaneously. The approach increases performance, but a processing
  order of output files, or log records, can not be guarantied.
</p>

<h2>See also</h2>
<p>
<a href="http://integral.physics.muni.cz/fitspng">Fitspng</a>
is a converter from FITS to PNG.
<a href="http://munipack.physics.muni.cz">Munipack</a> is a general utility
to work with FITS images.
</p>
<p>
Development notes can be found in
<a href="http://monteboo.blogspot.com/search/label/Rawtran">Hroch's diary.</a>
</p>


<h2>License</h2>
<p>
  Rawtran is
  <a href="http://www.gnu.org/philosophy/free-sw.html">free software</a>
  licensed under the <a href="http://www.gnu.org/licenses/gpl.html">GNU
    General Public License</a>.
  This gives you the freedom to use and modify Rawtran to suit your needs.
</p>

<p class="foot">
Copyright &copy; 2007 — 2019, <a href="mailto:hroch@physics.muni.cz">F. Hroch</a>,
<a href="http://www.physics.muni.cz">Institute of Theoretical Physics and Astrophysics</a>,
<a href="http://www.muni.cz/en">Masaryk University</a>,
<a href="http://en.wikipedia.org/wiki/Brno">Brno</a>,
<a href="http://en.wikipedia.org/wiki/Czech_Republic">Czech Republic</a>.
</p>

</body>
</html>

<!--
* M67 test
-->