.\" Automatically generated by Pod::Man version 1.02
.\" Tue Jun  1 14:56:29 2004
.\"
.\" Standard preamble:
.\" ======================================================================
.de Sh \" Subsection heading
.br
.if t .Sp
.ne 5
.PP
\fB\\$1\fR
.PP
..
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Ip \" List item
.br
.ie \\n(.$>=3 .ne \\$3
.el .ne 3
.IP "\\$1" \\$2
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R

.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  | will give a
.\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
.\" to do unbreakable dashes and therefore won't be available.  \*(C` and
.\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
.tr \(*W-|\(bv\*(Tr
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` `
.    ds C' '
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
'br\}
.\"
.\" If the F register is turned on, we'll generate index entries on stderr
.\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
.\" index entries marked with X<> in POD.  Of course, you'll have to process
.\" the output yourself in some meaningful fashion.
.if \nF \{\
.    de IX
.    tm Index:\\$1\t\\n%\t"\\$2"
.    .
.    nr % 0
.    rr F
.\}
.\"
.\" For nroff, turn off justification.  Always turn off hyphenation; it
.\" makes way too many mistakes in technical documents.
.hy 0
.if n .na
.\"
.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
.\" Fear.  Run.  Save yourself.  No user-serviceable parts.
.bd B 3
.    \" fudge factors for nroff and troff
.if n \{\
.    ds #H 0
.    ds #V .8m
.    ds #F .3m
.    ds #[ \f1
.    ds #] \fP
.\}
.if t \{\
.    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
.    ds #V .6m
.    ds #F 0
.    ds #[ \&
.    ds #] \&
.\}
.    \" simple accents for nroff and troff
.if n \{\
.    ds ' \&
.    ds ` \&
.    ds ^ \&
.    ds , \&
.    ds ~ ~
.    ds /
.\}
.if t \{\
.    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
.    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
.    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
.    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
.    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
.    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
.\}
.    \" troff and (daisy-wheel) nroff accents
.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
.ds ae a\h'-(\w'a'u*4/10)'e
.ds Ae A\h'-(\w'A'u*4/10)'E
.    \" corrections for vroff
.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
.    \" for low resolution devices (crt and lpr)
.if \n(.H>23 .if \n(.V>19 \
\{\
.    ds : e
.    ds 8 ss
.    ds o a
.    ds d- d\h'-1'\(ga
.    ds D- D\h'-1'\(hy
.    ds th \o'bp'
.    ds Th \o'LP'
.    ds ae ae
.    ds Ae AE
.\}
.rm #[ #] #H #V #F C
.\" ======================================================================
.\"
.IX Title "FITSIO_STACK 1"
.TH FITSIO_STACK 1 "June 2004" "0.3" "CASU"
.UC
.SH "NAME"
fitsio_stack \- \s-1WCS\s0 or pixel based stacking of \s-1FITS\s0 images with optional 
rejection
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBfitsio_stack\fR \fIinputfiles\fR \fBwcs\fR=\fIy|n\fR \fBclip\fR=\fIy|n\fR \fIoutputfile\fR 
[\fI\fIconfmap\fI\|(s)in\fR] [\fIconfmapout\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBfitsio_stack\fR performs a \s-1WCS\s0 or pixel-based stack of a given set of
input \s-1FITS\s0 images, writing the output to \fIoutputfile\fR.  Confidence
maps (essentially an inverse variance weight map modulo bad pixel mask) 
may optionally be used in stacking, specified by \fIconfmapin\fR, and
the stacked output confidence map is written to \fIconfmapout\fR if specified.
The original version assumed all the files for stacking were tagged with 
the same confidence map.  This version allows general use of confidence 
maps or the single option.
.PP
The input \s-1FITS\s0 images \fIinputfiles\fR [\fI\fIconfmap\fI\|(s)in\fR] can be listed 
as a comma-separated
list on the command-line, or if this parameter begins with an @
character, the file named is read as an \s-1ASCII\s0 list of input files, one
per line (see \s-1EXAMPLES\s0, below).
.PP
The first \s-1FITS\s0 image in the list is used as a reference.  In WCS-based
stacking the other input images are resampled into the \s-1WCS\s0 of the first
image, whereas for a pixel stack no resampling is performed.  The (clipped)
average of the pixel values from all of the files, scaled by their exposure
times (given by the \s-1EXPTIME\s0 or \s-1EXPOSED\s0 \s-1FITS\s0 headers) and weighted by
the confidence value from \fIconfmapin\fR, and the average relative inverse 
variance noise properties of each image is computed and recorded in
the output map.  The output condidence map contains the sum of the
confidence values at each pixel, renormalised to a median value of
100.
.PP
Single or multi-extension \s-1FITS\s0 images may be processed.  All \s-1FITS\s0
images and confidence maps must have the same number of extensions.
In the case of a multi-extension input, each extension is stacked
separately, writing out the result to the corresponding extensions in
the output image and confidence map (if used).
.PP
During the stacking process all input image extensions for the
extension being processed are stored in \s-1RAM\s0.  The F77 version has an in 
built limit of at most 6 files in the stack.  In the \*(L"C\*(R" version,
for large input images, the stacking process is split into \*(L"chunks\*(R", 
loading only a subset of
the input images to save memory.  This is controlled by a threshold
parameter \s-1INMAXMEM\s0 in \fIfitsio_stack.c\fR, which specifies a \*(L"target\*(R"
memory usage.  The default value of 200MB is appropriate for a
computer with 512MB \s-1RAM\s0, and should be changed proportionately on
other systems.  
.SH "OPTIONS"
.IX Header "OPTIONS"
The following options are supported.  Note that they must be given in
the same order as listed in \s-1SYNOPSIS\s0, above.
.Ip "\fBwcs\fR=\fIy|n\fR" 4
.IX Item "wcs=y|n"
Stacking based on the world coordinate system (\s-1WCS\s0) found in the input
\&\s-1FITS\s0 files is performed if this parameter is wcs=y, otherwise a
straight pixel stack is performed.  Only the \s-1ZPN\s0 and \s-1TAN\s0 projection types 
are currently supported in the input \s-1WCS\s0.  Interpolation is currently based 
on a nearest neighbour pixel scheme.
.Ip "\fBclip\fR=\fIy|n\fR" 4
.IX Item "clip=y|n"
For clip=y, a baseline 3\-sigma upper and lower clip is performed on the 
stacked pixels.
Using clip=n disables this.  A robust MAD-based sky noise estimator defines
the clip base level.  This is modulated by a signal Poisson noise component
with a simple allowance for pixellation effects.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Stack \s-1FITS\s0 images \fI1.fit\fR, \fI2.fit\fR, \fI3.fit\fR, writing the result
to \fIoutput.fit\fR.  No confidence maps are used, and the default \s-1WCS\s0
based stacking, with clipping enabled, is used.
.PP
.Vb 1
\&  fitsio_stack 1.fit,2.fit,3.fit wcs=y clip=y output.fit
.Ve
Stack the files listed in \fIlist\fR, writing the result to
\&\fIoutput.fit\fR.  The confidence map \fIconf.fit\fR is used, writing the
stacked confidence map to \fIconfo.fit\fR.
.PP
.Vb 1
\&  fitsio_stack @list wcs=y clip=y output.fit conf.fit confo.fit
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Mike Irwin (mike@ast.cam.ac.uk), Jonathan Irwin (jmi@ast.cam.ac.uk)