8e4d5a94ed
git-svn-id: https://subversion.xor.aps.anl.gov/synApps/areaDetector/trunk@15324 dc6c5ff5-0b8b-c028-a01f-ffb33f00fc8b
470 lines
15 KiB
HTML
Executable File
470 lines
15 KiB
HTML
Executable File
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
|
|
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
|
|
<html xml:lang="en" xmlns="http://www.w3.org/1999/xhtml">
|
|
<head>
|
|
<title>areaDetector Plugin NDPluginOverlay</title>
|
|
<meta content="text/html; charset=ISO-8859-1" http-equiv="Content-Type" />
|
|
</head>
|
|
<body>
|
|
<div style="text-align: center">
|
|
<h1>
|
|
areaDetector Plugin NDPluginOverlay</h1>
|
|
<h2>
|
|
October 1, 2012</h2>
|
|
<h2>
|
|
Mark Rivers</h2>
|
|
<h2>
|
|
University of Chicago</h2>
|
|
</div>
|
|
<h2>
|
|
Contents</h2>
|
|
<ul>
|
|
<li><a href="#Overview">Overview</a></li>
|
|
<li><a href="#Configuration">Configuration</a></li>
|
|
<li><a href="#Screens">Screen shots</a></li>
|
|
</ul>
|
|
<h2 id="Overview">
|
|
Overview
|
|
</h2>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<p>
|
|
NDPluginOverlay is both a <b>recipient</b> of callbacks and a <b>source</b> 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.
|
|
</p>
|
|
<p>
|
|
NDPluginOverlay can only be used for 2-D arrays or 3-D color arrays, it is not fully
|
|
N-dimensional.
|
|
</p>
|
|
<p>
|
|
NDPluginOverlay inherits from NDPluginDriver. The <a href="areaDetectorDoxygenHTML/class_n_d_plugin_overlay.html">
|
|
NDPluginOverlay class documentation</a> describes this class in detail.
|
|
</p>
|
|
<p>
|
|
NDPluginOverlay.h defines the following parameters. It also implements all of the
|
|
standard plugin parameters from <a href="pluginDoc.html#NDPluginDriver">NDPluginDriver</a>.
|
|
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 <code>NDPluginOverlayName</code>.
|
|
</p>
|
|
<table border="1" cellpadding="2" cellspacing="2" style="text-align: left">
|
|
<tbody>
|
|
<tr>
|
|
<td align="center" colspan="7,">
|
|
<b>Parameter Definitions in NDPluginOverlay.h and EPICS Record Definitions in NDOverlayN.template</b>
|
|
</td>
|
|
</tr>
|
|
<tr>
|
|
<th>
|
|
Parameter index variable</th>
|
|
<th>
|
|
asyn interface</th>
|
|
<th>
|
|
Access</th>
|
|
<th>
|
|
Description</th>
|
|
<th>
|
|
drvInfo string</th>
|
|
<th>
|
|
EPICS record name</th>
|
|
<th>
|
|
EPICS record type</th>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
NDPluginOverlay<br />
|
|
Name</td>
|
|
<td>
|
|
asynOctet</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
Name for this overlay.</td>
|
|
<td>
|
|
NAME</td>
|
|
<td>
|
|
$(P)$(R)Name<br />
|
|
$(P)$(R)Name_RBV</td>
|
|
<td>
|
|
stringout<br />
|
|
stringin</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
NDPluginOverlay<br />
|
|
Use</td>
|
|
<td>
|
|
asynInt32</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
Flag indicating whether to use (enable) this overlay. 0=No, 1=Yes.</td>
|
|
<td>
|
|
USE</td>
|
|
<td>
|
|
$(P)$(R)Use<br />
|
|
$(P)$(R)Use_RBV</td>
|
|
<td>
|
|
bo<br />
|
|
bi</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
NDPluginOverlay<br />
|
|
OverlayPositionX</td>
|
|
<td>
|
|
asynInt32</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
The X position of this overlay.</td>
|
|
<td>
|
|
OVERLAY_POSITION_X</td>
|
|
<td>
|
|
$(P)$(R)PositionX<br />
|
|
$(P)$(R)PositionX_RBV</td>
|
|
<td>
|
|
longout<br />
|
|
longin</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
N.A.</td>
|
|
<td>
|
|
N.A.</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
Link to fetch the desired X position of this overlay. The .DOL field of this record
|
|
can be set to another record which will then change PositionX whenever the other
|
|
record updates. The link <i>must</i> have the "CP" attribute, so that this record
|
|
processes whenever the record it is linked to changes. For example, the link could
|
|
be set to "13PS1:Stats1:CentroidX_RBV CP NMS" to fetch its position from the X centroid
|
|
calculated by an NDPluginStats plugin, or to "13PS1:ROI1:MinX_RBV CP MS" to fetch
|
|
its position from the X position of an ROI. If this link field is blank or points
|
|
to a non-existent record then the X position of the overlay can be manually controlled.
|
|
Note that this linking is done entirely in the EPICS database, and not in the plugin
|
|
code.</td>
|
|
<td>
|
|
N.A.</td>
|
|
<td>
|
|
$(P)$(R)PositionXLink</td>
|
|
<td>
|
|
longout</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
NDPluginOverlay<br />
|
|
OverlayPositionY</td>
|
|
<td>
|
|
asynInt32</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
The Y position of this overlay.</td>
|
|
<td>
|
|
OVERLAY_POSITION_Y</td>
|
|
<td>
|
|
$(P)$(R)PositionY<br />
|
|
$(P)$(R)PositionY_RBV</td>
|
|
<td>
|
|
longout<br />
|
|
longin</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
N.A.</td>
|
|
<td>
|
|
N.A.</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
Link to fetch the desired Y position of this overlay. See the notes for PositionXLink
|
|
above.</td>
|
|
<td>
|
|
N.A.</td>
|
|
<td>
|
|
$(P)$(R)PositionYLink</td>
|
|
<td>
|
|
longout</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
NDPluginOverlay<br />
|
|
OverlaySizeX</td>
|
|
<td>
|
|
asynInt32</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
The X size of this overlay.</td>
|
|
<td>
|
|
OVERLAY_SIZE_X</td>
|
|
<td>
|
|
$(P)$(R)SizeX<br />
|
|
$(P)$(R)SizeX_RBV</td>
|
|
<td>
|
|
longout<br />
|
|
longin</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
N.A.</td>
|
|
<td>
|
|
N.A.</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
Link to fetch the desired X size of this overlay. See the notes for PositionXLink
|
|
above.</td>
|
|
<td>
|
|
N.A.</td>
|
|
<td>
|
|
$(P)$(R)SizeXLink</td>
|
|
<td>
|
|
longout</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
NDPluginOverlay<br />
|
|
OverlaySizeY</td>
|
|
<td>
|
|
asynInt32</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
The Y size of this overlay.</td>
|
|
<td>
|
|
OVERLAY_SIZE_Y</td>
|
|
<td>
|
|
$(P)$(R)SizeY<br />
|
|
$(P)$(R)SizeY_RBV</td>
|
|
<td>
|
|
longout<br />
|
|
longin</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
N.A.</td>
|
|
<td>
|
|
N.A.</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
Link to fetch the desired Y size of this overlay. See the notes for PositionXLink
|
|
above.</td>
|
|
<td>
|
|
N.A.</td>
|
|
<td>
|
|
$(P)$(R)SizeYLink</td>
|
|
<td>
|
|
longout</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
NDPluginOverlay<br />
|
|
Shape</td>
|
|
<td>
|
|
asynInt32</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
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.</td>
|
|
<td>
|
|
OVERLAY_SHAPE</td>
|
|
<td>
|
|
$(P)$(R)Shape<br />
|
|
$(P)$(R)Shape_RBV</td>
|
|
<td>
|
|
longout<br />
|
|
longin</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
NDPluginOverlay<br />
|
|
DrawMode</td>
|
|
<td>
|
|
asynInt32</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
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.</td>
|
|
<td>
|
|
OVERLAY_DRAW_MODE</td>
|
|
<td>
|
|
$(P)$(R)DrawMode<br />
|
|
$(P)$(R)DrawMode_RBV</td>
|
|
<td>
|
|
longout<br />
|
|
longin</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
NDPluginOverlay<br />
|
|
Red</td>
|
|
<td>
|
|
asynInt32</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
The red value to use when drawing the overlay. This is only used for color images.
|
|
</td>
|
|
<td>
|
|
OVERLAY_RED</td>
|
|
<td>
|
|
$(P)$(R)Red<br />
|
|
$(P)$(R)Red_RBV</td>
|
|
<td>
|
|
longout<br />
|
|
longin</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
NDPluginOverlay<br />
|
|
Green</td>
|
|
<td>
|
|
asynInt32</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
The green value to use when drawing the overlay. This is the value that is used
|
|
for monochrome images as well.</td>
|
|
<td>
|
|
OVERLAY_GREEN</td>
|
|
<td>
|
|
$(P)$(R)Green<br />
|
|
$(P)$(R)Green_RBV</td>
|
|
<td>
|
|
longout<br />
|
|
longin</td>
|
|
</tr>
|
|
<tr>
|
|
<td>
|
|
NDPluginOverlay<br />
|
|
Blue</td>
|
|
<td>
|
|
asynInt32</td>
|
|
<td>
|
|
r/w</td>
|
|
<td>
|
|
The blue value to use when drawing the overlay. This is only used for color images.
|
|
</td>
|
|
<td>
|
|
OVERLAY_BLUE</td>
|
|
<td>
|
|
$(P)$(R)Blue<br />
|
|
$(P)$(R)Blue_RBV</td>
|
|
<td>
|
|
longout<br />
|
|
longin</td>
|
|
</tr>
|
|
</tbody>
|
|
</table>
|
|
<h3>
|
|
Display limits for Position and Size fields</h3>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<h2 id="Configuration">
|
|
Configuration</h2>
|
|
<p>
|
|
The NDPluginOverlay plugin is created with the NDOverlayConfigure command, either
|
|
from C/C++ or from the EPICS IOC shell.</p>
|
|
<pre>
|
|
NDOverlayConfigure(const char *portName, int queueSize, int blockingCallbacks,
|
|
const char *NDArrayPort, int NDArrayAddr, int maxOverlays,
|
|
int maxBuffers, size_t maxMemory,
|
|
int priority, int stackSize)
|
|
</pre>
|
|
<p>
|
|
For details on the meaning of the parameters to this function refer to the detailed
|
|
documentation on the NDOverlayConfigure function in the <a href="areaDetectorDoxygenHTML/_n_d_plugin_process_8cpp.html">
|
|
NDPluginOverlay.cpp documentation</a> and in the documentation for the constructor
|
|
for the <a href="areaDetectorDoxygenHTML/class_n_d_plugin_process.html">NDPluginOverlay
|
|
class</a>.
|
|
</p>
|
|
<h2 id="Screens">
|
|
Screen shots</h2>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<div style="text-align: center">
|
|
<h3>
|
|
NDOverlay.adl</h3>
|
|
<img alt="NDOverlay.png" src="NDOverlay.png" />
|
|
</div>
|
|
<p>
|
|
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.
|
|
</p>
|
|
<div style="text-align: center">
|
|
<img alt="NDOverlayN.png" src="NDOverlayN.png" />
|
|
</div>
|
|
<p>
|
|
The following is the MEDM screen that provides control of most the parameters of
|
|
8 overlay objects, and a link to the screen above for each one.
|
|
</p>
|
|
<div style="text-align: center">
|
|
<img alt="NDOverlay8.png" src="NDOverlay8.png" />
|
|
</div>
|
|
<p>
|
|
Image display from ImageJ for the overlay settings in the screen above. Note that
|
|
the cursor is set to track the centroid of a laser pointer via its X and Y position
|
|
input links.</p>
|
|
<div style="text-align: center">
|
|
<img alt="NDOverlay_image.jpg" src="NDOverlay_image.jpg" />
|
|
</div>
|
|
</body>
|
|
</html>
|