| |
|
|
|
2 USER'S GUIDE
This part of the document provides a description of the programmatic interface of the CCD software. It gives software engineers, writing applications using a ACE based CCD camera, information on what they have to implement in their code to be able to interact with the CCD software.
For people having no experience with the CCD software yet, it is highly recommendable, although not necessary, before starting to read this section, first to have a look at the interactive usage of the CCD software as stand-alone instrument (see [14]) and possibly try it out; it can help to get a better idea of the way how the CCD software works, as well as of the functionality currently implemented.
2.1 Overview
The CCD Detectors Control Software is distributed over three hardware platforms: WS, LCU and ACE transputer network.
The current standard configuration (see [14]) foresees that all sub-systems (readout, shutter, telemetry and temperature) are controlled by the ACE software.
The present document assumes that the standard configuration is used.
On the other hand, the design of the CCD LCU software is such that it allows to replace the standard control software of one or more sub-systems with other software developed for special hardware (e.g. a special shutter). For more information on this subject, see [17]
For a description of the hardware and software needed to run the CCD software, see section 4.2.
A program accesses the functionality provided by the CCD software in the following way:
1. It retrieves information about configuration and status of the CCD camera through functions available in the library libccd (see section 2.11). Whenever the information wanted cannot be retrieved by means of library function calls, a direct access to the public part of the on-line database is possible (see section 2.16).
2. It asks the CCD software for services by mean of commands using the CCS message system (see section 2.10).
3. It can use the CCS event system to be informed about changes of status of the CCD system (see section 2.19.1).
Note: In the examples shown in the next sections we take the following setting (see section 4.6.1):
2.2 Parallelism
One of the main requirements for the CCD software is to optimize observation time, performing as much as possible operations in parallel.
For this reason, parts of image already been read-out are transferred to the Workstation and saved in FITS file and/or displayed (depending from the setup), while the next image portion is being read-out.; this parallelism of read-out and image transfer guarantees that the time interval between the end of the read-out and the completion of image display or FITS file on disk is minimized.
2.3 Exposure definitions
2.3.1 CCD Exposure Id
In order to be able to uniquely identify an exposure among those already finished and the running one, an Identification number is associated to each exposure.
The Id used by the CCD sw for this purpose is an integer sequential number (vltINT32) returned by the CCD DCS software as reply parameter to the command START.
Applications must pass this Id as parameter to all commands dealing with a running exposure (e.g. ABORT, see section 3.2.1).
Special values (see ccd.h) can be used; applications are encouraged to use them whenever possible:
The Id defined here does NOT replace the exposure Id as defined in the INS Common Software document [4]. It is just a different Id, which has to be used in the communication between the CCD sw and external sw (e.g. INS OS). In particular:
1. The OS expoId follows the rules in [4] and is generated by OS. It is used to communicate between OS and the software on top of it (GUI panel, Sequencer etc.). Applications using only TCCDS only can just ignore this point.
2. The CCD expoId is a different variable and is generated by CCD at START time. It is used only for the internal communication between CCD sw and higher level sw (e.g. INS OS or TCS AG sw).
ii. Use ccdEXP_LAST (0), or the value returned by the CCD sw to the START command, for a running exposure (e.g. to change the exposure time).
No expoId has to be passed as parameter. On the contrary, the reply contains the expoId value of the exposure just started.
2.3.2 Exposure types
The CCD Detector Control Software distinguishes among three different types of exposure (see also [3]).
c. During the integration the shutter is kept closed. For cameras without shutter (e.g. TCCDS), only dark with 0 integration time (bias) are meaningful and possible.
b. The CCD is normally wiped before starting a new exposure, unless the time interval between the expected start of the new exposure and the last read-out or wipe is shorter than the value of the database attribute exposures.wipeTimeTol.
3. Multi-step (in the present release supported only for systems without shutter). It has the following characteristics:
b. The CCD is normally wiped before starting a new exposure, unless the time interval between the expected start of the new exposure and the last read-out or wipe is shorter than the value of the database attribute exposures.wipeTimeTol.
d. After each integration, excluding the last one, the exposure is automatically paused (the shutter, if present, is closed)
e. During pauses between consecutive integrations, rows may be shifted on chip, according to the value of the setup parameter DET.READ.SHIFT (see also ccdREADSHIFT in file ccd.h).
f. For systems with shutter, the next integration is started with a CONT command. For systems without shutter (e.g. TCCDS) the integration is started as soon the rows shift operation has been completed.
It is responsibility of higher level software (e.g. Observation Software) to translate the various supported exposure types as defined in [5] into one of the types known by CCD DCS for the setup parameter DET.EXP.TYPE. It is recommended to use variables of type ccdEXPTYPE or the macros associated to the corresponding strings (e.g. ccdEXP_DARK_STR), defined in ccd.h, for all operations dealing with the CCD DCS exposure type.
2.3.3 Exposure status
An attribute in the on-line database (exposures:exposure_1.expStatus, see also section 2.16) is dedicated to the storage of the status of a running exposure (or the end status of the last finished exposure if no new exposure has been started yet). It is a bit-field value and the meaning of each bit is (less significant bit is indicated as 1):
Note that, in case of a loop of repeated exposures, the status does NOT change during the whole loop. Applications interested in the status of each single exposure should not use the repeated exposure feature.
The exposure status returned by the CCD sw in the reply to some commands (e.g. STATUS and WAIT) is coded in the same way. Additionally, for those exposures already completed, whose final status is not available any more (e.g. because a new exposure has been meanwhile started), the returned status is ccdEXP_DONE (see ccd.h)
See also file ccd.h for all macros and associated values (e.g. ccdEXP_INACTIVE).
2.4 Operational modes and simulation
A detailed description of the operational modes implemented and their meaning is given in [14].
The current operational mode can be retrieved through the command STATUS (see 2.10).
It is recommended to use variables of type ccdOPMODE, defined in ccd.h, for all operations dealing with the CCD software operational mode
Note: any change to the current operational mode have effect only after the CCD software is brought to OFF state (Shutdown, see also 2.5).
2.5 Operational states
The list of operational states implemented in the CCD software is given in [14]. In Table 1 are shown the commands needed to do any change in the operational state of a CCD camera.
See section 2.10 for more information about commands available.
The current operational state can be retrieved through the command STATUS (see 2.10).
It is recommended to use variables of type ccdSTATE, defined in ccd.h, for all operations dealing with the CCD software operational state.
2.6 Image processing
This section applies mainly to applications dealing with TCCDS.
2.6.1 Image processing on Workstation
The CCD sw provides a C library, called libccdObj (see also section 2.11), containing functions which, using on-line Midas (see also [27]), determine the location and intensity of objects within a frame contained in a FITS file. The functions available allow to:
3. Determine and return the location and intensity of the detected object in a frame, closest to a reference point.
2.6.2 Real-time image processing on LCU
The CCD sw provides facilities to perform real-time image processing on the CCD LCU while the image data are being read-out and before they are transferred to Workstation.
Currently these facilities consist of:
1. Bias subtraction (see section 2.14 on setup parameter DET.WIN<i>.BIAS). In order to perform this operation a bias frame must have been stored before in the LCU memory; this can be done in two ways:
b. At startup, the CCD sw looks for a file in the image directory with name bias_<CCDNAME>.fits and loads it automatically in the LCU memory.
2. Flat field division (see section 2.14 on setup parameter DET.WIN<i>.FLATF). In order to perform this operation a flat-field frame must have been stored before in the LCU memory; this can be done in two ways:
b. At startup, the CCD sw looks for a file in the image directory with name flat_<CCDNAME>.fits and loads it automatically in the LCU memory.
The results are stored in the LCU on-line database (see also section 2.16) in the same sequential order as below:
4. Calculation of centroiding over image; it implies step 3. It does not implement any pattern recognition algorithm; it simply first subtracts the background level, then applies a threshold (all pixels below the threshold are set to 0), and finally computes the centre of gravity of the resulting image. The way how the background level and threshold are determined is discussed in section 2.14 (setup parameter DET.WIN<i>.CENTROID).
The results are stored in the LCU on-line database (see also section 2.16) in the same sequential order as below:
5. Hook to user function implementing a special application-dependant algorithm (see section 2.14 on setup parameters DET.WIN<i>.IPFUNC and DET.WIN<i>.IPBUFF). It implies step 3. This function must comply with the prototype defined in ccd.h (see ccdIPUSERFUNC). A template is also provided with the tape: <TAPEROOT>/CCD/ccdip/src/ccdipUsrFuncTemplate.
Steps 1. to 5. can be individually enabled/disabled. If more than one is enabled, then they are executed, for each window being read-out, sequentially in the same order as above (user function always last). Example: the setup defines that two windows have to be read-out, on the first one statistics and user function have to be called, on the second one statistics, centroiding and user function. The sequencial order is then: statistics on window 1, user function on window 1, statistics on window 2, centroiding on window 2, user function on window 2.
The results of the centroiding calculation for each window are stored in the LCU on-line database after both steps 4. and 5., if enabled, have been performed. They are stored in the same sequential order as below:
If no object is detected (e.g. all pixels are below the threshold), all attributes are set to 0.
It is responsibility of the user function, whenever enabled, to return in the ccdIPIMAGE strcucture (see ccd.h ) the computed centroiding results, if supposed to do centroiding, otherwise to leave these values unchanged, if supposed to do something else.
2.7 Startup
The CCD DCS software provides a startup script.
Type from the Workstation shell (see also manual page at section 3.3):
Note 1: As from the NOV97 release, the script ccdDcsWarmStart.sh has become obsolete and it still available for backwards compatibility reasons only. Application sw is invited to use ccdDcsStart.sh only.
2.7.1 Startup verification
To verify if the CCD sw startup was successful:
2. The following processes must be running in the WS environment (use option Rtap Perf. Monitor from ccsei to check)
3. The following processes must be running in the LCU environment (use lqsPrintLocalTbl from the VxWorks shell to check):
2.8 Shutdown
The CCD DCS software provides a shutdown script.
Type from the Workstation shell (see also manual page at section 3.3):
2.9 Include files
Applications dealing with CCD DCS software have to include the file ccd.h (see also 3.5).
2.10 Command Interface
The only CCD process accessible via CCS commands from external software is ccdconCI_$CCDNAME, running on the Workstation (e.g. if CCDNAME is set to myccd, the process name is ccdconCI_myccd).
The command interface between CCD software and external software is represented therefore by the Command Definition Table of that process.
Here a simple list of all the commands implemented is given. For more details, see Command Definition Table at section 3.2.1
5. Dump. Dump last image read or the specified one from VME memory. If no image available, read the chip(s) and then transfer to WS.
15. Setup. Define or just check setup values for next exposure or change values for the specified running exposure. See also sections 2.14 and 3.7.1.
16. Standal. CCD sw is used in stand-alone. All FITS information is merged in the image file and optionally the archive is informed of new images produced.
18. Start. Start new exposure (possibly repeated). Setup parameters can be specified as well. One single reply is returned as soon the exposure has started.
19. StartAg. Start autoguiding. An infinite loop is started using the current setup overloaded with the dedicated setup file ccdCmdStartAg.det. Each iteration consists of:
20. StartLoop. Start an infinite loop of repeated exposures using the current setup overloaded with the dedicated setup file ccdCmdStartLp.det.
External applications are recommended to use the macros for commands and parameters as specified in ccd.h (e.g. command ccdCMD_SETUP, parameter ccdEXP_TYPE)
2.11 C libraries
The library libccd provides routines for external software:
1. ccdGetConf. Get the current camera configuration (see also types ccdCAMERA and ccdCONFIG in ccd.h). See manual page in section 3.1
2. ccdGetCIName. Get name of the CCD process to send commands to (see also section 2.10). See manual page in section 3.1
3. ccdCheckSetup. Check a complete setup and return computed values (see types ccdSETUP and ccdSETUPRES in ccd.h). See manual page in section 3.1
The library libccdObj provides object detection functions. It uses on-line Midas and all functions implemented assume that a background Midas session is running (see also manual pages of the scripts ccdMidasBgStart.sh and ccdMidasBgStop.sh in section 3.3 on how to start/stop a MIdas background session). The test program ccdTestObj and script ccdTestMidasObj.sh, distributed with the tape and located in the directory CCD/ccd/ws/test, can be used as example.
The functions implemented are:
1. ccdObjAll. Detects objects in a frame from a FITS file and returns their location and intensity. See manual page in section 3.1
2. ccdObjBright. Detects objects in a frame from a FITS file and returns location and intensity of the brightest one. See manual page in section 3.1
3. ccdObjClose. Detects objects in a frame from a FITS file and returns location and intensity of the closest one to a reference point. See manual page in section 3.1
2.12 Graphical User Interface CCD classes
It is foreseen to provide applications using the CCD software with a set of classes, produced with the CCS panel editor, to be instantiated in bigger application panels.
The classes provided are available in the public library libccdGuiPublic.tcl (which has to be registered to any panel using it, see [22]):
1. ccdExpStatus_uifClass. It displays the status of an exposure. See also Fig.2 and manual page at section 3.4
2. ccdExpSetup_uifClass. It displays the main setup parameters of the most recently started exposure. See also Fig.2 and manual page at section 3.4
3. ccdReadoutSetup_uifClass. It displays the read-out setup parameters of the most recently started exposure. See also Fig.2 and manual page at section 3.4
4. ccdIpStatus_uifClass. It displays the status of real-time image processing on LCU. See also Fig.4 and manual page at section 3.4.
2.13 Data Interface Dictionary
The CCD software needs a Data Interface Dictionary file to be able to operate with setup keywords and files and to create proper headers in FITS files. The name of the dictionary is specified through the environment variable CCDDID (see section 4.6.1). The default dictionary (if CCDDID is not defined) is CCDDCS (full name ESO-VLT-DIC.CCDDCS)
2.14 Setup parameters and files
Among all kinds of setup files defined in [4], the CCD sw handles only detector setup files. They are normally created and modified through GUI panels and can be used as input for exposure setup definition (setup file name is passed as parameter to the SETUP command as well as single setup keywords).
The keywords currently implemented, and documented in the CCD DCS Data Dictionary (ESO-VLT-DIC.CCDDCS) are listed in the setup file shown in section 3.7.1 (it represents a complete setup file for CCD DCS). Information about the parameters for the SETUP command are also given in the CDT of ccdconCI (section 3.2.1) and in the include files ccd.h and ccdDbPublic.h (section 3.5)
2.14.1 Exposure
1. The parameter DET.EXP.TYPE defines the type of exposure and can take the following string values (see section 2.3.2 and ccd.h):
Applications interested in knowing the intermediate status of an exposure must set it to 1 (no repetition).
3. The parameter DET.FRAM.TYPE indicates the type of frame resulting from the next exposure. Possible values are ccdFRAME_NORMAL, ccdFRAME_BIAS, ccdFRAME_FLAT. The LCU CCD sw keeps in memory at any time the last acquired image of each type.
2.14.2 Times
1. The parameter DET.EXP.TIMEREP defines the period (in secs) between consecutive exposures for repeated exposures. A value of 0 means no delay between exposure (next started as soon previous one finishes).
2. The parameter DET.WIN1.UIT<i> specifies the (sub-)integration time in seconds. If DET.EXP.TYPE is not ccdEXP_MULTI_STR, only DET.WIN1.UIT1 must be used.
3. The parameter DET.EXP.WIPETIM indicates if a wipe is wished or not for exposures in a loop. The wipe for the first exposure is always done.
Note: If DET.EXP.WIPETIM is negative, depending on the setup, it may result in a discrepancy between the requested exposure time DET.WIN1.UIT1 and the effective exposure time if the exposure cycle time is larger than the exposure time: the effective exposure time is obtained as the maximum of (cycle time, exposure time) where the cycle time is the sum of exposure time + readout + process + transfer times.
The following diagrams illustrate some timing cases:
They apply for Technical CCD on small windows so that the transfer starts at readout completion.
In the last case, the integration of the next exposure starts at the end of the Frame Transfer (FT) performed before the readout of the current one, it terminates with the start of the next readout FT.
The asynchronous data transfer is performed by the CPU when time is available; thus it may end a couple of exposures later depending on the LCU load.
2.14.3 Readout
1. The parameter DET.READ.CLKIND is an integer number (range 1-10). It determines which read-out mode among those supported has to be used. This choice determines automatically the read-out speed and the number and location of on-chip outputs used (see also panel ccdConfig to find the correspondence between this index and the characteristics of the associated read-out).
Normally in case of TCCDs this parameter must be set to 1. For a limited set of TCCD systems (only of type C, i.e. large format), the value should be better set to 2 (slow read-out mode). The list of TCCD heads for which a value 2 is recommended is available in the CCD section of the Release Notes accompanying every VLT sw release.
2. The parameter DET.OUT1.GAININD defines the amplifier gain to be used during read-out. Each read-out mode has a default gain associated. For normal observations the default value should be used and therefore this parameter should NOT be set. However for laboratory tests a gain different from the default one may be wished; in this case the value of parameter DET.OUT1.GAININD has to be specified after the definition of DET.READ.CLKIND (see interpretation of parameters to command SETUP in [4]) in order to overwrite the default value. The allowed range for SCCDS is 0-7, the allowed values for TCCDS are 1,2,4,8.
4. The parameter DET.WIN<i>.ST is of logical type (T/F) and indicates if a windowed readout is wanted. Currently the system supports a maximum of two windows (DET.WIN1.ST and DET.WIN2.ST). There are however limitations to be taken into account:
a. For TCCDS systems, parallel windowing and binning is not supported. Therefore, whenever DET.WIN1.BINX or DET.WIN1.BINY is greater than 1 (binning), DET.WIN<i>.ST must be F (and whenever DET.WIN<i>.ST is T, DET.WIN1.BINX and DET.WIN1.BINY must be 1).
b. For SCCDS systems, windowing is supported ONLY if the whole chip read-out is performed through one single output, i.e. for some values, varying from system to system, of DET.READ.CLKIND, windowing may not be supported. For the system in use, the maximum number of windows allowed for each supported read-out mode is shown in the configuration panel (see [16]).
In case of two windows read-out, they must be either completely aligned vertically (DET.WIN2.STRY=DET.WIN1.STRY and DET.WIN2.NY=DET.WIN1.NY) or completely misaligned (DET.WIN2.STRX > DET.WIN1.STRY+DET.WIN1.NY or DET.WIN1.STRY > DET.WIN2.STRY+DET.WIN2.NY).
5. The parameters DET.WIN<i>.STRX, DET.WIN<i>.STRY, DET.WIN<i>.NX and DET.WIN<i>.NY define the location (lower left corner; first pixel in the chip has coordinate 1,1) and size of a window.
6. The parameter DET.READ.SIMIMG is ignored if the operational mode is not ccdSIM_LCU (ACE simulated at LCU level). It defines the file containing the simulated image to be loaded in the LCU in place of the standard synthetic image generation. The path is supposed to be relative to the directory where images are normally stored (see OLDB attribute images.imageDirectory, section 2.16. Useful for testing centroiding algorithms on real images.
2.14.4 Processing
The following parameters are described in the order they are used as shown in the data flow diagram on page 20.
1. The parameter DET.WIN<i>.BIAS is of logical type (T/F) and indicates if a bias subtraction has to be applied to the data for the specified window. It presumes that an image of type Bias is stored in the pool of images on the LCU. See section 2.6 for more information.
2. The parameter DET.WIN<i>.FLATF is of logical type (T/F) and indicates if a flat field division has to be applied to the data for the specified window. It presumes that an image of type Flat is stored in the pool of images on the LCU. See section 2.6 for more information.
3. The parameter DET.WIN<i>.MINMAX is of logical type (T/F) and indicates if statistics (e.g. minimum/maximum, average) has to be computed on the data for the specified window.
4. The parameters DET.WIN<i>.IPLLX/Y, DET.WIN<i>.IPURX/Y define the offsets with respect to the defined window (see DET.WIN<i>.STRX etc.), identifying the sub-window on which the image processing, such as centroiding, has to be performed. IPLLX and IPLLY define respectively the horizontal and vertical offset with from the lower left corner, IPURX and IPURY the same with respect to the upper right corner. As for TCCDS the first column as result of the read-out is always brighter than the rest, it is recommended to exclude it from the image processing; in this case it should be IPLLX = 1, IPLLY = IPURX = IPURY = 0.
5. The parameter DET.WIN<i>.CENTROID indicates the kind of centroiding algorithm wanted for the specified window (see also section 2.6.2). The following values are supported (see ccd.h):
This parameter must always preceed DET.WIN<i>.BACKGND and DET.WIN<i>.THRMIN ; if they are not defined by the user, they are defaulted to resp. ccdBCKGND_FLUX_WINDOW_SELF and ccdTHRMIN_3SIGMA_WINDOW_SELF. Thus attention must be observed in the setting precedence.
6. The parameter DET.WIN<i>.BACKGND defines the background level to be used in the centroiding algorithm when parameter DET.WIN<i>.CENTROID has value ccdCEN_THRESHOLD_STR. It can have any positive value or the following negative values with special meaning (see ccd.h):
a. ccdBCKGND_FLUX_WINDOW_SELF (-1): background level is set to the average value over the related window images:process:window_<i>.ipBGnd.
b. ccdBCKGND_FLUX_WINDOW_PREV (-11): background level is set to the average value over window1 (attribute images:process:window_1.ipBGnd). Meaningful only if set for DET.WIN2.BACKGND and two windows are defined)
7. The parameter DET.WIN<i>.THRMIN defines the threshold level to be used in the centroiding algorithm when parameter DET.WIN<i>.CENTROID has value ccdCEN_THRESHOLD_STR. It can have any positive value or the following negative values with special meaning (see ccd.h):
where s = standard deviation over the background level of the related window (attribute images:process:window_<i>.ipBGnd_SD)
where s = standard deviation over the pixel intensity on window1 (attribute images:process:window_1.ipStdDev). Meaningful only if set for DET.WIN2.THRMIN and two windows are defined.
8. The parameters DET.WIN<i>.REFX and DET.WIN<i>.REFY define the reference point for the computation of the error vector in the centroiding algorithm. These values may be modified during an infinite loop of exposures.
9. The parameter DET.WIN<i>.IPFUNC indicates the name of the user function the CCD LCU sw has to call as last step of the image processing for the specified window. If set to ccdIP_NO_USER_FUN, no user function is called. See also section 2.6.
10. The parameter DET.WIN<i>.IPBUFF indicates the name of a global variable whose address has to be passed to the user function specified by DET.WIN<i>.IPFUNC. If set to ccdIP_NO_USER_BUF, a NULL pointer is passed to the user function. See also section 2.6.
2.14.5 Transfer
1. The parameters DET.DISPLAY specifies the frame Id for the VLT Real-Time display facility (see also [26]). The value ccdNO_DISPLAY (see ccd.h) indicates that images do not need to be displayed.
2. The parameter DET.FRAM.FITSMTD indicates if and how an image has to be saved on disk in FITS format. Currently only ccdDISK_NONE and ccdDISK_UNCOMPRESS are implemented (see ccd.h)
3. The parameter DET.FRAM.FITSUNC specifies the name of the file. It must have suffix .fits. The maximum allowed length is ccdMAXLENFILE (see ccd.h).
4. The parameter DET.FRAM.SAMPLE indicates how frequently images have to be transferred to the Workstation during a loop of repeated exposures. A value of 1 means that all images have to be transferred. A value N higher than 1 means that only one image out of N has to be transferred. Useful to reduce network load if no high refresh rate is needed on Workstation.
It is ignored for single not repeated exposures (DET.EXP.NREP set to 1) or repeated exposures where images are not needed on Workstation (DET.FRAM.FITSMTD set to ccdDISK_NONE and DET.FRAM.DISPLAY set to ccdNO_DISPLAY).
5. The parameter DET.FRAM.XFERSYN is of logical type (T/F) and indicates if the image transfer shall occur synchronously. For single exposures, this flag has little effect: the last exposure in a loop is always transfered synchronously; therefore this parameter is ignored for single exposures. If set to T, the system waits for the image transfer to WS to be completed before running the next exposure in a loop, otherwise it starts the next exposure as soon the readout and image processing are ready.
It is recommended to set this keyword always to T, except special applications requiring high performances at LCU level and using the image transfer only for real-time display of the image.
2.14.6 Multiple Exposure
A multiple exposure is a sequence of integrations separated by a effective shift of the object on the detector. Currently, this feature is only available on Technical CCD. The shift is obtained by moving a given number of lines from the illuminated part to the cache of the CCD.
The exposure type DET.EXP.TYPE must be set to ccdEXP_MULTI_STR. The following parameters are ignored if DET.EXP.TYPE is not ccdEXP_MULTI_STR.
1. The parameter DET.WIN1.NDIT specifies the number of sub-integrations to be performed. The maximum value allowed by the CCD sw is ccdMAXINTEGR (=10).
2. The parameter DET.WIN1.ASUIT1 is of logical type (T/F). If set to T, all sub-integrations have the same time, as specified in DET.WIN1.UIT1, if F, each sub-integration time is defined as in DET.WIN1.UIT<i>.
3. The parameter DET.READ.SHIFTYP determines which type of on-chip rows shift has to be applied between sub-integrations.
a. ccdLINE_SHIFT_ALT_STR. Shift alternatively up and down the amount of rows specified in DET.READ.SHIFT1 (va-et-vient mode, see [3]).
b. ccdLINE_SHIFT_IDEM_STR. Shift always in the same direction the amount of rows specified in DET.READ.SHIFT1.
4. The parameter DET.READ.SHIFT<i> specifies the amount of rows to be shifted after a sub-integration. The sign indicates the direction: if positive, rows are shifted downwards, if negative upwards. The latter is possible only when there are at least two on-chip outputs, one at the bottom and one at the top. In case of TCCDS (one output only at the bottom) only positive values are valid.
Applications handling CCD setup parameters are requested to use the macros defined in ccd.h (e.g. ccdEXP_TYPE).
2.15 Image data
Image data are provided by the CCD DCS software in two ways:
The orientation of the image is independent from the clock pattern used (see request from Fors VLT-LET-VIC-13110-0030): independently from the outputs involved in the readout, the image is displayed and/or stored on file always with the same orientation. This strategy has of course its price, namely that for some clock pattern the whole chip must be read-out before displaying and storing on file the very first pixel; in other words, the overall performance of the system depends heavily on the clock pattern used, as in some cases image readout and image storage must be performed sequentially, in other cases they can be done in parallel (this point does not concern technical CCDs, because only one clock pattern is provided and performances are optimized for that one).
The CCD sw does not know the orientation of the camera with respect to the sky. It thinks exclusively in terms of physical coordinates on the chip.
Location (1,1) corresponds to the first pixel value stored in a FITS file.
2.15.1 Raw-data for real-time display
The CCD software provides raw data for the VLT sw real-time display utility whenever the setup parameter DET.DISPLAY is set to a value higher than ccdNO_DISPLAY. The setting of this parameter determines the frame where the image will be displayed (currently the utility rtd defines frame Id 0 for the big frame and 4 for the rapid frame). The CCD software supports up to 10 different frames Id during the same session (10 different images displayed on different frames).
The mechanism to deliver raw data is the same as defined in [26].
Raw-data are written in shared memory as they come out from the ACE, namely with full resolution (16-bits unsigned integer). No reduction (e.g. to 8-bits) is done by the CCD software.
In addition to the display of the raw-data, the CCD sw supports also the display of World Coordinates through rtd. One point in the CCD branch of the OLDB is dedicated to this feature. It contains two different kind of attributes:
1. Attributes having static values, i.e. they do not change from one exposure to another. They can be set once and forever through the script ccdDcsWcs.sh (see section 3.3).
2. Attributes having values, which may change from one exposure to another. They are part of the public part of the CCD database (see also section 2.16). It is responsibility of applications using CCDs to enter in these attributes the right values at the right time.
2.15.2 FITS files
Images, as result of exposures, are written on WS disk in FITS format (see [4]), whenever the setup parameter DET.FRAM.FITSMTD is other than ccdDISK_NONE (see ccdDISKSAVE in ccd.h).
Currently the only format supported for pixels values is 16-bits signed
Independently from the read-out mode used, the complete physical image is stored in one single FITS file. For multiple windows (currently a maximum of two not overlapping windows is supported), they are also stored in one FITS file with IMAGE extension (see [5]).
The option to get in a second file image data compressed (e.g. to be transferred to a remote station) is not implemented yet (ccdDISK_COMPRESS is treated as ccdDISK_NONE). Only uncompressed data files are produced.
Apart from the image raw data, the CCD software is also responsible to provide keywords for the FITS header. Depending on their type, keywords are treated in two different ways.
· Standard keywords. Some basic keywords, needed by any image analysis system to read the FITS file, are written at the beginning of the file directly by the CCD sw, such that, whatever happens to higher level software (e.g. OS), a readable FITS file is saved, although with basic information only. The number of 80-characters lines reserved by the CCD sw at the beginning of the file is defined by the macro ccdDCSHEADLINES in ccd.h. See also the example given in section 3.8.1
· Hierarchical keywords. They are not strictly needed to interpret the pixel values and normally do not appear at the beginning of the FITS header. Since the CCD sw cannot know at which position in the FITS header they must be written, they are written into a separate file with the same name as the image file and extension defined by the macro ccdFITSHIERSUFF in ccd.h; it is responsibility of the higher level software (e.g. OS for an instrument) to read this file and merge the information contained with the other information collected from the various equipment (e.g. instrument, telescope). See also the example given in section 3.8.2
CCD DCS first writes in these files, then sets the exposure status to ccdEXP_COMPLETED
The responsibility to build image FITS files is shared among DCS and OS (or TCS in case of technical CCDs). The following rules are set by the CCD DCS software:
1. OS sets in the CCD database, before the CCD DCS software is started, the name of the directory where image files must be saved (see 2.16 and ccdConfig in [16] for an alternative interactive way).
3. OS passes to CCD DCS the name of the file as setup parameter before an exposure is started (see ccdCMD_SETUP and ccdFILE_UNC in ccd.h).
4. When read-out is started, CCD DCS looks for the file specified by OS (see point 3.) and opens it for writing.
Note 1: Normally the file should be there and have the size for the complete FITS header (see point 2.). If it is not there, CCD DCS creates it. If it is there, but not accessible (e.g. write protected), CCD DCS tries to create a new one with the same name, followed by a sequential integer index, starting from 1 (see [6]), incrementing the index until it succeeds.
Note 2: In case the number of FITS file to be produced is more than one (e.g. setup parameter exposure repetition factor, see ccdREPEAT_DEF in ccd.h, is set to 3), CCD DCS assumes that all files will have the same name, followed by a sequential integer index, starting from 1. Example:
CCD DCS will look for files myImage.fits (first exposure), myImage.0.fits (second exposure) and myImage.1.fits (third exposure)
If the exposure repetition factorDET.EXP.NREP is set to ccdREPEAT_FOREVER, the file is overwritten and contains the last image.
5. CCD DCS writes the basic standard keywords at the beginning of the file and then moves up to the end of the file (space reserved by OS for the rest of the header).
7. If multiple window read-out has been performed, CCD DCS writes the first extension header after the first frame data, reserves as much space as in the main header and then writes the second frame data.
10. OS retrieves from the CCD database (see section 2.16) the name of the file containing the image. Normally it is the same as the setup values passed by OS, but CCD DCS may have been obliged to change it (see point 4.before).
11. OS collects hierarchical information from all sub-systems, moves ccdDCSHEADLINES from the beginning of the file and writes them. If multiple window read-out has been performed, the same operation has to be done for all extension headers.
OS knows how much space it has reserved for the header and is therefore the only responsible to avoid that the image data section is overwritten with header information.
Note 1: tools and functions for handling image FITS files are provided by the INS common sw (slx, see [24], and oslx, see [25]).
Note 2: in order to get the proper absolute time information in the FITS header (in particular the keyword MJD-OBS) and logs, the CCD LCU has to be properly configured: the tim module has to be loaded if the LCU is connected to the Time Reference System, otherwise the ntp module has to be loaded (see also section 4.6.7).
2.16 Public part of the CCD database
Some attributes of the CCD branch of the on-line database are made public for direct read/write operations from external software. Attributes which are accessed indirectly from external software through commands, functions or panels provided by the CCD software (e.g. all setup attributes set with the command SETUP, configuration attributes read with the function ccdGetConf and set with the panel ccdConfig) are not considered public (no direct call to dbRead/dbWrite CCS functions).
When accessing CCD database attributes with direct CCS db calls, applications are requested to use the macros defined in ccdDbPublic.h: in this way, any change in name or location of the attribute would require just a new compilation.
All database paths below are meant to be relative to the root point for the CCD database branch.
2.16.1 Public part of the CCD Workstation database
The attributes marked with (*) require that the Scan System is working between CCD LCU and WS.
c. exposures:exposure_1:transfer.fileNameUnComp (dbBYTES32) Name of FITS file where uncompressed image data are written. (ccdDB_EXP_FILEUNC1).
As already mentioned in section 2.12, the CCD software provides applications with CCD GUI classes to be incorporated in their own panels. It is strongly recommended to use these classes in application panels. For all cases where this is not possible, the following attributes are made public for usage within GUI panels;.
e. failureWs (dbINT32) Stack Id for asynchronous errors occurring on WS (e.g. the disk is full while transferring the image result of an exposure) (ccdDB_STA_FAILURE_WS).
f. failureLcu (*) (dbINT32) Stack Id for asynchronous errors occurring on LCU (e.g. the image read-out fails) (ccdDB_STA_FAILURE_LCU).
g. temperature.message (*) (dbBYTES256) Message showing a summary of the status of temperature sensors (ccdDB_STA_TMPMESSAGE)
h. telemetry.message (*) (dbBYTES256) Message showing a summary of the status of telemetry sensors (ccdDB_STA_TELMESSAGE)
2.16.2 Public part of the CCD LCU database
c. images:process:window_1.ipXCen (dbDOUBLE) Error vector (x-component) from centroiding calculation. Same for window_2 (ccdDB_IP<index>_XCEN).
d. images:process:window_1.ipYCen (dbDOUBLE) Error vector (y-component) from centroiding calculation. Same for window_2 (ccdDB_IP<index>_YCEN).
e. images:process:window_1.ipCenVal (dbDOUBLE) Value of the pixel closest to the computed centroid position. Same for window_2 (ccdDB_IP<index>_CENVAL).
f. images:process:window_1.ipXMin (dbINT32) Horizontal position of pixel with minimum intensity. Same for window_2 (ccdDB_IP<index>_XMIN).
g. images:process:window_1.ipYMin (dbINT32) Vertical position of pixel with minimum intensity. Same for window_2 (ccdDB_IP<index>_YMIN).
h. images:process:window_1.ipMinVal (dbDOUBLE) Minimum intensity. Same for window_2 (ccdDB_IP<index>_MINVAL).
i. images:process:window_1.ipXMax (dbINT32) Horizontal position of pixel with maximum intensity. Same for window_2 (ccdDB_IP<index>_XMAX).
j. images:process:window_1.ipYMax (dbINT32) Vertical position of pixel with maximum intensity. Same for window_2 (ccdDB_IP<index>_YMAX).
k. images:process:window_1.ipMaxVal (dbDOUBLE) Maximum intensity. Same for window_2 (ccdDB_IP<index>_MAXVAL).
l. images:process:window_1.ipFlux (dbDOUBLE) Average pixel intensity value. Same for window_2 (ccdDB_IP<index>_FLUX).
m. images:process:window_1.ipStdDev (dbDOUBLE) Pixels intensity standard deviation. Same for window_2 (ccdDB_IP<index>_STDDEV).
n. images:process:window_1.ipNumPix (dbINT32) Total number of pixels with intensity higher than 0 after background subtraction and thresholding. Same for window_2 (ccdDB_IP<index>_NUMPIX).
o. images:process:window_1.ipSNR (dbDOUBLE) Estimated Signal-to-Noise Ratio. Same for window_2 (ccdDB_IP<index>_SNR).
p. images:process:window_1.ipBGnd (dbDOUBLE) Background intensity estimation. Same for window_2 (ccdDB_IP<index>_BGND).
q. images:process:window_1.ipBGnd_SD (dbDOUBLE) Std Dev. on background intensity estimation. Same for window_2 (ccdDB_IP<index>_BGND_SD).
r. images:process:window_1.ipFWHM_X (dbDOUBLE) Object FWHM estimation along X-axis. Same for window_2 (ccdDB_IP<index>_FWHM_X).
s. images:process:window_1.ipFWHM_Y (dbDOUBLE) Object FWHM estimation along Y-axis. Same for window_2 (ccdDB_IP<index>_FWHM_Y).
2.17 Configuration and operational logs
The CCD sw logs the main operations it performs, using the VLT CCS Logging System, in FITS format. Examples of logs produced by the CCD sw are given in section 3.9
According to the syntax specified in [5], the last part of the log message must contain a source mask, in order to identify the sub-system the log is coming from. As CCD cameras are used in many different sub-systems, this mask cannot be set by the CCD sw itself, but must be defined and set by the sub-system using it. A script, to be executed once when configuring the CCD sw (see sections 4.6.6 and 4.6.10) and called ccdDcsSetLogMask.sh (see also section 3.3) is dedicated to this purpose. Examples:
2.18 Examples for Technical CCD Camera
2.18.1 Usage of CCD technical cameras
The following example is a Sequencer script available on tape (file <TAPE>/CCD/ccdcon/ws/test/ccdconTestTec.tcl).
In the following we consider the case of cameras used for auto-guiding (AG)
2.18.2 Full Frame setup
The following setup is typically used by the Active Optics.
DET.EXP.TYPE "Normal "; # Type of exposure as known to the CCD sw
DET.EXP.NREP 1; # Single exposure
DET.READ.CLKIND 1; # Index of clock pattern used
DET.OUT1.GAININD 8; # Gain index for output
DET.WIN1.UIT1 30.000; # user defined subintegration time
DET.WIN1.BINX 1; # Binning factor in X
DET.WIN1.BINY 1; # Binning factor along Y
DET.DISPLAY -1; # no real-time image display
DET.FRAM.FITSMTD 0; # no data save on disk
DET.FRAM.SAMPLE 1; # Image sampling on workstation
DET.FRAM.XFERSYN T; # Image transfer synchronous
DET.FRAM.TYPE "Normal "; # Type of frame
DET.WIN1.ST "F"; # Full Frame
DET.WIN1.BIAS "F"; # no bias frame subtraction performed
DET.WIN1.FLATF "F"; # no flat field division performed
DET.WIN1.MINMAX "F"; # no image extrema search performed
DET.WIN1.CENTROID "none "; # no centroiding calculation
DET.WIN1.IPFUNC "None "; # no User Function
DET.WIN2.ST "F"; # Full Frame
DET.WIN2.BIAS "F"; # no bias frame subtraction performed
DET.WIN2.FLATF "F"; # no flat field division performed
DET.WIN2.MINMAX "F"; # no image extrema search performed
DET.WIN2.CENTROID "none "; # no centroiding calculation
DET.WIN2.IPFUNC "None "; # no User Function
2.18.3 1 Window setup
The following setup is typically used by the TCS Autoguider/Field Stabilization.
DET.EXP.TYPE "Normal "; # Exposure type
DET.WIN1.UIT1 0.010; # user defined subintegration time
DET.EXP.NREP 0; # infinite loop
DET.EXP.WIPETIM 0; # wipe before each exposure
DET.READ.CLKIND 1; # Index of clock pattern used
DET.OUT1.GAININD 8; # Gain index for output
DET.FRAM.FITSMTD 0; # No Data storage
DET.DISPLAY 0; # real-time image display frame ID
DET.WIN1.BINX 1; # Binning factor along X
DET.WIN1.BINY 1; # Binning factor along Y
DET.FRAM.SAMPLE 1; # Image sampling on workstation
DET.FRAM.TYPE "Normal "; # Type of frame
DET.FRAM.XFERSYN "F"; # Asynchronous transfer
DET.EXP.TIMEREP 1.000000; # Time between two repeated exposures
DET.WIN1.ST "T"; # One Window
DET.WIN1.STRX 209; # Lower left pixel in X
DET.WIN1.NX 25; # # of pixels along X
DET.WIN1.STRY 134; # Lower left pixel in Y
DET.WIN1.NY 25; # # of pixels along Y
DET.WIN1.CENTROID "threshold"; # type of centroiding calculation
DET.WIN1.BACKGND -1.000000; # sky background
DET.WIN1.THRMIN -3.000000; # lower threshold
DET.WIN1.REFX 221.773; # X position of reference
DET.WIN1.REFY 146.590; # Y position of reference
DET.WIN1.MINMAX "F"; # image extrema search performed
DET.WIN1.IPFUNC "None "; # user defined function name
DET.WIN1.IPBUFF "None "; # buffer variable in user function
DET.WIN1.BIAS "F"; # bias frame subtraction performed
DET.WIN1.FLATF "F"; # flat field division performed
DET.WIN1.IPLLX 1; # X offset from bottom left for proc. sub-window
DET.WIN1.IPURX 1; # X offset from top right for proc. sub-window
DET.WIN2.ST "F"; # Window 1 only
2.18.4 2 Window setup
The following setup is typically used by the Astronomical Site Monitor in Seeing mode (DIMM).
DET.EXP.TYPE "Normal "; # Exposure type
DET.EXP.NREP 800; # number of repeated exposures
DET.READ.CLKIND 1; # Index of clock pattern used
DET.OUT1.GAININD 8; # Gain index for output
DET.FRAM.FITSMTD 0; # Data storage method
DET.DISPLAY 0; # real-time image display frame ID
DET.WIN1.BINX 1; # Binning factor along X
DET.WIN1.BINY 1; # Binning factor along Y
DET.FRAM.SAMPLE 20; # Image sampling on workstation
DET.FRAM.TYPE "Normal "; # Type of frame
DET.EXP.TIMEREP 0.00; # Time between two repeated exposures
DET.FRAM.XFERSYN "F"; # asynchronous image transfer
DET.EXP.WIPETIM 0; # wipe before starting exposure
DET.WIN1.ST "T"; # If T, window enabled
DET.WIN1.STRX 158; # Lower left pixel in X
DET.WIN1.NX 31; # # of pixels along X
DET.WIN1.STRY 125; # Lower left pixel in Y
DET.WIN1.NY 30; # # of pixels along Y
DET.WIN1.CENTROID "threshold"; # type of centroiding calculation
DET.WIN1.REFX 184.00; # X position of reference
DET.WIN1.REFY 144.00; # Y position of reference
DET.WIN1.MINMAX "T"; # image extrema search performed
DET.WIN1.IPFUNC "asmdimUSR"; # user defined function name
DET.WIN1.IPBUFF "None "; # buffer variable in user function
DET.WIN1.BIAS "F"; # bias frame subtraction performed
DET.WIN1.FLATF "F"; # flat field division performed
DET.WIN1.BACKGND -1.000000; # sky background
DET.WIN1.THRMIN -3.000000; # lower threshold
DET.WIN1.IPLLX 1; # X offset from bottom left
DET.WIN1.IPLLY 0; # Y offset from bottom left
DET.WIN1.IPURX 0; # X offset from top right
DET.WIN1.IPURY 0; # Y offset from top right
DET.WIN2.ST "T"; # If T, window enabled
DET.WIN2.STRX 200; # Lower left pixel in X
DET.WIN2.NX 31; # # of pixels along X
DET.WIN2.STRY 125; # Lower left pixel in Y
DET.WIN2.NY 30; # # of pixels along Y
DET.WIN2.CENTROID "threshold"; # type of centroiding calculation
DET.WIN2.REFX 212.00; # X position of reference
DET.WIN2.REFY 144.00; # Y position of reference
DET.WIN2.MINMAX "T"; # image extrema search performed
DET.WIN2.IPFUNC "asmdimUSR"; # user defined function name
DET.WIN2.IPBUFF "None "; # buffer variable in user function
DET.WIN2.BIAS "F"; # bias frame subtraction performed
DET.WIN2.FLATF "F"; # flat field division performed
DET.WIN2.BACKGND -1.000000; # sky background
DET.WIN2.THRMIN -3.000000; # lower threshold
DET.WIN2.IPLLX 1; # X offset from bottom left
DET.WIN2.IPLLY 0; # Y offset from bottom left
DET.WIN2.IPURX 0; # X offset from top right
DET.WIN2.IPURY 0; # Y offset from top right
DET.WIN1.NDIT 1; # # of subintegrations
DET.WIN1.ASUIT1 "T"; # All UITi as UIT1 else as defined in UITi
DET.WIN1.UIT1 0.010; # user defined subintegration time
# --- oOo ---
2.18.5 Multiple exposure setup
The following setup is typically used by the Astronomical Site Monitor in WaveFront Coherence mode.
DET.EXP.TYPE "Multiple"; # Exposure type
DET.EXP.NREP 400; # number of repeated exposures
DET.READ.CLKIND 1; # Index of clock pattern used
DET.OUT1.GAININD 8; # Gain index for output
DET.FRAM.FITSMTD 0; # Data storage method
DET.DISPLAY 0; # real-time image display frame ID
DET.WIN1.BINX 1; # Binning factor along X
DET.WIN1.BINY 1; # Binning factor along Y
DET.FRAM.SAMPLE 10; # Image sampling on workstation
DET.FRAM.TYPE "Normal "; # Type of frame
DET.EXP.TIMEREP 0.00; # Time between two repeated exposures
DET.FRAM.XFERSYN "F"; # If T, image transfer occurs synchronously
DET.EXP.WIPETIM 0; # wipe before starting exposure in a loop
DET.WIN1.ST "T"; # If T, window enabled
DET.WIN1.STRX 94; # Lower left pixel in X
DET.WIN1.NX 32; # # of pixels along X
DET.WIN1.STRY 1; # Lower left pixel in Y
DET.WIN1.NY 290; # # of pixels along Y
DET.WIN1.CENTROID "none "; # type of centroiding calculation
DET.WIN1.REFX 128.00; # X position of reference
DET.WIN1.REFY 207.00; # Y position of reference
DET.WIN1.MINMAX "F"; # image extrema search performed
DET.WIN1.IPFUNC "ccdipWCE"; # user defined function name
DET.WIN1.IPBUFF "None "; # buffer variable in user function
DET.WIN1.BIAS "F"; # bias frame subtraction performed
DET.WIN1.FLATF "F"; # flat field division performed
DET.WIN1.BACKGND -1.000000; # sky background
DET.WIN1.THRMIN -3.000000; # lower threshold
DET.WIN1.IPLLX 1; # X offset from bottom left for proc. sub-window
DET.WIN1.IPLLY 0; # Y offset from bottom left for proc. sub-window
DET.WIN1.IPURX 0; # X offset from top right for proc. sub-window
DET.WIN1.IPURY 0; # Y offset from top right for proc. sub-window
DET.WIN2.ST "T"; # If T, window enabled
DET.WIN2.STRX 132; # Lower left pixel in X
DET.WIN2.NX 32; # # of pixels along X
DET.WIN2.STRY 1; # Lower left pixel in Y
DET.WIN2.NY 290; # # of pixels along Y
DET.WIN2.CENTROID "none "; # type of centroiding calculation
DET.WIN2.REFX 128.00; # X position of reference
DET.WIN2.REFY 207.00; # Y position of reference
DET.WIN2.MINMAX "F"; # image extrema search performed
DET.WIN2.IPFUNC "ccdipWCE"; # user defined function name
DET.WIN2.IPBUFF "None "; # buffer variable in user function
DET.WIN2.BIAS "F"; # bias frame subtraction performed
DET.WIN2.FLATF "F"; # flat field division performed
DET.WIN2.BACKGND -1.000000; # sky background
DET.WIN2.THRMIN -3.000000; # lower threshold
DET.WIN2.IPLLX 1; # X offset from bottom left for proc. sub-window
DET.WIN2.IPLLY 0; # Y offset from bottom left for proc. sub-window
DET.WIN2.IPURX 0; # X offset from top right for proc. sub-window
DET.WIN2.IPURY 0; # Y offset from top right for proc. sub-window
DET.WIN1.NDIT 10; # # of subintegrations
DET.WIN1.ASUIT1 "T"; # All UITi as UIT1 else as defined in UITi
DET.READ.SHIFTYP "idem "; # Line shift type
DET.READ.SHIFT1 29; # Lines shifted between integration
DET.WIN1.UIT1 0.001; # user defined subintegration time
# --- oOo ---
2.19 Examples for Scientific CCD Camera
2.19.1 Usage of CCD scientific cameras
The following example is a Sequencer script available on tape (file <TAPE>/CCD/ccdcon/ws/test/ccdconTestSci.tcl).
In the following we consider the case of an instrument not handling parallel exposures with the same camera (see 2.2)
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|
