areaDetector Plugins

• Overview
• NDPluginDriver
• NDPluginStdArrays
  • Configuration
  • IDL Display Client
• NDPluginFile
  • Configuration
• NDPluginROI
  • Configuration

A powerful feature of the areaDetector module is the concept of plugins. A plugin is code that is called by a driver that passes NDArray data in a callback. Plugins can be used to process array data in real time. Existing plugins convert data to standard asyn arrays (NDPluginStdArrays) save data to disk (NDPluginFile), and select regions-of-interest (NDPluginROI). New plugins could be written to perform functions like finding the centroid of a beam, etc. Once a plugin is written it will work with any areaDetector driver. Plugins have the the following properties:

• They can execute either in a blocking mode or a non-blocking mode. In the blocking mode the callback is executed by the driver callback thread. In this mode the callback is guaranteed to execute for each NDArray callback. However, it can slow down the driver, and does not utilize the multi-core capability of modern CPUs. In the non-blocking mode the driver callback simply places the NDArray data in a queue that is part of the plugin. The plugin then executes the callback code in it own thread, removes NDArray data from the queue, processes it, and releases the data back to the NDArrayPool when it is done. In the non-blocking mode some additional memory is required for the NDArray objects that are in the queue. It is also possible to drop NDArray data if the queue is full, i.e. some callback data will not be processed. The non-blocking mode can utilize the multi-core capabilities of modern CPUs because each plugin is executing in its own thread. The operation of the queue and the NDArrayPool class means that data never needs to be copied, each plugin has a pointer to the data which will continue to be valid until the last plugin is done with it.
• They can be enabled or disabled at run time.
• They can be throttled to only execute at a limited rate. This means, for example, that a detector can be saving data to disk at full speed, but images can be posted to EPICS at a reduced rate.
• They can be unplugged from one driver, and plugged into another driver at run time. In particular the NDPluginROI driver is itself a source of NDArray data callbacks, so a file saving plugin could be unplugged from a detector driver (where it would be saving the entire detector), and plugged into a particular ROI, where it would just save a portion of the detector.

NDPluginDriver inherits from asynNDArrayDriver. NDPluginDriver is the class from which actual plugins are directly derived. The NDPluginDriver class handles most of the details of processing NDArray callbacks from the driver. Plugins derived from this class typically need to implement the processCallbacks method, the drvUser method, and one or more of the write(Int32, Float64, Octet) methods. The NDPluginDriver public interface is defined in NDPluginDriver.h as follows:

class NDPluginDriver : public asynNDArrayDriver {
public:
    NDPluginDriver(const char *portName, int queueSize, int blockingCallbacks, 
                 const char *NDArrayPort, int NDArrayAddr, int maxAddr, int paramTableSize,
                 int maxBuffers, size_t maxMemory, int interfaceMask, int interruptMask);
                 
    /* These are the methods that we override from asynNDArrayDriver */
    virtual asynStatus writeInt32(asynUser *pasynUser, epicsInt32 value);
    virtual asynStatus writeOctet(asynUser *pasynUser, const char *value, size_t maxChars,
                          size_t *nActual);
    virtual asynStatus readInt32Array(asynUser *pasynUser, epicsInt32 *value,
                                        size_t nElements, size_t *nIn);
    virtual asynStatus drvUserCreate(asynUser *pasynUser, const char *drvInfo, 
                                     const char **pptypeName, size_t *psize);
                                     
    /* These are the methods that are new to this class */
    virtual void processCallbacks(NDArray *pArray);
    virtual void driverCallback(asynUser *pasynUser, void *genericPointer);
    virtual void processTask(void);
    virtual asynStatus setArrayInterrupt(int connect);
    virtual asynStatus connectToArrayPort(void);    
    int createFileName(int maxChars, char *fullFileName);
...
}

The methods of the NDPluginDriver class are:

• NDPluginDriver This is the constructor for the class. All parameters except queueSize, blockingCallbacks, NDArrayPort, and NDArrayAddr are just passed to the constructor for asynNDArrayDriver. NDArrayPort and NDArrayAddr, and blockingCallbacks are the initial values for the NDPluginDriverArrayPort, NDPluginDriverArrayAddr and NDPluginDriverBlockingCallbacks parameters described in the table below.
• drvUserCreate This method returns one of the enum values for the parameters defined in NDPluginDriver.h if the driverInfo field matches one the strings defined in that file. Derived classes will typically provide an implementation of drvUserCreate() that searches for parameters that are unique to that plugin. If a parameter is not matched, then NDPluginDriver->drvUserCreate() will be called to see if it is a standard plugin parameter (defined in NDPluginDriver.h).
• processCallbacks This method is called each time a driver calls the plugin with a new NDArray object. Derived classes typically call this base class method, which handles some bookkeeping chores, and then they perform whatever operations are specific to that plugin.
• createFileName This is a convenience function that constructs a complete file name in the ADFullFileName parameter from the ADFilePath, ADFileName, ADFileNumber, and ADFileTemplate parameters.

NDPluginDriver defines parameters that all plugin drivers should implement if possible. These parameters are defined by enum values with an associated asyn interface, and access (read-only or read-write). The EPICS database NDPluginBase.template provides access to these standard plugin parameters, listed in the following table.

NDPluginStdArrays inherits from NDPluginDriver. NDPluginStdArrays converts the NDArray data from a callback into the 1-dimensional arrays supported by the standard asyn array interfaces, i.e. asyn[Int8, Int16, Int32, Float32, Float64]Array. These interfaces are supported by the EPICS waveform record using standard asyn device support. This plugin is thus the tool for converting the NDArray data produced by asynNDArrayDriver drivers into a form that can be accessed by EPICS. Because this plugin inherits from NDPluginDriver it also provides additional information on the array data (e.g. number of dimensions and dimension data described above) that are made available as EPICS PVs so that clients can correctly interpret the array data. The NDPluginStdArrays public interface is defined in NDPluginStdArrays.h as follows:

class NDPluginStdArrays : public NDPluginDriver {
public:
    NDPluginStdArrays(const char *portName, int queueSize, int blockingCallbacks, 
                      const char *NDArrayPort, int NDArrayAddr,
                      size_t maxMemory);

    /* These methods override the virtual methods in the base class */
    void processCallbacks(NDArray *pArray);
    virtual asynStatus readInt8Array(asynUser *pasynUser, epicsInt8 *value,
                                        size_t nElements, size_t *nIn);
    virtual asynStatus readInt16Array(asynUser *pasynUser, epicsInt16 *value,
                                        size_t nElements, size_t *nIn);
    virtual asynStatus readInt32Array(asynUser *pasynUser, epicsInt32 *value,
                                        size_t nElements, size_t *nIn);
    virtual asynStatus readFloat32Array(asynUser *pasynUser, epicsFloat32 *value,
                                        size_t nElements, size_t *nIn);
    virtual asynStatus readFloat64Array(asynUser *pasynUser, epicsFloat64 *value,
                                        size_t nElements, size_t *nIn);
    asynStatus drvUserCreate(asynUser *pasynUser, const char *drvInfo, 
                                        const char **pptypeName, size_t *psize);
...
}

NDPluginStdArrays defines the following parameters. It also implements all of the standard plugin parameters from NDPlugDriver listed above. The EPICS database NDStdArrays.template provides access to these parameters, listed in the following table.

If the array data contains more than 16,000 bytes then in order for EPICS clients to receive this data they must be built with EPICS R3.14 (not R3.13), and the environment variable EPICS_CA_MAX_ARRAY_BYTES on both the EPICS IOC computer and EPICS client computer must be set to a value at least as large as the array size in bytes.

The following is the MEDM screen that provides access to the parameters in NDPluginDriver.h and NDPluginStdArrays.h through records in NDPluginBase.template and NDStdArrays.template. This is the MEDM screen that is normally used to control the display of images via EPICS channel access.

Configuration

The NDPluginStdArrays plugin is created with the following command, either from C/C++ or from the EPICS IOC shell.

drvNDStdArraysConfigure(const char *portName, int queueSize, int blockingCallbacks, 
                        const char *NDArrayPort, int NDArrayAddr, size_t maxMemory)
  

IDL Image Display Client

There is an IDL program called epics_ad_display that can be used to display 2-dimensional ArrayData that the NDStdArrays plugin sends to EPICS. This IDL client is available as source code (which requires an IDL license), and also as a pre-built IDL .sav file that can be run for free under the IDL Virtual Machine. This IDL program can run on any machine that IDL runs on, and that has the ezcaIDL shareable library built for it. This includes Windows, Linux, Solaris, and Mac. epics_ad_display is included in the CARS IDL imaging software.

The control window for epics_ad_display is shown below. It has fields to input the base name of the EPICS PVs with the image data. The client uses the

Main window for IDL epics_ad_display

epics_ad_display uses the routine image_display.pro to display the images. This routine displays row and column profiles as the cursor is moved. It allows changing the color lookup tables, and zooming in and out with the left and right mouse buttons. The following is an example of image_display displaying a Pilatus image with an Fe55 source in front of the detector.

IDL image_display with Fe55 radioactive source

NDPluginFile inherits from NDPluginDriver. NDPluginFile saves the NDArray data from a callback to a disk file. This plugin currently saves data in the netCDF file format, which is a portable self-describing binary file format supported by UniData at UCAR (University Corporation for Atmospheric Research). Additional file formats, such as TIFF and HDF may be supported in the future.

The NDArray callback data can be written to disk in 1 of 3 modes:

1. Single mode. In this mode each NDArray callback results in a separate disk file.
2. Capture mode. In this mode a memory buffer is allocated before saving begins. Callback arrays are placed into this buffer, and when capture stops the file is written to disk. This mode limits the number of frames that can be saved, because they all must fit in a memory buffer. It is the fastest mode, with the least probability of dropping arrays, because no disk I/O is required while capture is in progress.
3. Stream mode. In this mode the data are written to a single disk file, with each frame being appended to the file without closing it. It is intermediate in speed between single mode and capture mode, but unlike capture mode it is not limited by available memory in the number of arrays that can be saved.

The NDPluginFile public interface is defined in NDPluginFile.h as follows:

/* Note that the file format enum must agree with the mbbo/mbbi records in the NDFile.template file */
typedef enum {
    NDFileFormatNetCDF,
} NDPluginFileFormat_t;

typedef enum {
    NDPluginFileModeSingle,
    NDPluginFileModeCapture,
    NDPluginFileModeStream
} NDPluginFileMode_t;

...
class NDPluginFile : public NDPluginDriver {
public:
    NDPluginFile(const char *portName, int queueSize, int blockingCallbacks, 
                 const char *NDArrayPort, int NDArrayAddr);
                 
    /* These methods override those in the base class */
    void processCallbacks(NDArray *pArray);
    asynStatus writeInt32(asynUser *pasynUser, epicsInt32 value);
    asynStatus writeNDArray(asynUser *pasynUser, void *genericPointer);
    asynStatus drvUserCreate(asynUser *pasynUser, const char *drvInfo, 
                             const char **pptypeName, size_t *psize);

...
}

NDPluginFile also supports all of the file saving parameters defined in ADStdDriverParams.h described above, e.g.ADFilePath, ADFileName, etc. Thus, the same interface that is used for saving files directly in a driver are used for this plugin.

The following is the MEDM screen that provides access to the parameters in NDPluginDriver.h and NDPluginFile.h through records in NDPluginBase.template and NDFile.template. This is the MEDM screen that is used to control the saving of images to disk for drivers that do not support saving files to disk themselves.

Configuration

The NDPluginFile plugin is created with the following command, either from C/C++ or from the EPICS IOC shell.

drvNDFileConfigure(const char *portName, int queueSize, int blockingCallbacks, 
                   const char *NDArrayPort, int NDArrayAddr)
  

NDPluginROI inherits from NDPluginDriver. NDPluginROI selects one or more rectangular "Regions-Of-Interest" (ROIs) from the NDArray callback data. The maximum number of ROIs is defined when the plugin is created. Each ROI can be any size, from a single array element to the entire array. NDPluginROI does 3 things with these ROIs:

1. Computes statistics, e.g. mean, maximum, minimum, total value, net (background subtracted) value
2. Computes a histogram of the values (e.g. number of pixels versus intensity per pixel)
3. Exports the ROI as a new NDArray object. In this regard NDPluginROI is different from the NDPluginStdArrays and NDPluginFile plugins because it is both a recipient of callbacks (as they are) and a source of NDArray callbacks, as a driver is. This means that the NDPluginStdArrays and NDPluginFile plugins can be connected to an NDPluginROI plugin, in which case they will save or display the selected ROI rather than the full detector driver data.

Each NDPluginROI can handle any number of ROIs. The maximum number of ROIs that the plugin can support is defined when the plugin is created. Several ROI plugins could be created for a single detector driver to increase the number of threads running in parallel, maximizing the use of multiple CPU cores. Individual ROIs are addressed through the asyn interfaces by the asyn "addr" field in the asynUser structure. Note that while the NDPluginROI should be N-dimensional, the definition of the ROI is currently limited to 2-D. This limitation will be removed in a future release.

The NDPluginROI public interface is defined in NDPluginROI.h as follows:

class NDPluginROI : public NDPluginDriver {
public:
    NDPluginROI(const char *portName, int queueSize, int blockingCallbacks, 
                 const char *NDArrayPort, int NDArrayAddr, int maxROIs, size_t maxMemory);
    /* These methods override the virtual methods in the base class */
    void processCallbacks(NDArray *pArray);
    asynStatus writeInt32(asynUser *pasynUser, epicsInt32 value);
    asynStatus drvUserCreate(asynUser *pasynUser, const char *drvInfo, 
                             const char **pptypeName, size_t *psize);

    /* These methods are unique to this class */
    asynStatus readFloat64Array(asynUser *pasynUser, epicsFloat64 *value, 
                                size_t nelements, size_t *nIn);
                                

The readFloat64Array method is used to read the histogram data for the ROI.

NDPluginROI.h defines the following parameters that are global to all ROIs for a plugin. It also implements all of the standard plugin parameters from NDPlugDriver listed above. The EPICS database NDROI.template provide access to these parameters, listed in the following table.

NDPluginROI.h defines the following parameters that are specific to each individual ROI in the plugin. The EPICS database NDROIN.template provide access to these parameters, listed in the following table. The pasynUser->addr is used to control which ROI is being addressed.

Configuration

The NDPluginROI plugin is created with the following command, either from C/C++ or from the EPICS IOC shell.

drvNDROIConfigure(const char *portName, int queueSize, int blockingCallbacks, 
                  const char *NDArrayPort, int NDArrayAddr, int maxROIs,
                  size_t maxMemory)

  

The following is the MEDM screen that provides access to the parameters in NDPluginDriver.h and NDPluginROI.h through records in NDPluginBase.template and NDROI.template. This is the MEDM screen that is used to control the behavior of the ROI plugin, but not the individual ROIs.

The following is the MEDM screen that provides access to the parameters for in NDPluginROI.h through records in NDROIN.template. This is the MEDM screen that is used to control the behavior of a specific ROI.

The following is another MEDM screen that provides access to the parameters for in NDPluginROI.h through records in NDROIN.template. This is the MEDM screen that is used to control the most commonly used properties of 8 ROIs.

The following is an IDL epics_ad_display screen illustrating the highlighting of ROIs. In this example the ROIs defined are those in the 8 ROI display above. The NDPluginStdArrays driver has been configured to be receiving its NDArray callbacks from the first ROI (which is defined to be the entire detector array), and the NDPluginROIHighlight flag is set to Yes.