ccdinstrument: Review and edit instrument translation files
Package: ccdred
Usage
ccdinstrument images
Parameters
- images
- List of images to be verified or used to setup a CCD instrument translation file.
- instrument = ")_.instrument"
- CCD instrument translation file. The default is to use the translation file defined in the ccdred 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.
- ssfile = ")_.ssfile"
- Subset translation file. The default is to use the file defined in the ccdred package parameters.
- 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.
- parameters = "basic"
- Parameters to be displayed. The choices are "basic" to display only the most basic parameters (those needed for the simplest automation of ccdred 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.
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 ccdlist provided some clues.
The ccdred 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 ccdred.instruments.
The instrument translation file translates the parameter names used by the ccdred 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 ccdred 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 ccdinstrument 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 ccdred task sees is the correct one and if not to modify the translation appropriately. In verify mode when the edit 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.
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
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.
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)
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 parameters keyword. The additional parameters not shown above are:
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
Examples
1. To verify the translations for a set of images using the default translation file:
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
2. Set up an instrument translation file from scratch.
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)?
3. Set default geometry parameters. Note that to set a default the arguments must be on the command line.
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)?
See also
instruments, setinstrument