areaDetector Roper driver

October 1, 2012

Mark Rivers

University of Chicago

Table of Contents

Introduction

This is an EPICS areaDetector driver for the Roper Scientific detectors, which includes those from Princeton Instruments and Photometrics.

The interface to the detector is via a the Microsoft COM interface to the WinView or WinSpec programs that Roper provides. The term WinView will be used in this document to refer to either WinView or WinSpec, as they are equivalent in terms of the areaDetector driver. The areaDetector driver effectively "drives" WinView through the COM interface, performing many of the same operations that can be performed using the WinView GUI. The advantage of this communication mechanism is that the user can continue to use WinView for viewing images and for configuration operations. WinView is normally started before the areaDetector software is started. However, if the areaDetector software is started without WinView running, then WinView will be started in the background, and will not be visible. This may be desirable in some applications.

Because EPICS and the WinView 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. Both EPICS and WinView will correctly display the current value of a parameter no matter how it was last changed. However, in WinView this requires closing and re-opening the window that controls that parameter, such as the Experiment Setup tabbed windows, to see any changes made by EPICS since the window was opened.

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 Roper detectors.The roper class documentation describes this class in detail.

Implementation of standard driver parameters

The following table describes how the Roper driver implements some of the standard driver parameters. Note that there are 3 possible levels of nested acquisition looping when using the Roper 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 Roper's terminology.
  2. ADNumImages ($(P)$(R)NumImages). This controls the number of images per acquisition. This is also called "number of images" in Roper's terminology. These images will all be acquired into a single 3-D array, and saved to a single SPE file in WinView.
  3. RoperNumAcquisitions ($(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.
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 Roper 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 Roper 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 Roper 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.

Roper specific parameters

The Roper 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 roper.cpp and EPICS Record Definitions in roper.template
Parameter index variable asyn interface Access Description drvInfo string EPICS record name EPICS record type
Status parameters
Roper
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. ROPER_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 Roper driver does not support the following standard driver parameters:

Configuration

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

int roperConfig(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 roperConfig function in the roper.cpp documentation and in the documentation for the constructor for the roper class.

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

MEDM screens

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

Roper.adl is the main screen used to control the Roper driver.

roper.adl

Roper.png

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

RoperFile.adl

RoperFile.png

WinView is program that the Roper driver is controlling via Microsoft COM.

WinView program from Roper Scientific

WinView.png

Performance measurements

The following measurements were done to demonstrate the performance that can be obtained with the areaDetector Roper 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. 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.
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 Roper driver: