=head1 NAME fitsio_colour - WCS or pixel based multi-colour stacking of FITS images =head1 SYNOPSIS B [B=I] [B=I] [B=I] I [...] I I: B=I [B=I] B=I [B=I] =head1 DESCRIPTION B performs a WCS or pixel-based combination of a given set of input FITS images, to produce an image for each of the three colour channels (red I, green I, blue I). The result is then written to a file in PNG format specified by F. A confidence map may optionally be used for each input image. For each input FITS image, the parameters B and B must be specified. I gives the filename of the FITS image, and I give the red, green and blue weights for this file respectively. These values are normalised to a total of 1.0 across all the files to give the relative fractions of each channel to take from the input images. The optional use of confidence maps is enabled by specifying one for each input image as I. The z-scaling may also be controlled on an individual basis for each input image by using the B parameter, described in OPTIONS, below. The first FITS image listed 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 mean 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 in each case (if used), is then taken, z-scaled into the range of 256 values used by the PNG files, and recorded in the fractions given by the normalised values of I, I, I to the output map channels. 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 the results out to separate PNG files. The naming of these is determined by F: for single-extension images the output will be F with an extension F<.png> appended, and for multi-extension images the output for extension I will have F<_n.png> appended. During the combining process all input image extensions for the extension being processed are stored in RAM. 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, 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=I 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 projection type is currently supported in the input WCS. =item B=I For scale=lin (the default), the z-scaling is performed linearly. This is most suitable for processing photographic images (for example scans of Schmidt plates) which have a non-linear response. For scale=log, the pixel values are scaled logarithmically to increase the range of intensities seen in the output image. The scale=hyp option applies a "hyperbolic" scaling of the form C for pixel values C similar to the "digital development" algorithm of Maxim/DL except without any spatial filtering. This is most suitable for images of objects such as galaxies and globular clusters (although for the latter the author is currently investigating other scaling techniques to find something more effective) taken on CCDs. =item B=I The parameters I and I give the minimum and maximum numbers of sigma above the sky level which will appear in the output image. This value can be specified globally, or individually for any number of the input FITS images. The default values are I<-2,10> for linear scaling, and I<-2,20> for logarithmic scaling. In general the values will need to be modified for the individual images to account for differences in the detector sensitivity in the different passbands used. =back =head1 EXAMPLES Process FITS images F, F, writing the result to filenames starting with F. The red and blue channels are taken entirely from F and F respectively, whereas the green channel is an equal mixture of the two files. The default linear scaling and z-scaling parameters are used. fitsio_colour file=R.fit colour=1,0.5,0 file=B.fit colour=0,0.5,1 col The same, using logarithmic scaling and modified z-scale parameters both globally and for the file F fitsio_colour scale=log z=-2,60 file=R.fit colour=1,0.5,0 file=B.fit colour=0,0.5,1 z=-2,30 col =head1 AUTHOR Jonathan Irwin (jmi@ast.cam.ac.uk) =cut