Initial commit

1 files changed, 256 insertions, 0 deletions

diff --git a/noao/imred/ccdred/doc/instruments.hlp b/noao/imred/ccdred/doc/instruments.hlp
new file mode 100644
index 00000000..95baff37
--- /dev/null
+++ b/noao/imred/ccdred/doc/instruments.hlp
@@ -0,0 +1,256 @@
+.help instruments Dec93 noao.imred.ccdred
+
+.ih
+NAME
+instruments -- Instrument specific data files
+.ih
+DESCRIPTION
+The \fBccdred\fR package has been designed to accommodate many different
+instruments, detectors, and observatories.  This is done by having
+instrument specific data files.  Note that by instrument we mean a
+combination of detector, instrument, application, and observatory, so
+there might be several "instruments" associated with a particular CCD
+detector.  Creating and maintaining the instrument files is generally
+the responsibility of the support staff, though the user may create or
+copy and modify his/her own instrument/application specific files.  The
+task \fBsetinstrument\fR makes this information available to the user
+and package easily.
+
+There are three instrument data files, all of which are optional.  The
+package may be used without the instrument files but much of the
+convenience of the package, particularly with respect to using the CCD
+image types, will be lost.  The three files are an instrument image
+header translation file, an initialization task which mainly sets
+default task parameters, and a bad pixel file identifying the cosmic
+bad pixels in the detector.  These files are generally stored in a
+system data directory which is a subdirectory of the logical
+directory "ccddb$".  Each file has a root name which identifies the
+instrument.
+.sh
+1. Instrument Translation File
+The instrument translation file translates the parameter names used by
+the \fBccdred\fR pacakge into instrument specific parameters and also
+supplies instrument specific default values.  The package parameter
+\fIccdred.instrument\fR specifies this file to the package.  The task
+\fBsetinstrument\fR sets this parameter, though it can be set
+explicitly like any other parameter.  For the standard instrument
+translation file the root name is the instrument identification and the
+extension is "dat" ("*.dat" files are protected from being removed in a
+"stripped" system, i.e. when all nonessential files are removed).
+Private instrument files may be given any name desired.
+
+The instrument translation proceeds as follows.  When a package task needs
+a parameter for an image, for example "imagetyp", it looks in the instrument
+translation file.  If the file is not found or none is specified then the
+image header keyword that is requested has the same name.  If an
+instrument translation file is defined then the requested
+parameter is translated to an image header keyword, provided a translation
+entry is given.  If no translation is given the package name is used.  For
+example the package parameter "imagetyp" might be translated to "data-typ"
+(the old NOAO CCD keyword).  If the parameter is not found then the default
+value specified in the translation file, if present, is returned.  For recording
+parameter information in the header, such as processing flags, the
+translation is also used.  The default value has no meaning in this case.
+For example, if the flag specifying that the image has been corrected
+by a flat field is to be set then the package parameter name "flatcor"
+might be translated to "ff-flag".  If no translation is given then the
+new image header parameter is entered as "flatcor".
+
+The format of the translation file are lines consisting of the package
+parameter name, followed by the image header keyword, followed by the
+default value.  The first two fields are parameter names.  The fields
+are separated by whitespace (blanks and tabs).  String  default values
+containing blanks must be quoted.  An example is given below.
+
+.nf
+    # Sample translation file.
+    exptime     itime
+    darktime    itime
+    imagetyp    data-typ
+    subset      f1pos
+    biassec     biassec    [411:431,2:573]
+    datasec     datasec    [14:385,2:573]
+
+    fixpix      bp-flag    0
+    overscan    bt-flag    0
+    zerocor     bi-flag    0
+    darkcor     dk-flag    0
+    flatcor     ff-flag    0
+    fringcor    fr-flag    0 
+.fi
+
+The first comment line is ignored as are blank lines.
+The first two lines translate the CCD image type, and the subset parameter
+without default values (see \fBccdtypes\fR and \fBsubsets\fR for more
+information).  The next two lines give the overscan bias strip
+section and the data section with default values for the instrument.
+Note that these parameters may be overridden in the task \fBccdproc\fR.
+
+The next set of translations requires further discussion.  For processing
+flags the package assumes that the absence of a keyword means that the
+processing has not been done.  If processing is always to be done with
+the \fBCCDRED\fR package and no processing keywords are recorded in the raw data
+then these parameters should be absent (unless you don't like the names
+used by the package).  However, for compatibility with the original NOAO
+CCD images, which may be processed outside of IRAF and which use 0 as the
+no processing value, the processing flags are translated and the false values
+are indicated by the default values.
+
+If there is more than one translation for the same CCDRED parameter,
+for example more than one exptime, then the last one is used.
+
+In addition to the parameter name translations the translation file
+contains translations between the value of the image type parameter
+and the image types used by the package.  These lines
+consist of the image header type string as the first field (with quotes
+if there are blanks) and the image type as recognized by the package.  The
+following example will make this clearer.
+
+.nf
+	'OBJECT (0)'		object
+	'DARK (1)'		dark
+	'PROJECTOR FLAT (2)'	flat
+	'SKY FLAT (3)'		other
+	'COMPARISON LAMP (4)'	other
+	'BIAS (5)'		zero
+	'DOME FLAT (6)'		flat
+.fi
+
+The values of the image type strings in the header contain blanks so they
+are quoted.  Also the case of the strings is important.  Note that there
+are two types of flat field images and three types of object images.
+
+The CCD image types recognized by the package are:
+
+.nf
+	zero   - zero level image such as a bias or preflash
+	dark   - dark count image
+	flat   - flat field image
+	illum  - iillumination image such as a sky image
+	fringe - fringe correction image
+	object - object image
+.fi
+
+There may be more than one image type that maps to the same package
+type.  In particular other standard CCD image types, such as comparison
+spectra, multiple exposure, standard star, etc., should be mapped to
+object or other.  There may also be more than one type of flat field,
+i.e. dome flat, sky flat, and lamp flat.  For more on the CCD image
+types see \fBccdtypes\fR.
+
+The complete set of package parameters are given below.
+The package parameter names are generally the same as the
+standard image header keywords being adopted by NOAO.
+
+.nf
+	General Image Header and Default Parameters
+    ccdmean		darktime	exptime		fixfile
+    imagetyp		ncombine	biassec		subset
+    title		datasec         nscanrow
+
+	       CCDRED Processing Flags
+    ccdproc		darkcor		fixpix		flatcor
+    fringcor		illumcor	overscan	trim
+    zerocor
+
+	       CCDRED CCD Image Types
+    dark		flat		fringe		illum
+    none		object		unknown		zero
+.fi
+
+The translation mechanism described here may become more
+sophisticated in the future and a general IRAF system facility may be
+implemented eventually.  For the present the translation mechanism is
+quite simple.
+.sh
+2. Instrument Setup Script
+The task \fBsetinstrument\fR translates an instrument ID into a
+CL script in the instrument directory.  This script is then executed.
+Generally this script simply sets the task parameters for an
+instrument/application.  However, it could do anything else the support
+staff desires.  Below are the first few lines of a typical instrument setup
+script.
+
+.nf
+	ccdred.instrument = "ccddb$kpno/example.dat"
+	ccdred.pixeltype = "real"
+	ccdproc.fixpix = yes
+	ccdproc.overscan = yes
+	ccdproc.trim = yes
+	ccdproc.zerocor = no
+	ccdproc.darkcor = no
+	ccdproc.flatcor = yes
+	ccdproc.biassec = "[411:431,2:573]"
+	ccdproc.datasec = "[14:385,2:573]"
+.fi
+
+The instrument parameter should always be set unless there is no
+translation file for the instrument.  The \fBccdproc\fR parameters
+illustrate setting the appropriate processing flags for the
+instrument.  The overscan bias and trim data sections show an alternate
+method of setting these instrument specific parameters.  They may be
+set in the setup script in which case they are given explicitly in the
+user parameter list for \fBccdproc\fR.  If the value is "image" then
+the parameters may be determined either through the default value in
+the instrument translation file, as illustrated in the previous
+section, or from the image header itself.
+
+The instrument setup script for setting default task parameters may be
+easily created by the support person as follows.  Set the package
+parameters using \fBeparam\fR or with CL statements.  Setting the
+parameters might involve testing.  When satisfied with the way the
+package is set then the parameters may be dumped to a setup script
+using the task \fBdparam\fR.  The final step is editing this script to
+delete unimportant and query parameters.  For example,
+
+.nf
+	cl> dparam ccdred >> file.cl
+	cl> dparam ccdproc >> file.cl
+	cl> dparam combine >> file.cl
+		...
+	cl> ed file.cl
+.fi
+.sh
+3. Instrument Bad Pixel File
+The bad pixel file describes the bad pixels, columns, and lines in the
+detector which are to be replaced by interpolation when processing the
+images.  This file is clearly detector specific.  The file consists of
+lines describing rectangular regions of the image.
+The regions are specified by four numbers giving the starting and ending
+columns followed by the starting and ending lines.  The starting and
+ending points may be the same to specify a single column or line.  The
+example below illustrates a bad pixel file.
+
+.nf
+	# RCA1 CCD untrimmed
+	25 25 1 512
+	108 108 1 512
+	302 302 403 512
+	1 512 70 70
+	245 246 312 315
+.fi
+
+If there is a comment line in the file containing the word "untrimmed"
+then the coordinates of the bad pixel regions apply to the original CCD
+detector coordinates.
+If the image has been trimmed and the bad pixels are replaced at a later
+stage then this word indicates that the trim region be determined from the
+image header and the necessary coordinate conversion made to the original
+CCD pixel coordinates.  Note that if a subraster readout is used the
+coordinates must still refer to the original CCD coordinates and
+not the raw, untrimmed readout image.  If the word
+"untrimmed" does not appear then the coordinates are assumed to apply to
+the image directly; i.e. the trimmed coordinates if the image has been
+trimmed or the original coordinates if the image has not been trimmed.
+The standard bad pixel files should always refer to the original, untrimmed
+coordinates.
+
+The first two bad pixel regions are complete bad columns (the image
+is 512 x 512), the next line is a partial bad column, the next line is
+a bad line, and the last line is a small bad region.  These files are
+easy to create, provided you have a good image to work from and a way
+to measure the positions with an image or graphics display.
+.ih
+SEE ALSO
+ccdtypes, subsets, setinstrument
+.endhelp