.\" Automatically generated by Pod::Man version 1.02
.\" Sun Nov 28 13:22:50 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_MOSAIC 1"
.TH FITSIO_MOSAIC 1 "October 2004" "0.5" "CASU"
.UC
.SH "NAME"
fitsio_mosaic \- mosaic \s-1FITS\s0 images
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBfitsio_mosaic\fR \fIinputfiles\fR \fIoutputfile\fR \fBscrunch\fR=\fIsv\fR
[\fBconfin\fR=\fIconfmapfiles\fR] [\fBconfout\fR=\fIconfmapout\fR]
[\fBradec\fR=\fIhh mm ss dd mm ss\fR] [\fBproj\fR=\fITAN|ZPN\fR]
[\fBfiddle\fR=\fIf1,f2....\fR] [\fBconflim\fR=\fIlimit\fR] [\fBoutsize\fR=\fIsize\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBfitsio_mosaic\fR mosaics the given set of input \s-1FITS\s0 images to form a 
single image, writing the output to \fIoutputfile\fR.  A set of
confidence maps, \fIconfmapfiles\fR may optionally be used, and the
mosaiced confidence map written to a file \fIconfmapout\fR.
.PP
The input \s-1FITS\s0 images \fIinputfiles\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).  Similarly, the list of input
confidence maps \fIconfmapfiles\fR is specified in the same manner, one
for each corresponding image file.  If only a single confidence map
is specified this is used for all the input images.
.PP
The first \s-1FITS\s0 image listed is used as a reference to generate the
world coordinate system (\s-1WCS\s0) of the output map using its tangent points
to define the location of the centre of the mosaic image (this centre
can be overriden using the \fIradec\fR option). The pixels 
from each extension in the set of input files are then \*(L"dropped\*(R" into the
output \s-1WCS\s0 pixels, scaling them by the relative exposure times and weighting
by the confidence values (if confidence maps are used).  Multiple pixels
from different input maps falling at the same location in the output map are
\&\*(L"averaged\*(R".  Regions of the (rectangular) output map with no pixel data
coverage (or pixels with zero overall confidence) are filled with the 
\&\*(L"average\*(R" sky level calculated over all the input maps.  The output 
confidence map contains the sum of the confidence values at each pixel in 
the output map, renormalised to a median of 100.
.PP
Single or multi-extension input \s-1FITS\s0 images may be processed.
Currently all input images must have the same number of extensions.
The output is always written as a single-extension \s-1FITS\s0 file, with the
mosaic image in the primary array.  For large output maps use the C-version
since the F77\-version has an in built maximum output file limit of 8kx8k
pixels and a maximum no. of input files to mosaic together of 12.
.SH "OPTIONS"
.IX Header "OPTIONS"
The following options are supported:
.Ip "\fBscrunch\fR=\fIsv\fR" 4
.IX Item "scrunch=sv"
Performs an optional rebinning (scrunching) by an integer factor of \fIsv\fR 
of the pixels in the image.  This has the effect of scaling the output image 
down by the factor \fIsv\fR, by effectively averaging the pixels in an
\&\fIsv\fRx\fIsv\fR square into a single pixel in the output map.  This option
must be specified: scrunch=1 disables any rebinning and must be given 
immediately after the output filename.
.Ip "\fBconfin\fR=\fIconfmapfiles\fR" 4
.IX Item "confin=confmapfiles"
Uses the confidence maps from \fIconfmapfiles\fR in the mosaicing process.  
If this option is used confidence maps must either be provided for each 
input image, or a single confidence map for all images.
.Ip "\fBconfout\fR=\fIconfmapout\fR" 4
.IX Item "confout=confmapout"
Writes the output confidence map to file \fIconfmapout\fR.  This option
may only be used when \fBconfin\fR has also been specified to provide a
set of input confidence maps.
.Ip "\fBradec\fR=\fIhh mm ss dd mm ss\fR" 4
.IX Item "radec=hh mm ss dd mm ss"
Allows the tangent point of the output \s-1WCS\s0 to be specified rather than
the default of taking it from the first input image.  This parameter
must be in sexagesimal format, with the \s-1RA\s0 first in units of hours and
the Dec in degrees, with each component separated by a space character.
.Ip "\fBproj\fR=\fITAN|ZPN\fR" 4
.IX Item "proj=TAN|ZPN"
Allows the projection used in the output \s-1WCS\s0 to be changed.  The
default is proj=TAN, producing a gnomonic projection.  Specifying
proj=ZPN causes a \s-1ZPN\s0 projection to be used, with the radial
distortion coefficients taken from the first input image.  The \s-1ZPN\s0
option generally produces less warping of the input frames but more
warping of the sky.
.Sp
Further optional `hidden' switches allowing the use of the following 
extra functionalilty:
.Ip "\fBfiddle=\fR" 4
.IX Item "fiddle="
When more than one file is being mosaiced the software computes an 
adjustment between the average sky levels for each input frame (ie.
between the averages for all the image extensions) to attempt a smooth 
join between different files.  On regions of rapidly varying background 
this may not be good enough and a comma-separated list of extra offsets to be 
applied to those computed internally may be specified.   [Note that this 
is in addition to the automatic extension-level adjustment that fitsio_mosaic
makes to the individual image extensions using the \fI\s-1PERCORR\s0\fR keywords
in the \s-1FITS\s0 headers.]
.Ip "\fBconflim=\fR" 4
.IX Item "conflim="
Allows the default 10% minimum confidence level to be overridden for an
input image to contribute to the final mosaiced map.  Can be used to
slice out badly vignetted bits of data.
.Ip "\fBoutsize=\fR" 4
.IX Item "outsize="
Allows the default maximum output map size to be altered.  Maps are (auto)
centred by default but this can be overriden using the \fBradec=\fR option
described previously.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Mosaic \s-1FITS\s0 images \fI1.fit\fR, \fI2.fit\fR, \fI3.fit\fR, writing the result to
\&\fIout.fit\fR.  No confidence maps are used, and the output image is
rebinned by a factor of 3 (which would give 1 arcsec pixels for \s-1INT\s0
wide field camera images).
.PP
.Vb 1
\&  fitsio_mosaic 1.fit,2.fit,3.fit out.fit scrunch=3
.Ve
Mosaic the files listed in \fIlist\fR, using confidence maps from
\&\fIclist\fR, writing the output image to \fIout.fit\fR and confidence map to
\&\fIconfo.fit\fR.  No rebinning is performed.  
.PP
.Vb 1
\&  fitsio_mosaic @list out.fit scrunch=1 confin=@clist confout=confo.fit
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Mike Irwin (mike@ast.cam.ac.uk), Jonathan Irwin (jmi@ast.cam.ac.uk)