=head1 NAME

fitsio_stack - WCS or pixel based stacking of FITS images with optional 
rejection

=head1 SYNOPSIS

B<fitsio_stack> I<inputfiles> B<wcs>=I<y|n> B<clip>=I<y|n> I<outputfile> 
[I<confmap(s)in>] [I<confmapout>]

=head1 DESCRIPTION

B<fitsio_stack> performs a WCS or pixel-based stack of a given set of
input FITS images, writing the output to F<outputfile>.  Confidence
maps (essentially an inverse variance weight map modulo bad pixel mask) 
may optionally be used in stacking, specified by F<confmapin>, and
the stacked output confidence map is written to F<confmapout> 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.

The input FITS images I<inputfiles> [I<confmap(s)in>] 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 ASCII list of input files, one
per line (see EXAMPLES, below).

The first FITS image in the list is used as a reference.  In WCS-based
stacking the other input images are resampled into the WCS 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 EXPTIME or EXPOSED FITS headers) and weighted by
the confidence value from I<confmapin>, 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.

Single or multi-extension FITS images may be processed.  All FITS
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).

During the stacking process all input image extensions for the
extension being processed are stored in RAM.  The F77 version has an in 
built limit of at most 6 files in the stack.  In the "C" version,
for large input images, the stacking process is split into "chunks", 
loading only a subset of
the input images to save memory.  This is controlled by a threshold
parameter INMAXMEM in F<fitsio_stack.c>, which specifies a "target"
memory usage.  The default value of 200MB is appropriate for a
computer with 512MB RAM, and should be changed proportionately on
other systems.  


=head1 OPTIONS

The following options are supported.  Note that they must be given in
the same order as listed in SYNOPSIS, above.

=over

=item B<wcs>=I<y|n>

Stacking based on the world coordinate system (WCS) found in the input
FITS files is performed if this parameter is wcs=y, otherwise a
straight pixel stack is performed.  Only the ZPN and TAN projection types 
are currently supported in the input WCS.  Interpolation is currently based 
on a nearest neighbour pixel scheme.

=item B<clip>=I<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.


=back

=head1 EXAMPLES

Stack FITS images F<1.fit>, F<2.fit>, F<3.fit>, writing the result
to F<output.fit>.  No confidence maps are used, and the default WCS
based stacking, with clipping enabled, is used.

  fitsio_stack 1.fit,2.fit,3.fit wcs=y clip=y output.fit

Stack the files listed in F<list>, writing the result to
F<output.fit>.  The confidence map F<conf.fit> is used, writing the
stacked confidence map to F<confo.fit>.

  fitsio_stack @list wcs=y clip=y output.fit conf.fit confo.fit

=head1 AUTHOR

Mike Irwin (mike@ast.cam.ac.uk), Jonathan Irwin (jmi@ast.cam.ac.uk)

=cut