# areaDetector Plugin NDPluginROI

## October 1, 2012

## Mark Rivers

## University of Chicago

## Contents

- Overview
- Configuration
- Screen shots

## Overview

NDPluginROI selects a rectangular "Region-Of-Interest" (ROI) from the NDArray callback data. The ROI can be any size, from a single array element to the entire array. NDPluginROI does the following operations, in this order:

1. Extracts the ROI as defined by its offset (starting array element) and size in each dimension.
2. Optional binning in any dimension.
3. Optional orientation reversal (mirroring) in any dimension.
4. Optional scaling (dividing) by a scale factor.
5. Optional conversion to a new data type.
6. Export the ROI as a new NDArray object. The NDPluginROI is both a recipient of callbacks and a source of NDArray callbacks, as a driver is. This means that other plugins like NDPluginStdArrays and NDPluginFile can be connected to an NDPluginROI plugin, in which case they will display or save the selected ROI rather than the full detector driver data.

If scaling is enabled then the array is promoted to a double when it is extracted and binned. The scaling is done on this double-precision array, and then the array is converted back to the desired output data type. This makes scaling relatively computationally intensive, but ensures that correct results are obtained, without integer truncation problems.

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 may be removed in a future release.

NDPluginROI inherits from NDPluginDriver. The NDPluginROI class documentation describes this class in detail.

NDPluginROI.h defines the following parameters. It also implements all of the standard plugin parameters from NDPluginDriver. The EPICS database NDROI.template provide access to these parameters, listed in the following table. 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 `NDPluginROIName`.

Parameter Definitions in NDPluginROI.h and EPICS Record Definitions in NDROI.template
Parameter index variable | asyn interface | Access | Description | drvInfo 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
ROI definition
NDPluginROI Dim0Enable | asynInt32 | r/w | Enable ROI calculations in the X dimension. If not enabled then the start, size, binning, and reverse operations are disabled in the X dimension, and the values from the input array are used. | DIM0_ENABLE | $(P)$(R)EnableX $(P)$(R)EnableX_RBV | bo bi
NDPluginROI Dim1Enable | asynInt32 | r/w | Enable ROI calculations in the Y dimension. If not enabled then the start, size, binning, and reverse operations are disabled in the Y dimension, and the values from the input array are used. | DIM1_ENABLE | $(P)$(R)EnableY $(P)$(R)EnableY_RBV | bo bi
NDPluginROI Dim2Enable | asynInt32 | r/w | Enable ROI calculations in the Z dimension. If not enabled then the start, size, binning, and reverse operations are disabled in the Z dimension, and the values from the input array are used. | DIM2_ENABLE | $(P)$(R)EnableZ $(P)$(R)EnableZ_RBV | bo bi
NDPluginROI Dim0Bin | asynInt32 | r/w | Binning in the X dimension | DIM0_BIN | $(P)$(R)BinX $(P)$(R)BinX_RBV | longout longin
NDPluginROI Dim1Bin | asynInt32 | r/w | Binning in the Y dimension | DIM1_BIN | $(P)$(R)BinY $(P)$(R)BinY_RBV | longout longin
NDPluginROI Dim2Bin | asynInt32 | r/w | Binning in the Z dimension | DIM2_BIN | $(P)$(R)BinZ $(P)$(R)BinZ_RBV | longout longin
NDPluginROI Dim0Min | asynInt32 | r/w | First pixel in the ROI in the X dimension. 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 dimension. 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 dimension. 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 dimension | DIM0_SIZE | $(P)$(R)SizeX $(P)$(R)SizeX_RBV | longout longin
NDPluginROI Dim1Size | asynInt32 | r/w | Size of the ROI in the Y dimension | DIM1_SIZE | $(P)$(R)SizeY $(P)$(R)SizeY_RBV | longout longin
NDPluginROI Dim2Size | asynInt32 | r/w | Size of the ROI in the Z dimension | DIM2_SIZE | $(P)$(R)SizeZ $(P)$(R)SizeZ_RBV | longout longin
NDPluginROI Dim0AutoSize | asynInt32 | r/w | Automatically set SizeX to the input array size minus MinX | DIM0_AUTO_SIZE | $(P)$(R)AutoSizeX $(P)$(R)AutoSizeX_RBV | bo bi
NDPluginROI Dim1AutoSize | asynInt32 | r/w | Automatically set SizeY to the input array size minus MinY | DIM1_AUTO_SIZE | $(P)$(R)AutoSizeY $(P)$(R)AutoSizeY_RBV | bo bi
NDPluginROI Dim2AutoSize | asynInt32 | r/w | Automatically set SizeZ to the input array size minus MinZ | DIM2_AUTO_SIZE | $(P)$(R)AutoSizeZ $(P)$(R)AutoSizeZ_RBV | bo bi
NDPluginROI Dim0MaxSize | asynInt32 | r/o | Maximum size of the ROI in the X dimension | DIM0_MAX_SIZE | $(P)$(R)MaxSizeX_RBV | longin
NDPluginROI Dim1MaxSize | asynInt32 | r/o | Maximum size of the ROI in the Y dimension | DIM1_MAX_SIZE | $(P)$(R)MaxSizeY_RBV | longin
NDPluginROI Dim2MaxSize | asynInt32 | r/o | Maximum size of the ROI in the Z dimension | DIM2_MAX_SIZE | $(P)$(R)MaxSizeZ_RBV | longin
NDPluginROI Dim0Reverse | asynInt32 | r/w | Reverse ROI in the X dimension. (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 dimension. (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 dimension. (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. | ROI_DATA_TYPE | $(P)$(R)DataType $(P)$(R)DataType_RBV | mbbo mbbi
NDArraySizeX | asynInt32 | r/o | Size of the ROI data in the X dimension | ARRAY_SIZE_X | $(P)$(R)ArraySizeX_RBV | longin
NDArraySizeY | asynInt32 | r/o | Size of the ROI data in the Y dimension | ARRAY_SIZE_Y | $(P)$(R)ArraySizeY_RBV | longin
NDArraySizeZ | asynInt32 | r/o | Size of the ROI data in the Z dimension | ARRAY_SIZE_Z | $(P)$(R)ArraySizeZ_RBV | longin
NDPluginROI EnableScale | asynInt32 | r/w | Enable dividing by the Scale value. (0=Disable, 1=Enable). This is very useful when binning or when converting from a higher precision data type to a lower precision data type. For example when binning 2x2, then Scale=4 (dividing by 4) will prevent integer overflow. Similarly, when converting from 16-bit to 8-bit integers one might scale by 256, or perhaps a smaller number if the 16-bit data does not use the full 16-bit range. | ENABLE_SCALE | $(P)$(R)EnableScale $(P)$(R)EnableScale_RBV | bo bi
NDPluginROI Scale | asynFloat64 | r/w | The scale value to divide by if EnableScale is enabled. | SCALE_VALUE | $(P)$(R)Scale $(P)$(R)Scale_RBV | ao ai

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 dimension, and the Y dimension refers to the vertical dimension. 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 dimensions were not automatically switched.

## Configuration

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

    NDROIConfigure(const char *portName, int queueSize, int blockingCallbacks,
                   const char *NDArrayPort, int NDArrayAddr,
                   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 NDROIConfigure function in the NDPluginROI.cpp documentation and in the documentation for the constructor for the NDPluginROI class.

## Screen shots

The following MEDM screen provides access to the parameters in NDPluginDriver.h and NDPluginROI.h through records in NDPluginBase.template and NDROI.template.

### NDROI.adl

The following MEDM screen provides access to 4 ROIs at once.

### NDROI4.adl