| |
|
|
|
2 USER'S GUIDE
This part of the document provides a description of the programmatic interface of the FIERA CCD sw. It gives software engineers, writing applications using a FIERA CCD controller, information on what they have to implement in their code to be able to interact with the FIERA CCD sw.
For people having no experience with the FIERA CCD sw, it is highly recommendable, although not necessary, before starting to read this section, to first look at the interactive usage of the FIERA CCD sw as stand-alone instrument (see Chapter 8) and if possible to try it out. This exercise can help you get a better idea of the way how the FIERA CCD sw works and its functionality.
2.1 Overview
The FIERA CCD Detectors Control Software is distributed over two hardware platforms: WS and the FIERA "Embedded Computer" or SLCU (SPARC based LCU), with a SPARC CPU and two TMS320C40 DSPs (see [5]).
For a description of the hardware and software needed to run the FIERA CCD sw, see section 5.2.
A program accesses the functionality provided by the FIERA CCD sw in the following way:
1. It retrieves information about configuration and status of the CCD camera through functions available in the library libfcd (see section 2.12). 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.14.4).
2. It asks the FIERA CCD sw for services by means of commands using the CCS message system (see section 2.11).
3. It can use the CCS event system to be informed about changes of status of the FIERA CCD system (see section 2.17).
The resulting image data can be returned as a FITS file format and/or as raw data to be shown through an online display.
Note: In the examples shown in the next sections we use the following setting:
2.2 Parallelism
One of the main requirements for the FIERA CCD sw is to optimize observation time, performing operations in parallel as much as possible.
For this reason, the portion of the image which has already been read out is 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 readout and image transfer ensures that the time interval between the end of the readout and the completion of image display or FITS file on disk is minimized. For most applications using CCDs this level of parallelism is fully sufficient to fulfill the performance requirements: most applications will only be concerned with one active exposure at any given time.
On the other hand, some applications (e.g., very large CCDs) may need to push optimization further and therefore control more than one exposure at a given time (e.g., next integration is started as soon the readout is completed, but the last portion of the image is still being transferred to the Workstation).
It has however to be remembered that this further optimization introduces complexity in the application: pro (better performance) and contra (complexity) should therefore be carefully evaluated.
Since more than one exposure can be active at a given point in time, the FIERA CCD sw provides several identical points in the on-line database, where information about one running exposure is stored (in the current release points exposures:exposure_1 and exposures:exposure_2 are provided).
Whenever a new exposure is started, and no exposure is already running, the point exposures:exposure_1 is always selected by the FIERA CCD sw to store information related to that exposure.
Applications not handling parallel exposures must therefore always look for information in exposures:exposure_1 and can ignore all other identical points.
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 those running, an identification number is associated to each exposure.
The exposure Id used by the FIERA CCD sw for this purpose is an integer sequential number (vltINT32).
· either passed to the FIERA CCD DCS software as a parameter of the command START (as defined in the INS Common Software document [3]),
· or generated by the FIERA CCD DCS software, in case the command START had no parameter (this in order to keep compatibility with the previous LCU based ESO CCD Control Software, see [17]).
The exposure Id is always returned as reply parameter to the command START.
Applications handling more than one running exposure at a time (see 2.2) must pass this Id as parameter to all commands dealing with a running exposure (e.g. ABORT, see section 4.2.1).
Special values (see fcd.h) can be used; applications are encouraged to use them whenever possible:
As described in [17], if the OS does not pass the exposure Id parameter with the START command, the Id generated by the FIERA CCD DCS is just an Id used in the communication between the FIERA CCD sw and external sw (e.g. INS OS). In particular:
1. The OS expoId follows the directions of [3] and is generated by OS. It is used to communicate between OS and the software on top of it (GUI panel, Sequencer etc.).
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).
a. Command SETUP. For exposures not started yet (command START not sent yet), always use fcdEXP_NEXT (-1) as expoId parameter.
c. Other commands related to a running exposure (ABORT etc.). They need an Id as a parameter. If only one exposure is still running (normal cases) one can use always fcdEXP_LAST (0) as Id. If more exposures are running in different phases (quite unusual), then the value returned by the FIERA CCD sw to the START command has to be passed as Id.
2.3.2 Exposure types
The FIERA CCD DCS distinguishes among different types of exposure (see [5]).
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 fcdREADSHIFT in file fcd.h).
It is the responsibility of higher level software (e.g. Observation Software) to translate the various supported exposure types as defined in [4] into one of the types known by FIERA CCD DCS for the setup parameter DET<i>.EXP.TYPE. We recommend using variables of the type fcdEXPTYPE or the macros associated with the corresponding strings (e.g. fcdEXP_DARK_STR), defined in fcd.h, for all operations dealing with the FIERA CCD DCS exposure type.
2.3.3 Exposure status
An attribute in the on-line database (exposures:exposure<index>.expStatus, see also section 2.14.4) 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 (least 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 FIERA CCD sw in the reply of 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 anymore (e.g. because a new exposure has been started), the returned status is fcdEXP_DONE (see fcd.h)
See also file fcd.h for all macros and associated values (e.g. fcdEXP_INACTIVE).
2.4 Operational modes and simulation
A detailed description of the operational modes implemented and their meaning is given in Chapter 8.
The operational mode can be set:
The current operational mode can be retrieved through the command STATUS (see 2.11).
We recommend using variables of the type fcdOPMODE, defined in fcd.h, for all operations dealing with the FIERA CCD sw operational mode
Note: Any change to the current operational mode takes effect only after the FIERA CCD sw is brought to OFF state (Shutdown, see also 2.5).
2.5 Operational states
The list of operational states implemented in the FIERA CCD sw is given in section 8.7. In Table 1 are shown the commands needed to modify in the operational state of a CCD camera.
See section 2.11 for more information about commands available.
The current operational state can be retrieved through the command STATUS (see 2.11).
We recommend using variables of the type fcdSTATE, defined in fcd.h, for all operations dealing with the FIERA CCD sw operational state.
2.6 Image processing
The FIERA CCD sw provides facilities to perform real-time image processing on the FIERA SLCU while the image data are being readout and before they are transferred to Workstation.
Currently these facilities consist of:
1. Computation of minimum and maximum pixel values in the image (see section 2.14.2 on setup parameter DET<i>.WIN<i>.MINMAX). The results are stored in the SLCU on-line database in the same sequential order as below:
2. Computation of rms of the pixel values in the image (see section 2.14.2 on setup parameter DET<i>.WIN<i>.RMS). The result is stored in the SLCU on-line database in:
3. Calculation of centroiding over an image. 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 considered to be 0), and finally computes the centre of gravity of the resulting image. The way that the background and threshold are determined is discussed in section 2.14.2 (setup parameter DET.WIN<i>.CENTROID).
4. Additional processing. An additional function may be invoked after the centroiding algorithm, currently the function IQE is implemented which performs a gaussian fit to determine an accurate centroid and full-width half-maximum. see section 2.14.2 (setup parameter DET.WIN<i>.IPFUNC).
Steps 1-4 can be individually enabled or disabled. If more than one is enabled they are performed sequentially in the order given above. The results of the centroiding and IQE function are stored in the attributes below:
a. images:process:window<index>.ipXCen. Difference between X coordinate of centre of gravity and reference position.
b. images:process:window<index>.ipYCen. Difference between Y coordinate of centre of
gravity and reference position.
If no object is found during the centroid or IQE function, all attributes are set to 0.
2.7 Telemetry Monitoring
The FIERA CCD sw provides facilities to monitor telemetry (temperature and pressure) values from the detector.
Telemetry is configured using the configuration panel fcdConfigTel, and can be displayed using the panel fcdTelemetry.
The telemetry sub-system is enabled and disabled using the commands STARTTL and STOPTL. The current telemetry values are available in the database attribute telemetry.current.
2.8 Startup
The FIERA CCD DCS software provides a cold startup script. It performs a complete startup, including operations which are needed only once at the beginning of a session, such as loading the on-line database with the configuration values for the camera used. This script has to be run at least once at the beginning of a session.
Type from the Workstation shell (see also manual page at section 4.3):
Additionally, the FIERA CCD DCS software provides a warm startup script, which only schedules the CCD processes, and assumes that the rest (database, CDTs, scan system) has already been configured.
Type from the Workstation shell (see also manual page at section 4.3):
2.8.1 Startup verification
To verify if the FIERA 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 SLCU environment (use option Rtap Perf. Monitor from ccsei to check):
2.9 Shutdown
The FIERA CCD DCS software provides a shutdown script.
Type from the Workstation shell (see also manual page at section 4.3):
2.9.1 Powering Down the FIERA SPARC
If you intend to power down the FIERA SPARC, it is essential that the SPARC is "halted" first.
Type from the Workstation Shell:
After the connection has been closed, wait 1 minute, it is then safe to power down the SPARC. The SPARC will boot automatically when it is powered up again.
2.9.2 Rebooting the FIERA SPARC
If you intend to reboot the FIERA SPARC, type from the Workstation Shell:
2.10 Include files
Applications interfacing to the FIERA CCD DCS software have to include the file fcd.h (see also 4.5).
2.11 Command Interface
The only FIERA CCD process accessible via CCS commands from external software is fcdconCI_$CCDNAME, running on the Workstation (e.g. if CCDNAME is set to myccd, the process name is fcdconCI_myccd).
The command interface between the FIERA CCD software and external software is represented by the Command Definition Table of that process.
Here a simple list of all the commands foreseen is given. For more details, see Command Definition Table at section 4.2.1
3. 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 (not yet implemented).
10. Setup. Define or check setup values for next exposure or change values for the specified running exposure. See also sections 2.14.2 and 4.7.1.
12. Start. Start new exposure (possibly repeated). Setup parameters can be specified as well. One single reply is returned as soon as the exposure has started.
External applications are recommended to use the macros for commands and parameters as specified in fcd.h (e.g. command fcdCMD_SETUP parameter fcdEXP_TYPE)
2.12 C libraries
The library libfcd provides routines for external software:
1. fcdGetConf. Get the current camera configuration (see also types fcdCAMERA and fcdCONFIG in fcd.h). See manual page in section 4.1
2. fcdGetCIName. Get name of the CCD process to send commands to (see also section 2.11). See manual page in section 4.1
3. fcdGetIndexFromId. Get index of database point for an exposure from its Id. See manual page in section 4.1
4. fcdCheckSetup. Check a complete setup and return computed values (see types fcdSETUP and fcdSETUPRES in fcd.h). See manual page in section 4.1
2.13 Graphical User Interface CCD classes
Applications using the FIERA CCD sw are provided 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 libfcdGuiPublic.tcl (which has to be registered to any panel using it, see [11]):
1. fcdExpStatus_uifClass. It displays the status of an exposure. See also Fig.2 and manual page at section 4.4
2. fcdExpSetup_uifClass. It displays the main setup parameters of the most recently started exposure. See also Fig.2 and manual page at section 4.4
3. fcdReadoutSetup_uifClass. It displays the readout setup parameters of the most recently started exposure. See also Fig.2 and manual page at section 4.4
4. fcdIpStatus_uifClass. It displays the status of real-time image processing on SLCU. See also Fig.4 and manual page at section 4.4.
2.14 Data
2.14.1 Data Interface Dictionary
The FIERA CCD sw needs two Data Interface Dictionary files to be able to operate with setup keywords and files and to create proper headers in FITS files:
1. The first dictionary is the generic CCD Dictionary (see [17]). The name of this dictionary is specified through the environment variable CCDDID (see [17] and section 5.6.1). The default generic CCD dictionary (if CCDDID is not defined) is CCDDCS (full name ESO-VLT-DIC.CCDDCS).
2. The second dictionary is the FIERA CCD Dictionary. The name of this dictionary is specified through the environment variable FCDDID (see section 5.6.1). The default FIERA CCD dictionary (if FCDDID is not defined) is FCDDCS (full name ESO-VLT-DIC.FCDDCS).
REMARK: These files still need approval from the ESO Data Interface Control Board. The contents is just a proposal and might be affected by substantial changes.
2.14.2 Setup parameters and files
Among all kinds of setup files defined in [3], the FIERA 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).
Currently not all setup keywords as defined in the CCD DCS Data Dictionaries (see 2.14.1) are implemented in the FIERA CCD DCS software. The keywords implemented are listed in the setup file shown in section 4.7.1 (at this stage it represents a complete setup file for FIERA CCD DCS). Information about the parameters for the SETUP command are also given in the CDT of fcdconCI (section 4.2.1) and in the include file fcd.h (section 2.10)
Some remarks on the implemented setup parameters:
1. The parameter DET<i>.EXP.TYPE can have the following string values (see section 2.3.2 and fcd.h):
Applications interested in knowing the intermediate status of an exposure must set DET<i>.EXP.NREP to 1 (no repetition).
3. The parameter DET<i>.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).
4. The parameter DET<i>.FRAM.TYPE indicates the type of frame resulting from the next exposure. The SLCU CCD sw keeps in memory at any time the last acquired image until it is overwritten by a new exposure. The image can be retrieved at any time by the DUMP command (e.g., in case of image transmission failures or problems on the instrument workstation).
5. The parameter DET<i>.WIN1.UIT<i> specifies the integration time in seconds of each integration step. If DET.EXP.TYPE is not fcdEXP_MULTI_STR, only UIT1 is used.
6. The parameter DET<i>.WIN1.NDIT specifies the number of sub-integrations to be performed. The maximum value permitted by the CCD S/W is 10 (fcdMAXINTEGR in fcdDbPublic.h). This value is used only if DET.EXP.TYPE is set to fcdEXP_MULTI_STR.
7. The parameter DET<i>.WIN1.ASUIT1 is ignored if DET<i>.EXP.TYPE is not set to fcdEXP_MULTI_STR. It is of logical type (T/F). If set to T, all sun-integrations are given the same time as specified for DET<i>.WIN1.UIT1.
8. The parameter DET<i>.READ.SHIFT<i> specifies the amount of rows to be shifted after a sub-integration. Lines are shifted towards the serial register specified by the DET<i>.READ.CLKIND.
9. The parameter DET<i>.READ.SHIFTYP determines which type of on-chip rows shift has to be applied between sub-integrations. It is ignored if DET<i>.EXP.TYPE is not fcdEXP_MULTI_STR. Possible values are (see fcd.h):
a. fcdLINE_SHIFT_IDEM_STR. Shift always in the same direction the amount of rows specified in DET<i>.READ.SHIFT1.
10. The parameter DET<i>.READ.CLKIND is an integer number (range 0-19). It determines which readout mode has to be used. This choice determines automatically the readout speed and the number and location of on-chip outputs used (see also panel fcdConfig to find the correspondence between this index and the characteristics of the associated readout). This choice does NOT determine the binning to be applied to the readout, which is set by DET<i>.WIN1.BINX and DET<i>.WIN1.BINY (see below).
11. The parameters DET<i>.WIN1.BINX and DET<i>.WIN1.BINY define the binning to be applied to the readout.
In the current release of the FIERA CCD software, the same binning factor (set by DET<i>.WIN1.BINX and DET<i>.WIN1.BINY) applies to all defined windows.
12. The parameter DET<i>.FRAM.FITSMTD indicates if and how an image is to be saved on disk in FITS format. Currently only fcdDISK_NONE and fcdDISK_UNCOMPRESS are implemented (see fcd.h).
13. The parameter DET<i>.FRAM.FITSUNC specifies the name of the file. It must have suffix .fits. The maximum allowed length is fcdMAXLENFILE (see fcd.h).
14. The parameters DET<i>.DISPLAY specifies the frame Id for the VLT Real-Time display facility. The value fcdNO_DISPLAY (see fcd.h) indicates that images do not need to be displayed.
15. The parameter DET<i>.FRAM.SAMPLE indicates how frequently images have to be transferred to the Workstation during a loop of repeated exposures (e.g., for Adaptive Optics systems). 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<i>.EXP.NREP set to 1) or repeated exposures where images are not needed on Workstation (DET<i>.FRAM.FITSMTD set to fcdDISK_NONE and DET<i>.FRAM.DISPLAY set to fcdNO_DISPLAY).
16. The parameter DET<i>.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<i>.WIN1.ST and DET<i>.WIN2.ST). There are however limitations to be taken into account:
a. in the current release of the FIERA CCD software, windowing is supported ONLY if the whole chip readout is performed through one single output, i.e. for some values, varying from system to system, of DET<i>.READ.CLKIND, windowing may not be supported.
17. The parameters DET<i>.WIN<i>.STRX, DET<i>.WIN<i>.STRY, DET<i>.WIN<i>.NX and DET<i>.WIN<i>.NY define the location (referred to the first pixel of the chip, see section 1.6) and size of a window.
18. The parameter DET<i>.WIN<i>.MINMAX is of logical type (T/F) and indicates if statistics (minimum/maximum, average) has to be computed on the data for the specified window.
19. The parameter DET<i>.WIN<i>.RMS indicates if and where the rms has to be computed on the data for the specified window (0 for no rms, 1 for rms on the whole window, 2 for rms on the central quarter of the window).
20. The parameter DET<i>.WIN<i>.CENTROID indicates the kind of centroiding algorithm wanted for the specified window. The following values are supported (see fcd.h):
21. The parameter DET<i>.WIN<i>.BACKGND defines the background level to be used in the centroiding algorithm when parameter DET<i>.WIN<i>.CENTROID has value fcdCEN_THRESHOLD_STR. It can have any positive value or the following negative values with special meaning (see fcd.h):
a. fcdBCKGND_FLUX_WINDOW_SELF: background level is set to the average value over the related window.
b. fcdBCKGND_FLUX_WINDOW_PREV: background level is set to the average value over window 1 (meaningful only if set for DET<i>.WIN2.BACKGND and two windows are going to be read-out).
22. The parameter DET<i>.WIN<i>.THRMIN defines the threshold level to be used in the centroiding algorithm when parameter DET<i>.WIN<i>.CENTROID has value fcdCEN_THRESHOLD_STR. It can have any positive value or the following negative values with special meaning (see fcd.h):
b. -10>N>-20: threshold level is set to N *s1 (s1 = standard deviation over the window 1). Meaningful only if set for DET<i>.WIN2.THRMIN and two windows are going to be read-out.
23. The parameter DET<i>.WIN<i>.IPFUNC indicates the name of the additional function the CCD SLCU sw has to call as last step of the image processing for the specified window. If set to fcdIP_NO_USER_FUN, no user function is called. See also section 2.6.
24. The parameters DET<i>.WIN<i>.IPLLX, DET<i>.WIN<i>.IPLLY, DET<i>.WIN<i>.IPURX and DET<i>.WIN<i>.IPURY define the offsets with respect to the defined window (see DET<i>.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.
25. The parameters DET<i>.WIN<i>.REFX and DET<i>.WIN<i>.REFY define the reference point (in absolute coordinates) for the computation of the error vector in the centroiding algorithm.
Applications handling CCD setup parameters are requested to use the macros defined in fcd.h (e.g. fcdEXP_TYPE).
2.14.3 Image data
Image data are provided by the FIERA CCD DCS software in two ways:
The orientation of the image is independent from the readout mode 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.
In the current release of the FIERA CCD software, this means that for some readout mode the whole chip must be readout before displaying and writing to disk the very first pixel; in other words, the overall performance of the system depends heavily on the readout mode used, as in some cases image readout and image storage must be performed sequentially, in other cases they can be done in parallel.
The FIERA 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.14.3.1 Proposed "image extension per port" format
A new FITS format has been proposed, allowing the usage of "image extensions" per port. This format has not been officially defined yet (details of this format are still under discussion with the DMD), therefore its use is recommended only for test purposes.
This format orders data by output i.e. each output used for readout corresponds to an extension. A primary header sits on the top of the file. In order to use this FITS format, it is necessary, using the configuration panel, to set the relevant option (see 8.1). It is also required to define the FCD_IT_HOST environment variable (see 5.6.1).
2.14.3.2 Raw-data for real-time display
the FIERA CCD sw provides raw data for the VLT sw real-time display utility whenever the setup parameter DET<i>.DISPLAY is set to a value higher than fcdNO_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, see [15]). The FIERA CCD sw 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 [15].
Raw-data are written in shared memory as they come out from the Detector Electronics, namely with full resolution (16-bits unsigned integer). No reduction (e.g. to 8-bits) is done by the FIERA CCD sw.
In addition to the display of the raw-data, the FIERA 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 fcdDcsWcs.sh (see section 4.3).
2. Attributes having values, which may change from one exposure to another. They are part of the public part of the FIERA CCD database (see also section 2.14.4). It is responsibility of applications using CCDs to enter in these attributes the correct values at the appropriate time.
2.14.3.3 FITS files
Images, as result of exposures, are written on WS disk in FITS format (see [3]), whenever the setup parameter DET<i>.FRAM.FITSMTD is other than fcdDISK_NONE (see fcdDISKSAVE in fcd.h).
Currently the only format supported for pixels values is 16-bits signed.
Independently from the readout mode used, the complete physical image is stored in one single FITS file. For multiple windows (currently a maximum of two not overlapping windows - see definition in section 1.6 - is supported), they are also stored in one FITS file with IMAGE extension (see [4]).
NOTE: The file format for multiple port readout is under discussion.
Apart from the image raw data, the FIERA CCD sw is also responsible for providing 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 FIERA 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 FIERA CCD sw at the beginning of the file is defined by the macro fcdDCSHEADLINES in fcd.h. See also the example given in section 4.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 FIERA 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 fcdFITSHIERSUFF in fcd.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).
FIERA CCD DCS first writes in these files, then sets the exposure status to fcdEXP_COMPLETED.
The responsibility to build image FITS files is shared among DCS and OS. The following rules are set by the FIERA CCD DCS software:
1. OS sets in the FIERA CCD database, before the FIERA CCD DCS software is started, the name of the directory where image files must be saved (see 2.14.4 and fcdConfig in 8.1 and 9.1.4 for an alternative interactive way).
3. OS passes to FIERA CCD DCS the name of the file as setup parameter before an exposure is started (see fcdCMD_SETUP and fcdFILE_UNC in fcd.h).
4. When readout is started, FIERA 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, FIERA CCD DCS creates it. If it is there, but not accessible (e.g. write protected), FIERA CCD DCS tries to create a new one with the same name, followed by a sequential integer index, starting from 1, 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 fcdREPEAT_DEF in fcd.h, is set to 3), FIERA CCD DCS assumes that all files will have the same name, followed by a sequential integer index, starting from 0. Example: if
FIERA CCD DCS will look for files myImage.fits (first exposure), myImage.1.fits (second exposure) and myImage.2.fits (third exposure)
5. FIERA 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).
If multiple window readout has been performed, FIERA 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.
9. OS retrieves from the FIERA CCD database (see section 2.14.4) the name of the file containing the image. Normally it is the same as the setup values passed by OS, but FIERA CCD DCS may have been obliged to change it (see point 4. above).
10. OS collects hierarchical information from all sub-systems, moves fcdDCSHEADLINES from the beginning of the file and writes them. If multiple window readout 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 must ensure that the image data section is not overwritten with header information.
Note: tools and functions for handling image FITS files are provided by the INS common sw (slx, see [13], and oslx, see [14]).
2.14.4 Public part of the FIERA 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 FIERA CCD sw (e.g. all setup attributes set with the command SETUP, configuration attributes read with the function fcdGetConf and set with the panel fcdConfig) are not considered public (no direct call to dbRead/dbWrite CCS functions).
When accessing FIERA CCD database attributes with direct CCS db calls, applications are requested to use the macros defined in fcdDbPublic.h (see 4.5): in this way, any change in name or location of the attribute only requires a new compilation.
All database paths below are meant to be relative to the root point for the FIERA CCD database branch. The attributes marked with (*) require that the Scan System is working between CCD SLCU and WS.
c. wcs.ra (dbDOUBLE) Centre right ascension in degrees for World Coordinates display (fcdDB_WCS_RA).
d. exposures:exposure_1.expStatus (*) (dbINT32) Status of exposure. Same for exposures:exposure_2.expStatus (fcdDB_EXP_POINT_<index>.fcdDB_STA_EXPOSURE).
e. exposures:exposure_1.expId (dbINT32) ID of exposure. Same for exposures:exposure_2.expId (fcdDB_EXP_POINT_<index>.fcdDB_STA_EXPID).
f. exposures:exposure_1:transfer.fileNameUnComp (dbBYTES32) Name of FITS file where uncompressed image data are written (on Workstation only). Same for exposures:exposure_2:transfer.fileNameUnComp (fcdDB_EXP_POINT_<index>:fcdDB_EXP_FILEUNC).
g. exposures:exposure_next:readout.modeIndex (dbINT32) Index of the mode chosen for readout (fcdDB_SET_MODEINDEX)
h. exposures:exposure_next:readout:window_%d.enabled (dbLOGICAL) Readout window enable (fcdDB_SET_WIN<index>_ENAB). Same for exposures:exposure_1:readout:window_%d.enabled (fcdDB_SET_WIN<index>_ENAB_1).
i. exposures:exposure_next:readout:window_%d.xBinning (dbINT32) Horizontal binning factor for readout window (fcdDB_SET_WIN<index>_XBIN). Same for exposures:exposure_1:readout:window_%d.xBinning (fcdDB_SET_WIN<index>_XBIN_1)
j. exposures:exposure_next:readout:window_%d.yBinning (dbINT32) Vertical binning factor for readout window (fcdDB_SET_WIN<index>_YBIN). Same for exposures:exposure_1:readout:window_%d.yBinning (fcdDB_SET_WIN<index>_YBIN_1)
k. exposures:exposure_next.timeDef (dbDOUBLE) Exposure time (fcdDB_SET_TIMEDEF). Same for exposures:exposure_1.timeDef (fcdDB_SET_TIMEDEF_1)
l. exposures:exposure_next.timeRepeat (dbDOUBLE) Exposure repeat time (fcdDB_SET_TIMEREP). Same for exposures:exposure_1.timeRepeat (fcdDB_SET_TIMEREP_1)
m. exposures:exposure_next.expType (dbINT32). Exposure type (fcdDB_SET_EXPTYPE). Same for exposures:exposure_1.expType (fcdDB_SET_EXPTYPE_1)
n. exposures:exposure_next.expRepeatDef (dbINT32) Number of repetitions (fcdDB_SET_EXPREPS). Same for exposures:exposure_1.expRepeatDef (fcdDB_SET_EXPREPS_1)
o. exposures:exposure_<index>:timeRem (*) (dbDouble) Exposure remaining time (fcdDB_EXP_POINT_<index>:fcdDB_STA_TIMEREM)
p. detector.chipInstances (Table of dbBYTES16, dbBYTES16, dbINT32, dbINT32, dbLOGICAL, dbLOGICAL, dbDOUBLE, dbDOUBLE) Table of chip Instances (fcdDB_CHIP_INST)
u. readout:mode_<index>.description (dbBYTES64) Readout mode description (fcdDB_POINT_RDT_MODE_<index>.fcdDB_CON_MODEDES)
v. readout:mode_<index>.elAdu (Vector of dbDOUBLE) Electrons per Adu per output (fcdDB_POINT_RDT_MODE_<index>.fcdDB_CON_ELADU)
w. readout:mode_<index>.ron (Vector of dbDOUBLE) readout nois per output (fcdDB_POINT_RDT_MODE_<index>.fcdDB_CON_RON)
x. readout:mode_<index>.speed (dbBYTES16) Description of readout speed (fcdDB_POINT_RDT_MODE_<index>.fcdDB_CON_SPEED)
ae. images:process:window_i.ipXFWHM (*) (dbDOUBLE) Full-width half maximum (x-component) (fcdDB_IP_X_FWHM_FMT).
af. images:process:window_i.ipYFWHM (*) (dbDOUBLE) Full-width half maximum (y-component) (fcdDB_IP_Y_FWHM_FMT).
ag. images:process:window_i.ipNumPix (*) (dbDOUBLE) Number of pixels above threshold level (fcdDB_IP_NUMPIX_FMT).
As already mentioned in section 2.13, the FIERA CCD sw provides applications with CCD GUI classes to be incorporated in their own panels. We strongly recommend using these classes in application panels. For all cases where this is not possible, the following attributes are made public for usage within GUI panels;.
2.15 Alarm System
As part of the telemetry monitoring, if a telemetry value goes out of limits (defined using the Telemetry Configuration Panel, see Fig.7 of Chapter 8) an alarm is raised with the alarm system. The alarm generated is tmOutOfLimit. Alarms can be monitored using the standard VLT utility alrmDisplay.
2.16 Configuration and operational logs
The FIERA CCD sw logs the main operations it performs, using the VLT CCS Logging System, in FITS format. Examples of logs produced by the FIERA CCD sw are given in section 4.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 section 5.6.5) and called fcdDcsSetLogMask.sh (see also section 4.3) is dedicated to this purpose. Example:
2.17 Example of usage of CCD cameras
Assuming that all the environment variables have been properly set (see 5.6.1), in the following example the FIERA software is started and some exposures are performed.
 Quadralay Corporation http://www.webworks.com Voice: (512) 719-3399 Fax: (512) 719-3606 sales@webworks.com |
| |
|
|
|