diff --git a/documentation/LightField.png b/documentation/LightField.png new file mode 100755 index 0000000..2eabe98 Binary files /dev/null and b/documentation/LightField.png differ diff --git a/documentation/LightFieldApplication.png b/documentation/LightFieldApplication.png new file mode 100755 index 0000000..a6a1c7d Binary files /dev/null and b/documentation/LightFieldApplication.png differ diff --git a/documentation/LightFieldDoc.html b/documentation/LightFieldDoc.html new file mode 100755 index 0000000..86972fd --- /dev/null +++ b/documentation/LightFieldDoc.html @@ -0,0 +1,606 @@ + + + + areaDetector LightField driver + + + +
+

+ areaDetector LightField driver

+

+ September 29, 2013

+

+ Mark Rivers

+

+ University of Chicago

+
+

+ Table of Contents

+ +

+ Introduction

+

+ This is a driver for recent + Princeton Instruments detectors including the ProEM, PIXIS, PI-MAX3, PI-MAX4, PyLoN, + and Quad-RO. It also supports the Acton Series spectrographs. +

+

+ The interface to the detector is via a the MicroSoft Common Language Runtime (CLR) + interface to the LightField + program that Princeton Instruments sells. The areaDetector driver effectively "drives" LightField + through the CLR interface, performing most of the same operations that can be performed + using the LightField GUI. The advantage of this communication mechanism is that the + user can continue to use LightField for viewing images and for configuration operations. + LightField is automatically started when the areaDetector software is started. +

+

+ Because EPICS and the LightField GUI can control many of the same parameters the user + must be aware of the interactions between the two control systems. The basic rule + is that the value of a parameter will be determined by whichever control system + last wrote to that parameter. The LightField widget will display the + current value of a parameter no matter how it was last changed. EPICS will correctly display + the current value of the parameter in the "readback" record, which typically ends in "_RBV", + no matter how the value was last changed. However the EPICS output record does not currently + update if the value is changed in LightField. This may change in a future version of asyn + device support. +

+

+ This driver inherits from ADDriver. + It implements many of the parameters + asynNDArrayDriver.h and in + ADArrayDriver.h. It also implements a number of parameters that are specific + to the LightField application.The LightField + class documentation describes this class in detail.

+

+ Implementation of standard driver parameters

+

+ The following table describes how the LightField driver implements some of the standard + driver parameters. Note that there are 3 possible levels of nested acquisition looping + when using the LightField driver. From the innermost to outermost loop these are as follows:

+
    +
  1. ADNumExposures ($(P)$(R)NumExposures). This controls the number of exposures per + image. This is called "accumulations" in LightField's terminology.
    2. +
  2. ADNumImages ($(P)$(R)NumImages). This controls the number of images per acquisition. + This is also called "number of images" in LightField's terminology. These images will + all be acquired into a single 3-D array, and saved to a single SPE file in WinView.
    3. +
  3. LightFieldNumAcquisitions ($(P)$(R)NumNumAcquisitions). This controls the number of + times that the driver will repeat an acquisition sequence. This is has no equivalent + in WinView, it is handled entirely by the areaDetector driver. It can be used to + acquire multiple data sets, where each is controlled by the above parameters.
    4. +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Implementation of Parameters in asynNDArrayDriver.h and ADDriver.h, and EPICS Record + Definitions in ADBase.template and NDFile.template
+ Parameter index variable + EPICS record name + Description
+ ADImageMode + $(P)$(R)ImageMode + The driver redefines the choices for the ADImageMode parameter (record $(P)$(R)ImageMode) + from ADDriver.h. The choices for the LightField are: +
    +
  • Normal: This is the same as pressing the Acquire button in WinView. It may collect + more than 1 exposure per image if NumExposures>1, more than 1 image per acquisition + if NumImages>1, and more than 1 aquisition if NumAcquisitions>1.
    • +
  • Continuous: This will cause the driver to perform acquisitions indefinitely, i.e. + it acts as if NumAcquisitions is infinite.
    • +
  • Focus: This is the same as pressing the Focus button in WinView. It causes acquisition + to proceed as quickly as possible. It does not save the data. It currently does + not call the callbacks for each frame, so the images can only be seen in WinView + and not in EPICS. This may be fixed in a future release.
    • +
+
+ ADAcquirePeriod + $(P)$(R)AcquirePeriod + Controls the period between images when ADImageMode is Continuous. If this is greater + than the acquisition time plus readout overhead then the driver will wait until + the period has elapsed before starting the next acquisition.
+ ADNumExposures + $(P)$(R)NumExposures + Controls the number of exposures (accumulations) to acquire into a single image. +
+ ADNumImages + $(P)$(R)NumImages + Controls the number of images to acquire into a single 3-D data set.
+ ADTriggerMode + $(P)$(R)TriggerMode + The driver redefines the choices for the ADTriggerMode parameter (record $(P)$(R)TriggerMode) + from ADDriver.h. The choices for the LightField are: +
    +
  • Free run: This acquires images as quickly as possible given the exposure and readout + times.
    • +
  • Ext. sync: This acquires one image for each external trigger pulse.
    • +
  • Bulb trig.: The exposure time is determined by the external trigger pulse width. +
    • +
  • Single trig.: A single external trigger pulse will acquire an entire sequence + of images.
    • +
+
+ NDFileFormat + $(P)$(R)FileFormat + The driver redefines the choices for the NDFileFormat parameter (record $(P)$(R)FileFormat) + from asynNDArrayDriver.h. The choices for the LightField are: +
    +
  • SPE: This is the default file format for WinView. It is a binary format with a + header containing all of the acquisition and setup information.
    • +
  • TIFF: TIFF files that contain the full resolution of the image data. The TIFF + files do not contain any acquisition or setup information.
    • +
  • 8-bit TIFF: 8-bit TIFF files that contain limited resolution image data. The TIFF + files do not contain any acquisition or setup information.
    • +
+ The driver does not automatically change the file extension (.SPE, .TIFF, etc.) + when the FileFormat is changed, the user should do this using the FileTemplate record. +
+ ADGain + $(P)$(R)Gain + The precision of the $(P)$(R)Gain record is changed to 0 because the gain in WinView + is an integer. Allowed values are detector dependent, but 1 and 2 are typically + supported.
+

+ LightField specific parameters

+

+ The LightField driver implements the following parameters in addition to those in asynNDArrayDriver.h + and ADDriver.h. Note that to reduce the width of this table the parameter index + variable names have been split into 2 lines, but these are just a single name, for + example marCCDState. +

+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Parameter Definitions in LightField.cpp and EPICS Record Definitions in LightField.template +
+ Parameter index variable + asyn interface + Access + Description + drvInfo string + EPICS record name + EPICS record type
+ Status parameters
+ LightField
+ NumAcquisitions		 + asynInt32 + r/w + The number of acquisitions to perform when acquisition is started. This controls + the number of iterations in the outermost acquisition loop explained above. + LightField_NACQUISITIONS + $(P)$(R)NumAcquisitions
+ $(P)$(R)NumAcquisitions_RBV		 + longout
+ longin
+ Roper
+ NumAcquisitionsCounter		 + asynInt32 + r/o + The number of acquisitions performed so far. + ROPER_NACQUISITIONS_COUNTER + $(P)$(R)NumAcquisitionsCounter_RBV + longin
+ Roper
+ AutoDataType		 + asynInt32 + r/w + A flag controlling whether WinView will automatically chose the optimal data type + for the image data. 0=No, 1=Yes. If this flag is 1 then the NDDataType parameter + ($(P)$(R)DataType record) is ignored. If this flag is 0 then the NDDataType parameter + controls the data type of the images. + AUTO_DATA_TYPE + $(P)$(R)AutoDataType
+ $(P)$(R)AutoDataType_RBV		 + bo
+ bi
+ Roper
+ ShutterMode		 + asynInt32 + r/w + The shutter operating mode for shutters controlled by WinView. Allowed values are: +
    +
  • Normal: The detector shutter will be opened and closed normally for each exposure.
    • +
  • Disabled closed: The shutter will be forced closed. Useful for taking a dark current + image.
    • +
  • Disabled open: The shutter will be forced open.
    • +
+ 		+ ROPER_SHUTTER_MODE + $(P)$(R)RoperShutterMode
+ $(P)$(R)RoperShutterMode_RBV		 + mbbo
+ mbbi
+ Roper
+ Comment(1-5)		 + asynOctet + r/w + User comments for the data file. 5 comment fields of 80 characters each are available + in the header of WinView SPE files. These are waveform records with FTVL=UCHAR and + NELM=80 so that they can be longer than the 40 character string limit in EPICS. + + COMMENT(1-5) + $(P)$(R)Comment(1-5)
+ $(P)$(R)Comment(1-5)_RBV		 + waveform
+ waveform
+

+ Unsupported standard driver parameters

+

+ The LightField driver does not support the following standard driver parameters:

+ +

+ Configuration

+

+ The LightField driver is created with the LightFieldConfig command, either from C/C++ or from + the EPICS IOC shell.

+ 
int LightFieldConfig(const char *portName,
+                int maxBuffers, size_t maxMemory,
+                int priority, int stackSize)
+
+

+ For details on the meaning of the parameters to this function refer to the detailed + documentation on the LightFieldConfig function in the + LightField.cpp documentation and in the documentation for the constructor for the + LightField class. +

+

+ There an example IOC boot directory and startup script (iocBoot/iocLightField/st.cmd) + provided with areaDetector. +

+

+ MEDM screens

+

+ The following show the MEDM screens that are used to control the LightField detector. + Note that the general purpose screen ADBase.adl can be used, but it exposes a few + controls that are not applicable to the LightField, and lacks some fields that are important + for the LightField.

+

+ LightField.adl is the main screen used to control the LightField driver. +

+
+

+ LightField.adl

+ LightField.png
+

+ LightFieldFile.adl is the screen used to control WinView file I/O. +

+
+

+ LightFieldFile.adl

+ LightFieldFile.png
+

+ WinView is program that the LightField driver is controlling via Microsoft + COM. +

+
+

+ WinView program from LightField Scientific

+ WinView.png
+

+ Performance measurements

+

+ The following measurements were done to demonstrate the performance that can be + obtained with the areaDetector LightField driver. These measurements were made with a + CoolSnap-HQ2 detector which has 1392x1040 pixels. The acquisition time was 0.01 + second. The overhead per image in the table below is the total time to acquire the + data set minus 1.00 seconds (the acquisition time) divided by 100. Acquisitions + were done in 2 modes:

+
    +
  1. In the first mode NumImages=100 and NumAcquisitions=1, i.e. the data were all + collected into a single SPE file. In this mode the time per image is really controlled + by the acquisition time and readout time. At the end of the acquisition there is + then a delay, perhaps in copying the data from one buffer to another. The acquisition + time in this mode is the time from when acquire was started until WinView reported + acquisition was complete and the write to disk began. The additional time to write + the file to disk is also listed.
    2. +
  2. In the second mode NumImages=1 and NumAcquisitions=100, i.e. the data were collected + into 100 SPE files. This is equivalent to pressing the Acquire button in WinView + 100 times. There is additional overhead per image that arises from downloading parameters + to the camera and in creating a new display window in WinView. In this mode the + test was done both with the EPICS AutoSave PV set to 1 (which effectively does a + WinView "Save As" operation for each file), and with AutoSave set to 0, which does + not write disk files at all. The acquisition time listed is with AutoSave on, i.e. + saving 100 disk files. Interestingly it was generally faster to collect the + data with AutoSave on than with it off! The time to save the 100 disk files is thus + actually negative, i.e. it took that much longer to collect the data sets without + saving the disk files. The reason for this is unclear, but it seems to be something + internal to WinView.
    3. +
+ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
+ Binning + Image dimensions + Image size + Mode + Acquisition time for 100 images + Overhead per image + File size + File saving time
+ 1x1 + 1392x1040 + 2827 KB + 1 SPE file + 29.49 + 0.28 + 276 MB + 20.04
+ 1x1 + 1392x1040 + 2827 KB + 100 SPE files + 80.67 + 0.79 + 2.76 MB + -3.62
+ 2x2 + 696x520 + 707 KB + 1 SPE file + 10.27 + 0.09 + 69 MB + 4.86
+ 2x2 + 696x520 + 707 KB + 100 SPE files + 46.14 + 0.45 + 0.71 MB + -.72
+ 4x4 + 348x260 + 177 KB + 1 SPE file + 4.48 + 0.03 + 17 MB + 1.40
+ 4x4 + 348x260 + 177 KB + 100 SPE files + 36.59 + 0.35 + 0.18 MB + 0.69
+

+ Restrictions

+

+ The following are some current restrictions of the LightField driver:

+ + + diff --git a/documentation/LightFieldFile.png b/documentation/LightFieldFile.png new file mode 100755 index 0000000..47fa466 Binary files /dev/null and b/documentation/LightFieldFile.png differ