From 40e5a5811c6ffce9b0974e93cdd927cbcf60c157 Mon Sep 17 00:00:00 2001
From: Joe Hunkeler <jhunkeler@gmail.com>
Date: Tue, 11 Aug 2015 16:51:37 -0400
Subject: Repatch (from linux) of OSX IRAF

---
 noao/imred/ccdred/doc/ccdproc.hlp | 825 ++++++++++++++++++++++++++++++++++++++
 1 file changed, 825 insertions(+)
 create mode 100644 noao/imred/ccdred/doc/ccdproc.hlp

(limited to 'noao/imred/ccdred/doc/ccdproc.hlp')

diff --git a/noao/imred/ccdred/doc/ccdproc.hlp b/noao/imred/ccdred/doc/ccdproc.hlp
new file mode 100644
index 00000000..26ec6d1d
--- /dev/null
+++ b/noao/imred/ccdred/doc/ccdproc.hlp
@@ -0,0 +1,825 @@
+.help ccdproc Dec93 noao.imred.ccdred
+.ih
+NAME
+ccdproc -- Process CCD images
+.ih
+USAGE	
+ccdproc images
+.ih
+PARAMETERS
+.ls images
+List of input CCD images to process.  The list may include processed
+images and calibration images.
+.le
+.ls output = ""
+List of output images.  If no list is given then the processing will replace
+the input images with the processed images.  If a list is given it must
+match the input image list.  \fINote that any dependent calibration images
+still be processed in-place with optional backup.\fR
+.le
+.ls ccdtype = ""
+CCD image type to select from the input image list.  If no type is given
+then all input images will be selected.  The recognized types are described
+in \fBccdtypes\fR.
+.le
+.ls max_cache = 0
+Maximum image caching memory (in Mbytes).  If there is sufficient memory
+the calibration images, such as zero level, dark count, and flat fields,
+will be cached in memory when processing many input images.  This
+reduces the disk I/O and makes the task run a little faster.  If the
+value is zero image caching is not used.
+.le
+.ls noproc = no
+List processing steps only?
+.le
+
+.ce
+PROCESSING SWITCHES
+.ls fixpix = yes
+Fix bad CCD lines and columns by linear interpolation from neighboring
+lines and columns?  If yes then a bad pixel mask, image, or file must be
+specified.
+.le
+.ls overscan = yes
+Apply overscan or prescan bias correction?  If yes then the overscan
+image section and the readout axis must be specified.
+.le
+.ls trim = yes
+Trim the image of the overscan region and bad edge lines and columns?
+If yes then the data section must be specified.
+.le
+.ls zerocor = yes
+Apply zero level correction?  If yes a zero level image must be specified.
+.le
+.ls darkcor = yes
+Apply dark count correction?  If yes a dark count image must be specified.
+.le
+.ls flatcor = yes
+Apply flat field correction?  If yes flat field images must be specified.
+.le
+.ls illumcor = no
+Apply iillumination correction?  If yes iillumination images must be specified.
+.le
+.ls fringecor = no
+Apply fringe correction?  If yes fringe images must be specified.
+.le
+.ls readcor = no
+Convert zero level images to readout correction images?  If yes then
+zero level images are averaged across the readout axis to form one
+dimensional zero level readout correction images.
+.le
+.ls scancor = no
+Convert zero level, dark count and flat field images to scan mode flat
+field images?  If yes then the form of scan mode correction is specified by
+the parameter \fIscantype\fR.
+.le
+
+.ce
+PROCESSING PARAMETERS
+.ls readaxis = "line"
+Read out axis specified as "line" or "column".
+.le
+.ls fixfile
+Bad pixel mask, image, or file.  If "image" is specified then the name is
+specified in the image header or instrument translation file.  If "BPM" is
+specified then the standard BPM image header keyword defines a bad pixel
+mask.  A bad pixel mask is a compact format (".pl" extension) with zero
+values indicating good pixels and non-zero values indicating bad pixels.  A
+bad pixel image is a regular image in which zero values are good pixels and
+non-zero values are bad pixels.  A bad pixel file specifies bad pixels or
+rectangular bad pixel regions as described later.  The direction of
+interpolation is determined by the mask value with a value of two
+interpolating across columns, a value of three interpolating across lines,
+and any other non-zero value interpolating along the narrowest dimension.
+.le
+.ls biassec
+Overscan bias strip image section.  If "image" is specified then the overscan
+bias section is specified in the image header or instrument translation file.
+Only the part of the bias section along the readout axis is used.  The
+length of the bias region fit is defined by the trim section.  If one
+wants to limit the region of the overscan used in the fit to be less
+than that of the trim section then the sample region parameter,
+\fIsample\fR, should be used.  It is an error if no section or the
+whole image is specified.
+.le
+.ls trimsec
+image section for trimming.  If "image" is specified then the trim
+image section is specified in the image header or instrument translation file.
+.le
+.ls zero = ""
+Zero level calibration image.  The zero level image may be one or two
+dimensional.  The CCD image type and subset are not checked for these
+images and they take precedence over any zero level calibration images
+given in the input list.
+.le
+.ls dark = ""
+Dark count calibration image.  The CCD image type and subset are not checked
+for these images and they take precedence over any dark count calibration
+images given in the input list.
+.le
+.ls flat = ""
+Flat field calibration images.  The flat field images may be one or
+two dimensional.  The CCD image type is not checked for these
+images and they take precedence over any flat field calibration images given
+in the input list.  The flat field image with the same subset as the
+input image being processed is selected.
+.le
+.ls illum = ""
+Iillumination correction images.  The CCD image type is not checked for these
+images and they take precedence over any iillumination correction images given
+in the input list.  The iillumination image with the same subset as the
+input image being processed is selected.
+.le
+.ls fringe = ""
+Fringe correction images.  The CCD image type is not checked for these
+images and they take precedence over any fringe correction images given
+in the input list.  The fringe image with the same subset as the
+input image being processed is selected.
+.le
+.ls minreplace = 1.
+When processing flat fields, pixel values below this value (after
+all other processing such as overscan, zero, and dark corrections) are
+replaced by this value.  This allows flat fields processed by \fBccdproc\fR
+to be certain to avoid divide by zero problems when applied to object
+images.
+.le
+.ls scantype = "shortscan"
+Type of scan format used in creating the CCD images.  The modes are:
+.ls "shortscan"
+The CCD is scanned over a number of lines and then read out as a regular
+two dimensional image.  In this mode unscanned zero level, dark count and
+flat fields are numerically scanned to form scanned flat fields comparable
+to the observations.
+.le
+.ls "longscan"
+In this mode the CCD is clocked and read out continuously to form a long
+strip.  Flat fields are averaged across the readout axis to
+form a one dimensional flat field readout correction image.  This assumes
+that all recorded image lines are clocked over the entire active area of the
+CCD.
+.le
+.le
+.ls nscan
+Number of object scan readout lines used in short scan mode.  This parameter
+is used when the scan type is "shortscan" and the number of scan lines
+cannot be determined from the object image header (using the keyword
+nscanrows or it's translation).
+.le
+
+
+.ce
+OVERSCAN FITTING PARAMETERS
+
+There are two types of overscan (or prescan) determinations.  One determines
+a independent overscan value for each line  and is only available for a
+\fIreadaxis\fR of 1.  The other averages the overscan along the readout
+direction to make an overscan vector, fits a smoothing function to the vector,
+and then evaluate and then evaluates the smooth function at each readout
+line or column.  The line-by-line determination only uses the
+\fIfunction\fR parameter and the smoothing determinations uses all
+the following parameters.
+
+.ls function = "legendre"
+Line-by-line determination of the overscan is specified by:
+
+.nf
+         mean - the mean of the biassec columns at each line
+       median - the median of the biassec columns at each line
+       minmax - the mean at each line with the min and max excluded
+.fi
+
+The smoothed overscan vector may be fit by one of the functions:
+
+.nf
+     legendre - legendre polynomial
+    chebyshev - chebyshev polynomial
+      spline1 - linear spline
+      spline3 - cubic spline
+.fi
+.le
+.ls order = 1
+Number of polynomial terms or spline pieces in the overscan fit.
+.le
+.ls sample = "*"
+Sample points to use in the overscan fit.  The string "*" specified all
+points otherwise an \fBicfit\fR range string is used.
+.le
+.ls naverage = 1
+Number of points to average or median to form fitting points.  Positive
+numbers specify averages and negative numbers specify medians.
+.le
+.ls niterate = 1
+Number of rejection iterations to remove deviant points from the overscan fit.
+If 0 then no points are rejected.
+.le
+.ls low_reject = 3., high_reject = 3.
+Low and high sigma rejection factors for rejecting deviant points from the
+overscan fit.
+.le
+.ls grow = 0.
+One dimensional growing radius for rejection of neighbors to deviant points.
+.le
+.ls interactive = no
+Fit the overscan vector interactively?  If yes and the overscan function type
+is one of the \fBicfit\fR types then the average overscan vector is fit
+interactively using the \fBicfit\fR package.  If no then the fitting parameters
+given below are used.
+.le
+.ih
+DESCRIPTION
+\fBCcdproc\fR processes CCD images to correct and calibrate for
+detector defects, readout bias, zero level bias, dark counts,
+response, iillumination, and fringing.  It also trims unwanted
+lines and columns and changes the pixel datatype.  It is efficient
+and easy to use; all one has to do is set the parameters and then
+begin processing the images.  The task takes care of most of the
+record keeping and automatically does the prerequisite processing
+of calibration images.  Beneath this simplicity there is much that
+is going on.  In this section a simple description of the usage is
+given.  The following sections present more detailed discussions
+on the different operations performed and the order and logic
+of the processing steps.  For a user's guide to the \fBccdred\fR
+package see \fBguide\fR.  Much of the ease of use derives from using
+information in the image header.  If this information is missing
+see section 13.
+
+One begins by setting the task parameters.  There are many parameters
+but they may be easily reviewed and modified using the task \fBeparam\fR.
+The input CCD images to be processed are given as an image list.
+Previously processed images are ignored and calibration images are
+recognized, provided the CCD image types are in the image header (see
+\fBinstruments\fR and \fBccdtypes\fR).  Therefore it is permissible to
+use simple image templates such as "*.imh".  The \fIccdtype\fR parameter
+may be used to select only certain types of CCD images to process
+(see \fBccdtypes\fR).
+
+The processing operations are selected by boolean (yes/no) parameters.
+Because calibration images are recognized and processed appropriately,
+the processing operations for object images should be set.
+Any combination of operations may be specified and the operations are
+performed simultaneously.  While it is possible to do operations in
+separate steps this is much less efficient.  Two of the operation
+parameters apply only to zero level and flat field images.  These
+are used for certain types of CCDs and modes of operation.
+
+The processing steps selected have related parameters which must be
+set.  These are things like image sections defining the overscan and
+trim regions and calibration images.  There are a number of parameters
+used for fitting the overscan or prescan bias section.  These are
+parameters used by the standard IRAF curve fitting package \fBicfit\fR.
+The parameters are described in more detail in the following sections.
+
+In addition to the task parameters there are package parameters
+which affect \fBccdproc\fR.  These include the instrument and subset
+files, the text and plot log files, the output pixel datatype,
+the amount of memory available for calibration image caching,
+the verbose parameter for logging to the terminal, and the backup
+prefix.  These are described in \fBccdred\fR.
+
+Calibration images are specified by task parameters and/or in the
+input image list.  If more than one calibration image is specified
+then the first one encountered is used and a warning is issued for the
+extra images.  Calibration images specified by
+task parameters take precedence over calibration images in the input list.
+These images also need not have a CCD image type parameter since the task
+parameter identifies the type of calibration image.  This method is
+best if there is only one calibration image for all images
+to be processed.  This is almost always true for zero level and dark
+count images.  If no calibration image is specified by task parameter
+then calibration images in the input image list are identified and
+used.  This requires that the images have CCD image types recognized
+by the package.  This method is useful if one may simply say "*.imh"
+as the image list to process all images or if the images are broken
+up into groups, in "@" files for example, each with their own calibration
+frames.
+
+When an input image is processed the task first determines the processing
+parameters and calibration images.  If a requested operation has been
+done it is skipped and if all requested operations have been completed then
+no processing takes place.  When it determines that a calibration image
+is required it checks for the image from the task parameter and then
+for a calibration image of the proper type in the input list.
+
+Having
+selected a calibration image it checks if it has been processed for
+all the operations selected by the CCDPROC parameters.
+After the calibration images have been identified, and processed if
+necessary, the images may be cached in memory.  This is done when there
+are more than two input images (it is actually less efficient to
+cache the calibration images for one or two input images) and the parameter
+\fImax_cache\fR is greater than zero.  When caching, as many calibration
+images as allowed by the specified memory are read into memory and
+kept there for all the input images.  Cached images are, therefore,
+only read once from disk which reduces the amount of disk I/O.  This
+makes a modest decrease in the execution time.  It is not dramatic
+because the actual processing is fairly CPU intensive.
+
+Once the processing parameters and calibration images have been determined
+the input image is processed for all the desired operations in one step;
+i.e. there are no intermediate results or images.  This makes the task
+efficient.  If a matching list of output images is given then the processed
+image is written to the specified output image name.  If no output image
+list is given then the corrected image is output as a temporary image until
+the entire image has been processed.  When the image has been completely
+processed then the original image is deleted (or renamed using the
+specified backup prefix) and the corrected image replaces the original
+image.  Using a temporary image protects the data in the event of an abort
+or computer failure.  Keeping the original image name eliminates much of
+the record keeping and the need to generate new image names.
+.sh
+1. Fixpix
+Regions of bad lines and columns may be replaced by linear
+interpolation from neighboring lines and columns when the parameter
+\fIfixpix\fR is set.  This algorithm is the same as used in the
+task \fBfixpix\fR.  The bad pixels may be specified by a pixel mask,
+an image, or a text file.  For the mask or image, values of zero indicate
+good pixels and other values indicate bad pixels to be replaced.
+
+The text file consists of lines with four fields, the starting and
+ending columns and the starting and ending lines.  Any number of
+regions may be specified.  Comment lines beginning with the character
+'#' may be included.  The description applies directly to the input
+image (before trimming) so different files are needed for previously
+trimmed or subsection readouts.  The data in this file is internally
+turned into the same description as a bad pixel mask with values of
+two for regions which are narrower or equal across the columns and
+a value of three for regions narrower across lines.
+
+The direction of interpolation is determined from the values in the
+mask, image, or the converted text file.  A value of two interpolates
+across columns, a value of three interpolates across lines, and any
+other value interpolates across the narrowest dimension of bad pixels
+and using column interpolation if the two dimensions are equal.
+
+The bad pixel description may be specified explicitly with the parameter
+\fIfixfile\fR or indirectly if the parameter has the value "image".  In the
+latter case the instrument file must contain the name of the file.
+.sh
+2. Overscan
+If an overscan or prescan correction is specified (\fIoverscan\fR
+parameter) then the image section (\fIbiassec\fR parameter) defines
+the overscan region.
+
+There are two types of overscan (or prescan) determinations.  One determines
+a independent overscan value for each line  and is only available for a
+\fIreadaxis\fR of 1.  The other averages the overscan along the readout
+direction to make an overscan vector, fits a smoothing function to the vector,
+and then evaluate and then evaluates the smooth function at each readout
+line or column.
+
+The line-by-line determination provides an mean, median, or
+mean with the minimum and maximum values excluded.  The median
+is lowest value of the middle two when the number of overscan columns
+is even rather than the mean.
+
+The smoothed overscan vector determination uses the \fBicfit\fR options
+including interactive fitting.  The fitting function is generally either a
+constant (polynomial of 1 term) or a high order function which fits the
+large scale shape of the overscan vector.  Bad pixel rejection is also
+available to eliminate cosmic ray events.  The function fitting may be done
+interactively using the standard \fBicfit\fR iteractive graphical curve
+fitting tool.  Regardless of whether the fit is done interactively, the
+overscan vector and the fit may be recorded for later review in a metacode
+plot file named by the parameter \fIccdred.plotfile\fR.  The mean value of
+the bias function is also recorded in the image header and log file.
+.sh
+3. Trim
+When the parameter \fItrim\fR is set the input image will be trimmed to
+the image section given by the parameter \fItrimsec\fR.  This trim
+should, of course, be the same as that used for the calibration images.
+.sh
+4. Zerocor
+After the readout bias is subtracted, as defined by the overscan or prescan
+region, there may still be a zero level bias.  This level may be two
+dimensional or one dimensional (the same for every readout line).  A
+zero level calibration is obtained by taking zero length exposures;
+generally many are taken and combined.  To apply this zero
+level calibration the parameter \fIzerocor\fR is set.  In addition if
+the zero level bias is only readout dependent then the parameter \fIreadcor\fR
+is set to reduce two dimensional zero level images to one dimensional
+images.  The zero level images may be specified by the parameter \fIzero\fR
+or given in the input image list (provided the CCD image type is defined).
+
+When the zero level image is needed to correct an input image it is checked
+to see if it has been processed and, if not, it is processed automatically.
+Processing of zero level images consists of bad pixel replacement,
+overscan correction, trimming, and averaging to one dimension if the
+readout correction is specified.
+.sh
+5. Darkcor
+Dark counts are subtracted by scaling a dark count calibration image to
+the same exposure time as the input image and subtracting.  The
+exposure time used is the dark time which may be different than the
+actual integration or exposure time.  A dark count calibration image is
+obtained by taking a very long exposure with the shutter closed; i.e.
+an exposure with no light reaching the detector.  The dark count
+correction is selected with the parameter \fIdarkcor\fR and the dark
+count calibration image is specified either with the parameter
+\fIdark\fR or as one of the input images.  The dark count image is
+automatically processed as needed.  Processing of dark count images
+consists of bad pixel replacement, overscan and zero level correction,
+and trimming.
+.sh
+6. Flatcor
+The relative detector pixel response is calibrated by dividing by a
+scaled flat field calibration image.  A flat field image is obtained by
+exposure to a spatially uniform source of light such as an lamp or
+twilight sky.  Flat field images may be corrected for the spectral
+signature in spectroscopic images (see \fBresponse\fR and
+\fBapnormalize\fR), or for iillumination effects (see \fBmkillumflat\fR
+or \fBmkskyflat\fR).  For more on flat fields and iillumination corrections
+see \fBflatfields\fR.  The flat field response is dependent on the
+wavelength of light so if different filters or spectroscopic wavelength
+coverage are used a flat field calibration for each one is required.
+The different flat fields are  automatically selected by a subset
+parameter (see \fBsubsets\fR).
+
+Flat field calibration is selected with the parameter \fBflatcor\fR
+and the flat field images are specified with the parameter \fBflat\fR
+or as part of the input image list.  The appropriate subset is automatically
+selected for each input image processed.  The flat field image is
+automatically processed as needed.  Processing consists of bad pixel
+replacement, overscan subtraction, zero level subtraction, dark count
+subtraction, and trimming.  Also if a scan mode is used and the
+parameter \fIscancor\fR is specified then a scan mode correction is
+applied (see below).  The processing also computes the mean of the
+flat field image which is used later to scale the flat field before
+division into the input image.  For scan mode flat fields the ramp
+part is included in computing the mean which will affect the level
+of images processed with this flat field.  Note that there is no check for
+division by zero in the interest of efficiency.  If division by zero
+does occur a fatal error will occur.  The flat field can be fixed by
+replacing small values using a task such as \fBimreplace\fR or
+during processing using the \fIminreplace\fR parameter.  Note that the
+\fIminreplace\fR parameter only applies to flat fields processed by
+\fBccdproc\fR.
+.sh
+7. Illumcor
+CCD images processed through the flat field calibration may not be
+completely flat (in the absence of objects).  In particular, a blank
+sky image may still show gradients.  This residual nonflatness is called
+the iillumination pattern.  It may be introduced even if the detector is
+uniformly illuminated by the sky because the flat field lamp
+iillumination may be nonuniform.  The iillumination pattern is found from a
+blank sky, or even object image, by heavily smoothing and rejecting
+objects using sigma clipping.  The iillumination calibration image is
+divided into the data being processed to remove the iillumination
+pattern.  The iillumination pattern is a function of the subset so there
+must be an iillumination correction image for each subset to be
+processed.  The tasks \fBmkillumcor\fR and \fBmkskycor\fR are used to
+create the iillumination correction images.  For more on iillumination
+corrections see \fBflatfields\fR.
+
+An alternative to treating the iillumination correction as a separate
+operation is to combine the flat field and iillumination correction
+into a corrected flat field image before processing the object
+images.  This will save some processing time but does require creating
+the flat field first rather than correcting the images at the same
+time or later.  There are two methods, removing the large scale
+shape of the flat field and combining a blank sky image iillumination
+with the flat field.  These methods are discussed further in the
+tasks which create them; \fBmkillumcor\fR and \fBmkskycor\fR.
+.sh
+8. Fringecor
+There may be a fringe pattern in the images due to the night sky lines.
+To remove this fringe pattern a blank sky image is heavily smoothed
+to produce an iillumination image which is then subtracted from the
+original sky image.  The residual fringe pattern is scaled to the
+exposure time of the image to be fringe corrected and then subtracted.
+Because the intensity of the night sky lines varies with time an
+additional scaling factor may be given in the image header.
+The fringe pattern is a function of the subset so there must be
+a fringe correction image for each subset to be processed.
+The task \fBmkfringecor\fR is used to create the fringe correction images.
+.sh
+9. Readcor
+If a zero level correction is desired (\fIzerocor\fR parameter)
+and the parameter \fIreadcor\fR is yes then a single zero level
+correction vector is applied to each readout line or column.  Use of a
+readout correction rather than a two dimensional zero level image
+depends on the nature of the detector or if the CCD is operated in
+longscan mode (see below).  The readout correction is specified by a
+one dimensional image (\fIzero\fR parameter) and the readout axis
+(\fIreadaxis\fR parameter).  If the zero level image is two dimensional
+then it is automatically processed to a one dimensional image by
+averaging across the readout axis.  Note that this modifies the zero
+level calibration image.
+.sh
+10. Scancor
+CCD detectors may be operated in several modes in astronomical
+applications.  The most common is as a direct imager where each pixel
+integrates one point in the sky or spectrum.  However, the design of most CCD's
+allows the sky to be scanned across the CCD while shifting the
+accumulating signal at the same rate.  \fBCcdproc\fR provides for two
+scanning modes called "shortscan" and "longscan".  The type of scan
+mode is set with the parameter \fIscanmode\fR.
+
+In "shortscan" mode the detector is scanned over a specified number of
+lines (not necessarily at sideral rates).  The lines that scroll off the
+detector during the integration are thrown away.  At the end of the
+integration the detector is read out in the same way as an unscanned
+observation.  The advantage of this mode is that the small scale, zero
+level, dark count and flat field responses are averaged in one dimension
+over the number of lines scanned.  A zero level, dark count or flat field may be
+observed in the same way in which case there is no difference in the
+processing from unscanned imaging and the parameter \fIscancor\fR may be
+no.  If it is yes, though, checking is done to insure that the calibration
+image used has the same number of scan lines as the object being
+processed.  However, one obtains an increase in the statistical accuracy of
+if they are not scanned during the observation but
+digitally scanned during the processing.  In shortscan mode with
+\fIscancor\fR set to yes, zero level, dark count and flat field images are
+digitally scanned, if needed, by the same number of scan lines as the
+object.  The number of scan lines is determined from the object image
+header using the keyword nscanrow (or it's translation).  If not found the
+object is assumed to have been scanned with the value given by the
+\fInscan\fR parameter.  Zero, dark and flat calibration images are assumed
+to be unscanned if the header keyword is not found.
+
+If a scanned zero level, dark count or flat field image is not found
+matching the object then one may be created from the unscanned calibration
+image.  The image will have the root name of the unscanned image with an
+extension of the number of scan rows; i.e. Flat1.32 is created from Flat1
+with a digital scanning of 32 lines.
+
+In "longscan" mode the detector is continuously read out to produce an
+arbitrarily long strip.  Provided data which has not passed over the entire
+detector is thrown away, the zero level, dark count, and flat field
+corrections will be one dimensional.  If \fIscancor\fR is specified and the
+scan mode is "longscan" then a one dimensional zero level, dark count, and
+flat field correction will be applied.
+.sh
+11. Processing Steps
+The following describes the steps taken by the task.  This detailed
+outline provides the most detailed specification of the task.
+
+.ls 5 (1)
+An image to be processed is first checked that it is of the specified
+CCD image type.  If it is not the desired type then go on to the next image.
+.le
+.ls (2)
+A temporary output image is created of the specified pixel data type
+(\fBccdred.pixeltype\fR).  The header parameters are copied from the
+input image.
+.le
+.ls (3)
+If trimming is specified and the image has not been trimmed previously,
+the trim section is determined.
+.le
+.ls (4)
+If bad pixel replacement is specified and this has not been done
+previously, the bad pixel file is determined either from the task
+parameter or the instrument translation file.  The bad pixel regions
+are read.  If the image has been trimmed previously and the bad pixel
+file contains the word "untrimmed" then the bad pixel coordinates are
+translated to those of the trimmed image.
+.le
+.ls (5)
+If an overscan correction is specified and this correction has not been
+applied, the overscan section is averaged along the readout axis.  If
+trimming is to be done the overscan section is trimmed to the same
+limits.  A function is fit either interactively or noninteractively to
+the overscan vector.  The function is used to produce the overscan
+vector to be subtracted from the image.  This is done in real
+arithmetic.
+.le
+.ls (6)
+If the image is a zero level image go to processing step 12.
+If a zero level correction is desired and this correction has not been
+performed, find the zero level calibration image.  If the zero level
+calibration image has not been processed it is processed at this point.
+This is done by going to processing step 1 for this image.  After the
+calibration image has been processed, processing of the input image
+continues from this point.
+The processed calibration image may be
+cached in memory if it has not been previously and if there is enough memory.
+.le
+.ls (7)
+If the image is a dark count image go to processing step 12.
+If a dark count correction is desired and this correction has not been
+performed, find the dark count calibration image.  If the dark count
+calibration image has not been processed it is processed at this point.
+This is done by going to processing step 1 for this image.  After the
+calibration image has been processed, processing of the input image
+continues from this point.  The ratio of the input image dark time
+to the dark count image dark time is determined to be multiplied with
+each pixel of the dark count image before subtracting from the input
+image.
+The processed calibration image may be
+cached in memory if it has not been previously and if there is enough memory.
+.le
+.ls (8)
+If the image is a flat field image go to processing step 12.  If a flat
+field correction is desired and this correction has not been performed,
+find the flat field calibration image of the appropriate subset.  If
+the flat field calibration image has not been processed it is processed
+at this point.  This is done by going to processing step 1 for this
+image.  After the calibration image has been processed, processing of
+the input image continues from this point.  The mean of the image
+is determined from the image header to be used for scaling.  If no
+mean is found then a unit scaling is used.
+The processed calibration image may be
+cached in memory if it has not been previously and if there is enough memory.
+.le
+.ls (9)
+If the image is an iillumination image go to processing step 12.  If an
+iillumination correction is desired and this correction has not been performed,
+find the iillumination calibration image of the appropriate subset.
+The iillumination image must have the "mkillum" processing flag or the
+\fBccdproc\fR will abort with an error.  The mean of the image
+is determined from the image header to be used for scaling.  If no
+mean is found then a unit scaling is used.  The processed calibration
+image may be
+cached in memory if it has not been previously and there is enough memory.
+.le
+.ls (10)
+If the image is a fringe image go to processing step 12.  If a fringe
+correction is desired and this correction has not been performed,
+find the fringe calibration image of the appropriate subset.
+The iillumination image must have the "mkfringe" processing flag or the
+\fBccdproc\fR will abort with an error.  The ratio of the input
+image exposure time to the fringe image exposure time is determined.
+If there is a fringe scaling in the image header then this factor
+is multiplied by the exposure time ratio.  This factor is used
+for scaling.  The processed calibration image may be
+cached in memory if it has not been previously and there is enough memory.
+.le
+.ls (11)
+If there are no processing operations flagged, delete the temporary output
+image, which has been opened but not used, and go to 14.
+.le
+.ls (12)
+The input image is processed line by line with trimmed lines ignored.
+A line of the input image is read.  Bad pixel replacement and trimming
+is applied to the image.  Image lines from the calibration images
+are read from disk or the image cache.  If the calibration is one
+dimensional (such as a readout zero
+level correction or a longscan flat field correction) then the image
+vector is read only once.  Note that IRAF image I/O is buffered for
+efficiency and accessing a line at a time does not mean that image
+lines are read from disk a line at a time.  Given the input line, the
+calibration images, the overscan vector, and the various scale factors
+a special data path for each combination of corrections is used to
+perform all the processing in the most efficient manner.  If the
+image is a flat field any pixels less than the \fIminreplace\fR
+parameter are replaced by that minimum value.  Also a mean is
+computed for the flat field and stored as the CCDMEAN keyword and
+the time, in a internal format, when this value was calculated is stored
+in the CCDMEANT keyword.  The time is checked against the image modify
+time to determine if the value is valid or needs to be recomputed.
+.le
+.ls (13)
+The input image is deleted or renamed to a backup image.  The temporary
+output image is renamed to the input image name.
+.le
+.ls (14)
+If the image is a zero level image and the readout correction is specified
+then it is averaged to a one dimensional readout correction.
+.le
+.ls (15)
+If the image is a zero level, dark count, or flat field image and the scan
+mode correction is specified then the correction is applied.  For shortscan
+mode a modified two dimensional image is produced while for longscan mode a
+one dimensional average image is produced.
+.le
+.ls (16)
+The processing is completed and either the next input image is processed
+beginning at step 1 or, if it is a calibration image which is being
+processed for an input image, control returns to the step which initiated
+the calibration image processing.
+.le
+.sh
+12. Processing Arithmetic
+The \fBccdproc\fR task has two data paths, one for real image pixel datatypes
+and one for short integer pixel datatype.  In addition internal arithmetic
+is based on the rules of FORTRAN.  For efficiency there is
+no checking for division by zero in the flat field calibration.
+The following rules describe the processing arithmetic and data paths.
+
+.ls (1)
+If the input, output, or any calibration image is of type real the
+real data path is used.  This means all image data is converted to
+real on input.  If all the images are of type short all input data
+is kept as short integers.  Thus, if all the images are of the same type
+there is no datatype conversion on input resulting in greater
+image I/O efficiency.
+.le
+.ls (2)
+In the real data path the processing arithmetic is always real and,
+if the output image is of short pixel datatype, the result
+is truncated.
+.le
+.ls (3)
+The overscan vector and the scale factors for dark count, flat field,
+iillumination, and fringe calibrations are always of type real.  Therefore,
+in the short data path any processing which includes these operations
+will be coerced to real arithmetic and the result truncated at the end
+of the computation.
+.le
+.sh
+13. In the Absence of Image Header Information
+The tasks in the \fBccdred\fR package are most convenient to use when
+the CCD image type, subset, and exposure time are contained in the
+image header.  The ability to redefine which header parameters contain
+this information makes it possible to use the package at many different
+observatories (see \fBinstruments\fR).  However, in the absence of any
+image header information the tasks may still be used effectively.
+There are two ways to proceed.  One way is to use \fBccdhedit\fR
+to place the information in the image header.
+
+The second way is to specify the processing operations more explicitly
+than is needed when the header information is present.  The parameter
+\fIccdtype\fR is set to "" or to "none".  The calibration images are
+specified explicitly by task parameter since they cannot be recognized
+in the input list.  Only one subset at a time may be processed.
+
+If dark count and fringe corrections are to be applied the exposure
+times must be added to all the images.  Alternatively, the dark count
+and fringe images may be scaled explicitly for each input image.  This
+works because the exposure times default to 1 if they are not given in
+the image header.
+.ih
+EXAMPLES
+The user's \fBguide\fR presents a tutorial in the use of this task.
+
+1. In general all that needs to be done is to set the task parameters
+and enter
+
+	cl> ccdproc *.imh &
+
+This will run in the background and process all images which have not
+been processed previously.
+.ih
+TIME REQUIREMENTS
+.nf
+o SUN-3, 15 MHz 68020 with 68881 floating point hardware (no FPA)
+o 8 Mb RAM, 2 Fuji Eagle disks.
+o Input images = 544 x 512 short
+o Output image = 500 x 500 real
+o Operations are overscan subtraction (O), trimming to 500x500 (T),
+  zero level subtraction (Z), dark count scaling and subtraction (D),
+  and flat field scaling and subtraction (F).
+o UNIX statistics
+  (user, system, and clock time, and misc. memory and i/o statistics):
+
+[OTF] One calibration image and 9 object images:
+No caching:  110.6u 25.5s 3:18 68% 28+ 40K 3093+1645io   9pf+0w
+Caching:     111.2u 23.0s 2:59 74% 28+105K 2043+1618io   9pf+0w
+
+[OTZF] Two calibration images and 9 object images:
+No caching:  119.2u 29.0s 3:45 65% 28+ 50K 4310+1660io   9pf+0w
+Caching:     119.3u 23.0s 3:07 75% 28+124K 2179+1601io   9pf+0w
+
+[OTZDF] Three calibration images and 9 object images:
+No caching:  149.4u 31.6s 4:41 64% 28+ 59K 5501+1680io  19pf+0w
+Caching:     151.5u 29.0s 4:14 70% 27+227K 2346+1637io 148pf+0w
+
+[OTZF] 2 calibration images and 20 images processed:
+No caching:  272.7u 63.8u 8:47 63% 28+ 50K 9598+3713io  12pf+0w
+Caching:     271.2u 50.9s 7:00 76% 28+173K 4487+3613io  51pf+0w
+.fi
+.ih
+REVISIONS
+.ls CCDPROC V2.11.2
+A new "output" parameter is available to specify an output image leaving
+the input image unchanged.  If this parameter is not specified then
+the previous behavior of "in-place" operation with an optional backup
+occurs.
+.le
+.ls CCDPROC V2.11
+The bad pixel fixing was modified to allow use of pixel masks,
+images, or the text file description.  Bad pixel masks are the
+desired description and use of text files is only supported for
+backward compatibility.  Note that support for the trimmed
+or untrimmed conversion from text files has been eliminated.
+
+Line-by-line overscan/prescan subtraction is now provided with
+three simple algorithms.
+.le
+.ls CCDPROC: V2.10.3
+The output pixel datatypes (specified by the package parameter
+\fIpixeltype\fR have been extended to include unsigned short
+integers.  Also it was previously possible to have the output
+pixel datatype be of lower precision than the input.  Now the
+output pixel datatype is not allowed to lose precision; i.e.
+a real input image may not be processed to a short datatype.
+
+For short scan data the task now looks for the number of scan lines in the
+image header.  Also when a calibration image is software scanned a new
+image is created.  This allows processing objects with different numbers of
+scan lines and preserving the unscanned calibration image.
+
+It is an error if no biassec is specified rather than defaulting to
+the whole image.
+
+The time, in a internal format, when the CCDMEAN value is calculated is
+stored in the CCDMEANT keyword.  The time is checked against the image
+modify time to determine if the value is valid or needs to be recomputed.
+.le
+.ih
+SEE ALSO
+.nf
+instruments, ccdtypes, flatfields, icfit, ccdred, guide, mkillumcor,
+mkskycor, mkfringecor
+.fi
+.endhelp
-- 
cgit 

