areaDetector Plugin NDPluginROI

January 30, 2009

Mark Rivers

University of Chicago

Contents

Overview

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 EPICS interface to the definition of the ROI is currently limited to a maximum of 3-D. This limitation will be removed in a future release.

NDPluginROI inherits from NDPluginDriver. 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. The EPICS database NDROI.template provide access to these parameters, listed in the following table.

Parameter Definitions in NDPluginROI.h and EPICS Record Definitions in NDROI.template
Enum name asyn interface Access Description drvUser string EPICS record name EPICS record type
NDPluginROIHighlight asynInt32 r/w Flag to indicate if the borders of ROIs should be highlighted (0=No, 1=Yes). If set then the borders of all ROIs will be highlighted in all other ROIs where they overlap. One common use of this is to set the first ROI to be the entire detector, and then the location of all other ROIs will be visible when the first ROI is displayed. The highlighting is done by replacing the border pixels with the maximum value of the data in that ROI. Statistics are computed before the highlighting is done. HIGHLIGHT $(P)$(R)Highlight
$(P)$(R)Highlight_RBV
bo
bi

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. Note that to reduce the width of this table the enum names have been split into 2 lines, but these are just a single name, for example NDPluginROIName.

Parameter Definitions in NDPluginROI.h and EPICS Record Definitions in NDROIN.template
Enum name asyn interface Access Description drvUser string EPICS record name EPICS record type
NDPluginROI
Name
asynOctet r/w Name of this ROI NAME $(P)$(R)Name
$(P)$(R)Name_RBV
stringout
stringin
NDPluginROI
Use
asynInt32 r/w Flag to control whether this ROI is used (0=No, 1=Yes). Not using an ROI reduces CPU load. USE $(P)$(R)Use
$(P)$(R)Use_RBV
bo
bi
ROI definition
NDPluginROI
Dim0Bin
asynInt32 r/w Binning in the X direction DIM0_BIN $(P)$(R)BinX
$(P)$(R)BinX_RBV
longout
longin
NDPluginROI
Dim1Bin
asynInt32 r/w Binning in the Y direction DIM1_BIN $(P)$(R)BinY
$(P)$(R)BinY_RBV
longout
longin
NDPluginROI
Dim2Bin
asynInt32 r/w Binning in the Z direction DIM2_BIN $(P)$(R)BinZ
$(P)$(R)BinZ_RBV
longout
longin
NDPluginROI
Dim0Min
asynInt32 r/w First pixel in the ROI in the X direction.
0 is the first pixel in the array.
DIM0_MIN $(P)$(R)MinX
$(P)$(R)MinX_RBV
longout
longin
NDPluginROI
Dim1Min
asynInt32 r/w First pixel in the ROI in the Y direction.
0 is the first pixel in the array.
DIM1_MIN $(P)$(R)MinY
$(P)$(R)MinY_RBV
longout
longin
NDPluginROI
Dim2Min
asynInt32 r/w First pixel in the ROI in the Z direction.
0 is the first pixel in the array.
DIM2_MIN $(P)$(R)MinZ
$(P)$(R)MinZ_RBV
longout
longin
NDPluginROI
Dim0Size
asynInt32 r/w Size of the ROI in the X direction DIM0_SIZE $(P)$(R)SizeX
$(P)$(R)SizeX_RBV
longout
longin
NDPluginROI
Dim1Size
asynInt32 r/w Size of the ROI in the Y direction DIM1_SIZE $(P)$(R)SizeY
$(P)$(R)SizeY_RBV
longout
longin
NDPluginROI
Dim2Size
asynInt32 r/w Size of the ROI in the Z direction DIM2_SIZE $(P)$(R)SizeZ
$(P)$(R)SizeZ_RBV
longout
longin
NDPluginROI
Dim0MaxSize
asynInt32 r/o Maximum size of the ROI in the X direction DIM0_MAX_SIZE $(P)$(R)MaxSizeX_RBV longin
NDPluginROI
Dim1MaxSize
asynInt32 r/o Maximum size of the ROI in the Y direction DIM1_MAX_SIZE $(P)$(R)MaxSizeY_RBV longin
NDPluginROI
Dim2MaxSize
asynInt32 r/o Maximum size of the ROI in the Z direction DIM2_MAX_SIZE $(P)$(R)MaxSizeZ_RBV longin
NDPluginROI
Dim0Reverse
asynInt32 r/w Reverse ROI in the X direction
(0=No, 1=Yes)
DIM0_REVERSE $(P)$(R)ReverseX
$(P)$(R)ReverseX_RBV
longout
longin
NDPluginROI
Dim1Reverse
asynInt32 r/w Reverse ROI in the Y direction
(0=No, 1=Yes)
DIM1_REVERSE $(P)$(R)ReverseY
$(P)$(R)ReverseY_RBV
longout
longin
NDPluginROI
Dim2Reverse
asynInt32 r/w Reverse ROI in the Z direction
(0=No, 1=Yes)
DIM2_REVERSE $(P)$(R)ReverseZ
$(P)$(R)ReverseZ_RBV
longout
longin
NDPluginROI
DataType
asynInt32 r/w Data type of the ROI (NDDataType_t). This can be different from the data type of the NDArray callback data. DATA_TYPE $(P)$(R)DataType
$(P)$(R)DataType_RBV
mbbo
mbbi
NDPluginROI
BgdWidth
asynInt32 r/w Width of the background in pixels to use when computing net counts. 0=no background subtraction, so the net counts is the same as the total counts. BGD_WIDTH $(P)$(R)BgdWidth
$(P)$(R)BgdWidth_RBV
longout
longin
ADImageSizeX asynInt32 r/o Size of the ROI data in the X direction IMAGE_SIZE_X $(P)$(R)ImageSizeX_RBV longin
ADImageSizeY asynInt32 r/o Size of the ROI data in the Y direction IMAGE_SIZE_Y $(P)$(R)ImageSizeY_RBV longin
ADImageSizeZ asynInt32 r/o Size of the ROI data in the Z direction IMAGE_SIZE_Z $(P)$(R)ImageSizeZ_RBV longin
ROI statistics
NDPluginROI
ComputeStatistics
asynInt32 r/w Flag to control whether to compute statistics for this ROI (0=No, 1=Yes). Not computing statistics reduces CPU load. COMPUTE_STATISTICS $(P)$(R)ComputeStatistics
$(P)$(R)ComputeStatistics_RBV
bo
bi
NDPluginROI
MinValue
asynFloat64 r/o Minimum value in any element in the ROI MIN_VALUE $(P)$(R)MinValue_RBV ai
NDPluginROI
MaxValue
asynFloat64 r/o Maximum value in any element in the ROI MAX_VALUE $(P)$(R)MaxValue_RBV ai
NDPluginROI
MeanValue
asynFloat64 r/o Mean value in the ROI MEAN_VALUE $(P)$(R)MeanValue_RBV ai
NDPluginROI
Total
asynFloat64 r/o Sum (total) of all elements in the ROI TOTAL $(P)$(R)Total_RBV ai
NDPluginROI
Net
asynFloat64 r/o Net (background subtracted) total of all elements in the ROI. The background is calculated by determining the average counts per array element in a border around the ROI of width NDPluginROIBgdWidth. This average background counts per element is then subtracted from all elements inside the ROI. NET $(P)$(R)Net_RBV ai
ROI histogram
NDPluginROI
ComputeHistogram
asynInt32 r/w Flag to control whether to compute the histogram for this ROI (0=No, 1=Yes). Not computing the histogram reduces CPU load. COMPUTE_HISTOGRAM $(P)$(R)ComputeHistogram
$(P)$(R)ComputeHistogram_RBV
bo
bi
NDPluginROI
HistSize
asynInt32 r/w Number of elements (bins) in the histogram HIST_SIZE $(P)$(R)HistSize
$(P)$(R)HistSize_RBV
longout
longin
NDPluginROI
HistMin
asynFloat64 r/w Minimum value for the histogram. All values less than or equal to this will be in the first bin of the histogram. HIST_MIN $(P)$(R)HistMin
$(P)$(R)HistMin_RBV
ao
ai
NDPluginROI
HistMax
asynFloat64 r/w Maximum value for the histogram. All values greater than or equal to this will be in the last bin of the histogram. HIST_MAX $(P)$(R)HistMax
$(P)$(R)HistMax_RBV
ao
ai
NDPluginROI
HistEntropy
asynFloat64 r/o Entropy of the image. This is a measure of the sharpness of the histogram, and is often a useful figure of merit for determining sharpness of focus, etc. It is defined as -SUM(BIN[i]*log(BIN[i]), where the sum is over the number of bins in the histogram and BIN[i] is the number of elements in bin i. HIST_ENTROPY $(P)$(R)HistEntropy_RBV ai
NDPluginROI
HistArray
asynFloat64Array r/o Histogram array, i.e. counts in each histogram bin. HIST_ARRAY $(P)$(R)Histogram_RBV waveform

A special case is made when the NDArray data has colorMode=NDColorModeRGB1 or NDColorModeRGB2. In these cases the user interface to the array dimensions is changed so that the Z PVs always refer to the color dimension (as for NDColorModeRGB3), the X dimension refers to the horizontal direction, and the Y direction refers to the vertical direction. This is very convenient, because it means that the ROI does not need to redefined if, for example, the color mode is changed from Mono to RGB1, which would be required if the X, Y and Z directions were not automatically switched.

Configuration

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

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


  
Argument Description
portName The name of the asyn port for this plugin.
queueSize The maximum number of NDArray objects that can be queued for processing. Passed to the NDPluginDriver base class constructor.
blockingCallbacks Flag controlling whether callbacks block. Passed to the NDPluginDriver base class constructor.
NDArrayPort The name of the asyn port of the driver that will provide the NDArray data. Passed to the NDPluginDriver base class constructor.
NDArrayAddr The asyn addr of the asyn port of the driver that will provide the NDArray data. Passed to the NDPluginDriver base class constructor.
maxROIs Maximum number of ROIs that this plugin will support.
maxBuffers Maximum number of NDArray buffers to be created for plugin callbacks, i.e. for plugins that will be getting called from this plugin. Passed to the constructor for the NDPluginDriver base class.
maxMemory Maximum number of bytes of memory to be allocated from the NDArrayPool. Passed to the constructor for the NDPluginDriver base class. The NDPluginROI plugin allocates one NDArray object for each ROI, so this should be at least maxROIs times the size of the largest NDArray to be used.

Screen shots

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.

NDROI.adl

NDROI.png

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

NDROIN.adl

NDROIN.png

The following is another MEDM screen that provides access to the parameters 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.

NDROI8.adl

NDROI8.png

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.

Highlighted Regions-of-Interest

ROI_outlines.png