+ NDOverlay.adl
+
+ + NDPluginOverlay adds graphics overlays to an NDArray image. It can be used to highlight ROIs + on an image, to implement cursors, and other similar operations. It supports any number of + overlay objects. For each object there is control of the location, size, color, and drawing + mode. The size and location can be directly controlled, or links can be used to control the + position and size from other PVs. For example, links to the PVs definining an ROI in the NDPluginROI plugin + can be used to define a rectangular overlay in thus plugin. Similarly links to the PVs defining the + X and Y centroid and sigma of + an image computed in the NDPluginStats plugin can be used to control the location and size of a crosshair + overlay in this plugin. The cursor will then follow the location of a "beam" in the image. + Putting such graphics overlays into an areaDetector plugin allows the use + of simple image display clients, which don't need to compute the graphics themselves. +
+Each NDPluginOverlay plugin can contain any number of overlay objects, each with a different shape, position, color, etc. + The number of overlay objects is defined when the NDPluginOverlay is created in the startup script. Each object + is referenced by its asyn "addr" address field. +
++ NDPluginOverlay is both a recipient of callbacks and a source of NDArray + callbacks. This means that other plugins, such as the NDPluginStdArray plugin, can be connected + to an NDPluginOverlay plugin. In that case an image display client will receive the arrays + with the graphics overlays. +
++ NDPluginOverlay can only be used for 2-D arrays or 3-D color arrays, it is not fully N-dimensional. +
++ NDPluginOverlay inherits from NDPluginDriver. The + NDPluginOverlay class documentation describes this class in detail. +
+
+ NDPluginOverlay.h defines the following parameters. It also implements all of the
+ standard plugin parameters from NDPluginDriver.
+ There are 2 EPICS databases for the NDPluginOverlay plugin.
+ NDOverlay.template provide access to global parameters that are not specific
+ to each overlay object. There are currently no records in this database, because it currently
+ needs nothing beyond what is contained in NDPluginBase.template, but there may be
+ records added to this in the future. NDOverlayN.template provides access to the parameters for
+ each individual overlay object, described
+ 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 NDPluginOverlayName.
+
| + Parameter Definitions in NDPluginOverlay.h and EPICS Record Definitions in NDOverlayN.template | +||||||
| + Parameter index variable | ++ asyn interface | ++ Access | ++ Description | ++ drvInfo string | ++ EPICS record name | ++ EPICS record type | +
|---|---|---|---|---|---|---|
|
+ NDPluginOverlay + Name |
+ + asynOctet | ++ r/w | ++ Name for this overlay. | ++ NAME | +
+ $(P)$(R)Name + $(P)$(R)Name_RBV |
+
+ stringout + stringin |
+
|
+ NDPluginOverlay + Use |
+ + asynInt32 | ++ r/w | ++ Flag indicating whether to use (enable) this overlay. 0=No, 1=Yes. | ++ USE | +
+ $(P)$(R)Use + $(P)$(R)Use_RBV |
+
+ bo + bi |
+
|
+ NDPluginOverlay + OverlayPositionX |
+ + asynInt32 | ++ r/w | ++ The X position of this overlay. | ++ OVERLAY_POSITION_X | +
+ $(P)$(R)PositionX + $(P)$(R)PositionX_RBV |
+
+ longout + longin |
+
|
+ NDPluginOverlay + OverlayPositionY |
+ + asynInt32 | ++ r/w | ++ The Y position of this overlay. | ++ OVERLAY_POSITION_Y | +
+ $(P)$(R)PositionY + $(P)$(R)PositionY_RBV |
+
+ longout + longin |
+
|
+ NDPluginOverlay + OverlaySizeX |
+ + asynInt32 | ++ r/w | ++ The X size of this overlay. | ++ OVERLAY_SIZE_X | +
+ $(P)$(R)SizeX + $(P)$(R)SizeX_RBV |
+
+ longout + longin |
+
|
+ NDPluginOverlay + OverlaySizeY |
+ + asynInt32 | ++ r/w | ++ The Y size of this overlay. | ++ OVERLAY_SIZE_Y | +
+ $(P)$(R)SizeY + $(P)$(R)SizeY_RBV |
+
+ longout + longin |
+
|
+ NDPluginOverlay + Shape |
+ + asynInt32 | ++ r/w | ++ The shape of this overlay. 0=cross, 1=rectangle. Other shapes may be added in the future. + The X and Y position of a cross is located at the center. The X and Y size of a cross is the size + on either side of the center, i.e. the total width = 2*OverlaySizeX. This is done so when HOPR for + the X and Y size records is set to the total image size, the cross can be the total size of the + image no matter where it is positioned. The X and Y position of a rectangle is located at Xmin,Ymin. + The X and Y size of a rectangle is the total width and height. These definitions are + consistent with the way ROIs are defined in the NDPluginROI plugin. | ++ OVERLAY_SHAPE | +
+ $(P)$(R)Shape + $(P)$(R)Shape_RBV |
+
+ longout + longin |
+
|
+ NDPluginOverlay + DrawMode |
+ + asynInt32 | ++ r/w | ++ The operation to use when drawing this overlay. 0=Set, 1=XOR. In Set mode the Red, Green, and Blue + values (Green for mono images) are written directly into the pixel values. In XOR mode the value + in the pixel is XOR'ed with the Red, Green, and Blue values. XOR operation typically results in an overlay that + has better visibility no matter what the values of the surrounding pixels, while Set mode with Green=255, + for example, will show up well on dark areas of the image, but will be hard to see in bright areas of the image. + Note that XOR is not supported for NDFloat32 or NDFloat64 data types directly, but they are cast to + int if XOR is selected for arrays with those data types. | ++ OVERLAY_DRAW_MODE | +
+ $(P)$(R)DrawMode + $(P)$(R)DrawMode_RBV |
+
+ longout + longin |
+
|
+ NDPluginOverlay + Red |
+ + asynInt32 | ++ r/w | ++ The red value to use when drawing the overlay. This is only used for color images. | ++ OVERLAY_RED | +
+ $(P)$(R)Red + $(P)$(R)Red_RBV |
+
+ longout + longin |
+
|
+ NDPluginOverlay + Green |
+ + asynInt32 | ++ r/w | ++ The green value to use when drawing the overlay. This is the value that is used + for monochrome images as well. | ++ OVERLAY_GREEN | +
+ $(P)$(R)Green + $(P)$(R)Green_RBV |
+
+ longout + longin |
+
|
+ NDPluginOverlay + Blue |
+ + asynInt32 | ++ r/w | ++ The blue value to use when drawing the overlay. This is only used for color images. | ++ OVERLAY_BLUE | +
+ $(P)$(R)Blue + $(P)$(R)Blue_RBV |
+
+ longout + longin |
+
+ It is very convenient to have slider widgets to control the size and position + of user-defined overlays. For these to work correctly, the HOPR fields of the + X and Y position and size widgets must be set to the maximum allowed values. + This is handled in the NDOverlay.template database, where the HOPR fields are automatically + set to the actual size of the input array whenever that changes. Note that if HOPR + changes, then with medm it is necessary to close and reopen the display with the sliders, + because medm only retrieves the value the display limits when it first connects to a channel. +
++ The NDPluginOverlay plugin is created with the NDOverlayConfigure command, either + from C/C++ or from the EPICS IOC shell.
++NDOverlayConfigure(const char *portName, int queueSize, int blockingCallbacks, + const char *NDArrayPort, int NDArrayAddr, int maxOverlays, + 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 NDOverlayConfigure function in the + NDPluginOverlay.cpp documentation and in the documentation for the constructor + for the NDPluginOverlay + class. +
++ The following is the MEDM screen that provides access to the parameters in NDPluginDriver.h + and NDPluginOverlay.h through records in NDPluginBase.template and NDOverlay.template. + This screen does not provide anything beyond the PVs in NDPluginBase.template except for the + menus to call up the related displays. +
+
+ + The following is the MEDM screen that provides access to the parameters in + NDPluginOverlay.h through records in NDOverlayN.template. This allows control of + the parameters of a single overlay object. +
+
+ + The following is the MEDM screen that provides control of most + the parameters of 8 overlay objects, and a link to the screen above. +
+
+ + Image display from ImageJ for the overlay settings in the screen above. Note that + the cursor is set to track the centroid of the beam via the input links.
+
+