lin-epics-modules/ADAndor
0
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Documentation additions

Browse Source 
git-svn-id: https://subversion.xor.aps.anl.gov/synApps/areaDetector/trunk@8948 dc6c5ff5-0b8b-c028-a01f-ffb33f00fc8b
This commit is contained in:
rivers
2009-05-15 12:01:20 +00:00
parent a6575fa193
commit b44383824f
5 changed files with 256 additions and 385 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
documentation/Doxyfile
View File

@@ -656,7 +656,8 @@ EXCLUDE_SYMLINKS = NO
# against the file with absolute path, so to exclude all test directories
# for example use the pattern */test/*
EXCLUDE_PATTERNS = */CDocFile40.h */CExpSetup20.h */CROIRect0.h */CWinx32App20.h
EXCLUDE_PATTERNS = */CDocFile40.h */CExpSetup20.h */CROIRect0.h */CWinx32App20.h \
*/tiny*
# The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names
# (namespaces, classes, functions, etc.) that should be excluded from the

83
documentation/areaDetector.html
View File

@@ -79,7 +79,7 @@
From <a href="http://optoelectronics.perkinelmer.com/">Perkin Elmer</a></p>
<ul>
<li>Amorphous silicon flat panel detectors. This support was written by Brian Tieman
from the APS and will be part of areaDetector soon.</li>
and John Hammonds from the APS.</li>
</ul>
<p>
Please email any comments and bug reports to <a href="mailto:rivers@cars.uchicago.edu">
@@ -95,7 +95,7 @@
You can download the software from the links in the table below. The software is
available both in source code form, and in pre-built form so that it can be used
without an EPICS build system. The pre-built form includes binaries for linux-x86,
win32-x86, solaris-sparc and some vxWorks archtectures.</p>
win32-x86, cygwin-x86, solaris-sparc, and some vxWorks archtectures.</p>
<table border="1" summary="Where to find the software">
<tbody>
<tr align="center">
@@ -114,6 +114,22 @@
<th>
Known Problems</th>
</tr>
<tr>
<td>
1-5</td>
<td>
xxx-May-2009</td>
<td>
<a href="http://cars.uchicago.edu/software/pub/areaDetectorR1-5.tgz">areaDetectorR1-5.tgz</a></td>
<td>
<a href="http://cars.uchicago.edu/software/pub/areaDetectorPrebuilt_R1-5.tgz">areaDetectorPrebuilt_R1-5.tgz</a></td>
<td>
<a href="areaDetectorDoc.html">areaDetectorDoc</a></td>
<td>
<a href="areaDetectorReleaseNotes.html">Release notes</a></td>
<td>
See release notes</td>
</tr>
<tr>
<td>
1-4</td>
@@ -210,6 +226,64 @@
<th>
Required for</th>
</tr>
<tr>
<td rowspan="7">
1-5</td>
<td>
EPICS base</td>
<td>
3.14.10</td>
<td>
Base support</td>
</tr>
<tr>
<td>
asyn</td>
<td>
4-11</td>
<td>
Socket and interface support</td>
</tr>
<tr>
<td>
busy</td>
<td>
1-2</td>
<td>
busy record. This was formerly included in sscan, but now has its own support module.</td>
</tr>
<tr>
<td>
calc</td>
<td>
2-7</td>
<td>
scalcout record, needed by sscan database and useful for other databases</td>
</tr>
<tr>
<td>
sscan</td>
<td>
2-6-3</td>
<td>
sscan record</td>
</tr>
<tr>
<td>
mca</td>
<td>
6-11</td>
<td>
mca record for getting time sequence of ROI counts</td>
</tr>
<tr>
<td>
autosave</td>
<td>
4-5</td>
<td>
Save/restore</td>
</tr>
<tr>
<td rowspan="7">
1-4</td>
@@ -497,9 +571,8 @@
<p>
This software was originally developed by Mark Rivers.</p>
<ul>
<li>ANL/APS : In use at CARS beamlines.</li>
<li>NSLS: In use on X17B2 and other beamlines.</li>
<li>Australian Synchrotron : In use at microspectroscopy beamline, ID5.</li>
<li>In use at APS, NSLS, DLS, SLS, BESSY, NSRRC and others.</li>
</ul>
</body>
</html>

362
documentation/areaDetectorDoc.html
View File

@@ -83,9 +83,10 @@
<li>Provide a mechanism for device-independent real-time data analysis such as regions-of-interest
and statistics.</li>
<li>Provide detector drivers for commonly used detectors in synchrotron applications.
These include Prosilica GigE video cameras, MAR-CCD x-ray detectors, MAR-345 online
imaging plate detectors, the Pilatus pixel-array detector, and the Roper Scientific
CCD cameras.</li>
These include Prosilica GigE video cameras, IEEE 1394 (Firewire) cameras,
MAR-CCD x-ray detectors, MAR-345 online
imaging plate detectors, the Pilatus pixel-array detector, Roper Scientific
CCD cameras, and the Perkin-Elmer amorphous silicon detector.</li>
</ul>
<p>
&nbsp;</p>
@@ -102,11 +103,12 @@
hardware. It is usually provided by the detector vendor. It may consist of a library
or DLL, of a socket protocol to a driver, a Microsoft COM interface, etc.</li>
<li>Layer 2. This is the driver that is written for the areaDetector application to
control a particular detector. It is normally written in C++ and inherits from the
control a particular detector. It is written in C++ and inherits from the
ADDriver class. It uses the standard asyn interfaces for control and status information.
Each time it receives a new data array it passes it as an NDArray object to all
Layer 3 clients that have registered for callbacks. This is the only code that needs
to be written to implement a new detector. Existing drivers range from 650 to 1050
Each time it receives a new data array it can pass it as an NDArray object to all
Layer 3 clients that have registered for callbacks.
This is the only code that needs
to be written to implement a new detector. Existing drivers range from 800 to 1800
lines of code.</li>
<li>Layer 3. Code running at this level is called a "plug-in". This code registers
with a driver for a callback whenever there is a new data array. The existing plugins
@@ -114,7 +116,7 @@
color mode conversion (NDPluginColorConvert), and conversion of detector data to
standard EPICS array types for use by Channel Access clients (NDPluginStdArrays).
Plugins are normally written in C++ and inherit from NDPluginDriver. Existing plugins
range from 300 to 700 lines of code.</li>
range from 300 to 800 lines of code.</li>
<li>Layer 4. This is standard asyn device support that comes with the EPICS asyn module.</li>
<li>Layer 5. These are standard EPICS records, and EPICS database (template) files
that define records to communicate with drivers at Layer 2 and plugins at Layer
@@ -122,7 +124,7 @@
<li>Layer 6. These are EPICS channel access clients, such as MEDM that communicate
with the records at Layer 5. There is a free IDL client that can display images
using EPICS waveform and other records communicating with the NDPluginStdArrays
plugin at Layer 3.</li>
plugin at Layer 3. Other clients are being developed, including an ImageJ plugin.</li>
</ul>
<p>
The code in Layers 1-3 is essentially independent of EPICS. There are only 2 EPICS
@@ -153,7 +155,7 @@
to displaying this subregion. Similarly, the NDPluginFile plugin can be switched
at run-time from saving the entire image to saving a selected ROI, just by changing
its input source. Plugins can be used to form an image processing pipeline, for
example with a detector providing data to a color convert plugin, which feed an
example with a detector providing data to a color convert plugin, which feeds an
ROI plugin, which feeds a file saving plugin. Each plugin can run in its own thread,
and hence in its own core on a modern multi-core CPU.
</p>
@@ -166,10 +168,7 @@
</p>
<p>
What follows is a detailed description of the software, working from the bottom
up. Most of the code is object oriented, and written in C++. The parts of the code
that depend on anything from EPICS except libCom and asyn have been kept in in separate
C files, so that it should be easy to build applications that do not run as part
of an EPICS IOC.
up. Most of the code is object oriented, and written in C++.
</p>
<h2 id="Implementation_details">
Implementation details</h2>
@@ -187,347 +186,60 @@
Detector drivers and plugins are asyn port drivers, meaning that they implement
one or more of the standard asyn interfaces. They register themselves as interrupt
sources, so that they do callbacks to registered asyn clients when values change.
They inherit from the <a href="http://www.aps.anl.gov/epics/modules/soft/asyn">asynPortDriver
base C++ class</a> that is provided in the asyn module. That base class handles
They inherit from the <a href="asynPortDriver.html">asynPortDriver
base C++ class</a> that is provided in the asyn module. (The previous link is temporary
until asyn R4-11 is release). That base class handles
all of the details of registering the port driver, registering the supported interfaces,
and registering the required interrupt sources.
and registering the required interrupt sources. There is also
<a href="asynDoxygenHTML/index.html">detailed source documentation</a> for asynPortDriver.
</p>
<h3 id="NDArray">
NDArray</h3>
<p>
The NDArray (N-Dimensional array) is the class that is used for passing detector
data from drivers to plugins. The NDArray class is defined as follows:
</p>
<pre>#define ND_ARRAY_MAX_DIMS 10
#define ND_SUCCESS 0
#define ND_ERROR -1
/* Enumeration of array data types */
typedef enum
{
NDInt8,
NDUInt8,
NDInt16,
NDUInt16,
NDInt32,
NDUInt32,
NDFloat32,
NDFloat64
} NDDataType_t;
/* Enumeration of color modes */
typedef enum
{
NDColorModeMono,
NDColorModeBayer,
NDColorModeRGB1,
NDColorModeRGB2,
NDColorModeRGB3,
NDColorModeYUV444,
NDColorModeYUV422,
NDColorModeYUV421
} NDColorMode_t;
typedef enum
{
NDBayerRGGB = 0, /* First line RGRG, second line GBGB... */
NDBayerGBRG = 1, /* First line GBGB, second line RGRG... */
NDBayerGRBG = 2, /* First line GRGR, second line BGBG... */
NDBayerBGGR = 3 /* First line BGBG, second line GRGR... */
} NDBayerPattern_t;
typedef struct NDDimension {
int size;
int offset;
int binning;
int reverse;
} NDDimension_t;
typedef struct NDArrayInfo {
int nElements;
int bytesPerElement;
int totalBytes;
} NDArrayInfo_t;
class NDArray {
public:
/* Data: NOTE this must come first because ELLNODE must be first, i.e. same address as object */
/* The first 2 fields are used for the freelist */
ELLNODE node;
int referenceCount;
/* The NDArrayPool object that created this array */
void *owner;
int uniqueId;
double timeStamp;
int ndims;
NDDimension_t dims[ND_ARRAY_MAX_DIMS];
NDDataType_t dataType;
NDColorMode_t colorMode;
NDBayerPattern_t bayerPattern;
int dataSize;
void *pData;
/* Methods */
NDArray();
int initDimension (NDDimension_t *pDimension, int size);
int getInfo (NDArrayInfo_t *pInfo);
int reserve();
int release();
};
</pre>
<p>
data from drivers to plugins.
An NDArray is a general purpose class for handling array data. An NDArray object
is self-describing, meaning it contains enough information to describe the data
itself. It is not intended to contain meta-data describing how the data was collected,
etc.
itself. It can optionally contain "attributes" (class NDAttribute) which
contain meta-data describing how the data was collected, etc.
</p>
<p>
An NDArray can have up to ND_ARRAY_MAX_DIMS dimensions, currently 10. A fixed maximum
number of dimensions is used to significantly simplify the code compared to unlimited
number of dimensions. Each dimension of the array is described by an NDDimension_t
structure. The fields in NDDimension_t are as follows:
</p>
<ul>
<li><code>size</code> is the number of elements in this dimension.</li>
<li><code>offset</code> is the starting element in this dimension relative to the
first element of the detector in unbinned units. If a selected region of the detector
is being read, then this value may be &gt;0. The offset value is cumulative, so
if a plugin such as NDPluginROI further selects a subregion, the offset is relative
to the first element in the detector, and not to the first element of the region
passed to NDPluginROI.</li>
<li><code>binning</code> is the binning (sumation of elements) in this dimension.
The offset value is cumulative, so if a plugin such as NDPluginROI performs binning,
the binning is expressed relative to the pixels in the detector and not to the possibly
binned pixels passed to NDPluginROI.</li>
<li><code>reverse</code> is 0 if the data are in their normal order as read out from
the detector in this dimension, and 1 if they are in reverse order. This value is
cumulative, so if a plugin such as NDPluginROI reverses the data, the value must
reflect the orientation relative to the original detector, and not to the possibly
reversed data passed to NDPluginROI.</li>
</ul>
number of dimensions. Each dimension of the array is described by an
<a href="areaDetectorDoxygenHTML/struct_n_d_dimension.html">NDDimension structure<a>.
The <a href="areaDetectorDoxygenHTML/class_n_d_array.html">
NDArray class documentation </a> describes this class in detail.
<p>
The first 3 data fields in the NDArray class, <code>(node, referenceCount, owner)</code>
are used by the NDArrayPool class discussed below. The remaining data fields are
as follows:
</p>
<ul>
<li><code>uniqueId</code> This should be a number that uniquely identifies this array,
e.g. frame number. Detector drivers should assign this number to the NDArray before
calling the plugins.</li>
<li><code>timeStamp</code> This should be a timestamp value in seconds recording when
the frame was collected. The time=0 reference is driver-dependent because of differences
in vendor libraries. If there is a choice, it is recommended to use timeStamp=0
for Epoch, (00:00:00 UTC, January 1, 1970).</li>
<li><code>ndims</code> The number of dimensions in this array.</li>
<li><code>dims</code> Array of NDDimension_t structures. The array is of length ND_MAX_DIMS,
but only the first <code>ndims</code> values must contain valid information.</li>
<li><code>dataType</code> The data type of this array, one of the NDDataType_t enum
values. The data types supported are signed and unsigned 8, 16, and 32-bit integers,
and 32 and 64-bit floats. </li>
<li><code>colorMode</code> The color mode this array, one of the NDColorMode_t enum
values. The following are the supported color modes:
<ul>
<li><code>NDColorModeMono</code>: Monochromatic data, i.e. a single value at each
pixel.</li>
<li><code>NDColorModeBayer</code>: Bayer color. There is a single value at each pixel,
but the pixels have a color filter array in front of them. The supported Bayer filter
is the most common one, a repeating 2x2 array of
<pre> Blue Green
Green Red
</pre>
Transmitting data from the camera using the Bayer format consumes 3 times less bandwidth
than transmitting one of the RGB formats. However, it requires more computation
on the host to convert the data to an RGB format that most clients can display.</li>
<li><code>NDColorModeRGB1</code>: Red, green, blue data with pixel interlace, i.e.
the data array is [3, NX, NY], with the color being the fastest varying array index.</li>
<li><code>NDColorModeRGB2</code>: Red, green, blue data with row interlace, i.e. the
data array is [NX, 3, NY], with the color being the second fastest varying array
index.</li>
<li><code>NDColorModeRGB3</code>: Red, green, blue data with planar interlace, i.e.
the data array is [NX, NY, 3], with the color being the slowest varying array index.</li>
<li><code>NDColorModeYUV444</code>: YUV data with 96 bits for 4 pixels, or 24 bits
per pixel. This is the same number of bits as 8-bit RGB.</li>
<li><code>NDColorModeYUV422</code>: YUV data with 64 bits for 4 pixels, or 16 bits
per pixel. This is 2/3 of the number of bits required for 8-bit RGB.</li>
<li><code>NDColorModeYUV421</code>: YUV data with 48 bits for 4 pixels, or 12 bits
per pixel. This is 1/2 of the number of bits required for 8-bit RGB.</li>
</ul>
</li>
<li><code>bayerPattern</code> The Bayer pattern for this array, one of the NDBayerPattern_t
enum values. This value is only meaningful if colorMode is NDColorModeBayer. The
Bayer pattern values are explained in the comments above. This value is needed because
the Bayer pattern will change when reading out a subset of the chip, for example
if the X or Y offset values are not even numbers.</li>
<li><code>dataSize</code> The size of the memory buffer pointed to by <code>pData</code>
in bytes. This may be larger than the amount actually required to hold the data
for this array.</li>
<li><code>pData</code> Pointer to the memory for this array. The data is assumed to
be stored in the order of <code>dims[0]</code> changing fastest, and <code>dims[ndims-1]</code>
changing slowest.</li>
</ul>
<p>
The methods of the NDArray class are:
</p>
<ul>
<li><code>initDimension</code> This method simply initializes the dimension structure
to size=size, binning=1, reverse=0, offset=0.</li>
<li><code>getInfo</code>. This convenience method returns information about an NDArray,
including the total number of elements, the number of byte per element, and the
total number of bytes in the array.</li>
<li><code>reserve</code>. This method calls NDArrayPool->reserve() for this object.
It increases the reference count for this array.</li>
<li><code>release</code>. This method calls NDArrayPool->release() for this object.
It decreases the reference count for this array.</li>
</ul>
<h3 id="NDArrayPool">
NDArrayPool</h3>
<p>
The NDArrayPool class manages a free list (pool) of NDArray objects (described above).
The NDArrayPool class manages a free list (pool) of NDArray objects.
Drivers allocate NDArray objects from the pool, and pass these objects to plugins.
Plugins increase the reference count on the object when they place the object on
their queue, and decrease the reference count when they are done processing the
array. When the reference count reaches 0 again the NDArray object is placed back
on the free list. This mechanism minimizes the copying of array data in plugins.
The public interface of the NDArrayPool class is defined as follows:
</p>
<pre>class NDArrayPool {
public:
NDArrayPool (int maxBuffers, size_t maxMemory);
NDArray* alloc (int ndims, int *dims, NDDataType_t dataType, int dataSize, void *pData);
NDArray* copy (NDArray *pIn, NDArray *pOut, int copyData);
int reserve (NDArray *pArray);
int release (NDArray *pArray);
int convert (NDArray *pIn,
NDArray **ppOut,
NDDataType_t dataTypeOut,
NDDimension_t *outDims);
int report (int details);
</pre>
<p>
The methods of the NDArrayPool class are:
</p>
<ul>
<li><code>NDArrayPool</code> This is the constructor for the class. The maxBuffers
argument is the maximum number of NDArray objects that the pool is allowed to contain.
If this value is negative then there is no limit on the number of NDArray objects.
The maxMemory argument is the maxiumum number of bytes of memory the the pool is
allowed to use, summed over all of the NDArray objects. If this value is negative
then there is no limit on the amount of memory in the pool.</li>
<li><code>alloc</code> This method allocates a new NDArray object. The first 3 arguments
are required. ndims is the number of dimensions in the NDArray. dims is an array
of dimensions, whose size must be at least ndims. dataType is the data type of the
NDArray data. dataSize is the number of bytes to allocate for the array data. If
it is 0 then alloc() will compute the size required from ndims, dims, and dataType.
pData is a pointer to a data buffer. If it is NULL then alloc will allocate a new
array buffer. If pData is not NULL then it is assumed to point to a valid buffer.
In this case dataSize must contain the actual number of bytes in the existing array,
and this array must be large enough to hold the array data. alloc() searches its
free list to find a free NDArray buffer. If is cannot find one then it will allocate
a new one and add it to the free list. If doing so would exceed maxBuffers then
alloc() will return an error. Similarly if allocating the memory required for this
NDArray would cause the cumulative memory allocated for the pool to exceed maxMemory
then an error will be returned. alloc() sets the reference count for the returned
NDArray to 1.</li>
<li><code>copy</code>. This method makes a copy of an NDArray object. If the output
array pointer is NULL then it is first allocated. If the output array object already
exists (pOut!=NULL) then it must have sufficient memory allocated to it to hold
the data. If the copyData flag is 1 then the array data is copied. If the copyData
flag is 0 then all array fields except the data itself are copied, and the data
will be initialized to 0.</li>
<li><code>reserve</code>. This method increases the reference count for the NDArray
object. Plugins must call reserve() when an NDArray is placed on a queue for later
processing.</li>
<li><code>release</code>. This method decreases the reference count for the NDArray
object. Plugins must call release() when an NDArray is removed from the queue and
processing on it is complete. Drivers must call release() after calling all plugins.</li>
<li><code>convert</code> This method creates a new output NDArray from an input NDArray,
performing conversion operations. The conversion can change the data type if dataTypeOut
is different from pIn->dataType. It can also change the dimensions. outDims may
have different values of size, binning, offset and reverse for each of its dimensions
from input array dimensions (pIn->dims).</li>
<li><code>report</code> This method reports on the free list size and other properties
of the NDArrayPool object.</li>
</ul>
The <a href="areaDetectorDoxygenHTML/class_n_d_array_pool.html">
NDArrayPool class documentation </a> describes this class in detail.
<h3 id="asynNDArrayDriver">
asynNDArrayDriver</h3>
<p>
asynNDArrayDriver inherits from asynPortDriver. It implements the asynGenericPointer
functions, assuming that these reference NDArray objects. This is the class from
which both plugins and area detector drivers are indirectly derived. Its public
interface is defined as follows:
functions, for NDArray objects. This is the class from
which both plugins and area detector drivers are indirectly derived.
The <a href="areaDetectorDoxygenHTML/class_asyn_n_d_array_driver.html">
asynNDArrayDriver class documentation </a> describes this class in detail.
</p>
<pre>class asynNDArrayDriver : public asynPortDriver {
public:
asynNDArrayDriver(const char *portName, int maxAddr, int paramTableSize, int maxBuffers, size_t maxMemory,
int interfaceMask, int interruptMask);
virtual asynStatus readGenericPointer(asynUser *pasynUser, void *genericPointer);
virtual asynStatus writeGenericPointer(asynUser *pasynUser, void *genericPointer);
virtual void report(FILE *fp, int details);
};
</pre>
<p>
The methods of the asynNDArrayDriver class are:
</p>
<ul>
<li><code>asynNDArrayDriver</code> This is the constructor for the class. portName,
maxAddr, paramTableSize, interfaceMask and interruptMask are simply passed to the
asynPortDriver base class constructor. asynNDArray creates an NDArrayPool object
to allocate NDArray objects. maxBuffers and maxMemory are passed to the constructor
for the NDArrayPool object.</li>
<li><code>readGenericPointer</code> This method copies an NDArray object from the
asynNDArrayDriver to an NDArray whose address is passed by the caller in the genericPointer
argument. The caller must allocate the memory for the array, and pass the size in
NDArray->dataSize. The method will limit the amount of data copied to the actual
array size or the input dataSize, whichever is smaller.</li>
<li><code>writeGenericPointer</code> This method currently does nothing. Derived classes
must implement this method as required.</li>
<li><code>report</code> This method calls the report function in the asynPortDriver
base class. It then calls the NDArrayPool->report() method if details &gt;5.</li>
</ul>
<h3 id="ADDriver">
ADDriver</h3>
<p>
ADDriver inherits from asynNDArrayDriver. This is the class from which area detector
drivers are directly derived. Its public interface is defined as follows:
</p>
<pre>class ADDriver : public asynNDArrayDriver {
public:
ADDriver(const char *portName, int maxAddr, int paramTableSize, int maxBuffers, size_t maxMemory,
int interfaceMask, int interruptMask);
/* These are the methods that we override from asynPortDriver */
virtual asynStatus drvUserCreate(asynUser *pasynUser, const char *drvInfo,
const char **pptypeName, size_t *psize);
/* These are the methods that are new to this class */
virtual asynStatus writeInt32(asynUser *pasynUser, epicsInt32 value);
int createFileName(int maxChars, char *fullFileName);
void setShutter(int open)
</pre>
<p>
The methods of the ADDriver class are:
</p>
<ul>
<li><code>ADDriver</code> This is the constructor for the class. All of the arguments
are simply passed to the constructor for the asynNDArrayDriver base class. After
calling the base class constructor this method sets reasonable default values for
all of the parameters defined in ADStdDriverParams.h.</li>
<li><code>drvUserCreate</code> This method returns one of the enum values for the
parameters defined in ADStdDriverParams.h if the driverInfo field matches one the
strings defined in that file. Derived classes will typically provide an implementation
of drvUserCreate() that searches for parameters that are unique to that detector
driver. If a parameter is not matched, then ADDriver->drvUserCreate() will be called
to see if it is a standard driver parameter (defined in ADStdDriverParams.h).</li>
<li><code>createFileName</code> This is a convenience function that constructs a complete
file name in the ADFullFileName parameter from the ADFilePath, ADFileName, ADFileNumber,
and ADFileTemplate parameters.</li>
<li><code>setShutter</code> This method will open (1) or close (0) the shutter if
ADShutterMode==ADShutterModeEPICS. Drivers will implement setShutter if they support
ADShutterModeDetector. If ADShutterMode=ADShutterModeDetector they will control
the shutter directly, else they will call this method.</li>
</ul>
drivers are directly derived.
The <a href="areaDetectorDoxygenHTML/class_a_d_driver.html">
ADDriver class documentation </a> describes this class in detail.
<h3 id="ADStdDriverParams">
ADStdDriverParams</h3>
<p>

135
documentation/areaDetectorReleaseNotes.html
View File

@@ -9,31 +9,118 @@
<h1 style="text-align: center">
areaDetector Release Notes</h1>
<h2 style="text-align: center">
Release 1-5 (xxx-April-2009)</h2>
Release 1-5 (xxx-May-2009)</h2>
<ul>
<li>Added a driver for mar345 online image plate detector. This driver communicates
via a TCP/IP socket with the mar345dtb program, which must be used to control the
detector.</li>
<li>Added a driver for Firewire IIDC/DCAM cameras under Windows. This driver uses
the Windows 1394 camera driver from Carnegie Mellon University.</li>
<li>Added support for color to the simulation detector driver. It now supports color
modes Mono, RGB1, RGB2 and RGB3.</li>
<li>Fixed 2 serious bugs in the Roper driver. It was not selecting ROI mode correctly.
When NumAcquisitions was &gt 1 it was only collecting the first frame correctly,
subsequent frames were the same as a first one. This has been isolated to a bug
in the WinView COM interface, and a workaround for the problem has been implemented.</li>
<li>Began to document the source code with comments that doxygen can processes. Thanks
to John Hammonds from APS for doing this.</li>
<li>Moved the asynPortDriver base C++ class from the areaDetector module to the asyn
module. The asynPortDriver base class was modified slightly to make it more general.
In particular the constructor no longer hardcodes ASYN_CANBLOCK, ASYN_MULTIDEVICE,
epicsThreadPriorityMedium, and epicsThreadStackMedium. This requires that asyn R4-11
or later be used, and requires 2 additional arguments to the constructor (priority
and stackSize) for all areaDetector drivers and plugins.</li>
<li>Fixed bug in NDPluginFile: was not closing file properly when stream mode was
stopped before the requested number of frames.</li>
<li>Fixed Makefiles to instantiate templates on vxWorks.</li>
<li>Minor bug fixes for Prosilica driver (function names in debug statements).</li>
<li>General
<ul>
<li>Added "attributes" to NDArray. Attributes are used to contain metadata about
the array. Each attribute has a name, description, datatype and value. Attributes
can be added by drivers or plugins, and travel with the array through the plugin chain,
and can ultimately be written with the array data to a file. Attributes can come
from driver or plugin parameters, or from EPICS PVs anywhere on the network.</li>
<li>Separated parameters and functions which are general to NDArray data
(asynNDArrayDriver base class) from those which are specific to areaDetector data (ADDriver
base class). This makes it easy and clean to use asynNDArray driver for future applications
beyond areaDetector, such as drivers for the XIA xMAP digital spectroscopy system.</li>
</ul>
</li>
<li>Drivers
<ul>
<li>New driver for mar345 online image plate detector. This driver communicates
via a TCP/IP socket with the mar345dtb program, which must be used to control the
detector.</li>
<li>New driver for Firewire IIDC/DCAM cameras under Windows. This driver uses
the Windows 1394 camera driver from Carnegie Mellon University.</li>
<li>New driver for the Perkin-Elmer amorphous silicon flat panel detectors. Thanks to
Brian Tieman and John Hammonds for this driver.</li>
<li>Added support for color to the simulation detector driver. It now supports color
modes Mono, RGB1, RGB2 and RGB3.</li>
<li>Fixed 2 serious bugs in the Roper driver. It was not selecting ROI mode correctly.
When NumAcquisitions was &gt; 1 it was only collecting the first frame correctly,
subsequent frames were the same as a first one. This has been isolated to a bug
in the WinView COM interface, and a workaround for the problem has been implemented.</li>
<li>Solved problem of Prosilica driver crashing on Linux. The problem was with the
SIGALARM signal handlers in EPICS base (R3.14.10 and earlier). There is a patch for
base to fix this problem, and this fix will be included in EPICS base 3.14.11.</li>
</ul>
</li>
<li>Plugins
<ul>
<li>Changed NDPluginFile from directly supporting netCDF to be a base class from which
actual file plugins derive.</li>
<li>Changed netCDF file support to be derived class inheriting from NDPluginFile.
Added support for writing NDArray attributes to the netCDF file.</li>
<li>New file plugin for TIFF files. The TIFF support includes 8, 16 and 32-bit integers.
It supports monochrome and color images, including all 3 color interleave modes (RGB1, RGB2
and RGB3. areaDetector contains all required support files to build and run the TIFF
file plugin on win32-x86 and cygwin-x86. To build on Linux it is necessary to install
the libtiff and libtiffstatic packages.
Thanks to John Hammonds for the initial work on this plugin.</li>
<li>New file plugin for JPEG files. The JPEG support is limited to 8-bit integers, but
it supports monochrome and color images, including all 3 color interleave modes (RGB1, RGB2
and RGB3. Control is provided for the JPEG quality (compression) on a scaler of 0 (worst)
to 100 (best). areaDetector contains all required support files to build and run the JPEG
file plugin on win32-x86 and cygwin-x86. To build on Linux it is necessary to install
the libjpeg and libjpegstatic packages. </li>
<li>Fixed bug in NDPluginFile: was not closing file properly when stream mode was
stopped before the requested number of frames.</li>
<li>Fixed logic problem with FileNumber record in NDFile.template database. The previous
logic that kept the ao record in sync with the ai record was causing the ao record to
process when it should not have been, causing an extra call to the driver.</li>
</ul>
</li>
<li>Viewers
<ul>
<li>Improved IDL epics_ad_display viewer. The last image is now stored in the program, and
it is now redisplayed if the view mode is changed (TVSCL to iimage, etc.) or if the display
parameters are changed (autoscale, flip Y, minimum, maximum, etc.).</li>
</ul>
</li>
<li>Documentation
<ul>
<li>Documented the source code with comments that doxygen can processes to produce HTML
documentation directly from the source. This provides documentation for each class, as
well as the class inheritence tree.
Thanks to John Hammonds for starting this.</li>
</ul>
</li>
<li>Internals
<ul>
<li>Moved the asynPortDriver base C++ class from the areaDetector module to the asyn
module. The asynPortDriver base class was modified slightly to make it more general.
In particular the constructor no longer hardcodes ASYN_CANBLOCK, ASYN_MULTIDEVICE,
epicsThreadPriorityMedium, and epicsThreadStackMedium. This requires that asyn R4-11
or later be used, and requires 2 additional arguments to the constructor (priority
and stackSize) for all areaDetector drivers and plugins.</li>
<li>Removed mutexId from asynPortDriver base class, and added lock() and unlock()
methods. This hides the implementation of the locking, since we might want to
implement these with asynManager->lockPort in the future.</li>
<li>Removed the file ADStdParams.h. Moved the definition of parameters that are
general to NDArray drivers into asynNDArrayDriver.h, and those that are specific
to areaDetector drivers into ADDriver.h.</li>
<li>Added an XML parser which is used for attribute definition files.</li>
<li>Fixed Makefiles to instantiate templates on vxWorks.</li>
<li>Moved createFileName() from ADDriver and NDPluginDriver to their base class,
asynNDArrayDriver.</li>
<li>Changed colorMode and bayerPattern from being properties of NDArray to being attributes,
since they are not general to NDArray but are specific to areaDetector.</li>
<li>Added new method asynPortDriver::drvUserCreateParam, which simplifies drvUserCreate code in all
drivers and plugins.</li>
<li>Reduced number of files for all plugins and drivers. Previously there was an XXX.cpp, drvXXX.h,
and drvXXXEpics.c. The .h and .c files were used to keep the drivers and plugins independent of
EPICS IOC code. It was decided that that extra 2 files per driver and plugin were not
worth the added complexity. If it is desired to run drivers and plugins outside of an IOC
it could be done with conditional compilation of the IOC dependent code, which is all at the
end of the .cpp file.</li>
<li>Renamed a few parameters and the drvInfo strings to logically separate things that
are general to NDArrays and things that are specific to area detectors. For example,
the drvInfo fields IMAGE_SIZE_xxx were renamed to ARRAY_SIZE_xxx, and IMAGE_COUNTER was
renamed to ARRAY_COUNTER.</li>
<li>Added call to epicsExit() to all driver IOC main programs. This is important for allowing
EPICS to exit cleanly. Without this on Linux it was often necessary to kill the IOC with ^C,
rather than just typing "exit".</li>
</ul>
</li>
</ul>
<h2 style="text-align: center">
Release 1-4 (30-January-2009)</h2>

58
documentation/todo.txt
View File

@@ -1,48 +1,46 @@
For R1-5
- Update documentation to link to doxygen files and remove details of code
from HTML files.
- Include TIFF and JPEG libraries in all applications so the plugins will work.
- Load the TIFF and JPEG drivers, databases and adl screens for all drivers.
- Make all writeXXX methods invoke the base class in the case where the
parameter is not recognized and the number is less than the first parameter
for this class.
- Implement portNameSelf in asynPortDriver (but leave it in ADBase.template).
- Test all drivers.
Longer term:
General
- Look at Marty's comments, respond
- Documentation
- Performance measurements
- Implement and improve connection management
- Make any asynBusy record, same as bo, except:
- Does not call recGblFwdLink until VAL=0.
- Soft device support is same as bo record.
- Flag indicating callback from device support, don't write output.
asynParamBase
asynPortDriver
- Make it handle array interfaces with pointers?
NDPluginBase
- Add all 10 dimensions to database
- Add all 10 dimensions to database?
drvNDFile
- Test reading
drvNDStdArrays
File plugins
- Implement reading
drvNDROI
- Add cross-sections
- Add cross-sections?
- Add scaling and offset, useful when converting data types?
drvSimDetector driver
- Test all image data types with all waveform data types
- Add connection state
drvProsilica driver
- Connection management
- Sense disconnect, autoreconnect
- Implement link callback. When matches uniqueID, call Disconnect or Connect
- Support color
Other drivers
- Roper using WinView/OLE
- Pilatus
- MAR-CCD
- MAR-345
IDL
- Fix image_display
- Make TVSCL image
Resizeable;
- Change table widgets to text widgets or CW_field widgets
- Use rotate rather than order keyword on tv
- Check if data is byte and scaling is 0 to 255 don't scale the image
- Data saving?
- Get Stephen Mudie's code included and fixed
- Change image_display table widgets to text widgets or CW_field widgets