/usr/share/doc/munipack/man_flat.html is in munipack-doc 0.5.10-1.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 | <!DOCTYPE HTML>
<html lang="en">
<head>
<!-- meta -->
<meta http-equiv="content-type" content="text/html; charset=UTF-8">
<meta name="description" content="A general astronomical image processing software">
<meta name="author" content="Filip Hroch">
<link href="news_feed.xml" type="application/atom+xml" rel="alternate" title="Sitewide ATOM Feed" />
<link type="text/css" rel="stylesheet" href="munipack.css">
<link rel="shortcut icon" href="favicon.ico">
<title>Munipack ‒ Flat-field frame</title>
</head>
<body>
<header>
<a href="munipack.html"><img src="title_logo.png" alt="Munipack's logo" class="head"></a>
<div class="headhead">
<div class="headtitle">
<a class="headtitle" href="munipack.html">Munipack</a>
<a class="headsubtitle" href="munipack.html">A general astronomical image processing software</a>
</div>
<ul class="menu">
<li class="menu">◈ <a href="docs.html" class="menu">Documents</a></li>
<li class="menu">☺ <a href="guide.html" class="menu">User guide</a></li>
</ul>
</div>
</header>
<!-- TODO:
* describe of verbose info (for all commands!)
-->
<h1>Flat-field frame</h1>
<p class="abstract">
The <samp>flat</samp> utility is designed to
constructs of an average flat-field frame by
a set of individual flat-field frames.
</p>
<h2>Synopsis</h2>
<code>
munipack flat [.. parameters ..] file(s)
</code>
<h2>Description</h2>
<p>
A flat-field frame is a map of the photometric response of an instrument
(both detector and optical configuration together). Flat-fields are used
to remove all imperfections like variable light sensitivity of pixels,
dust grains, vignetting and similar
effects on per-pixel basis. Flat-fields can be acquired
on sky during twilight, as night sky images, the dome flats
or by another technique.
</p>
<p class="indent">
This routine creates a new flat-field frame by averaging of
a set of such flat-fields. The averaging improves precision of
the flat-field by factor of square root of input frames count
(sixteen input frames increases precision by factor 4×). Moreover,
all defects presented on any single frame (like random
cosmics) are softly cleared.
</p>
<p class="indent">
The output flat-field <i>F<sub>ij</sub></i> is computed as the
massive sequence of non-linear implicit equations for every pixel
of every input frame,
which needs a lot of both computer power and time.
Amount of frames is limited only by available memory
(width × height × 4 × 2 bytes per frame). One hundred of
1000×1000 frames takes 800MB.
</p>
<p class="indent">
Relative precision of a final flat-field increase as
square root of amount of input frames <i>√N</i>.
Implemented robust methods works well when amount of
input frames is over thirteen frames <i>N > 13</i>.
A single frame on input is normalised only.
</p>
<p class="indent">
The input flat-fields should be preparatory corrected for all of these
gain, bias and dark:
</p>
<p>
<i>F<sub>ij</sub> → g(F<sub>ij</sub> - x D<sub>ij</sub> - B<sub>ij</sub>)</i>.
</p>
<p>
The meaning of <i>x</i> and the algorithm itself are the same as in
<a href="man_phcorr.html">photometric corrections</a>.
</p>
<p class="indent">
It is strongly recommended to set of correct value of FITS_KEY_FILTER
(<a href="man_env.html">environment variables</a>), because
the filter identification in the FITS header of the flat-field
should be available for some later processing.
</p>
<h2>Gain estimate</h2>
<p>
Flat-fielding can be used to estimate of gain <i>g</i> of a camera.
The estimation determines
<a href="https://en.wikipedia.org/wiki/Variance">variance</a>
<i>σ<sup>2</sup></i> and the mean value
<i><span style="text-decoration: overline">c</span></i>
of individual flat-field frames. Ratio satisfies the condition
<i><span style="text-decoration: overline">c</span>/σ<sup>2</sup> ≈ 1</i>
only for <a href="http://en.wikipedia.org/wiki/Poisson_distribution">Poisson distributed</a> data, when other sources of noise are negligible.
Values significantly violating the conditions
indicates that <i>g</i> is differ to one.
The recommended mean values for all <i>c</i> are about half of full well
capacity of a detector.
</p>
<p class="indent">
The gain <i>g</i> is determined by the relation
</p>
<p>
<i>g = <span style="text-decoration: overline">c</span> / σ²</i>
</p>
<p class="indent">
The estimated values of variance <i>σ<sup>2</sup></i> and gain <i>g</i>
are printed on the output as the last two columns:
</p>
<pre>
...
Filename, mean level[ct], std.err., reliable, std.dev., gain:
[σ] [g]
...
flat-V_000002.fits: 1.15777E+05 58.5 T 339.14 1.007
flat-V_000003.fits: 98909. 50.0 T 313.62 1.006
...
</pre>
<p class="indent">
Gain is determined only on
request by using of <samp>--gain-estimate</samp> switch
(verbose mode is invoked), because it slows down computations.
</p>
<p class="indent">
A recommended way to determine of gain is preliminary set
some value
(<i>g=1</i> if no the right value is already known) and invoke
the estimate.
Than use the newly determined value
to set the gain again and repeat the procedure
while estimated gain will remain on value near to one
(with a few percent precision).
</p>
<p class="indent">
When gain keyword is available in the header, the values are
initially scaled by the gain so results will be determined relative
against to the value.
</p>
<p class="indent">
The estimation of value of gain is just indicative and to check by some
alternative method (factory provided, …) is highly recommended.
</p>
<h2>Input and output</h2>
<p>
On input, list of observed flat-fields is expected.
Optionally, all gain, bias and dark corrections can
by applied on every frame.
</p>
<p>
On output, just the flat-field frame is created.
</p>
<h2>Parameters</h2>
<dl>
<dt><samp>-gain g</samp></dt><dd>provide value of gain (rather than
FITS keyword) in [e-/ADU]</dd>
<dt><samp>-bias file</samp></dt><dd>bias frame</dd>
<dt><samp>-dark file</samp></dt><dd>dark frame</dd>
<dt><samp>-xdark x</samp></dt><dd>dark frame multiplicative factor</dd>
<dt><samp>-bitmask file</samp></dt><dd>mask frame (see
<a href="man_phcorr.html">phcorr</a> for description). Only pixels,
marked by this mask are processed.
</dd>
<dt><samp>-st, --saturate s</samp></dt><dd>Set saturate limit in
units of input frames.
All pixels with values out of the range
<i>th < flat < s</i> (see also --threshold)
are rejected from any processing.
This switch is useful mainly for over-exposed flat-fields
and elimination of non-linear parts of gradation curve.
If leaved unset, the value is determined from FITS header
(by FITS_KEY_SATURATE, <a href="man_setup.html">see</a>).
If the keyword is not found and the frame contains
an integer number type, the maximum value 2**BITPIX-1 is
provided, otherwise the maximum value of the first frame on input
is used (which practically switch-off the saturation bound check).
The value is set in ADU (values reported by camera).
</dd>
<dt><samp>-th, --threshold th</samp></dt><dd>Set threshold limit
in units of input frames.
All pixels below the value are rejected from any processing.
If unset, the value is zero. Threshold is minor significance parameter.
It should help in case of faulty values in frames or filtering
of bad flat-fields. Its recommended value is inside interval
from zero to one quarter of full range.
The value is set in ADU (values reported by camera).
</dd>
<dt><samp>--gain-estimate</samp></dt><dd>Rough estimate of gain.
</dd>
<dt><samp>--approximation [basic|standard]</samp></dt><dd>
Basic approximation computes only robust mean of all flat-fields.
It is only very rough estimate.
The standard approximation provides more precise
solution on base of the basic initial estimate.
</dd>
<dt><samp>-B bitpix</samp></dt><dd>Set numerical type of output images.
Only the default -32 should be used.
The mean value of outputs will be changed to <i>100, 10<sup>4</sup>,
10<sup>9</sup></i> for BITPIX 8,16 and 32.
</dd>
<dt><samp>-o filename</samp></dt><dd>save to the output file</dd>
</dl>
<p>Also see <a href="man_com.html">Common options</a></p>
<h2>Environment variables</h2>
<p>
FITS_KEY_FILTER, FITS_KEY_DATEOBS, FITS_KEY_EXPTIME, FITS_KEY_IMAGETYP,
FITS_KEY_GAIN, FITS_KEY_SATURATE
(see <a href="man_env.html">Environment variables</a>).
</p>
<p class="indent">
No one is mandatory, but remember, a flat-field with no filter
identification is like heavy water without neutron.
</p>
<h2>Examples</h2>
<code>
$ munipack flat -o f_R.fits -gain 2.3 -dark d30.fits -st 6e4 f30_*R.fits
</code>
<figure>
<img class="figure" src="f10_1.png" alt="f10_1.png" title="A flat-field image">
<figcaption>
A single flat-field frame.
</figcaption>
</figure>
<figure>
<img class="figure" src="autoflat.png" alt="autoflat.png" title="A scaled robust mean of flats">
<figcaption>
A scaled robust mean of flat-field frames.
</figcaption>
</figure>
<h2>See also</h2>
<p>
<a href="flatfielding.html">Flat-fielding</a>,
<a href="lctut.html">Light curve tutorial</a>,
<a href="phcorrtut.html">Photometry corrections tutorial</a>,
<a href="man_bias.html">Averaged bias frame</a>,
<a href="man_dark.html">Averaged dark frame</a>.
</p>
<footer>
<div style="float:left; margin-left:2em;">
Copyright © 1997 – 2018
Filip Hroch (<a style="text-decoration: none" href="mailto:hroch@physics.muni.cz?Subject=Munipack" title="Author's Email">✉</a>), license <a href="http://www.gnu.org/licenses/gpl.html">GPLv3</a>.
</div>
<div style="float:right; margin-right:2em; margin-top:-0.2em;">
<a href="http://monteboo.blogspot.com/search/label/Munipack" title="Munipack on MonteBoo Blog"><img src="favicon-blogger.png" alt="Blogger"></a>
<a href="http://www.muni.cz/?lang=en" title="Masaryk University in Brno, Czech Republic"><img src="mu-logo.png" alt="Masaryk University"></a>
<a href="news_feed.xml" title="Munipack's Releases in Atom Syndication Format"><img src="Feed-icon.png" alt="Atom Feed"></a>
</div>
</footer>
</body>
</html>
|