From f3503b459465603613492b8d306d17d0f6bf7ee4 Mon Sep 17 00:00:00 2001 From: rivers Date: Mon, 22 Mar 2010 17:31:37 +0000 Subject: [PATCH] Major changes, rewrite from old ROI plugin docs git-svn-id: https://subversion.xor.aps.anl.gov/synApps/areaDetector/trunk@10302 dc6c5ff5-0b8b-c028-a01f-ffb33f00fc8b --- documentation/NDPluginProcess.html | 1507 +++++++++++++--------------- 1 file changed, 724 insertions(+), 783 deletions(-) diff --git a/documentation/NDPluginProcess.html b/documentation/NDPluginProcess.html index 9953f29..d9e95fd 100755 --- a/documentation/NDPluginProcess.html +++ b/documentation/NDPluginProcess.html @@ -2,15 +2,15 @@ "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"> - areaDetector Plugin NDPluginROI + areaDetector Plugin NDPluginProcess

- areaDetector Plugin NDPluginROI

+ areaDetector Plugin NDPluginProcess

- March 7, 2010

+ March 20, 2010

Mark Rivers

@@ -27,64 +27,58 @@ 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 optinally does the following operations with these ROIs, in this order: + NDPluginProcess performs arithmetic processing on NDArray data. It performs the + following operations in the order listed. Each of these operations can be individually + enabled and disabled.

    -
  1. Extracts of the selected region. When the ROI is extracted the following operations - can be performed: -
      -
    • Binning in any dimension.
      • -
    • Orientation reversal (mirroring) in any dimension.
      • -
    • Conversion to a new data type.
      • -
    -
  2. Subtracts a background array which has been previously acquired.
    3. -
  3. Clips to minimum and maximum specified values.
    4. -
  4. Computes statistics, e.g. mean, maximum, minimum, total, net (background subtracted), - and centroid values.
    5. -
  5. Computes a histogram of the values (e.g. number of pixels versus intensity per - pixel)
    6. -
  6. 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.
    7. +
  7. Divides by a flat field array which has been previously acquired, and then multiplies + by a flat field scale factor.
    8. +
  8. Multiplies by a scale factor and adds an offset.
    9. +
  9. Clips to a minimum specified value.
    10. +
  10. Clips to a minimum specified value.
    11. +
  11. Applies a recursive digital filter.
    12. +
  12. Converts to the specified output data type.
    13. +
  13. Exports the processed data as a new NDArray object.

- Each of these operations can be enabled or disabled independently. + If any of the above operations is enabled, then the array is first converted to + NDFloat64 data type, i.e. double-precision float. The operations are all performed + in double-precision, and then the array is converted to the specified output data + type.

- Each NDPluginROI can handle any number of ROIs. 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 may be removed - in a future release. + NDPluginProcess is both a recipient of callbacks and a source of NDArray + callbacks. This means that other plugins, such the NDPluginStdArrays, NDPluginStats, + and NDPluginFile plugins can be connected to an NDPluginProcess plugin, in which + case they will use the processed data.

- NDPluginROI inherits from NDPluginDriver. The - NDPluginROI class documentation describes this class in detail. + NDPluginProcess is fully N-dimensional. It can be used for 2-D images, 3-D (color) + images, or any type of N-dimensional data.

- 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 - NDPluginDriver. The EPICS database NDROI.template provide access to these - parameters, listed in the following table. + NDPluginProcess inherits from NDPluginDriver. The + NDPluginProcess class documentation describes this class in detail. +

+

+ NDPluginProcess.h defines the following parameters. It also implements all of the + standard plugin parameters from NDPluginDriver. + The EPICS database NDProcess.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 + NDPluginProcessSaveBackground.

+ Parameter Definitions in NDPluginProcess.h and EPICS Record Definitions in NDProcess.template + Parameter index variable - - - - - - - - - - -
- Parameter Definitions in NDPluginROI.h and EPICS Record Definitions in NDROI.template
- Enum name asyn interface @@ -98,506 +92,35 @@ 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. -

- - - - - - - - - - - + Background subtraction - - - - - - - - - + NDPluginProcess
+ SaveBackground - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + SAVE_BACKGROUND + $(P)$(R)SaveBackground
+ $(P)$(R)SaveBackground_RBV @@ -605,9 +128,9 @@ r/o + for this array using SaveBackground. This flag will be Invalid (0) if no background + has been acquired, or if the size of the array has changed since the background + was last acquired. + Flag indicating whether the background array acquired with SaveBackground should + be subtracted when processing the array. If ValidBackground=0 then no background + subtraction is done even if EnableBackground=Enable. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -662,18 +344,15 @@ @@ -686,15 +365,15 @@ @@ -707,18 +386,15 @@ @@ -729,349 +405,614 @@ ao
ai - - - + NDPluginProcess
+ DataType + Data type of the output array (NDDataType_t). This can be different from the data + type of the NDArray callback data. + PROCESS_DATA_TYPE + $(P)$(R)DataTypeOut
+ $(P)$(R)DataTypeOut_RBV + mbbo
+ mbbi + + + + NDPluginProcess
+ EnableFilter + asynInt32 + r/w - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + ENABLE_FILTER - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - + $(P)$(R)EnableFilter
+ $(P)$(R)EnableFilter_RBV + NDPluginProcess
+ ResetFilter + Command to reset the filter back to its initial state. + RESET_FILTER + $(P)$(R)ResetFilter
+ $(P)$(R)ResetFilter_RBV + + + + + + + + + + NDPluginProcess
+ NumFiltered + + + + + + + + + + + + + + + + + + + Output offset coefficient. + + FILTER_OOFFSET + $(P)$(R)OOffset
+ $(P)$(R)OOffset_RBV + NDPluginProcess
+ OScale + Output scale coefficient. + + FILTER_OSCALE + $(P)$(R)OScale
+ $(P)$(R)OScale_RBV + NDPluginProcess
+ OC1 + r/w + Output coefficient #1. + + FILTER_OC1 + $(P)$(R)OC1
+ $(P)$(R)OC1_RBV + NDPluginProcess
+ OC2 + asynFloat64 + r/w + Output coefficient #2. + + FILTER_OC2 + $(P)$(R)OC2
+ $(P)$(R)OC2_RBV + ao
+ ai + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
- 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. - ROI_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
- 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
- ROI clipping and background subtraction
- NDPluginROI
- GrabBackground		 - asynInt32 - r/w - Command to use the most recently acquired ROI array as a background. Note that this - recently acquired ROI should have been acquired with EnableBackground=0, or else + Command to use the most recently acquired array as a background. Note that this + recently acquired array should have been acquired with EnableBackground=0, or else that array will already have had the background subtracted, which is probably not what was intended! - GRAB_BACKGROUND - $(P)$(R)GrabBackground
- $(P)$(R)GrabBackground_RBV		 bo
bi
- NDPluginROI
+ NDPluginProcess
ValidBackground		 asynInt32 Flag indicating whether there is a valid background array that has been acquired - for this ROI using GrabBackground. This flag will be Invalid (0) if no background - has been acquired, or of the size of the ROI has changed since the background was - last acquired. VALID_BACKGROUND @@ -617,19 +140,16 @@
- NDPluginROI
+ NDPluginProcess
EnableBackground		 asynInt32 r/w - Flag indicating whether the background array acquired with GrabBackground should - be subtracted when computing this ROI. This background subtraction is done before - the clipping operations, and before the statistics are computed. If ValidBackground=0 - then no background subtraction is done. This background subtraction modifies the - ROI data, so other plugins that use this ROI will receive the background subtracted - data. ENABLE_BACKGROUND @@ -639,17 +159,179 @@ bo
bi
+ Flat field normalization
- NDPluginROI
+ NDPluginProcess
+ SaveFlatField		 + asynInt32 + r/w + Command to use the most recently acquired array as a flat field. Note that this + recently acquired array should have been acquired with EnableFlatField=0, or else + that array will already have been flat field normalized, which is probably not what + was intended! + SAVE_FLAT_FIELD + $(P)$(R)SaveFlatField
+ $(P)$(R)SaveFlatField_RBV		 + bo
+ bi
+ NDPluginProcess
+ ValidFlatField		 + asynInt32 + r/o + Flag indicating whether there is a valid flat field array that has been acquired + for this array using SaveFlatField. This flag will be Invalid (0) if no flat field + has been acquired, or if the size of the array has changed since the flat field + was last acquired. + VALID_FLAT_FIELD + $(P)$(R)ValidFlatField_RBV + bi
+ NDPluginProcess
+ EnableFlatField		 + asynInt32 + r/w + Flag indicating whether the array should be divided by the flat field array (acquired + with SaveFlatField) when processing the array. If ValidFlatField=0 then no flat + field normalization is done even if EnableBackground=Enable. The processing step + consists of: +
+ Array = Array / FlatField * ScaleFlatField		 + ENABLE_FLAT_FIELD + $(P)$(R)EnableFlatField
+ $(P)$(R)EnableFlatField_RBV		 + bo
+ bi
+ NDPluginProcess
+ ScaleFlatField		 + asynFloat64 + r/w + The scale factor to multiply by after dividing the array by the flat field array. + This scale factor is normally chosen so that the data after scaling fills the dynamic + range of the output data type. + + SCALE_FLAT_FIELD + $(P)$(R)ScaleFlatField
+ $(P)$(R)ScaleFlatField_RBV		 + ao
+ ai
+ Scaling and offset
+ NDPluginProcess
+ EnableScaleOffset		 + asynInt32 + r/w + Flag indicating whether the array should be multiplied by Scale and then summed + with Offset when processing the array. The processing step consists of: +
+ Array = Array * Scale + Offset		 + ENABLE_SCALE_OFFSET + $(P)$(R)EnableScaleOffset
+ $(P)$(R)EnableScaleOffset_RBV		 + bo
+ bi
+ NDPluginProcess
+ Scale		 + asynFloat64 + r/w + The scale factor to multiply by. + + SCALE + $(P)$(R)Scale
+ $(P)$(R)Scale_RBV		 + ao
+ ai
+ NDPluginProcess
+ Offset		 + asynFloat64 + r/w + The offset to add. + + OFFSET + $(P)$(R)Offset
+ $(P)$(R)Offset_RBV		 + ao
+ ai
+ Low and high clipping
+ NDPluginProcess
EnableLowClip		 asynInt32 r/w - Flag to control whether to clip values to the LowClip value for this ROI (0=No, - 1=Yes). + Flag to control whether to clip values to the LowClip value for this array (0=Disable, + 1=Enable). ENABLE_LOW_CLIP
- NDPluginROI
+ NDPluginProcess
LowClip		 asynFloat64 r/w - The minimum allowed value for this ROI. If EnableLowClip=1, then all values in the - array less than LowClip will be replaced by LowClip. This clipping operation is - performed after the background is subtracted (if EnableBackground=1). This clipping - modifies the ROI data, so other plugins that use this ROI will receive the clipped - data. + The minimum allowed value for this array. If EnableLowClip=1, then all values in + the array less than LowClip will be replaced by LowClip. LOW_CLIP
- NDPluginROI
+ NDPluginProcess
EnableHighClip		 asynInt32 r/w - Flag to control whether to clip values to the HighClip value for this ROI (0=No, - 1=Yes). + Flag to control whether to clip values to the HighClip value for this array (0=Disable, + 1=Enable). ENABLE_HIGH_CLIP
- NDPluginROI
+ NDPluginProcess
HighClip		 asynFloat64 r/w - The maximum allowed value for this ROI. If EnableHighClip=1, then all values in - the array greater than HighClip will be replaced by HighClip. This clipping operation - is performed after the background is subtracted (if EnableBackground=1). This clipping - modifies the ROI data, so other plugins that use this ROI will receive the clipped - data. + The maximum allowed value for this array. If EnableHighClip=1, then all values in + the array greater than HighClip will be replaced by HighClip. HIGH_CLIP
- 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
+ Recursive filter
- 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. If NDPluginROIBgdWidth is ≤ - 0 then no background is computed. Note that this background subtraction is done - after the "array" background is subtracted if EnableBackground=1, as described above. + Flag indicating whether the array should be processed with a recursive filter. The + details of the filter operation are explained below.
 - NET - $(P)$(R)Net_RBV - ai
- NDPluginROI
- CentroidX		 - asynFloat64 - r/o - X centroid of the ROI. - CENTROIDX_VALUE - $(P)$(R)CentroidX_RBV - ai
- NDPluginROI
- CentroidY		 - asynFloat64 - r/o - Y centroid of the ROI. - CENTROIDY_VALUE - $(P)$(R)CentroidY_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		 + bo
+ bi
+ NDPluginProcess
+ NumFilter		 + asynInt32 + r/w + The characteristic number of arrays to use when filtering. The value of NumFiltered + will increase as each array is processed, until it reaches the value of NumFilter, + when it will no longer increase. The value of NumFiltered is used in the filter + equations, as explained below. + + NUM_FILTER + $(P)$(R)NumFilter
+ $(P)$(R)NumFilter_RBV		 longout
longin
- NDPluginROI
- HistMin		 + asynInt32 + r/o + The number of arrays that have been processed by the filter since the filter was + last reset. The value of NumFiltered is incremented as each array is processed, + until it reaches the value of NumFilter, when it will cease incrementing. The value + of NumFiltered is used in the filter equations, as explained below. + + NUM_FILTERED + $(P)$(R)NumFiltered_RBV + longin
+ N.A. + N.A. + r/w + The filter type, chosen from a predefined list, as described below. + + N.A. + $(P)$(R)FilterType + mbbo
+ NDPluginProcess
+ OOffset		 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 + ao
ai
- NDPluginROI
- HistArray		 - asynFloat64Array - r/o - Histogram array, i.e. counts in each histogram bin. - HIST_ARRAY - $(P)$(R)Histogram_RBV - waveform
+ NDPluginProcess
+ OC3		 + asynFloat64 + r/w + Output coefficient #3. + + FILTER_OC3 + $(P)$(R)OC3
+ $(P)$(R)OC3_RBV		 + ao
+ ai
+ NDPluginProcess
+ OC4		 + asynFloat64 + r/w + Output coefficient #4. + + FILTER_OC4 + $(P)$(R)OC4
+ $(P)$(R)OC4_RBV		 + ao
+ ai
+ NDPluginProcess
+ FOffset		 + asynFloat64 + r/w + Filter offset coefficient. + + FILTER_FOFFSET + $(P)$(R)FOffset
+ $(P)$(R)FOffset_RBV		 + ao
+ ai
+ NDPluginProcess
+ FScale		 + asynFloat64 + r/w + Filter scale coefficient. + + FILTER_FSCALE + $(P)$(R)FScale
+ $(P)$(R)FScale_RBV		 + ao
+ ai
+ NDPluginProcess
+ FC1		 + asynFloat64 + r/w + Filter coefficient #1. + + FILTER_FC1 + $(P)$(R)FC1
+ $(P)$(R)FC1_RBV		 + ao
+ ai
+ NDPluginProcess
+ FC2		 + asynFloat64 + r/w + Filter coefficient #2. + + FILTER_FC2 + $(P)$(R)FC2
+ $(P)$(R)FC2_RBV		 + ao
+ ai
+ NDPluginProcess
+ FC3		 + asynFloat64 + r/w + Filter coefficient #3. + + FILTER_FC3 + $(P)$(R)FC3
+ $(P)$(R)FC3_RBV		 + ao
+ ai
+ NDPluginProcess
+ FC4		 + asynFloat64 + r/w + Filter coefficient #4. + + FILTER_FC4 + $(P)$(R)FC4
+ $(P)$(R)FC4_RBV		 + ao
+ ai
+ NDPluginProcess
+ ROffset		 + asynFloat64 + r/w + Reset offset coefficient. + + FILTER_ROFFSET + $(P)$(R)ROffset
+ $(P)$(R)ROffset_RBV		 + ao
+ ai
+ NDPluginProcess
+ RC1		 + asynFloat64 + r/w + Filter coefficient #1. + + FILTER_RC1 + $(P)$(R)RC1
+ $(P)$(R)RC1_RBV		 + ao
+ ai
+ NDPluginProcess
+ RC2		 + asynFloat64 + r/w + Filter coefficient #2. + + FILTER_RC2 + $(P)$(R)RC2
+ $(P)$(R)RC2_RBV		 + ao
+ ai
+

+ Recursive filter implementation

- 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.

+ The recursive filter performs filtering in the time (not spatial) domain. It is + implemented in a fairly general manner, so that a variety of filters can be implemented. + These include integrating filters and differentiating filter types. The recursive + filter stores one "filter" array internally. Using this internal filter array, and + a new input array, it computes an output array, and a new version of the filter + array. The equations governing the output array and new filter array are: +

+ 
+O[n] = OOffset + OScale*((OC1 + OC2/N)*F[n-1] +
+                         (OC3 + OC4/N)*I[n])
+F[n] = FOffset + FScale*((FC1 + FC2/N)*F[n-1] +
+                         (FC3 + FC4/N)*I[n])
+On filter reset
+F[0] = ROffset + RC1*F[0] + RC2*I[0] 
+  
+where
+  I[n] = New input array from callback
+  I[0] = First input array after a filter reset
+F[n-1] = Stored filter array
+  F[n] = New filter array
+  F[0] = Current filter array when filter is reset.  
+         May be a copy of I[0] if there was no valid filter array.
+     N = Current value of NumFiltered
+  O[n] = Output array passed to clients
+
+

+ Predefined filters

+

+ The NDProcess.template database implements the following predefined filters using + the $(P)$(R)FilterType record. The implementation of these predefined filter types + is done entirely in the database, not in the plugin code. The database simply downloads + values of OC1-OC4, FC1-FC4, and RC1-RC2 that result in predefined filter behaviours. + The operation of the recursive filter is by no means limited to these fixed filter + types, they are simply provided as a convenience, and can be easily modified or + extended. Note that the database does not download values of OOffset, OScale, FOffset, + FScale, or ROffset, so these remain unchanged when a new filter is selected. The + equations below do not include these offset and scale values, but they are useful + in many circumstances.

+

+ The NDProcess_settings.req file for save/restore saves the values of all of the + filter coefficients, and downloads them when EPICS initialized at iocInit. It also + saves the FilterType, but does not process this record at iocInit, so that any customized + filter coefficients will be preserved, and will not be replaced by the defaults + for that filter type. +

+

+ Recursive Average

+

+ The recursive average filter does input array averaging. It is defined as:

+ 
+O[n] = F[n] = (1-1/N)*F[n-1] + 1/N*I[n]
+
+

+ N is the characteristic number of arrays in the average. For example, if N=100, + then each new array is weighted by 0.01 and the previous filter value is weighted + by 0.99. This is an infinite impulse response (IIR) filter, because the effect of + one array never complelely dissappears, but rather decays exponentially. When this + filter is reset the filter array is initialized with the first input array. This + filter can be used to decrease the noise and increase the dynamic range of a repetitive + input signal with a small signal. In that case it can be useful to use set EnableScaleOffset=Enable + and set Scale to a large enough number to more fully use the dynamic range of the + output data type. The averaged signal will then better use the dynamic range of + the output data type. +

+

+ Recursive Sum

+

+ The recursive average filter does input array summing. It is defined as:

+ 
+O[n] = F[n] = F[n-1] + 1/N*I[n]
+
+

+ N is the characteristic number of arrays in the sum. For example, if N=100, then + each new array is weighted by 0.01. When this filter is reset the filter array is + initialized to 0. This filter typically cannot be run forever, because the output + grows monotonically and will lead to overflow. +

+

+ Difference

+

+ The difference filter computes the difference between frame N and frame N-1. It + is defined as:

+ 
+O[n] = -F[n-1] + I[n]
+F[n] = I[n]
+
+

+ Note that the difference will often be a small signed number. If the output datatype + is unsigned, or if a display client expects unsigned numbers, then it can be useful + to set OOffset to a non-zero value to add an offset to the result. For example, + if the output data type is UInt8 (unsigned 8-bit), then setting OOffset to 128 will + produce an unsigned image centered at 128. Similarly OScale can be used to increase + the range of the difference by multiplying by a factor greater than 1, although + this will not increase the dynamic range of the result, only the absolute range. +

+

+ Recursive Average Difference

+

+ This filter computes the difference between frame N and the recursive average of + previous frames. It is a combination of the Difference and Recursive Average filters + described above. The new filter is a recursive average, but the output is the difference + between the current frame and that recursive average. It is defined as:

+ 
+O[n] = -F[n-1] + I[n]
+F[n] = (1-1/N)*F[n-1] + 1/N*I[n]
+
+

+ N is again the characteristic number of arrays in the average. +

+

+ Copy to Filter

+

+ This filter simply copies the input array to the filter array and the output array. + It is defined as:

+ 
+O[n] = F[n] = I[n]
+
+

+ This filter can be used to load the filter (F) with a certain array, which is then + subsequently used for some other filter type.

Configuration

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

+ The NDPluginProcess plugin is created with the NDProcessConfigure 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 maxROIs,
-               int maxBuffers, size_t maxMemory,
-               int priority, int stackSize)
+NDProcessConfigure(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 + documentation on the NDProcessConfigure function in the + NDPluginProcess.cpp documentation and in the documentation for the constructor + for the NDPluginProcess 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. + and NDPluginProcess.h through records in NDPluginBase.template and NDProcess.template. In this + example the input image is first scaled by 35 and offset by -110. The image is then run through + a recursive averaging filter with N=100.

- NDROI.adl

- NDROI.png + NDProcess.adl + NDProcess.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. -
-

+ Image collected with 30 microsecond exposure time, so it is very noisy. This is + the image output from the NDPlugProcess plugin with Scale and Offset as shown above, + but with the recursive filter disabled.

-

- NDROIN.adl

- NDROIN.png + NDProcess_unfilted.jpg

- 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. -

+ NDPluginStats plugin connected to the NDPluginProcess filter for the noisy image + above. Note that there are only 6 non-zero intensities in the histogram, because + the brightest pixels are only 6 A/D units above background.

-

- NDROI8.adl

- NDROI8.png + NDStats_unfiltered.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. -

+ Same image collected with 30 microsecond exposure time. This is the image output + from the NDPlugProcess plugin with Scale and Offset as shown above, with the recursive + filter enabled. Note the dramatic improvement in signal to noise.

-

- Highlighted Regions-of-Interest

- ROI_outlines.png + NDProcess_filtered.jpg +
+

+ NDPluginStats plugin connected to the NDPluginProcess filter for the filtered image + above. Note that there are many non-zero intensities in the histogram, because the + filtering is improving the dynamic range significantly.

+
+ NDStats_filtered.png