BAIT: photo command

NAME

photo - takes ccd images with automatic imaging telescope

SYNOPSIS

photo [verbose] [nopoint] [nofilter] [noguide] [noopen] [nofocus] [nozero] [fork]

DESCRIPTION

photo controls the AIT to take a picture. Depending on the options and the environment, photo opens the observatory, points the telescope, positions the filter, starts the guider, takes an image and generates the FITS header.

Environment variables (denoted here in upper case) control the program and are usually set by telco. If RA is specified, the telescope will point to the object. The mode of acquisition and guiding is specified by the GUIDEMOD parameter (see below).

photo produces output FITS file with the value of the keyword `DATID', but with the extension `.fts'.

If the `noopen' keyword is not specified, the first command of the procedure is to issue the `openup' command to prepare the observatory for observations. If the dome slit cannot be opened, the program exits with an non-zero exit code.

The fork keyword causes the ccd readout to occur in the background. Watch outand delay flat fielding until the image is finished.

If any failure occurs, a non-zero exit code will be generated.

REQUEST KEYWORDS

EXPTIME - is the shutter open time in seconds; if it does not exist (or is negative) it is assumed to be 0. The value will be transferred to the FITS header. (If the actual exposure time were to differ significantly, a fatal error will be generated.) The EXPTIME is not allowed to be greater than the value of SHUTMAX in ait.config. If IMAGETYP is dark the shutter is not opened.

FILTERS - if specified, the filter wheel is rotated to the filter with the specified name. If the filter does not exist a fatal error is generated. The FILTERS line is written in the FITS data only if the shutter has been opened. The filter name - filter bolt correspondence is listed in the file ait.config.

GAIN- if GAIN exists it specifies the value of the CCD gain which can be an integer greater than 0. The default value is 1.

GURA, GUDEC, GUEPOCH - if GURA exists the guider stage will move so that the star specified by GURA, GUDEC, and GUEPOCH (all three must exist) can be acquired. If GUIDEMOD is not specified, the presence of GURA will set the guiding mode to `guide' (see below). These quantities will be transferred to the FITS header if the guider is used. (See GUSTAT).

GUIDEMOD - specifies how photo handles acquisition and guiding. There are three modes: 'noguide' - just points the telescope and does not run the acquire or guide programs. 'guide' - calls the acquire program. If this procedure fails then photo exits with a non-zero code. If acquire succeeds then it invokes the guide program. If guide fails or looses track the exposure will continue, since there is no method of stopping an exposure; however, a strange statistic will be written into the header file in the GUSTAT keyword. 'tryguide' - runs the acquire program. If acquire succeeds then the guiding will be turned on as in guide mode. However, if it fails `photo' will continue without activating the guide program.

The guide program sends messages to keep the dome slit open and centered as the telescope tracks. If this program is not invoked, it calls the keepopen program to perform these functions.

IMAGETYP - if it does not exist then it will be assigned to be type 'OBJECT'. If it is type 'DARK' then program delays for EXPTIME with the shutter closed before reading the CCD. If the value is `ZERO' the program will read the CCD immediately with the shutter closed

OBJECT - is a string containing the name of the object. If it exists it is transferred to FITS header.

RA, DEC, EPOCH - if RA exists, the telescope will point to the target (all three must also exist otherwise a fatal error will occur) If the telescope was pointed, then the requested RA, DEC, and EPOCH values will be transferred into the FITS header. We write the requested instead of the meas_ured coordinates was chosen because if there is a discrepancy outside of the pointing errors, a fatal error would occur. photo checks to see if the telescope point will obey all telescope limits at the beginning and end of the exposure. It checks before the point and after the acquisition is complete.

GUIDEMAG - if it exists is copied to the header.

MAGNITUD - if specified is copied to header.

MAILADDR - if specified is copied to header.

REQID - the id of the request file is copied to header if present.

SENDMAIL - if specified is copied to header.

TRACK - is a string that must contain two fields specifying the ra and dec tracking rates in arc-seconds per second. If not present, sidereal tracking is assumed. If present, the track rate is applied just before shutter opening and its value placed in the header. Note: the track rate may not have settled properly.

USERID - an optional user specified id is copied to header if present.

CONFIGURATION KEYWORDS

The following keywords are copied from ait.config and written into the FITS header.

CCDSEC - the format of the ccd.

CDELTn - the increment per pixel of the coordinate value in decimal degrees.

CRVALn - the axis value (e.g. declination) in decimal degrees at the center of the chip. The equinox is the epoch of the observation.

CRPIXn - the pixel to which CRVAL applies which is the center pixel.

CSOURCE - this local keyword describes the source of CRVAL, CDELT, CROT and currently only has the value `telescope' which means it comes from the file ait.config and relies on open loop telescope pointing.

CROTAn - the rotation angle of the axis (always assumed to be 0 degrees.)

CTYPEn - a character string describing the type of axis the two choices are `RA---TAN' and `DEC--TAN'. The TAN describes the telescope projection.

DETECTOR - the name of the CCD chip.

INSTRUME - the name of the system taking the image. OBSER-VAT - the name of the observatory.

TELESCOP - the name of the telescope.

OTHER FITS KEYWORDS

Although many keywords in the FITS header will be transferred from either the request file, or the configuration file, others will be generated by the program.

AIRMASS - the number of air masses calculated with a spherical atmosphere approximation and integrated over the time of the exposure.

CAMTEMP - the camera temperature in degrees centigrade.

DARKTIME - the length of time (in seconds) between CCD reads. If the time is unknown, it is set to -1 second.

DATE-OBS, UT - are the strings `dd/mm/yyyy' and `hh/mm/ss' of the UT of the shutter opening (for a dark it is the date and time of CCD read. These values are set from the system clock.

DOMESLIT - reports the value `CLOSED' if the slit was closed at the end of the exposure. This may occur if some weather condition has been exceeded. If the slit was open the keyword does not appear.

GUSTAT - is a string reporting of the behavior of the guider; see guide for the meaning.

GUSTAGE - this string contains the x and y guider stage coordinates in mm. This keyword is inserted by the `guide' program.

HA - the hour angle as an hh:mm:ss string at the start of the observation.

HUMIDITY - the relative humidity in percent at the start of the exposure. This keyword may not always be available.

IRVOLTS - the infrared cloud sensor voltage. This keyword may not always be available.

STANZA - records which stanza of the request file generated the data file. Numbers start at one.

TELFOCUS - the telescope focus in arbitrary, but consistent units.

WINDSPEED - the windspeed in knots at the start of the exposure. This keyword may not always be available.

OPTIONS

Many of the normal functions of photo can be over-ridden by command line keywords. nopoint - disables the point program even though RA is specified. noopen - disables the call to openup nofocus - calls openup with the nofocus keyword. nozero - calls openup with the nofocus keyword. noguide disables acquisition and guiding regardless of the state of GUIDEMOD or GURA. nofilter - prevents the filter wheel from rotating.

NEEDED PROCESSES

photo needs the `tserver' process to be running.