=head1 NAME fitsio_mosaic - mosaic FITS images =head1 SYNOPSIS B I I B=I [B=I] [B=I] [B=I] [B=I] [B=I] [B=I] [B=I] =head1 DESCRIPTION B mosaics the given set of input FITS images to form a single image, writing the output to I. A set of confidence maps, I may optionally be used, and the mosaiced confidence map written to a file I. The input FITS images I 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). Similarly, the list of input confidence maps I 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. The first FITS image listed is used as a reference to generate the world coordinate system (WCS) 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 I option). The pixels from each extension in the set of input files are then "dropped" into the output WCS 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 "averaged". Regions of the (rectangular) output map with no pixel data coverage (or pixels with zero overall confidence) are filled with the "average" 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. Single or multi-extension input FITS images may be processed. Currently all input images must have the same number of extensions. The output is always written as a single-extension FITS 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. =head1 OPTIONS The following options are supported: =over =item B=I Performs an optional rebinning (scrunching) by an integer factor of I of the pixels in the image. This has the effect of scaling the output image down by the factor I, by effectively averaging the pixels in an IxI 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. =item B=I Uses the confidence maps from I 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. =item B=I Writes the output confidence map to file I. This option may only be used when B has also been specified to provide a set of input confidence maps. =item B=I Allows the tangent point of the output WCS to be specified rather than the default of taking it from the first input image. This parameter must be in sexagesimal format, with the RA first in units of hours and the Dec in degrees, with each component separated by a space character. =item B=I Allows the projection used in the output WCS to be changed. The default is proj=TAN, producing a gnomonic projection. Specifying proj=ZPN causes a ZPN projection to be used, with the radial distortion coefficients taken from the first input image. The ZPN option generally produces less warping of the input frames but more warping of the sky. Further optional `hidden' switches allowing the use of the following extra functionalilty: =item B 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 I keywords in the FITS headers.] =item B 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. =item B Allows the default maximum output map size to be altered. Maps are (auto) centred by default but this can be overriden using the B option described previously. =back =head1 EXAMPLES Mosaic FITS images F<1.fit>, F<2.fit>, F<3.fit>, writing the result to F. No confidence maps are used, and the output image is rebinned by a factor of 3 (which would give 1 arcsec pixels for INT wide field camera images). fitsio_mosaic 1.fit,2.fit,3.fit out.fit scrunch=3 Mosaic the files listed in F, using confidence maps from F, writing the output image to F and confidence map to F. No rebinning is performed. fitsio_mosaic @list out.fit scrunch=1 confin=@clist confout=confo.fit =head1 AUTHOR Mike Irwin (mike@ast.cam.ac.uk), Jonathan Irwin (jmi@ast.cam.ac.uk) =cut