.\" Automatically generated by Pod::Man version 1.02
.\" Mon Oct  6 10:39:02 2003
.\"
.\" 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_COLOUR 1"
.TH FITSIO_COLOUR 1 "September 2003" "0.2" "CASU"
.UC
.SH "NAME"
fitsio_colour \- \s-1WCS\s0 or pixel based multi-colour stacking of \s-1FITS\s0 images
.SH "SYNOPSIS"
.IX Header "SYNOPSIS"
\&\fBfitsio_colour\fR [\fBwcs\fR=\fIy|n\fR] [\fBscale\fR=\fIlin|log|hyp\fR]
[\fBz\fR=\fIzlow,zhigh\fR] \fIinfile\fR [...] \fIoutputbase\fR
.PP
\&\fIinfiles\fR: \fBfile\fR=\fIinfilename\fR [\fBconf\fR=\fIconfname\fR]
\&\fBcolour\fR=\fIr,g,b\fR [\fBz\fR=\fIzlow,zhigh\fR]
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
\&\fBfitsio_colour\fR performs a \s-1WCS\s0 or pixel-based combination of a given 
set of input \s-1FITS\s0 images, to produce an image for each of the three
colour channels (red \fIr\fR, green \fIg\fR, blue \fIb\fR).  The result is then
written to a file in \s-1PNG\s0 format specified by \fIoutputbase\fR.  A
confidence map may optionally be used for each input image.
.PP
For each input \s-1FITS\s0 image, the parameters \fBfile\fR and \fBcolour\fR must
be specified.  \fIinfilename\fR gives the filename of the \s-1FITS\s0 image, and
\&\fIr,g,b\fR 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 \fIconfname\fR.  The z-scaling
may also be controlled on an individual basis for each input image by
using the \fBz\fR parameter, described in \s-1OPTIONS\s0, below.
.PP
The first \s-1FITS\s0 image listed 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 mean
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 \fIconfname\fR in each case (if used), is then
taken, z-scaled into the range of 256 values used by the \s-1PNG\s0 files,
and recorded in the fractions given by the normalised values of 
\&\fIr\fR, \fIg\fR, \fIb\fR to the output map channels.
.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 the results out to separate \s-1PNG\s0 files.  The
naming of these is determined by \fIoutputbase\fR: for single-extension
images the output will be \fIoutputbase\fR with an extension \fI.png\fR
appended, and for multi-extension images the output for extension \fIn\fR
will have \fI_n.png\fR appended.
.PP
During the combining process all input image extensions for the
extension being processed are stored in \s-1RAM\s0.  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_colour.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 projection type is
currently supported in the input \s-1WCS\s0.
.Ip "\fBscale\fR=\fIlin|log|hyp\fR" 4
.IX Item "scale=lin|log|hyp"
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 \*(L"hyperbolic\*(R" scaling of the form \f(CW\*(C`x / (x+a)\*(C'\fR for
pixel values \f(CW\*(C`x\*(C'\fR similar to the \*(L"digital development\*(R" 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.
.Ip "\fBz\fR=\fIzlow,zhigh\fR" 4
.IX Item "z=zlow,zhigh"
The parameters \fIzlow\fR and \fIzhigh\fR 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 \s-1FITS\s0 images.  The default values are \fI\-2,10\fR for
linear scaling, and \fI\-2,20\fR 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.
.SH "EXAMPLES"
.IX Header "EXAMPLES"
Process \s-1FITS\s0 images \fIR.fit\fR, \fIB.fit\fR, writing the result to filenames
starting with \fIcol\fR.  The red and blue channels are taken entirely
from \fIR.fit\fR and \fIB.fit\fR respectively, whereas the green channel is
an equal mixture of the two files.  The default linear scaling and
z-scaling parameters are used.
.PP
.Vb 1
\&  fitsio_colour file=R.fit colour=1,0.5,0 file=B.fit colour=0,0.5,1 col
.Ve
The same, using logarithmic scaling and modified z-scale parameters
both globally and for the file \fIB.fit\fR
.PP
.Vb 2
\&  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
.Ve
.SH "AUTHOR"
.IX Header "AUTHOR"
Jonathan Irwin (jmi@ast.cam.ac.uk)