Initial commit

1 files changed, 391 insertions, 0 deletions

diff --git a/noao/imred/ccdred/doc/ccdinst.hlp b/noao/imred/ccdred/doc/ccdinst.hlp
new file mode 100644
index 00000000..ea90f4a7
--- /dev/null
+++ b/noao/imred/ccdred/doc/ccdinst.hlp
@@ -0,0 +1,391 @@
+.help ccdinstrument Dec93 noao.imred.ccdred
+.ih
+NAME
+ccdinstrument -- Setup and verify CCD instrument translation files
+.ih
+USAGE	
+ccdinstrument images
+.ih
+PARAMETERS
+.ls images
+List of images to be verified or used to setup a CCD instrument translation
+file.
+.le
+.ls instrument = ")_.instrument"
+CCD instrument translation file.  The default is to use the translation
+file defined in the \fBccdred\fR package parameters.  Note that one would
+need write permission to update this file though the task has a write
+command to save any changes to a different file.
+.le
+.ls ssfile = ")_.ssfile"
+Subset translation file.  The default is to use the file defined in
+the \fBccdred\fR package parameters.
+.le
+.ls edit = yes
+Edit the instrument translation file?  If "yes" an interactive
+mode is entered allowing translation parameters to be modified while if
+"no" the task is simply used to verify the translations noninteractively.
+.le
+.ls parameters = "basic"
+Parameters to be displayed.  The choices are "basic" to display only the
+most basic parameters (those needed for the simplest automation of
+\fBccdred\fR tasks),  "common" to display the common parameters used
+by the package (most of these are keywords to be written to the image
+rather than translated), and "all" to display all the parameters
+referenced by the package including the most obscure.  For most uses
+the "basic" set is all that is important and the other options are
+included for completeness.
+.le
+.ih
+DESCRIPTION
+The purpose of this task is to provide an interface to simplify setting
+up CCD instrument translation files and to verify the translations
+for a set of images.  Before this task was written users who needed to
+set up translation files for new instruments and observatories had
+to directly create the files with an editor.  Many people encountered
+difficulties and were prone to errors.  Also there was no task that
+directly verified the translations though \fBccdlist\fR provided some
+clues.
+
+The \fBccdred\fR package was designed to make intelligent use of
+information in image headers for determining things such as image
+calibration or object type and exposure times.  While the package may
+be used without this capability it is much more convenient to be
+able to use information from the image.  The package was also intended
+to be used with many different instruments, detectors, and observatories.
+The key to providing image header access across different observatories
+is the ability to translate the needs of the package to the appropriate
+keywords in the image header.  This is done through a file called
+an "instrument translation file".  For a complete description of
+this file and other instrument setup features of the package see
+\fBccdred.instruments\fR.
+
+The instrument translation file translates the parameter names used by
+the \fBccdred\fR package into image specific parameters and also
+supplies default values for parameters.  The 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 is assumed to have 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, translation is also used.  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 CCD image type requires a second level of translation also defined
+in the translation file.  Once the image keyword which identifies the
+type of CCD image, for example a flat field or object, is translated
+to an imahe keyword the specific
+string value must be translated to one of the CCD image types used
+by the package.  The translation works in the same way, the specific
+string found is translated to the \fBccdred\fR type and returned to
+the task.  This translation is tricky in that the exact string
+including all spaces and capitalizations must be correctly defined
+in the translation file.  The \fBccdinstrument\fR allows doing
+this automatically thus minimizing typing errors.
+
+The basic display format of the task is a table of five columns
+giving the parameter name used by the package, the image keyword
+to which it is translated, the default value (if any), the value
+the task will receive for the current image after translation,
+and the actual keyword value in the image.  A "?" is printed if
+a value cannot be determined.  The idea of the task is to make sure
+that the value a \fBccdred\fR task sees is the correct one and if not
+to modify the translation appropriately.  In verify mode when the
+\fBedit\fR parameter is not set the translation table is simply
+printed for each input image.
+
+In edit mode the user interactively gives commands at the ccdinstrument
+prompt to display or modify keywords.  The modifications can then be
+written to the instrument file or saved in a private copy.  The
+list of commands is shown below and may be printed using ? or help.
+
+.in 4
+.nf
+			CCDINSTRUMENT COMMANDS
+
+?	    Print command summary
+help	    Print command summary
+imheader    Page image header
+instrument  Print current instrument translation file
+next	    Next image
+newimage    Select a new image
+quit	    Quit
+read	    Read instrument translation file
+show	    Show current translations
+write	    Write instrument translation file
+
+translate   Translate image string selected by the imagetyp
+	    parameter to one of the CCDRED types given as an
+	    argument or queried:
+	    object, zero, dark, flat, comp, illum, fringe, other
+
+.fi
+The following are CCDRED parameters which may be translated.  You are
+queried for the image keyword to use or it may be typed after the command.
+An optional default value (returned if the image does not contain the
+keyword) may be typed as the second argument of the command.
+.nf
+
+	BASIC PARAMETERS
+imagetyp	Image type parameter (see also translate)
+subset		Subset or filter parameter
+exptime		Exposure time
+darktime	Dark time (may be same as the exposure time)
+.fi
+.in -4
+
+The commands may be followed by values such as file names for some of
+the general commands or the keyword and default value for the parameters
+to be translated.  Note this is the only way to specify a default value.
+If no arguments are given the user is prompted with the current value
+which may then be changed.
+
+The set of parameters shown above are only those considered "basic".
+In order to avoid confusion the task can limit the set of parameters
+displayed.  Without going into great detail, it is only the basic
+parameters which are generally required to have valid translations to
+allow the package to work well.  However, for completeness, and if someone
+wants to go wild with translations, further parameters may be displayed
+and changed.  The parameters displayed is controlled by the \fIparameters\fR
+keyword.  The additional parameters not shown above are:
+
+.in 4
+.nf
+	USEFUL DEFAULT GEOMETRY PARAMETERS
+biassec		Bias section (often has a default value)
+trimsec		Trim section (often has a default value)
+
+	COMMON PROCESSING FLAGS
+fixpix		Bad pixel replacement flag
+overscan	Overscan correction flag
+trim		Trim flag
+zerocor		Zero level correction flag
+darkcor		Dark count correction flag
+flatcor		Flat field correction flag
+
+	RARELY TRANSLATED PARAMETERS
+ccdsec		CCD section
+datasec		Data section
+fixfile		Bad pixel file
+
+fringcor	Fringe correction flag
+illumcor	Ilumination correction flag
+readcor		One dimensional zero level read out correction
+scancor		Scan mode correction flag
+nscanrow	Number of scan rows
+
+illumflt	Ilumination flat image
+mkfringe	Fringe image
+mkillum		Iillumination image
+skyflat		Sky flat image
+
+ccdmean		Mean value
+ccdmeant	Mean value compute time
+fringscl	Fringe scale factor
+ncombine	Number of images combined
+date-obs	Date of observations
+dec		Declination
+ra		Right Ascension
+title		Image title
+.fi
+.in -4
+.ih
+EXAMPLES
+1. To verify the translations for a set of images using the default
+translation file:
+
+.nf
+	cl> setinst "" review-
+	cl> ccdinst dev$pix edit-
+	Image: dev$pix
+	Instrument file: 
+	Subset file: subsets
+
+	CCDRED    IMAGE     DEFAULT   CCDRED    IMAGE   
+	PARAM     KEYWORD   VALUE     VALUE     VALUE   
+	--------------------------------
+	imagetyp  imagetyp            none      ?
+	subset    subset                        ?
+	exptime   exptime             ?         ?
+	darktime  darktime            ?         ?
+
+	cl> setinst "" site=kpno dir=ccddb$ review-
+	cl> ccdinst dev$pix edit-
+	Image: dev$pix
+
+	Instrument file: ccddb$kpno/camera.dat
+	Subset file: subsets
+
+	CCDRED    IMAGE     DEFAULT   CCDRED    IMAGE   
+	PARAM     KEYWORD   VALUE     VALUE     VALUE   
+	--------------------------------
+	imagetyp  data-typ            object    OBJECT (0)
+	subset    f1pos               2         2
+	exptime   otime               600       600
+	darktime  ttime               600       600
+.fi
+
+2.  Set up an  instrument translation file from scratch.
+
+.nf
+	ccdinst ech???.imh instr=myccd edit+
+	Warning: OPEN: File does not exist (myccd)
+	Image: ech001.imh
+	Instrument file: myccd
+	Subset file: subsets
+	
+	CCDRED    IMAGE     DEFAULT   CCDRED    IMAGE   
+	PARAM     KEYWORD   VALUE     VALUE     VALUE   
+	------------------------------------------------------
+	imagetyp  imagetyp            none      ?
+	subset    subset                        ?
+	exptime   exptime             ?         ?
+	darktime  darktime            ?         ?
+	
+	ccdinstrument> imagetyp
+	Image keyword for image type (imagetyp): ccdtype
+	imagetyp  ccdtype             unknown   BIAS
+	ccdinstrument> translate
+	CCDRED image type for 'BIAS' (unknown): zero
+	imagetyp  ccdtype             zero      BIAS
+	ccdinstrument> subset
+	Image keyword for subset parameter (subset): filters
+	subset    filters             1         1 0
+	ccdinstrument> exptime integ
+	exptime   integ               0.        0.
+	ccdinstrument> darktime integ
+	darktime  integ               0.        0.
+	ccdinstrument> show
+	Image: ech001.imh
+	Instrument file: myccd
+	Subset file: subsets
+	
+	CCDRED    IMAGE     DEFAULT   CCDRED    IMAGE   
+	PARAM     KEYWORD   VALUE     VALUE     VALUE   
+	------------------------------------------------------
+	imagetyp  ccdtype             zero      BIAS
+	subset    filters             1         1 0
+	exptime   integ               0.        0.
+	darktime  integ               0.        0.
+	
+	ccdinstrument> next
+	Image: ech002.imh
+	Instrument file: myccd
+	Subset file: subsets
+	
+	CCDRED    IMAGE     DEFAULT   CCDRED    IMAGE   
+	PARAM     KEYWORD   VALUE     VALUE     VALUE   
+	------------------------------------------------------
+	imagetyp  ccdtype             unknown   PROJECTOR FLAT
+	subset    filters             1         1 0
+	exptime   integ               20.       20.
+	darktime  integ               20.       20.
+	
+	ccdinstrument> trans
+	CCDRED image type for 'PROJECTOR FLAT' (unknown): flat
+	imagetyp  ccdtype             flat      PROJECTOR FLAT
+	ccdinstrument> next
+	Image: ech003.imh
+	Instrument file: myccd
+	Subset file: subsets
+	
+	CCDRED    IMAGE     DEFAULT   CCDRED    IMAGE   
+	PARAM     KEYWORD   VALUE     VALUE     VALUE   
+	------------------------------------------------------
+	imagetyp  ccdtype             unknown   COMPARISON
+	subset    filters             1         1 0
+	exptime   integ               300       300
+	darktime  integ               300       300
+	
+	ccdinstrument> translate comp
+	imagetyp  ccdtype             comp      COMPARISON
+	ccdinstrument> next
+	Image: ech004.imh
+	Instrument file: myccd
+	Subset file: subsets
+	
+	CCDRED    IMAGE     DEFAULT   CCDRED    IMAGE   
+	PARAM     KEYWORD   VALUE     VALUE     VALUE   
+	------------------------------------------------------
+	imagetyp  ccdtype             unknown   OBJECT
+	subset    filters             1         1 0
+	exptime   integ               3600      3600
+	darktime  integ               3600      3600
+	
+	ccdinstrument> translate object
+	imagetyp  ccdtype             object    OBJECT
+	ccdinstrument> inst
+	imagetyp                      ccdtype 
+	BIAS                          zero    
+	subset                        filters 
+	exptime                       integ   
+	darktime                      integ   
+	'PROJECTOR FLAT'              flat    
+	COMPARISON                    comp    
+	OBJECT                        object  
+
+	ccdinstrument> next
+	Update instrument file myccd (yes)? 
+.fi
+
+3.  Set default geometry parameters.  Note that to set a default the
+arguments must be on the command line.
+
+.nf
+	cc> ccdinst ech001 instr=myccd param=common edit+
+	Image: ech001
+	Instrument file: myccd
+	Subset file: subsets
+	
+	CCDRED    IMAGE     DEFAULT   CCDRED    IMAGE   
+	PARAM     KEYWORD   VALUE     VALUE     VALUE   
+	------------------------------------------------------
+	imagetyp  ccdtype             zero      BIAS
+	subset    filters             1         1 0
+	exptime   integ               0.        0.
+	darktime  integ               0.        0.
+	
+	biassec   biassec             ?         ?
+	trimsec   trimsec             ?         ?
+	
+	fixpix    fixpix              no        ?
+	overscan  overscan            no        ?
+	trim      trim                no        ?
+	zerocor   zerocor             no        ?
+	darkcor   darkcor             no        ?
+	flatcor   flatcor             no        ?
+	
+	ccdinstrument> biassec biassec [803:830,*]
+	biassec   biassec   [803:830,*]  [803:830,*]  ?
+	ccdinstrument> trimsec trimsec [2:798,2:798]
+	trimsec   trimsec   [2:798,2:798]  [2:798,2:798]  ?
+	ccdinstrument> instr
+	trimsec                       trimsec  [2:798,2:798]
+	biassec                       biassec  [803:830,*]
+	imagetyp                      ccdtype 
+	BIAS                          zero    
+	subset                        filters 
+	exptime                       integ   
+	darktime                      integ   
+	'PROJECTOR FLAT'              flat    
+	COMPARISON                    comp    
+	OBJECT                        object  
+	
+	ccdinstrument> q
+	Update instrument file myccd (yes)? 
+.fi
+.ih
+SEE ALSO
+instruments, setinstrument
+.endhelp