diff --git a/documentation/NDPluginROI.html b/documentation/NDPluginROI.html index 4662aa2..5bc4661 100755 --- a/documentation/NDPluginROI.html +++ b/documentation/NDPluginROI.html @@ -1,555 +1,549 @@ - - - areaDetector Plugin NDPluginROI - - - -
-

- areaDetector Plugin NDPluginROI

-

- March 19, 2010

-

- Mark Rivers

-

- University of Chicago

-
-

- Contents

- -

- 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. -
  2. Optional binning in any dimension.
    3. -
  3. Optional orientation reversal (mirroring) in any dimension.
    4. -
  4. Optional scaling (dividing) by a scale factor.
    5. -
  5. Optional conversion to a new data type.
    6. -
  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.
    7. -
-

- 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 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 NDROI.template
- Parameter index - 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
- 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. - ROI_DATA_TYPE - $(P)$(R)DataType
- $(P)$(R)DataType_RBV		 - mbbo
- mbbi
- NDArraySizeX - asynInt32 - r/o - Size of the ROI data in the X direction - ARRAY_SIZE_X - $(P)$(R)ArraySizeX_RBV - longin
- NDArraySizeY - asynInt32 - r/o - Size of the ROI data in the Y direction - ARRAY_SIZE_Y - $(P)$(R)ArraySizeY_RBV - longin
- NDArraySizeZ - asynInt32 - r/o - Size of the ROI data in the Z direction - 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 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 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 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 -
- - + "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> + + + areaDetector Plugin NDPluginROI + + + +
+

+ areaDetector Plugin NDPluginROI

+

+ March 19, 2010

+

+ Mark Rivers

+

+ University of Chicago

+
+

+ Contents

+ +

+ 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. +
  2. Optional binning in any dimension.
    3. +
  3. Optional orientation reversal (mirroring) in any dimension.
    4. +
  4. Optional scaling (dividing) by a scale factor.
    5. +
  5. Optional conversion to a new data type.
    6. +
  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.
    7. +
+

+ 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 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 NDROI.template
+ Parameter index variable + 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
+ 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. + ROI_DATA_TYPE + $(P)$(R)DataType
+ $(P)$(R)DataType_RBV		 + mbbo
+ mbbi
+ NDArraySizeX + asynInt32 + r/o + Size of the ROI data in the X direction + ARRAY_SIZE_X + $(P)$(R)ArraySizeX_RBV + longin
+ NDArraySizeY + asynInt32 + r/o + Size of the ROI data in the Y direction + ARRAY_SIZE_Y + $(P)$(R)ArraySizeY_RBV + longin
+ NDArraySizeZ + asynInt32 + r/o + Size of the ROI data in the Z direction + 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 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 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 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 +
+ +