-
-From the bottom to the top this architecture consists of the following:base- Features
-This is a driver for ADSC detectors. -It has been tested with the ADSC Q210. While not yet tested with other -models, it should work with the ADSC Q4 (with the upgrade to four computers), -Q4r, Q210, Q210r, Q270, Q315, and Q315r. -
- --This driver controls the detector via the detcon_lib_th detector -control library provided by ADSC. The detcon_lib_th library must -date from 2008-06-30 or newer. -
- -lib
DIRS += adscSrcto ADApp/Makefile
-This driver is configured via the adscConfig() function. If this is -to be used in an IOC, it must be called before iocInit(). It has the -following signature: -
- --The underlying ADSC control library obtains its configuration from the -environment. Therefore, the environment must be correctly configured (i.e. -ADSC environment variables set) for the ADSC control library before calling -adscConfig(). -
- --If being used in an IOC, and an EPICS PV interface with the driver is desired, -the ADBase.template and adsc.template databases should also -be loaded for the driver instance. -
- --An example IOC configuration for this driver is at -iocBoot/iocAdsc/st.cmd. -
- --The Single mode acquires just one image. -
- --The Multiple mode acquires the number of images specified in -$(P)$(R)NumImages_RBV. -
- --The Continuous mode acquires images indefinitely until last -image is set. In this mode, the last image of the acquisition must be -signaled before exposing the last image by setting -$(P)$(R)ADSCLastImage to 1. This requirement is due to how -the underlying ADSC control library works. -
- --The Internal mode will make the driver expose images on its own once -the acquisition is started. -
- --The External mode will make the driver expose images only when told -to once the acquisition is started. A special protocol must be followed to -trigger each image exposure. This would normally be very simple, but because -the ADSC control library can report that an exposure did not work and should -be retried after any exposure, a more complex protocol is required. -
- --The protocol is described in terms of the EPICS PV driver interface, but the -same rules apply if controlling the driver directly through ASYN. The -protocol is as follows: -
- --Note that care must be taken when waiting for $(P)$(R)ADSCExTrCtl_RBV -to be OK or Again to ensure the PV value is not stale (i.e. -from the previous exposure). There are at least two methods to ensure this: -
- --Dark images are acquired automatically at the beginning of a data acquisition. -They are taken if any of the following conditions are true: -
- -
-This driver provides status values and settings in addition to what is
-provided by areaDetector base
. They are listed here according
-to their label in the driver specific MEDM GUI and their EPICS PV name in the
-EPICS PV driver interface. A screenshot of the driver specific MEDM GUI can
-be seen in the Screenshots section.
-
dezingeredimages.
base-Features
dezingeredimages is not supported. This is a limitation -of the underlying ADSC control library which has a bug preventing it from -working correctly.
baseFeatures
+ This is a driver for ADSC detectors. It + has been tested with the ADSC Q210. While not yet tested with other models, it should + work with the ADSC Q4 (with the upgrade to four computers), Q4r, Q210, Q210r, Q270, + Q315, and Q315r. +
++ This driver controls the detector via the detcon_lib_th detector control + library provided by ADSC. The detcon_lib_th library must date from 2008-06-30 + or newer. +
+lib
DIRS += adscSrcto ADApp/Makefile
+ This driver is configured via the adscConfig() function. If this is to + be used in an IOC, it must be called before iocInit(). It has the following + signature: +
++ The underlying ADSC control library obtains its configuration from the environment. + Therefore, the environment must be correctly configured (i.e. ADSC environment variables + set) for the ADSC control library before calling adscConfig(). +
++ If being used in an IOC, and an EPICS PV interface with the driver is desired, the + ADBase.template and adsc.template databases should also be loaded + for the driver instance. +
++ An example IOC configuration for this driver is at iocBoot/iocAdsc/st.cmd. +
++ The Single mode acquires just one image. +
++ The Multiple mode acquires the number of images specified in $(P)$(R)NumImages_RBV. +
++ The Continuous mode acquires images indefinitely until last image + is set. In this mode, the last image of the acquisition must be signaled before + exposing the last image by setting $(P)$(R)ADSCLastImage to 1. + This requirement is due to how the underlying ADSC control library works. +
++ The Internal mode will make the driver expose images on its own once the + acquisition is started. +
++ The External mode will make the driver expose images only when told to + once the acquisition is started. A special protocol must be followed to trigger + each image exposure. This would normally be very simple, but because the ADSC control + library can report that an exposure did not work and should be retried after any + exposure, a more complex protocol is required. +
++ The protocol is described in terms of the EPICS PV driver interface, but the same + rules apply if controlling the driver directly through ASYN. The protocol is as + follows: +
++ Note that care must be taken when waiting for $(P)$(R)ADSCExTrCtl_RBV to + be OK or Again to ensure the PV value is not stale (i.e. from + the previous exposure). There are at least two methods to ensure this: +
++ Dark images are acquired automatically at the beginning of a data acquisition. They + are taken if any of the following conditions are true: +
+
+ This driver provides status values and settings in addition to what is provided
+ by areaDetector base
. They are listed here according to their label
+ in the driver specific MEDM GUI and their EPICS PV name in the EPICS PV driver interface.
+ A screenshot of the driver specific MEDM GUI can be seen in the
+ Screenshots section.
+
dezingeredimages.
baseFeatures
dezingeredimages is not supported. This is a limitation of the + underlying ADSC control library which has a bug preventing it from working correctly.
- -
- -
-The areaDetector module provides a general-purpose interface for area (2-D) detectors in EPICS. -It is intended to be used with a wide variety of detectors and cameras, ranging from high frame rate -CCD and CMOS cameras, pixel-array detectors such as the Pilatus, and large format detectors like the -MAR-345 online imaging plate.
--The goals of this module are: -
-- -
-The architecture of the areaDetector module is shown below.
-
-
-
-From the bottom to the top this architecture consists of the following:
-The code in Layers 1-3 is essentially independent of EPICS. There are only 2 EPICS dependencies in this -code. -
--In particular it is possible to eliminate layers 4-6 in the architecture shown in Figure 1, providing -there is a programs such as the high-performance GUI shown in Layer 3. This means that it is not necessary -to run an EPICS IOC or to use EPICS Channel Access when using the drivers and plugins at Layers 2 and 3. -
--The plugin architecture is very powerful, because new plugins can be written for application-specific -purposes. For example, a plugin could be written to analyze images and find the center of the beam, -and such a plugin would then work with any detector driver. -Plugins are also powerful because they can be reconfigured at run-time. For example -the NDPluginStdArrays can switch from getting its array data from a detector driver to an NDPluginROI -plugin. That way it will switch from displaying the entire detector to whatever sub-region the ROI -driver has selected. Any Channel Access clients connected to the NDPluginStdArrays driver -will automatically switch 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. -
--The use of plugins is optional, and it is only plugins that require the driver to make callbacks with -image data. If there are no plugins being used then EPICS can be used simply -to control the detector, without accessing the data itself. This is most useful when -the vendor API has the ability to save the data to a file. -
--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. -
- --The areaDetector module depends heavily on -asyn. -It is the software that is used for interthread communication, -using the standard asyn interfaces (e.g. asynInt32, asynOctet, etc.), and callbacks. -In order to minimize the amount of redundant code in drivers, areaDetector has been -implemented using C++ classes. The base classes, from which drivers and plugins are derived, -take care of many of the details of asyn and other common code. -
- --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. -asynPortDriver is a base C++ class that handles all of the details of registering the port driver, -registering the supported interfaces, -and registering the required interrupt sources. -
--Drivers and plugins each need to support a number of parameters that control their operation and provide -status information. Most of these can be treated as 32-bit integers, 64-bit floats, or strings. -When the new value of a parameter is sent to a driver, (e.g. detector binning in the X direction) -from an asyn client (e.g. an EPICS record), -then the driver will need to take some action. It may change some other parameters in response to this -new value (e.g. image size in the X direction). The sequence of operations in the driver can be summarized as -
--asynPortDriver provides methods to simplify the above sequence, which must be -implemented for each of the many parameters that the driver supports. Each parameter is assigned -a number, which is the value in the pasynUser-> reason field that asyn clients pass to -the driver when reading or writing that parameter. asynPortDriver maintains a table -of parameter values, associating each parameter number with a data type (integer, double, or string), -caching the current value, and maintaining a flag indicating if a value has changed. -Drivers use asynPortDriver methods to read the current value -from the table, and to set new values in the table. There is a method to call all registered callbacks -for values that have changed since callbacks were last done. -
--The following are the public definitions in the asynPortDriver class: -
-#define asynCommonMask 0x00000001
-#define asynDrvUserMask 0x00000002
-#define asynOptionMask 0x00000004
-#define asynInt32Mask 0x00000008
-#define asyUInt32DigitalMask 0x00000010
-#define asynFloat64Mask 0x00000020
-#define asynOctetMask 0x00000040
-#define asynInt8ArrayMask 0x00000080
-#define asynInt16ArrayMask 0x00000100
-#define asynInt32ArrayMask 0x00000200
-#define asynFloat32ArrayMask 0x00000400
-#define asynFloat64ArrayMask 0x00000800
-#define asynGenericPointerMask 0x00001000
-
-class asynPortDriver {
-public:
- asynPortDriver(const char *portName, int maxAddr, int paramTableSize, int interfaceMask, int interruptMask);
- virtual asynStatus getAddress(asynUser *pasynUser, const char *functionName, int *address);
- virtual asynStatus findParam(asynParamString_t *paramTable, int numParams, const char *paramName, int *param);
- virtual asynStatus readInt32(asynUser *pasynUser, epicsInt32 *value);
- virtual asynStatus writeInt32(asynUser *pasynUser, epicsInt32 value);
- virtual asynStatus getBounds(asynUser *pasynUser, epicsInt32 *low, epicsInt32 *high);
- virtual asynStatus readFloat64(asynUser *pasynUser, epicsFloat64 *value);
- virtual asynStatus writeFloat64(asynUser *pasynUser, epicsFloat64 value);
- virtual asynStatus readOctet(asynUser *pasynUser, char *value, size_t maxChars,
- size_t *nActual, int *eomReason);
- virtual asynStatus writeOctet(asynUser *pasynUser, const char *value, size_t maxChars,
- size_t *nActual);
- virtual asynStatus readInt8Array(asynUser *pasynUser, epicsInt8 *value,
- size_t nElements, size_t *nIn);
- virtual asynStatus writeInt8Array(asynUser *pasynUser, epicsInt8 *value,
- size_t nElements);
- virtual asynStatus doCallbacksInt8Array(epicsInt8 *value,
- size_t nElements, int reason, int addr);
- virtual asynStatus readInt16Array(asynUser *pasynUser, epicsInt16 *value,
- size_t nElements, size_t *nIn);
- virtual asynStatus writeInt16Array(asynUser *pasynUser, epicsInt16 *value,
- size_t nElements);
- virtual asynStatus doCallbacksInt16Array(epicsInt16 *value,
- size_t nElements, int reason, int addr);
- virtual asynStatus readInt32Array(asynUser *pasynUser, epicsInt32 *value,
- size_t nElements, size_t *nIn);
- virtual asynStatus writeInt32Array(asynUser *pasynUser, epicsInt32 *value,
- size_t nElements);
- virtual asynStatus doCallbacksInt32Array(epicsInt32 *value,
- size_t nElements, int reason, int addr);
- virtual asynStatus readFloat32Array(asynUser *pasynUser, epicsFloat32 *value,
- size_t nElements, size_t *nIn);
- virtual asynStatus writeFloat32Array(asynUser *pasynUser, epicsFloat32 *value,
- size_t nElements);
- virtual asynStatus doCallbacksFloat32Array(epicsFloat32 *value,
- size_t nElements, int reason, int addr);
- virtual asynStatus readFloat64Array(asynUser *pasynUser, epicsFloat64 *value,
- size_t nElements, size_t *nIn);
- virtual asynStatus writeFloat64Array(asynUser *pasynUser, epicsFloat64 *value,
- size_t nElements);
- virtual asynStatus doCallbacksFloat64Array(epicsFloat64 *value,
- size_t nElements, int reason, int addr);
- virtual asynStatus readGenericPointer(asynUser *pasynUser, void *pointer);
- virtual asynStatus writeGenericPointer(asynUser *pasynUser, void *pointer);
- virtual asynStatus doCallbacksGenericPointer(void *pointer, int reason, int addr);
- virtual asynStatus drvUserCreate(asynUser *pasynUser, const char *drvInfo,
- const char **pptypeName, size_t *psize);
- virtual asynStatus drvUserGetType(asynUser *pasynUser,
- const char **pptypeName, size_t *psize);
- virtual asynStatus drvUserDestroy(asynUser *pasynUser);
- virtual void report(FILE *fp, int details);
- virtual asynStatus connect(asynUser *pasynUser);
- virtual asynStatus disconnect(asynUser *pasynUser);
-
- virtual asynStatus setIntegerParam(int index, int value);
- virtual asynStatus setIntegerParam(int list, int index, int value);
- virtual asynStatus setDoubleParam(int index, double value);
- virtual asynStatus setDoubleParam(int list, int index, double value);
- virtual asynStatus setStringParam(int index, const char *value);
- virtual asynStatus setStringParam(int list, int index, const char *value);
- virtual asynStatus getIntegerParam(int index, int * value);
- virtual asynStatus getIntegerParam(int list, int index, int * value);
- virtual asynStatus getDoubleParam(int index, double * value);
- virtual asynStatus getDoubleParam(int list, int index, double * value);
- virtual asynStatus getStringParam(int index, int maxChars, char *value);
- virtual asynStatus getStringParam(int list, int index, int maxChars, char *value);
- virtual asynStatus callParamCallbacks();
- virtual asynStatus callParamCallbacks(int list, int addr);
- virtual void reportParams();
-
- /* asynUser connected to ourselves for asynTrace */
- asynUser *pasynUser;
-};
-
-
--A brief explanation of the methods and data in this class is provided here. Users should look at the -example driver (simDetector) and plugins provided with areaDetector for examples of how this -class is used. -
- -asynPortDriver(const char *portName, int maxAddr, int paramTableSize, int interfaceMask, int interruptMask); --
-This is the constructor for the class. -
-portName is the name of the asyn port for this driver or plugin.maxAddr is the maximum number of asyn addresses that this driver supports.
- This number returned by the pasynManager-> getAddr() function. Typically it is 1, but some
- plugins (e.g. NDPluginROI) support values > 1. This controls the number of parameter
- tables that are created.parmTableSize is the maximum number of parameters that this driver or plugin supports.
- This controls the size of the parameter tables.interfaceMask is a mask with each bit defining which asyn interfaces this driver
- or plugin supports.
- The bit mask values are defined in asynPortDriver.h, e.g. asynInt32Mask.interruptMask is a mask with each bit defining which of the asyn interfaces this driver
- or plugin supports can generate interrupts.
- The bit mask values are defined in asynPortDriver.h, e.g. asynInt8ArrayMask.virtual asynStatus getAddress(asynUser *pasynUser, const char *functionName, int *address); --
-Returns the value from pasynManager-> getAddr(pasynUser,...). -Returns an error if the address is not valid, e.g. >= this-> maxAddr. -
- -virtual asynStatus readInt32(asynUser *pasynUser, epicsInt32 *value); - virtual asynStatus readFloat64(asynUser *pasynUser, epicsFloat64 *value); - virtual asynStatus readOctet(asynUser *pasynUser, char *value, size_t maxChars, - size_t *nActual, int *eomReason); --
-These methods are called by asyn clients to return the current cached value for the
-parameter indexed by pasynUser-> reason in the parameter table defined by getAddress().
-Derived classed typically do not need to implement these methods.
-
virtual asynStatus writeInt32(asynUser *pasynUser, epicsInt32 value); - virtual asynStatus writeFloat64(asynUser *pasynUser, epicsFloat64 value); - virtual asynStatus writeOctet(asynUser *pasynUser, const char *value, size_t maxChars, - size_t *nActual); --
-These methods are called by asynClients to set the new value of a parameter. The -implementation of these methods in asynPortDriver copies the parameter into a cached -location for use by the asynRead(Int32, Float64, and Octet) methods. Most drivers -will provide their own implementations of these methods to do driver-dependent operations -when there is a new value of the parameter. -
- -- virtual asynStatus readXXXArray(asynUser *pasynUser, epicsInt8 *value, - size_t nElements, size_t *nIn); - virtual asynStatus writeXXXArray(asynUser *pasynUser, epicsInt8 *value, - size_t nElements); - virtual asynStatus doCallbacksXXXArray(epicsInt8 *value, - size_t nElements, int reason, int addr); - virtual asynStatus readGenericPointer(asynUser *pasynUser, void *handle); - virtual asynStatus writeGenericPointer(asynUser *pasynUser, void *handle); - virtual asynStatus doCallbacksGenericPointer(void *handle, int reason, int addr); --
-where XXX=(Int8, Int16, Int32, Float32, or Float64).
-The readXXX and writeXXX methods only have stub methods that return an error in asynPortDriver, so they
-must be implemented in the derived classes if the corresponding interface is
-used. They are not pure virtual functions so that the derived class need not implement
-the interface if it is not used. The doCallbacksXXX methods in asynPortDriver
-call any registered asyn clients on the corresponding interface if the reason
-and addr values match. It typically does not need to be implemented in derived classes.
-
- virtual asynStatus findParam(asynParamString_t *paramTable, int numParams, const char *paramName, int *param); - virtual asynStatus drvUserCreate(asynUser *pasynUser, const char *drvInfo, - const char **pptypeName, size_t *psize); - virtual asynStatus drvUserGetType(asynUser *pasynUser, - const char **pptypeName, size_t *psize); - virtual asynStatus drvUserDestroy(asynUser *pasynUser); --
-drvUserCreate must be implemented in derived classes that use the parameter facilities of asynPortDriver.
-The findParam method is a convenience function that searches an array of {enum, string} structures
-and returns the enum (parameter number) matching the string. This is typically used in the
-implementation of drvUserCreate in derived classes. drvUserGetType and
-drvUserDestroy typically do not need to be implemented in derived classes.
-
- virtual void report(FILE *fp, int details); - virtual asynStatus connect(asynUser *pasynUser); - virtual asynStatus disconnect(asynUser *pasynUser); --
-The report function prints information on registered interrupt clients if details > 0, and prints
-parameter table information if details > 5. It is typically called by the implementation of
-report in derived classes before or after
-they print specific information about themselves. connect and disconnect call
-pasynManager-> exceptionConnect and pasynManager-> exceptionDisconnect respectively.
-Derived classes may or may not need to implement these functions.
-
- virtual asynStatus setIntegerParam(int index, int value); - virtual asynStatus setIntegerParam(int list, int index, int value); - virtual asynStatus setDoubleParam(int index, double value); - virtual asynStatus setDoubleParam(int list, int index, double value); - virtual asynStatus setStringParam(int index, const char *value); - virtual asynStatus setStringParam(int list, int index, const char *value); - virtual asynStatus getIntegerParam(int index, int * value); - virtual asynStatus getIntegerParam(int list, int index, int * value); - virtual asynStatus getDoubleParam(int index, double * value); - virtual asynStatus getDoubleParam(int list, int index, double * value); - virtual asynStatus getStringParam(int index, int maxChars, char *value); - virtual asynStatus getStringParam(int list, int index, int maxChars, char *value); - virtual asynStatus callParamCallbacks(); - virtual asynStatus callParamCallbacks(int list, int addr); --
-The setXXXParam methods set the value of a parameter in the parameter table
-in the object. If the value is different from the previous value of the parameter
-they also set the flag indicating that the value has changed. The getXXXParam
-methods return the current value of the parameter. There are two versions of the
-setXXXParam and getXXXParam methods, one with a list
-argument, and one without. The one without uses list=0, since there
-is often only a single parameter list (i.e. if maxAddr=1). The callParamCallbacks
-methods call back any registered clients for parameters that have changed since the last
-time callParamCallbacks was called. The version of callParamCallbacks
-with no arguments uses the first parameter list and matches asyn address=0. There is a
-second version of callParamCallbacks that takes an argument specifying the parameter list
-number, and the asyn address to match.
-
-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: -
- -#define ND_ARRAY_MAX_DIMS 10
-
-/* Enumeration of array data types */
-typedef enum
-{
- NDInt8,
- NDUInt8,
- NDInt16,
- NDUInt16,
- NDInt32,
- NDUInt32,
- NDFloat32,
- NDFloat64
-} NDDataType_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;
- int dataSize;
- void *pData;
-
- /* Methods */
- NDArray();
- int initDimension (NDDimension_t *pDimension, int size);
- int getInfo (NDArrayInfo_t *pInfo);
- int copy (NDArray *pOut);
- int reserve();
- int release();
-};
-
-
-
--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. -
--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: -
-size is the number of elements in this dimension.offset 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
- > 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.binning 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.reverse 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.
-The first 3 data fields in the NDArray class, (node, referenceCount, owner) are used
-by the NDArrayPool class discussed below.
-The remaining data fields are as follows:
-
uniqueId This should be a number that uniquely identifies this array. Detector
- drivers should assign this number to the NDArray before calling the plugins.timeStamp 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).ndims The number of dimensions in this array.dims Array of NDDimension_t structures. The array is of length ND_MAX_DIMS, but
- only the first ndims values must contain valid information.dataType 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. dataSize The size of the memory buffer pointed to by pData in bytes. This may be
- larger than the amount actually required to hold the data for this array.pData Pointer to the memory for this array. The data is assumed to be stored
- in the order of dims[0] changing fastest, and dims[ndims-1] changing slowest.-The methods of the NDArray class are: -
-initDimension This method simply initializes the dimension structure to size=size,
- binning=1, reverse=0, offset=0.getInfo. 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.copy. 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.reserve. This method calls NDArrayPool->reserve() for this object. It increases the reference
- count for this array.release. This method calls NDArrayPool->release() for this object. It decreases the reference
- count for this array.-The NDArrayPool class manages a free list (pool) of NDArray objects (described above). 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: -
- -class NDArrayPool {
-public:
- NDArrayPool (int maxBuffers, size_t maxMemory);
- NDArray* alloc (int ndims, int *dims, NDDataType_t dataType, int dataSize, void *pData);
- int reserve (NDArray *pArray);
- int release (NDArray *pArray);
- int convert (NDArray *pIn,
- NDArray **ppOut,
- NDDataType_t dataTypeOut,
- NDDimension_t *outDims);
- int report (int details);
-
-
--The methods of the NDArrayPool class are: -
-NDArrayPool This is the constructor for the class. The maxBuffers argument is the maximum
- number of NDArray objects that the pool is allowed to contain. 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.alloc 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.reserve. 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.release. 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.convert 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).report This method reports on the free list size and other properties of the NDArrayPool object.-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: -
- -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);
-
-};
-
--The methods of the asynNDArrayDriver class are: -
-asynNDArrayDriver 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.readGenericPointer 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.writeGenericPointer This method currently does nothing. Derived classes must implement this method
- as required.report This method calls the report function in the asynPortDriver base class. It then
- calls the NDArrayPool->report() method if details > 5.-ADDriver inherits from asynNDArrayDriver. This is the class from which area detector drivers are directly derived. -Its public interface is defined as follows: -
-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 */
- int createFileName(int maxChars, char *fullFileName);
-
--The methods of the ADDriver class are: -
-ADDriver 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.drvUserCreate 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).createFileName This is a convenience function that constructs a complete file name in
- the ADFullFileName parameter from the
- ADFilePath, ADFileName, ADFileNumber, and ADFileTemplate parameters.
-The file ADStdDriverParams.h defines the following:
-
/* Enumeration of shutter status */
-typedef enum
-{
- ADShutterClosed,
- ADShutterOpen
-} ADShutterStatus_t;
-
-/* Enumeration of detector status */
-typedef enum
-{
- ADStatusIdle,
- ADStatusAcquire,
- ADStatusReadout,
- ASStatusCorrect,
- ADStatusSaving,
- ADStatusAborting,
- ADStatusError,
-} ADStatus_t;
-
-typedef enum
-{
- ADImageSingle,
- ADImageMultiple,
- ADImageContinuous
-} ADImageMode_t;
-
-typedef enum
-{
- ADTriggerInternal,
- ADTriggerExternal
-} ADTriggerMode_t;
-
-
--It also defines parameters that all area detector drivers should implement if possible. These parameters are defined -by enum values with an associated asyn interface, and access (read-only or read-write). The EPICS database -ADBase.template provides access to these standard driver parameters. The following table lists the -standard driver parameters. The columns are defined as follows: -
--Note that for parameters whose values are defined by enum values (e.g ADImageMode, ADTriggerMode, ADFileFormat, ADStatus), -drivers can use a different set of enum values for -these parameters. They can override the enum menu in ADBase.template with detector-specific choices by loading a -detector-specific template file after loading ADBase.template. -
-| Parameter Definitions in ADStdDriverParams.h and EPICS Record Definitions in ADBase.template | -||||||
| Enum name | -asyn interface | -Access | -Description | -drvUser string | -EPICS record name | -EPICS record type | -
|---|---|---|---|---|---|---|
| Information about the detector | -||||||
| ADManufacturer | -asynOctet | -r/o | -Detector manufacturer name | -MANUFACTURER | -$(P)$(R)Manufacturer_RBV | -stringin | -
| ADModel | -asynOctet | -r/o | -Detector model name | -MODEL | -$(P)$(R)Model_RBV | -stringin | -
| ADMaxSizeX | -asynInt32 | -r/o | -Maximum (sensor) size in the X direction | -MAX_SIZE_X | -$(P)$(R)MaxSizeX_RBV | -longin | -
| ADMaxSizeY | -asynInt32 | -r/o | -Maximum (sensor) size in the Y direction | -MAX_SIZE_Y | -$(P)$(R)MaxSizeY_RBV | -longin | -
| Detector readout control including gain, binning, region start and size, reversal | -||||||
| ADGain | -asynFloat64 | -r/w | -Detector gain | -GAIN | -$(P)$(R)Gain $(P)$(R)Gain_RBV |
- ao ai |
-
| ADBinX | -asynInt32 | -r/w | -Binning in the X direction | -BIN_X | -$(P)$(R)BinX $(P)$(R)BinX_RBV |
- longout longin |
-
| ADBinY | -asynInt32 | -r/w | -Binning in the Y direction | -BIN_Y | -$(P)$(R)BinY $(P)$(R)BinY_RBV |
- longout longin |
-
| ADMinX | -asynInt32 | -r/w | -First pixel to read in the X direction. 0 is the first pixel on the detector. |
- MIN_X | -$(P)$(R)MinX $(P)$(R)MinX_RBV |
- longout longin |
-
| ADMinY | -asynInt32 | -r/w | -First pixel to read in the Y direction. 0 is the first pixel on the detector. |
- MIN_Y | -$(P)$(R)MinY $(P)$(R)MinY_RBV |
- longout longin |
-
| ADSizeX | -asynInt32 | -r/w | -Size of the region to read in the X direction | -SIZE_X | -$(P)$(R)SizeX $(P)$(R)SizeX_RBV |
- longout longin |
-
| ADSizeY | -asynInt32 | -r/w | -Size of the region to read in the Y direction | -SIZE_Y | -$(P)$(R)SizeY $(P)$(R)SizeY_RBV |
- longout longin |
-
| ADReverseX | -asynInt32 | -r/w | -Reverse image in the X direction (0=No, 1=Yes) |
- REVERSE_X | -$(P)$(R)ReverseX $(P)$(R)ReverseX_RBV |
- longout longin |
-
| ADReverseY | -asynInt32 | -r/w | -Reverse image in the Y direction (0=No, 1=Yes) |
- REVERSE_Y | -$(P)$(R)ReverseY $(P)$(R)ReverseY_RBV |
- longout longin |
-
| Image and trigger modes | -||||||
| ADImageMode | -asynInt32 | -r/w | -Image mode (ADImageMode_t). | -IMAGE_MODE | -$(P)$(R)ImageMode $(P)$(R)ImageMode_RBV |
- mbbo mbbi |
-
| ADTriggerMode | -asynInt32 | -r/w | -Trigger mode (ADTriggerMode_t). | -TRIGGER_MODE | -$(P)$(R)TriggerMode $(P)$(R)TriggerMode_RBV |
- mbbo mbbi |
-
| Data type | -||||||
| ADDataType | -asynInt32 | -r/w | -Data type (NDDataType_t). | -DATA_TYPE | -$(P)$(R)DataType $(P)$(R)DataType_RBV |
- mbbo mbbi |
-
| Actual dimensions of image data | -||||||
| ADImageSizeX | -asynInt32 | -r/o | -Size of the image data in the X direction | -IMAGE_SIZE_X | -$(P)$(R)ImageSizeX_RBV | -longin | -
| ADImageSizeY | -asynInt32 | -r/o | -Size of the image data in the Y direction | -IMAGE_SIZE_Y | -$(P)$(R)ImageSizeY_RBV | -longin | -
| ADImageSize | -asynInt32 | -r/o | -Total size of image data in bytes | -IMAGE_SIZE | -$(P)$(R)ImageSize_RBV | -longin | -
| Acquisition time and period | -||||||
| ADAcquireTime | -asynFloat64 | -r/w | -Acquisition time per image | -ACQ_TIME | -$(P)$(R)AcquireTime $(P)$(R)AcquireTime_RBV |
- ao ai |
-
| ADAcquirePeriod | -asynFloat64 | -r/w | -Acquisition period between images | -ACQ_PERIOD | -$(P)$(R)AcquirePeriod $(P)$(R)AcquirePeriod_RBV |
- ao ai |
-
| Number of exposures and number of images | -||||||
| ADNumExposures | -asynInt32 | -r/w | -Number of exposures per image to acquire | -NEXPOSURES | -$(P)$(R)NumExposures $(P)$(R)NumExposures_RBV |
- longout longin |
-
| ADNumImages | -asynInt32 | -r/w | -Number of images to acquire in one acquisition sequence | -NIMAGES | -$(P)$(R)NumImages $(P)$(R)NumImages_RBV |
- longout longin |
-
| Acquisition control | -||||||
| ADAcquire | -asynInt32 | -r/w | -Start (1) or stop (0) image acquisition. This record is linked to an EPICS busy record - that does not process its forward link until acquisition is complete. Clients should write - 1 to the Acquire record to start acquisition, and wait for Acquire to go to 0 to know that - acquisition is complete. | -ACQUIRE | -$(P)$(R)Acquire | -bo | -
| File saving parameters | -||||||
| ADFilePath | -asynOctet | -r/w | -File path | -FILE_PATH | -$(P)$(R)FilePath $(P)$(R)FilePath_RBV |
- waveform waveform |
-
| ADFileName | -asynOctet | -r/w | -File name | -FILE_NAME | -$(P)$(R)FileName $(P)$(R)FileName_RBV |
- waveform waveform |
-
| ADFileNumber | -asynInt32 | -r/w | -File number | -FILE_NUMBER | -$(P)$(R)FileNumber $(P)$(R)FileNumber_RBV |
- longout longin |
-
| ADFileTemplate | -asynOctet | -r/w | -Format string for constructing ADFullFileName from ADFilePath, ADFileName, and ADFileNumber.
- The final file name (which is placed in ADFullFileName) is created with the following code:
- epicsSnprintf(FullFilename, sizeof(FullFilename), FileFormat, - FilePath, Filename, FileNumber); -- FilePath, Filename, FileNumber are converted in that order with FileFormat. - An example file format is "%s%s%4.4d.tif". The first %s converts the FilePath,
- followed immediately by another %s for Filename.
- FileNumber is formatted with %4.4d, which results in a
- fixed field with of 4 digits, with leading zeros as required. Finally, the .tif extension
- is added to the file name.
- This mechanism for creating file names is very flexible. Other characters, such as _ can be put
- in Filename or FileFormat as desired. If one does not want to have FileNumber in the file name
- at all, then just omit the %d format specifier from FileFormat. If the client wishes to construct
- the complete file name itself, then it can just put that file name into ADFileFormat with no
- format specifiers at all, in which case ADFilePath, ADFileName, and ADFileNumber will be ignored. |
- FILE_TEMPLATE | -$(P)$(R)FileTemplate $(P)$(R)FileTemplate_RBV |
- waveform waveform |
-
| ADFullFileName | -asynOctet | -r/o | -Full file name | -FULL_FILE_NAME | -$(P)$(R)FullFileName_RBV | -waveform waveform |
-
| ADAutoIncrement | -asynInt32 | -r/w | -Auto-increment flag. Controls whether FileNumber is automatically incremented by - 1 each time an acquisition completes (0=No, 1=Yes) | -AUTO_INCREMENT | -$(P)$(R)AutoIncrement $(P)$(R)AutoIncrement_RBV |
- bo bi |
-
| ADAutoSave | -asynInt32 | -r/w | -Auto-save flag (0=No, 1=Yes) | -AUTO_SAVE | -$(P)$(R)AutoSave $(P)$(R)AutoSave_RBV |
- bo bi |
-
| ADFileFormat | -asynInt32 | -r/w | -File format. The format to write/read data in (e.g. TIFF, netCDF, etc.) | -FILE_FORMAT | -$(P)$(R)FileFormat $(P)$(R)FileFormat_RBV |
- mbbo mbbi |
-
| ADWriteFile | -asynInt32 | -r/w | -Manually save the most recent image to a file when value=1 | -WRITE_FILE | -$(P)$(R)WriteFile | -longout | -
| ADReadFile | -asynInt32 | -r/w | -Manually read a file when value=1 | -READ_FILE | -$(P)$(R)ReadFile | -longout | -
| Status information | -||||||
| ADStatus | -asynInt32 | -r/o | -Acquisition status (ADStatus_t) | -STATUS | -$(P)$(R)DetectorState_RBV | -mbbi | -
| ADStatusMessage | -asynOctet | -r/o | -Status message string | -STATUS_MESSAGE | -$(P)$(R)StatusMessage_RBV | -waveform | -
| ADStringToServer | -asynOctet | -r/o | -String from driver to string-based vendor server | -STRING_TO_SERVER | -$(P)$(R)StringToServer_RBV | -waveform | -
| ADStringFromServer | -asynOctet | -r/o | -String from string-based vendor server to driver | -STRING_FROM_SERVER | -$(P)$(R)StringFromServer_RBV | -waveform | -
| ADImageCounter | -asynInt32 | -r/w | -Counter that increments by 1 each time an image is acquired | -IMAGE_COUNTER | -$(P)$(R)ImageCounter $(P)$(R)ImageCounter_RBV |
- longout longin |
-
| N/A | -N/A | -r/o | -Rate (Hz) at which ImageCounter is incrementing. Computed in database. | -N/A | -$(P)$(R)ImageRate_RBV | -calc | -
| Shutter control. Note: no areaDetector drivers yet implement shutter control, - and these parameters may change in the near future. | -||||||
| ADShutter | -asynInt32 | -r/w | -Shutter control (ADShutterStatus_t) | -SHUTTER | -$(P)$(R)ShutterMode $(P)$(R)ShutterMode_RBV |
- mbbo mbbi |
-
| Image data | -||||||
| NDArrayData | -asynGenericPointer | -r/w | -The image data as an NDArray object | -NDARRAY_DATA | -N/A. EPICS access to image data is through NDStdArrays plugin. | -N/A | -
| asyn port information | -||||||
| N/A | -N/A | -N/A | -The name of the asyn port for this driver | -N/A | -$(P)$(R)PortName_RBV | -stringin | -
| N/A | -N/A | -N/A | -asyn record to control debugging (asynTrace) | -N/A | -$(P)$(R)AsynIO | -asyn | -
-The following is the MEDM screen that provides access to the parameters in ADStdDriverParams through -records in ADBase.template. This is a -top-level MEDM screen that will work with any areaDetector driver. Note however that many drivers will not implement all -of these parameters, so detector-specific MEDM screens should generally be created that only display the EPICS PVs -for the features implemented for that detector. Note that the section of the screen labeled "Shutter" is not currently -implemented for any areaDetector driver, and is subject to change in the near future. -
-
-areaDetector has been designed to minimize the amount of work required to write a new detector driver. These -drivers are described in separate documents, linked to by the table of contents at the top of this page. -
- - + + ++
++
++ The areaDetector module provides a general-purpose interface for area (2-D) detectors + in EPICS. It is intended to be used with a wide variety of detectors and cameras, + ranging from high frame rate CCD and CMOS cameras, pixel-array detectors such as + the Pilatus, and large format detectors like the MAR-345 online imaging plate.
++ The goals of this module are: +
++
+
+ The architecture of the areaDetector module is shown below.
+
+ From the bottom to the top this architecture consists of the following:
+ The code in Layers 1-3 is essentially independent of EPICS. There are only 2 EPICS + dependencies in this code. +
++ In particular it is possible to eliminate layers 4-6 in the architecture shown in + Figure 1, providing there is a programs such as the high-performance GUI shown in + Layer 3. This means that it is not necessary to run an EPICS IOC or to use EPICS + Channel Access when using the drivers and plugins at Layers 2 and 3. +
++ The plugin architecture is very powerful, because new plugins can be written for + application-specific purposes. For example, a plugin could be written to analyze + images and find the center of the beam, and such a plugin would then work with any + detector driver. Plugins are also powerful because they can be reconfigured at run-time. + For example the NDPluginStdArrays can switch from getting its array data from a + detector driver to an NDPluginROI plugin. That way it will switch from displaying + the entire detector to whatever sub-region the ROI driver has selected. Any Channel + Access clients connected to the NDPluginStdArrays driver will automatically switch + 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. +
++ The use of plugins is optional, and it is only plugins that require the driver to + make callbacks with image data. If there are no plugins being used then EPICS can + be used simply to control the detector, without accessing the data itself. This + is most useful when the vendor API has the ability to save the data to a file. +
++ 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. +
++ The areaDetector module depends heavily on + asyn. It is the software that is used for interthread communication, using + the standard asyn interfaces (e.g. asynInt32, asynOctet, etc.), and callbacks. In + order to minimize the amount of redundant code in drivers, areaDetector has been + implemented using C++ classes. The base classes, from which drivers and plugins + are derived, take care of many of the details of asyn and other common code. +
++ 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. + asynPortDriver is a base C++ class that handles all of the details of registering + the port driver, registering the supported interfaces, and registering the required + interrupt sources. +
++ Drivers and plugins each need to support a number of parameters that control their + operation and provide status information. Most of these can be treated as 32-bit + integers, 64-bit floats, or strings. When the new value of a parameter is sent to + a driver, (e.g. detector binning in the X direction) from an asyn client (e.g. an + EPICS record), then the driver will need to take some action. It may change some + other parameters in response to this new value (e.g. image size in the X direction). + The sequence of operations in the driver can be summarized as +
++ asynPortDriver provides methods to simplify the above sequence, which must be implemented + for each of the many parameters that the driver supports. Each parameter is assigned + a number, which is the value in the pasynUser-> reason field that asyn clients + pass to the driver when reading or writing that parameter. asynPortDriver maintains + a table of parameter values, associating each parameter number with a data type + (integer, double, or string), caching the current value, and maintaining a flag + indicating if a value has changed. Drivers use asynPortDriver methods to read the + current value from the table, and to set new values in the table. There is a method + to call all registered callbacks for values that have changed since callbacks were + last done. +
++ The following are the public definitions in the asynPortDriver class: +
+#define asynCommonMask 0x00000001
+#define asynDrvUserMask 0x00000002
+#define asynOptionMask 0x00000004
+#define asynInt32Mask 0x00000008
+#define asyUInt32DigitalMask 0x00000010
+#define asynFloat64Mask 0x00000020
+#define asynOctetMask 0x00000040
+#define asynInt8ArrayMask 0x00000080
+#define asynInt16ArrayMask 0x00000100
+#define asynInt32ArrayMask 0x00000200
+#define asynFloat32ArrayMask 0x00000400
+#define asynFloat64ArrayMask 0x00000800
+#define asynGenericPointerMask 0x00001000
+
+class asynPortDriver {
+public:
+ asynPortDriver(const char *portName, int maxAddr, int paramTableSize, int interfaceMask, int interruptMask);
+ virtual asynStatus getAddress(asynUser *pasynUser, const char *functionName, int *address);
+ virtual asynStatus findParam(asynParamString_t *paramTable, int numParams, const char *paramName, int *param);
+ virtual asynStatus readInt32(asynUser *pasynUser, epicsInt32 *value);
+ virtual asynStatus writeInt32(asynUser *pasynUser, epicsInt32 value);
+ virtual asynStatus getBounds(asynUser *pasynUser, epicsInt32 *low, epicsInt32 *high);
+ virtual asynStatus readFloat64(asynUser *pasynUser, epicsFloat64 *value);
+ virtual asynStatus writeFloat64(asynUser *pasynUser, epicsFloat64 value);
+ virtual asynStatus readOctet(asynUser *pasynUser, char *value, size_t maxChars,
+ size_t *nActual, int *eomReason);
+ virtual asynStatus writeOctet(asynUser *pasynUser, const char *value, size_t maxChars,
+ size_t *nActual);
+ virtual asynStatus readInt8Array(asynUser *pasynUser, epicsInt8 *value,
+ size_t nElements, size_t *nIn);
+ virtual asynStatus writeInt8Array(asynUser *pasynUser, epicsInt8 *value,
+ size_t nElements);
+ virtual asynStatus doCallbacksInt8Array(epicsInt8 *value,
+ size_t nElements, int reason, int addr);
+ virtual asynStatus readInt16Array(asynUser *pasynUser, epicsInt16 *value,
+ size_t nElements, size_t *nIn);
+ virtual asynStatus writeInt16Array(asynUser *pasynUser, epicsInt16 *value,
+ size_t nElements);
+ virtual asynStatus doCallbacksInt16Array(epicsInt16 *value,
+ size_t nElements, int reason, int addr);
+ virtual asynStatus readInt32Array(asynUser *pasynUser, epicsInt32 *value,
+ size_t nElements, size_t *nIn);
+ virtual asynStatus writeInt32Array(asynUser *pasynUser, epicsInt32 *value,
+ size_t nElements);
+ virtual asynStatus doCallbacksInt32Array(epicsInt32 *value,
+ size_t nElements, int reason, int addr);
+ virtual asynStatus readFloat32Array(asynUser *pasynUser, epicsFloat32 *value,
+ size_t nElements, size_t *nIn);
+ virtual asynStatus writeFloat32Array(asynUser *pasynUser, epicsFloat32 *value,
+ size_t nElements);
+ virtual asynStatus doCallbacksFloat32Array(epicsFloat32 *value,
+ size_t nElements, int reason, int addr);
+ virtual asynStatus readFloat64Array(asynUser *pasynUser, epicsFloat64 *value,
+ size_t nElements, size_t *nIn);
+ virtual asynStatus writeFloat64Array(asynUser *pasynUser, epicsFloat64 *value,
+ size_t nElements);
+ virtual asynStatus doCallbacksFloat64Array(epicsFloat64 *value,
+ size_t nElements, int reason, int addr);
+ virtual asynStatus readGenericPointer(asynUser *pasynUser, void *pointer);
+ virtual asynStatus writeGenericPointer(asynUser *pasynUser, void *pointer);
+ virtual asynStatus doCallbacksGenericPointer(void *pointer, int reason, int addr);
+ virtual asynStatus drvUserCreate(asynUser *pasynUser, const char *drvInfo,
+ const char **pptypeName, size_t *psize);
+ virtual asynStatus drvUserGetType(asynUser *pasynUser,
+ const char **pptypeName, size_t *psize);
+ virtual asynStatus drvUserDestroy(asynUser *pasynUser);
+ virtual void report(FILE *fp, int details);
+ virtual asynStatus connect(asynUser *pasynUser);
+ virtual asynStatus disconnect(asynUser *pasynUser);
+
+ virtual asynStatus setIntegerParam(int index, int value);
+ virtual asynStatus setIntegerParam(int list, int index, int value);
+ virtual asynStatus setDoubleParam(int index, double value);
+ virtual asynStatus setDoubleParam(int list, int index, double value);
+ virtual asynStatus setStringParam(int index, const char *value);
+ virtual asynStatus setStringParam(int list, int index, const char *value);
+ virtual asynStatus getIntegerParam(int index, int * value);
+ virtual asynStatus getIntegerParam(int list, int index, int * value);
+ virtual asynStatus getDoubleParam(int index, double * value);
+ virtual asynStatus getDoubleParam(int list, int index, double * value);
+ virtual asynStatus getStringParam(int index, int maxChars, char *value);
+ virtual asynStatus getStringParam(int list, int index, int maxChars, char *value);
+ virtual asynStatus callParamCallbacks();
+ virtual asynStatus callParamCallbacks(int list, int addr);
+ virtual void reportParams();
+
+ /* asynUser connected to ourselves for asynTrace */
+ asynUser *pasynUser;
+};
+
+ + A brief explanation of the methods and data in this class is provided here. Users + should look at the example driver (simDetector) and plugins provided with areaDetector + for examples of how this class is used. +
+asynPortDriver(const char *portName, int maxAddr, int paramTableSize, int interfaceMask, int interruptMask); ++
+ This is the constructor for the class. +
+portName is the name of the asyn port for this driver or plugin.maxAddr is the maximum number of asyn addresses that this driver
+ supports. This number returned by the pasynManager-> getAddr() function.
+ Typically it is 1, but some plugins (e.g. NDPluginROI) support values > 1. This
+ controls the number of parameter tables that are created.parmTableSize is the maximum number of parameters that this driver
+ or plugin supports. This controls the size of the parameter tables.interfaceMask is a mask with each bit defining which asyn interfaces
+ this driver or plugin supports. The bit mask values are defined in asynPortDriver.h,
+ e.g. asynInt32Mask.interruptMask is a mask with each bit defining which of the asyn
+ interfaces this driver or plugin supports can generate interrupts. The bit mask
+ values are defined in asynPortDriver.h, e.g. asynInt8ArrayMask.virtual asynStatus getAddress(asynUser *pasynUser, const char *functionName, int *address); ++
+ Returns the value from pasynManager-> getAddr(pasynUser,...). Returns an error + if the address is not valid, e.g. >= this-> maxAddr. +
+virtual asynStatus readInt32(asynUser *pasynUser, epicsInt32 *value); + virtual asynStatus readFloat64(asynUser *pasynUser, epicsFloat64 *value); + virtual asynStatus readOctet(asynUser *pasynUser, char *value, size_t maxChars, + size_t *nActual, int *eomReason); ++
+ These methods are called by asyn clients to return the current cached value for
+ the parameter indexed by pasynUser-> reason in the parameter table defined by
+ getAddress(). Derived classed typically do not need to implement these
+ methods.
+
virtual asynStatus writeInt32(asynUser *pasynUser, epicsInt32 value); + virtual asynStatus writeFloat64(asynUser *pasynUser, epicsFloat64 value); + virtual asynStatus writeOctet(asynUser *pasynUser, const char *value, size_t maxChars, + size_t *nActual); ++
+ These methods are called by asynClients to set the new value of a parameter. The + implementation of these methods in asynPortDriver copies the parameter into a cached + location for use by the asynRead(Int32, Float64, and Octet) methods. Most drivers + will provide their own implementations of these methods to do driver-dependent operations + when there is a new value of the parameter. +
++ virtual asynStatus readXXXArray(asynUser *pasynUser, epicsInt8 *value, + size_t nElements, size_t *nIn); + virtual asynStatus writeXXXArray(asynUser *pasynUser, epicsInt8 *value, + size_t nElements); + virtual asynStatus doCallbacksXXXArray(epicsInt8 *value, + size_t nElements, int reason, int addr); + virtual asynStatus readGenericPointer(asynUser *pasynUser, void *handle); + virtual asynStatus writeGenericPointer(asynUser *pasynUser, void *handle); + virtual asynStatus doCallbacksGenericPointer(void *handle, int reason, int addr); ++
+ where XXX=(Int8, Int16, Int32, Float32, or Float64). The readXXX and writeXXX methods
+ only have stub methods that return an error in asynPortDriver, so they must be implemented
+ in the derived classes if the corresponding interface is used. They are not pure
+ virtual functions so that the derived class need not implement the interface if
+ it is not used. The doCallbacksXXX methods in asynPortDriver call any registered
+ asyn clients on the corresponding interface if the reason and addr
+ values match. It typically does not need to be implemented in derived classes.
+
+ virtual asynStatus findParam(asynParamString_t *paramTable, int numParams, const char *paramName, int *param); + virtual asynStatus drvUserCreate(asynUser *pasynUser, const char *drvInfo, + const char **pptypeName, size_t *psize); + virtual asynStatus drvUserGetType(asynUser *pasynUser, + const char **pptypeName, size_t *psize); + virtual asynStatus drvUserDestroy(asynUser *pasynUser); ++
+ drvUserCreate must be implemented in derived classes that use the parameter facilities
+ of asynPortDriver. The findParam method is a convenience function that
+ searches an array of {enum, string} structures and returns the enum (parameter number)
+ matching the string. This is typically used in the implementation of drvUserCreate
+ in derived classes. drvUserGetType and drvUserDestroy
+ typically do not need to be implemented in derived classes.
+
+ virtual void report(FILE *fp, int details); + virtual asynStatus connect(asynUser *pasynUser); + virtual asynStatus disconnect(asynUser *pasynUser); ++
+ The report function prints information on registered interrupt clients
+ if details > 0, and prints parameter table information if details > 5. It is
+ typically called by the implementation of report in derived classes
+ before or after they print specific information about themselves. connect
+ and disconnect call pasynManager-> exceptionConnect
+ and pasynManager-> exceptionDisconnect respectively. Derived classes
+ may or may not need to implement these functions.
+
+ virtual asynStatus setIntegerParam(int index, int value); + virtual asynStatus setIntegerParam(int list, int index, int value); + virtual asynStatus setDoubleParam(int index, double value); + virtual asynStatus setDoubleParam(int list, int index, double value); + virtual asynStatus setStringParam(int index, const char *value); + virtual asynStatus setStringParam(int list, int index, const char *value); + virtual asynStatus getIntegerParam(int index, int * value); + virtual asynStatus getIntegerParam(int list, int index, int * value); + virtual asynStatus getDoubleParam(int index, double * value); + virtual asynStatus getDoubleParam(int list, int index, double * value); + virtual asynStatus getStringParam(int index, int maxChars, char *value); + virtual asynStatus getStringParam(int list, int index, int maxChars, char *value); + virtual asynStatus callParamCallbacks(); + virtual asynStatus callParamCallbacks(int list, int addr); ++
+ The setXXXParam methods set the value of a parameter in the parameter
+ table in the object. If the value is different from the previous value of the parameter
+ they also set the flag indicating that the value has changed. The getXXXParam
+ methods return the current value of the parameter. There are two versions of the
+ setXXXParam and getXXXParam methods, one with a list
+ argument, and one without. The one without uses list=0, since there
+ is often only a single parameter list (i.e. if maxAddr=1). The callParamCallbacks
+ methods call back any registered clients for parameters that have changed since
+ the last time callParamCallbacks was called. The version of callParamCallbacks
+ with no arguments uses the first parameter list and matches asyn address=0. There
+ is a second version of callParamCallbacks that takes an argument specifying
+ the parameter list number, and the asyn address to match.
+
+ 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: +
+#define ND_ARRAY_MAX_DIMS 10
+
+/* Enumeration of array data types */
+typedef enum
+{
+ NDInt8,
+ NDUInt8,
+ NDInt16,
+ NDUInt16,
+ NDInt32,
+ NDUInt32,
+ NDFloat32,
+ NDFloat64
+} NDDataType_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;
+ int dataSize;
+ void *pData;
+
+ /* Methods */
+ NDArray();
+ int initDimension (NDDimension_t *pDimension, int size);
+ int getInfo (NDArrayInfo_t *pInfo);
+ int copy (NDArray *pOut);
+ int reserve();
+ int release();
+};
+
+
+
+ + 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. +
++ 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: +
+size is the number of elements in this dimension.offset 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 > 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.binning 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.reverse 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.
+ The first 3 data fields in the NDArray class, (node, referenceCount, owner)
+ are used by the NDArrayPool class discussed below. The remaining data fields are
+ as follows:
+
uniqueId This should be a number that uniquely identifies this array.
+ Detector drivers should assign this number to the NDArray before calling the plugins.timeStamp 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).ndims The number of dimensions in this array.dims Array of NDDimension_t structures. The array is of length ND_MAX_DIMS,
+ but only the first ndims values must contain valid information.dataType 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. dataSize The size of the memory buffer pointed to by pData
+ in bytes. This may be larger than the amount actually required to hold the data
+ for this array.pData Pointer to the memory for this array. The data is assumed to
+ be stored in the order of dims[0] changing fastest, and dims[ndims-1]
+ changing slowest.+ The methods of the NDArray class are: +
+initDimension This method simply initializes the dimension structure
+ to size=size, binning=1, reverse=0, offset=0.getInfo. 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.copy. 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.reserve. This method calls NDArrayPool->reserve() for this object.
+ It increases the reference count for this array.release. This method calls NDArrayPool->release() for this object.
+ It decreases the reference count for this array.+ The NDArrayPool class manages a free list (pool) of NDArray objects (described above). + 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: +
+class NDArrayPool {
+public:
+ NDArrayPool (int maxBuffers, size_t maxMemory);
+ NDArray* alloc (int ndims, int *dims, NDDataType_t dataType, int dataSize, void *pData);
+ int reserve (NDArray *pArray);
+ int release (NDArray *pArray);
+ int convert (NDArray *pIn,
+ NDArray **ppOut,
+ NDDataType_t dataTypeOut,
+ NDDimension_t *outDims);
+ int report (int details);
+
+ + The methods of the NDArrayPool class are: +
+NDArrayPool This is the constructor for the class. The maxBuffers
+ argument is the maximum number of NDArray objects that the pool is allowed to contain.
+ 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.alloc 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.reserve. 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.release. 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.convert 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).report This method reports on the free list size and other properties
+ of the NDArrayPool object.+ 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: +
+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);
+
+};
+
+ + The methods of the asynNDArrayDriver class are: +
+asynNDArrayDriver 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.readGenericPointer 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.writeGenericPointer This method currently does nothing. Derived classes
+ must implement this method as required.report This method calls the report function in the asynPortDriver
+ base class. It then calls the NDArrayPool->report() method if details > 5.+ ADDriver inherits from asynNDArrayDriver. This is the class from which area detector + drivers are directly derived. Its public interface is defined as follows: +
+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 */
+ int createFileName(int maxChars, char *fullFileName);
+
+ + The methods of the ADDriver class are: +
+ADDriver 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.drvUserCreate 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).createFileName This is a convenience function that constructs a complete
+ file name in the ADFullFileName parameter from the ADFilePath, ADFileName, ADFileNumber,
+ and ADFileTemplate parameters.
+ The file ADStdDriverParams.h defines the following:
+
/* Enumeration of shutter status */
+typedef enum
+{
+ ADShutterClosed,
+ ADShutterOpen
+} ADShutterStatus_t;
+
+/* Enumeration of detector status */
+typedef enum
+{
+ ADStatusIdle,
+ ADStatusAcquire,
+ ADStatusReadout,
+ ASStatusCorrect,
+ ADStatusSaving,
+ ADStatusAborting,
+ ADStatusError,
+} ADStatus_t;
+
+typedef enum
+{
+ ADImageSingle,
+ ADImageMultiple,
+ ADImageContinuous
+} ADImageMode_t;
+
+typedef enum
+{
+ ADTriggerInternal,
+ ADTriggerExternal
+} ADTriggerMode_t;
+
+
+ + It also defines parameters that all area detector drivers should implement if possible. + These parameters are defined by enum values with an associated asyn interface, and + access (read-only or read-write). The EPICS database ADBase.template provides access + to these standard driver parameters. The following table lists the standard driver + parameters. The columns are defined as follows: +
++ Note that for parameters whose values are defined by enum values (e.g ADImageMode, + ADTriggerMode, ADFileFormat, ADStatus), drivers can use a different set of enum + values for these parameters. They can override the enum menu in ADBase.template + with detector-specific choices by loading a detector-specific template file after + loading ADBase.template. +
+| + Parameter Definitions in ADStdDriverParams.h and EPICS Record Definitions in ADBase.template | +||||||
| + Enum name | ++ asyn interface | ++ Access | ++ Description | ++ drvUser string | ++ EPICS record name | ++ EPICS record type | +
|---|---|---|---|---|---|---|
| + Information about the detector | +||||||
| + ADManufacturer | ++ asynOctet | ++ r/o | ++ Detector manufacturer name | ++ MANUFACTURER | ++ $(P)$(R)Manufacturer_RBV | ++ stringin | +
| + ADModel | ++ asynOctet | ++ r/o | ++ Detector model name | ++ MODEL | ++ $(P)$(R)Model_RBV | ++ stringin | +
| + ADMaxSizeX | ++ asynInt32 | ++ r/o | ++ Maximum (sensor) size in the X direction | ++ MAX_SIZE_X | ++ $(P)$(R)MaxSizeX_RBV | ++ longin | +
| + ADMaxSizeY | ++ asynInt32 | ++ r/o | ++ Maximum (sensor) size in the Y direction | ++ MAX_SIZE_Y | ++ $(P)$(R)MaxSizeY_RBV | ++ longin | +
| + Detector readout control including gain, binning, region start and size, reversal | +||||||
| + ADGain | ++ asynFloat64 | ++ r/w | ++ Detector gain | ++ GAIN | +
+ $(P)$(R)Gain + $(P)$(R)Gain_RBV |
+
+ ao + ai |
+
| + ADBinX | ++ asynInt32 | ++ r/w | ++ Binning in the X direction | ++ BIN_X | +
+ $(P)$(R)BinX + $(P)$(R)BinX_RBV |
+
+ longout + longin |
+
| + ADBinY | ++ asynInt32 | ++ r/w | ++ Binning in the Y direction | ++ BIN_Y | +
+ $(P)$(R)BinY + $(P)$(R)BinY_RBV |
+
+ longout + longin |
+
| + ADMinX | ++ asynInt32 | ++ r/w | +
+ First pixel to read in the X direction.
+ + 0 is the first pixel on the detector. |
+ + MIN_X | +
+ $(P)$(R)MinX + $(P)$(R)MinX_RBV |
+
+ longout + longin |
+
| + ADMinY | ++ asynInt32 | ++ r/w | +
+ First pixel to read in the Y direction. + 0 is the first pixel on the detector. |
+ + MIN_Y | +
+ $(P)$(R)MinY + $(P)$(R)MinY_RBV |
+
+ longout + longin |
+
| + ADSizeX | ++ asynInt32 | ++ r/w | ++ Size of the region to read in the X direction | ++ SIZE_X | +
+ $(P)$(R)SizeX + $(P)$(R)SizeX_RBV |
+
+ longout + longin |
+
| + ADSizeY | ++ asynInt32 | ++ r/w | ++ Size of the region to read in the Y direction | ++ SIZE_Y | +
+ $(P)$(R)SizeY + $(P)$(R)SizeY_RBV |
+
+ longout + longin |
+
| + ADReverseX | ++ asynInt32 | ++ r/w | +
+ Reverse image in the X direction + (0=No, 1=Yes) |
+ + REVERSE_X | +
+ $(P)$(R)ReverseX + $(P)$(R)ReverseX_RBV |
+
+ longout + longin |
+
| + ADReverseY | ++ asynInt32 | ++ r/w | +
+ Reverse image in the Y direction + (0=No, 1=Yes) |
+ + REVERSE_Y | +
+ $(P)$(R)ReverseY + $(P)$(R)ReverseY_RBV |
+
+ longout + longin |
+
| + Image and trigger modes | +||||||
| + ADImageMode | ++ asynInt32 | ++ r/w | ++ Image mode (ADImageMode_t). | ++ IMAGE_MODE | +
+ $(P)$(R)ImageMode + $(P)$(R)ImageMode_RBV |
+
+ mbbo + mbbi |
+
| + ADTriggerMode | ++ asynInt32 | ++ r/w | ++ Trigger mode (ADTriggerMode_t). | ++ TRIGGER_MODE | +
+ $(P)$(R)TriggerMode + $(P)$(R)TriggerMode_RBV |
+
+ mbbo + mbbi |
+
| + Data type | +||||||
| + ADDataType | ++ asynInt32 | ++ r/w | ++ Data type (NDDataType_t). | ++ DATA_TYPE | +
+ $(P)$(R)DataType + $(P)$(R)DataType_RBV |
+
+ mbbo + mbbi |
+
| + Actual dimensions of image data | +||||||
| + ADImageSizeX | ++ asynInt32 | ++ r/o | ++ Size of the image data in the X direction | ++ IMAGE_SIZE_X | ++ $(P)$(R)ImageSizeX_RBV | ++ longin | +
| + ADImageSizeY | ++ asynInt32 | ++ r/o | ++ Size of the image data in the Y direction | ++ IMAGE_SIZE_Y | ++ $(P)$(R)ImageSizeY_RBV | ++ longin | +
| + ADImageSize | ++ asynInt32 | ++ r/o | ++ Total size of image data in bytes | ++ IMAGE_SIZE | ++ $(P)$(R)ImageSize_RBV | ++ longin | +
| + Acquisition time and period | +||||||
| + ADAcquireTime | ++ asynFloat64 | ++ r/w | ++ Acquisition time per image | ++ ACQ_TIME | +
+ $(P)$(R)AcquireTime + $(P)$(R)AcquireTime_RBV |
+
+ ao + ai |
+
| + ADAcquirePeriod | ++ asynFloat64 | ++ r/w | ++ Acquisition period between images | ++ ACQ_PERIOD | +
+ $(P)$(R)AcquirePeriod + $(P)$(R)AcquirePeriod_RBV |
+
+ ao + ai |
+
| + Number of exposures and number of images | +||||||
| + ADNumExposures | ++ asynInt32 | ++ r/w | ++ Number of exposures per image to acquire | ++ NEXPOSURES | +
+ $(P)$(R)NumExposures + $(P)$(R)NumExposures_RBV |
+
+ longout + longin |
+
| + ADNumImages | ++ asynInt32 | ++ r/w | ++ Number of images to acquire in one acquisition sequence | ++ NIMAGES | +
+ $(P)$(R)NumImages + $(P)$(R)NumImages_RBV |
+
+ longout + longin |
+
| + Acquisition control | +||||||
| + ADAcquire | ++ asynInt32 | ++ r/w | ++ Start (1) or stop (0) image acquisition. This record is linked to an EPICS busy + record that does not process its forward link until acquisition is complete. Clients + should write 1 to the Acquire record to start acquisition, and wait for Acquire + to go to 0 to know that acquisition is complete. | ++ ACQUIRE | ++ $(P)$(R)Acquire | ++ bo | +
| + File saving parameters | +||||||
| + ADFilePath | ++ asynOctet | ++ r/w | ++ File path | ++ FILE_PATH | +
+ $(P)$(R)FilePath + $(P)$(R)FilePath_RBV |
+
+ waveform + waveform |
+
| + ADFileName | ++ asynOctet | ++ r/w | ++ File name | ++ FILE_NAME | +
+ $(P)$(R)FileName + $(P)$(R)FileName_RBV |
+
+ waveform + waveform |
+
| + ADFileNumber | ++ asynInt32 | ++ r/w | ++ File number | ++ FILE_NUMBER | +
+ $(P)$(R)FileNumber + $(P)$(R)FileNumber_RBV |
+
+ longout + longin |
+
| + ADFileTemplate | ++ asynOctet | ++ r/w | +
+ Format string for constructing ADFullFileName from ADFilePath, ADFileName, and ADFileNumber.
+ The final file name (which is placed in ADFullFileName) is created with the following
+ code:
+ epicsSnprintf(FullFilename, sizeof(FullFilename), FileFormat, + FilePath, Filename, FileNumber); ++ FilePath, Filename, FileNumber are converted in that order with FileFormat. An example + file format is "%s%s%4.4d.tif". The first %s converts the FilePath,
+ followed immediately by another %s for Filename. FileNumber is formatted with %4.4d,
+ which results in a fixed field with of 4 digits, with leading zeros as required.
+ Finally, the .tif extension is added to the file name. This mechanism for creating
+ file names is very flexible. Other characters, such as _ can be put in Filename
+ or FileFormat as desired. If one does not want to have FileNumber in the file name
+ at all, then just omit the %d format specifier from FileFormat. If the client wishes
+ to construct the complete file name itself, then it can just put that file name
+ into ADFileFormat with no format specifiers at all, in which case ADFilePath, ADFileName,
+ and ADFileNumber will be ignored. |
+ + FILE_TEMPLATE | +
+ $(P)$(R)FileTemplate + $(P)$(R)FileTemplate_RBV |
+
+ waveform + waveform |
+
| + ADFullFileName | ++ asynOctet | ++ r/o | ++ Full file name | ++ FULL_FILE_NAME | ++ $(P)$(R)FullFileName_RBV | +
+ waveform + waveform |
+
| + ADAutoIncrement | ++ asynInt32 | ++ r/w | ++ Auto-increment flag. Controls whether FileNumber is automatically incremented by + 1 each time an acquisition completes (0=No, 1=Yes) | ++ AUTO_INCREMENT | +
+ $(P)$(R)AutoIncrement + $(P)$(R)AutoIncrement_RBV |
+
+ bo + bi |
+
| + ADAutoSave | ++ asynInt32 | ++ r/w | ++ Auto-save flag (0=No, 1=Yes) | ++ AUTO_SAVE | +
+ $(P)$(R)AutoSave + $(P)$(R)AutoSave_RBV |
+
+ bo + bi |
+
| + ADFileFormat | ++ asynInt32 | ++ r/w | ++ File format. The format to write/read data in (e.g. TIFF, netCDF, etc.) | ++ FILE_FORMAT | +
+ $(P)$(R)FileFormat + $(P)$(R)FileFormat_RBV |
+
+ mbbo + mbbi |
+
| + ADWriteFile | ++ asynInt32 | ++ r/w | ++ Manually save the most recent image to a file when value=1 | ++ WRITE_FILE | ++ $(P)$(R)WriteFile | ++ longout | +
| + ADReadFile | ++ asynInt32 | ++ r/w | ++ Manually read a file when value=1 | ++ READ_FILE | ++ $(P)$(R)ReadFile | ++ longout | +
| + Status information | +||||||
| + ADStatus | ++ asynInt32 | ++ r/o | ++ Acquisition status (ADStatus_t) | ++ STATUS | ++ $(P)$(R)DetectorState_RBV | ++ mbbi | +
| + ADStatusMessage | ++ asynOctet | ++ r/o | ++ Status message string | ++ STATUS_MESSAGE | ++ $(P)$(R)StatusMessage_RBV | ++ waveform | +
| + ADStringToServer | ++ asynOctet | ++ r/o | ++ String from driver to string-based vendor server | ++ STRING_TO_SERVER | ++ $(P)$(R)StringToServer_RBV | ++ waveform | +
| + ADStringFromServer | ++ asynOctet | ++ r/o | ++ String from string-based vendor server to driver | ++ STRING_FROM_SERVER | ++ $(P)$(R)StringFromServer_RBV | ++ waveform | +
| + ADImageCounter | ++ asynInt32 | ++ r/w | ++ Counter that increments by 1 each time an image is acquired | ++ IMAGE_COUNTER | +
+ $(P)$(R)ImageCounter + $(P)$(R)ImageCounter_RBV |
+
+ longout + longin |
+
| + N/A | ++ N/A | ++ r/o | ++ Rate (Hz) at which ImageCounter is incrementing. Computed in database. | ++ N/A | ++ $(P)$(R)ImageRate_RBV | ++ calc | +
| + Shutter control. Note: no areaDetector drivers yet implement shutter control, and + these parameters may change in the near future. | +||||||
| + ADShutter | ++ asynInt32 | ++ r/w | ++ Shutter control (ADShutterStatus_t) | ++ SHUTTER | +
+ $(P)$(R)ShutterMode + $(P)$(R)ShutterMode_RBV |
+
+ mbbo + mbbi |
+
| + Image data | +||||||
| + NDArrayData | ++ asynGenericPointer | ++ r/w | ++ The image data as an NDArray object | ++ NDARRAY_DATA | ++ N/A. EPICS access to image data is through NDStdArrays plugin. | ++ N/A | +
| + asyn port information | +||||||
| + N/A | ++ N/A | ++ N/A | ++ The name of the asyn port for this driver | ++ N/A | ++ $(P)$(R)PortName_RBV | ++ stringin | +
| + N/A | ++ N/A | ++ N/A | ++ asyn record to control debugging (asynTrace) | ++ N/A | ++ $(P)$(R)AsynIO | ++ asyn | +
+ The following is the MEDM screen that provides access to the parameters in ADStdDriverParams + through records in ADBase.template. This is a top-level MEDM screen that will work + with any areaDetector driver. Note however that many drivers will not implement + all of these parameters, so detector-specific MEDM screens should generally be created + that only display the EPICS PVs for the features implemented for that detector. + Note that the section of the screen labeled "Shutter" is not currently implemented + for any areaDetector driver, and is subject to change in the near future. +
++ areaDetector has been designed to minimize the amount of work required to write + a new detector driver. These drivers are described in separate documents, linked + to by the table of contents at the top of this page. +
+ + diff --git a/documentation/pilatusDoc.html b/documentation/pilatusDoc.html index 560f78f..3043f22 100755 --- a/documentation/pilatusDoc.html +++ b/documentation/pilatusDoc.html @@ -1,1029 +1,944 @@ - - -- -
-The interface to the detector is via a TCP/IP socket interface to the camserver server that Dectris provides. -The camserver program must be started before the areaDetector software is started, typically by running the -camonly script provided by Dectris. -
--The camserver program saves the data to disk as TIFF files. The areaDetector software reads these disk files in -order to read the data, because camserver does not provide another mechanism to access the data. -
--The following table describes how the Pilatus driver implements some of the standard driver parameters. -
-| Parameter Definitions in pilatusDetector.cpp and EPICS Record Definitions in pilatus.template | -||
| Enum name | -EPICS record name | -Description | -
|---|---|---|
| ADTriggerMode | -$(P$(R)TriggerMode | -The driver redefines the choices for the ADTriggerMode parameter (record $(P)$(R)TriggerMode) from ADStdDriverParams.h.
- The choices for the Pilatus are:
-
Exposure,
- ExtEnable, ExtTrigger, and ExtMTrigger respectively.
- Alignment mode uses the Exposure command as well, but continuously takes images into
- the same temporary file (alignment.tif).
- |
-
| ADExposureTime | -$(P$(R)ExposureTime | -In External Enable mode this value is not - used by camserver. However, it should be set larger than the maximum time exposure time from the - external source, so that pilatusROI.st can estimate how long - to wait for the data files to be created before timing out. | -ADNumImages | -$(P$(R)NumImages | -Controls the number of images to acquire. It applies in all trigger modes except - Alignment. | - -ADExposurePeriod | -$(P$(R)ExposurePeriod | -Controls the exposure period in seconds. It is only in Internal or External Trigger modes - when NumImages > 1. | - -
| ADNumExposures | -$(P$(R)NumExposures | -Controls the number of exposures per image. It is only used in External Enable mode. | -
| ADAquire | -$(P$(R)Acquire | -Controls the acquisition. Setting this to 1 starts image acquisition. - The driver sets the record to 0 when acquisition is complete. This means an entire - acquisition series if NImages > 1. Setting this to 0 aborts an acquisition. If the driver - was currently acquiring imges then this record will cause the "Stop" and "K" (Kill) commands to - be sent to camserver. | -
| ADFilePath | -$(P$(R)FilePath | -Controls the path for saving images. It must be a valid path for camserver - and for the areaDetector driver, which is normally running in an EPICS IOC. - If camserver and the EPICS IOC are not running on the same machine then soft links - will typically be used to make the paths look identical. | -ADFileFormat | -$(P)$(R)FileFormat | -camserver uses the file extension to determine what format to save the files in. The areaDetector Pilatus
- driver only supports TIFF files, so the extension should be .tif.
- When saving multiple images (NImages>1) camserver has its own rules for creating the
- names of the individual files. The rules are as follows.
- The name constructed using the algorithm described for ADFileTemplate in
- areaDetectorDoc.html
- is used as a basename.
- The following examples show the interpretation of the basename.
- - Basename Files produced - - test6.tif test6_00000.tif, test6_00001.tif, ... - test6_.tif test6_00000.tif, test6_00001.tif, ... - test6_000.tif test6_000.tif, test6_001.tif, ... - test6_014.tif test6_014.tif, test6_015.tif, ... - test6_0008.tif test6_0008.tif, test6_0009.tif, ... - test6_2_0035.tif test6_2_0035.tif, test6_2_0036.tif, ... -- - The numbers following the last '_' are taken as a format template, - and as a start value. The minimum format is 3; there is no maximum; the - default is 5. The format is also constrained by the requested number of images. |
-
-
-
-
-The Pilatus driver implements the following parameters in addition to those in ADStdDriverParams.h: -
-| Parameter Definitions in pilatusDetector.cpp and EPICS Record Definitions in pilatus.template | -||||||
| Enum name | -asyn interface | -Access | -Description | -drvUser string | -EPICS record name | -EPICS record type | -
|---|---|---|---|---|---|---|
| PilatusDelayTime | -asynFloat64 | -r/w | -Delay in seconds between the external trigger - and the start of image acquisition. It only applies in External Trigger mode | -DELAY_TIME | -$(P)$(R)DelayTime | -ao | -
| PilatusThreshold | -asynFloat64 | -r/w | -Threshold energy in keV | -THRESHOLD | -$(P)$(R)ThresholdEnergy | -ao | -
| N/A | -N/A | -r/w | -Gain menu. Controls the value of Vrf, which determines the shaping time and gain of the
- input amplifiers. The allowed values are:
-
|
- N/A | -$(P)$(R)GainMenu | -mbbo | -
| PilatusArmed | -asynInt32 | -r/o | -Flag to indicate when the Pilatus is ready to accept external trigger signals (0=not ready, 1=ready). - This should be used by clients to indicate when it is OK to start sending trigger pulses - to the Pilatus. If pulses are send before Armed=1 then the Pilatus may miss them, leading to - DMA timeout errors from camserver | -ARMED | -$(P)$(R)Armed | -bi | -
| PilatusTiffTimeout | -asynFloat64 | -r/w | -Timeout in seconds when reading a TIFF file | -TIFF_TIMEOUT | -$(P)$(R)ReadTiffTimeout | -ao | -
| PilatusBadPixelFile | -asynOctet | -r/w | -Name of a file to be used to replace bad pixels.
- If this record does not point to a valid bad pixel file then no bad pixel mapping is performed.
- The bad pixel map
- is used before making the NDArray callbacks. It does not modify
- the data in the files that camserver writes. This is a simple ASCII file with the following
- format:
- - badX1,badY1 replacementX1,replacementY1 - badX2,badY2 replacementX2,replacementY2 - ... -- The X and Y coordinates range from 0 to NXPixels-1 and NYPixels-1. Up to 100 bad pixels can be defined. - The bad pixel mapping simply replaces the bad pixels with another pixel's value. - It does not do any averaging. It is felt that this is sufficient for the purpose for which - pilatusROI was written, namely fast on-line viewing of ROIs and ImageData. More sophisticated - algorithms can be used for offline analysis of the image files themselves. - The following is an example bad pixel file for a GSECARS detector: - - 263,3 262,3 - 264,3 266,3 - 263,3 266,3 - 300,85 299,85 - 300,86 299,86 - 471,129 472,129 - |
- BAD_PIXEL_FILE | -$(P)$(R)BadPixelFile | -waveform | -
| PilatusNumBadPixels | -asynInt32 | -r/o | -The number of bad pixels defined in the bad pixel file. - Useful for seeing if the bad pixel file was read correctly. | -NUM_BAD_PIXELS | -$(P)$(R)NumBadPixels | -longin | -
| PilatusFlatFieldFile | -asynOctet | -r/w | -Name of a file to be used to correct for the flat field.
- If this record does not point to a valid flat field file then no flat field correction is performed.
- The flat field file is simply a TIFF file collected by the Pilatus that is used to correct for
- spatial non-uniformity in the response of the detector. It should be collected with a spatially uniform
- intensity on the detector at roughly the same energy as the measurements being corrected.
- When the flat field file is read, the average pixel value (averageFlatField) is computed
- using all pixels with intensities > PilatusMinFlatField. All pixels with intensity < PilatusMinFlatField
- in the flat field are replaced with averageFlatField.
- When images are collected before the NDArray callbacks are performed
- the following per-pixel correction is applied:
- - ImageData[i] = (averageFlatField * ImageData[i])/flatField[i]; - |
- FLAT_FIELD_FILE | -$(P)$(R)FlatFieldFile | -waveform | -
| PilatusMinFlatField | -asynInt32 | -r/w | -The mimimum valid intensity in the flat field. This value must be set > 0 to prevent divide by 0 errors. - If the flat field was collected with some pixels having very low intensity then this value can be used to - replace those pixels with the average response. | -MIN_FLAT_FIELD | -$(P)$(R)MinFlatField | -longout | -
| PilatusFlatFieldValid | -asynInt32 | -r/o | -This record indicates if a valid flat field file has been read. 0=No, 1=Yes. | -FLAT_FIELD_VALID | -$(P)$(R)FlatFieldValid | -bi | -
| N/A | -N/A | -N/A | -asyn record to control debugging communication with camserver | -N/A | -$(P)$(R)CamserverAsyn | -asyn | -
FullFilename (waveform, FTVL=UCHAR, NELM=256)ROI$(N)XMax (longout)ROI$(N)YMin (longout)ROI$(N)YMax (longout)ROI$(N)BgdWidth (longout)ROI$(N)TotalCounts (ao)ROI$(N)NetCounts (ao)ROI$(N)MinCounts (longout)ROI$(N)MaxCounts (longout)ROI$(N)Label (stringout)ROI$(N)WFTotalCounts (waveform, FTVL=DOUBLE, NELM=$(NCHANS))ROI$(N)WFNetCounts (waveform, FTVL=DOUBLE, NELM=$(NCHANS))MinWFUpdateTime (ao)ImageData (waveform, FTVL=LONG, NELM=$(NPIXELS))NXPixels (longout)NYPixels (longout)HighlightROIs (bo)PostImages (bo)MinImageUpdateTime (ao)FlatFieldValid (bo)ReadTiffTimeout (ao)SendMessage (waveform, FTVL=UCHAR, NELM=256)ReplyMessage (waveform, FTVL=UCHAR, NELM=256)Connect (bo)Disconnect (bo)scan1, scan2, scan3, scan4, scanH (sscan)- -
-pilatusROI.template is loaded with the following macro parameters: -
| Macro parameter | -Description | -
|---|---|
$(DET) |
- PV name prefix. This identifies this Pilatus detector from others that may be - running on the same subnet. - | -
$(NXPIXELS) |
- The number of pixels in the X (fast index) direction on the detector. This is 487 for the Pilatus 100K. | -
$(NYPIXELS) |
- The number of pixels in the Y (slow index) direction on the detector. This is 195 for the Pilatus 100K. | -
$(NPIXELS) |
- The total number of pixels on the detector. This is NXPIXELS*NYPIXELS=94965 for the Pilatus 100K. | -
$(PORT) |
- The name of the asyn port connected to the Pilatus via a TCP/IP socket. | -
-pilatusROI_N.template is loaded for each ROI with the following macro parameters: -
| Macro parameter | -Description | -
|---|---|
$(DET) |
- PV name prefix. This identifies this Pilatus detector from others that may be - running on the same subnet. | -
$(N) |
- The number of this ROI. Starts with 1. | -
$(XMIN) |
- The minimum value of X for this ROI. Starts with 0. | -
$(XMAX) |
- The maximum value of X for this ROI. Starts with 0. | -
$(YMIN) |
- The minimum value of Y for this ROI. Starts with 0. | -
$(YMAX) |
- The maximum value of Y for this ROI. Starts with 0. | -
$(BGD_WIDTH) |
- The background width for this ROI. - If BGD_WIDTH <=0 then no background subtraction is done, and NetCounts=TotalCounts. | -
$(NCHANS) |
- The maximum number of elements in the WFTotalCounts and WFNetCounts waveform arrays. - This sets the maximum value of NImages for collecting ROI arrays. | -
-The pilatusROIs SNL program is started with the following macro parameters: -
| Macro parameter | -Description | -
|---|---|
DET |
- PV name prefix. This identifies this Pilatus detector from others that may be - running on the same subnet. | -
PORT |
- The name of the asyn port connected to the Pilatus via a TCP/IP socket. | -
NROIS |
- The number of ROIs loaded in the substitutions file with pilatusROI_N.template. - Maximum=32. | -
-The following is an example st.cmd startup script: -
-< envPaths
-
-###
-# Load the EPICS database file
-dbLoadDatabase("$(PILATUS)/dbd/pilatus.dbd")
-pilatus_registerRecordDeviceDriver(pdbbase)
-
-###
-# Create the asyn port to talk to the Pilatus on port 41234.
-drvAsynIPPortConfigure("pilatus","gse-pilatus1:41234")
-# Set the input and output terminators.
-asynOctetSetInputEos("pilatus", 0, "\030")
-asynOctetSetOutputEos("pilatus", 0, "\n")
-# Define the environment variable pointing to stream protocol files.
-epicsEnvSet("STREAM_PROTOCOL_PATH", "$(PILATUS)/pilatusApp/Db")
-
-###
-# Specify where save files should be
-set_savefile_path(".", "autosave")
-
-###
-# Specify what save files should be restored. Note these files must be
-# in the directory specified in set_savefile_path(), or, if that function
-# has not been called, from the directory current when iocInit is invoked
-set_pass0_restoreFile("auto_settings.sav")
-set_pass1_restoreFile("auto_settings.sav")
-
-###
-# Specify directories in which to to search for included request files
-set_requestfile_path("./")
-set_requestfile_path("$(AUTOSAVE)", "asApp/Db")
-set_requestfile_path("$(CALC)", "calcApp/Db")
-set_requestfile_path("$(SSCAN)", "sscanApp/Db")
-set_requestfile_path("$(PILATUS)", "pilatusApp/Db")
-
-###
-# Load the save/restore status PVs
-dbLoadRecords("$(AUTOSAVE)/asApp/Db/save_restoreStatus.db", "P=PILATUS:")
-
-###
-# Load the substitutions for for this IOC
-dbLoadTemplate("PILATUS_all.subs")
-# Load an asyn record for debugging
-dbLoadRecords("$(ASYN)/db/asynRecord.db", "P=PILATUS:,R=asyn1,PORT=pilatus,ADDR=0,IMAX=80,OMAX=80")
-
-# Load sscan records for scanning
-dbLoadRecords("$(SSCAN)/sscanApp/Db/scan.db", "P=PILATUS:,MAXPTS1=2000,MAXPTS2=200,MAXPTS3=20,MAXPTS4=10,MAXPTSH=2048")
-
-###
-# Set debugging flags if desired
-#asynSetTraceIOMask("pilatus",0,2)
-#asynSetTraceMask("pilatus",0,3)
-
-###
-# Start the IOC
-iocInit
-
-###
-# Save settings every thirty seconds
-create_monitor_set("auto_settings.req", 30, "P=PILATUS:")
-
-###
-# Start the SNL program
-seq(pilatusROIs, "DET=PILATUS:, PORT=pilatus, NROIS=16")
-
-
-The following is the substutitions file PILATUS_all.subs referenced above.
-It creates 16 ROIS, and defines 5 valid ones: the entire chip, and the 4 quadrants of the chip:
-
-ffile $(PILATUS)/db/pilatusROI.template {
-pattern
-{DET, NXPIXELS, NYPIXELS, NPIXELS, PORT}
-{PILATUS:, 487, 195, 94965, pilatus}
-}
-
-file $(PILATUS)/db/pilatusROI_N.template {
-pattern
-{DET, N, XMIN, XMAX, YMIN, YMAX, BGD_WIDTH, NCHANS}
-{PILATUS:, 1, 0, 486, 0, 194, 1, 2000}
-{PILATUS:, 2, 0, 243, 0, 97, 1, 2000}
-{PILATUS:, 3, 0, 243, 98, 194, 1, 2000}
-{PILATUS:, 4, 244, 486, 0, 97, 1, 2000}
-{PILATUS:, 5, 244, 486, 98, 194, 1, 2000}
-{PILATUS:, 6, -1, -1, -1, -1, 1, 2000}
-{PILATUS:, 7, -1, -1, -1, -1, 1, 2000}
-{PILATUS:, 8, -1, -1, -1, -1, 1, 2000}
-{PILATUS:, 9, -1, -1, -1, -1, 1, 2000}
-{PILATUS:, 10, -1, -1, -1, -1, 1, 2000}
-{PILATUS:, 11, -1, -1, -1, -1, 1, 2000}
-{PILATUS:, 12, -1, -1, -1, -1, 1, 2000}
-{PILATUS:, 13, -1, -1, -1, -1, 1, 2000}
-{PILATUS:, 14, -1, -1, -1, -1, 1, 2000}
-{PILATUS:, 15, -1, -1, -1, -1, 1, 2000}
-{PILATUS:, 16, -1, -1, -1, -1, 1, 2000}
-}
-
-
-- -
-The following show the MEDM screens that are used to control the pilatusROI software.
- -- -
pilatusROI.adl is the main screen used to control the pilatusROI SNL
-program. All records except those that are specific to each ROI are accessed through this
-screen.
-
- -
pilatus8ROIs.adl is used to define the ROIs, and to display the statistics for
-each ROI. In this example there are 2 valid ROIs defined. ROI 1 is a small rectangle near the center
-containing the Bragg diffraction peak from a crystal. ROI 2 is the entire chip.
-
- -
pilatusROI_waveform.adl is used to plot the net or total counts in an ROI when
-NImages>1. In this example the plot is the net counts in ROI 1 as the diffractometer chi was scanned
-+- 1 degree with 1000 points at .02 seconds/point. This was done with the SPEC command
--lup chi -1 1 1000 .02 --using trajectory scanning on a Newport kappa diffractometer. This was a compound motor scan with the -Newport XPS putting out pulses every .02 seconds. These pulses triggered the Pilatus in External Enable mode. -The pilatusROI program read each TIFF file as it was created and updated this plot every 0.2 seconds. -The total time to collect this scan with 1000 images was 20 seconds. -
- -
scan_more.adl is used to define a scan. In this example the sscan record is set up
-to scan the ThresholdEnergy PV and to collect the total counts in ROI2, which was defined to include
-the entire detector.
-
- -
scanDetPlot.adl is used to plot the results of a scan after it is complete.
-In this example the total counts in ROI 2 are plotted as a function of the ThresholdEnergy as it was
-scanned from 3000 to 10000 eV in 250 eV steps. The source was Fe55, and the cut-off is at 6 keV, as
-expected for the Mn Ka and Mn Kb x-rays that this source produces.
-
- -
asynRecord.adl is used to control the debugging information printed by the asyn TCP/IP driver
-(asynTraceIODriver) and the SNL program (asynTraceIODevice).
-
- -
asynOctet.adl can be used to send any command to camserver and display the response. It can
-be loaded from the More menu in asynRecord.adl above.
-
- IDL Image Display Clientepics_image_display
-that can be used to display the ImageData PV that pilatusROI sends over EPICS. This IDL
-client is available as source code (which requires an IDL license), and also as a pre-built IDL .sav
-file that can be run for free under the IDL Virtual Machine. This IDL program can run on any machine that IDL
-runs on, and that has the ezcaIDL shareable library built for it. This includes Windows, Linux, Solaris, and Mac.
-epics_image_display is included in the
-CARS IDL imaging software.
-
-
-The control window for epics_image_display is shown below. It has fields to input the name of
-the EPICS PV with the image data, which is $(DET)ImageData in the case of pilatusROI. It also has fields
-for the number of pixels in the X and Y directions. This is needed because EPICS waveform records are
-1-dimensional only, and so do not contain the information on the number of rows and columns in the image.
-
-
- -
epics_image_display uses the routine
-image_display.pro
-to display the images. This routine displays row and column profiles as the cursor is moved. It allows
-changing the color lookup tables, and zooming in and out with the left and right mouse buttons. The following
-is an example of image_display displaying a Pilatus image with an Fe55 source in front of the detector.
-
-
- -
-# need some more globals (kludge)
-global PILATUS_ROI_PV
-global PILATUS_imgPATH_PV
-global PILATUS_FNAME_PV
-global PILATUS_FILENUMBER_PV
-global PILATUS_FILEFORMAT_PV
-global PILATUS_EXPSRTM_PV
-global PILATUS_NFRAME_PV
-global PILATUS_EXPPRD_PV
-global PILATUS_NEXPFRM_PV
-global PILATUS_ACQ_PV
-global PILATUS_ACQMODE_PV
-
-###############################################################
-def _setup_img '{
- local j, str
-
- # PILATUS_PREFIX should be detector aquisition pv (GSE-PILATUS1:)
- if ( PILATUS_PREFIX == "") PILATUS_PREFIX = "GSE-PILATUS1:"
- PILATUS_PREFIX = getval("Enter PILATUS pv prefix",PILATUS_PREFIX)
-
- # rois pvs
- PILATUS_ROI_PV = PILATUS_PREFIX "ROI1NetCounts"
- PILATUS_imgPATH_PV = PILATUS_PREFIX "FilePath"
- PILATUS_FNAME_PV = PILATUS_PREFIX "Filename"
- PILATUS_FILENUMBER_PV = PILATUS_PREFIX "FileNumber"
- PILATUS_FILEFORMAT_PV = PILATUS_PREFIX "FileFormat"
- PILATUS_EXPSRTM_PV = PILATUS_PREFIX "ExposureTime"
- PILATUS_NFRAME_PV = PILATUS_PREFIX "NImages"
- PILATUS_EXPPRD_PV = PILATUS_PREFIX "ExposurePeriod"
- PILATUS_NEXPFRM_PV = PILATUS_PREFIX "NExposures"
- PILATUS_ACQ_PV = PILATUS_PREFIX "Acquire"
- PILATUS_ACQMODE_PV = PILATUS_PREFIX "AcquireMode"
-...
-
-def epics_pilatus_count '{
-...
- # write to data base fields
- # Need to convert path from string to byte array
- # Note: we use the "wait" parameter in epics_put here (new to spec5.7.02) so that
- # it uses ca_put_callback, to know that all PVs have been processed
- # before we start counting. Use 1 second timeout, will actually be
- # much faster than this unless something is wrong.
- array _temp[256]
- _temp = PILATUS_IMAGE_DIR
- # Do not change path for now
- #epics_put(PILATUS_imgPATH_PV,_temp, 1)
- epics_put(PILATUS_FNAME_PV,img_fname, 1)
- epics_put(PILATUS_FILENUMBER_PV,NPTS, 1)
- epics_put(PILATUS_FILEFORMAT_PV,_fileformat, 1)
- epics_put(sc_prtm_pv,cnt_time_val, 1)
- epics_put(PILATUS_EXPSRTM_PV,cnt_time_val, 1)
- epics_put(PILATUS_ACQMODE_PV,0, 1) # Internal trigger
- epics_put(PILATUS_NFRAME_PV, 1, 1)
- epics_put(PILATUS_NEXPFRM_PV, 1, 1)
-
-
-def user_getcounts '{
- local pv_roi, j, pv
-
-...
- # using image_count routine
- } else if ( EPICS_COUNT == 4 ) {
- S[iroi] = 0
- S[iroi] = epics_get(PILATUS_ROI_PV)
-
-
-- -
- lup chi -2 2 1000 .015 -- This tells SPEC to do a relative scan of the chi axis from -2 degrees to +2 degrees with 1000 points - at .015 seconds/point. On our kappa diffractometer this entails a coordinated motion of the phi, kappa - and omega axes. The EPICS trajectory scanning software downloads the non-linear trajectory that SPEC computes - into the XPS controller, which executes it. As the motors are moving the XPS outputs synchronization pulses - at the period of the collection time, .015 seconds in this case. These pulses are stretched - (see Hardware notes below) and used as the external input to the Pilatus. - The time to execute this scan should be 15.0 seconds. The actual time was 16.3 seconds, measured - using camonitor on the Acquire PV. Again, this includes the time for camserver to save all 1000 images to disk - (366 MB), and for pilatusROI to read each file, correct the bad pixels and flat field, compute the ROIs, and post the ROIs - to EPICS. It also posted the images to EPICS at 1Hz (15 images total). The total additional time was less - than 1.3 seconds for all 1000 images. As soon as the acquisition was complete SPEC plotted the net counts in - the first ROI (containing the Bragg peak) as follows: -
- For comparison this identical scan was executed in traditional step-scanning mode, where the motors stopped - at each point in the scan. The Pilatus was run in Internal mode with NImages=1. The total time for the scan - was 870 seconds (more than 14 minutes), compared to 16.3 seconds in trajectory mode. Most of this overhead - is the settling time for the motors, with only a small fraction due to the Pilatus single-exposure mode. The - trajectory scanning mode is thus more than 50 times faster to execute the identical SPEC scan. -
- -
In External Enable mode (the camserver ExtEnable command) the Pilatus uses the external signal to control acquisition. -Only NImages and NExposures are used, ExposureTime and ExposurePeriod are not used. When the signal -is high the detector counts, and on the transition to low it begins its readout. - -
In External MultiTrigger Mode (the camserver ExtMTrigger command) the Pilatus uses the programmed ExposureTime, -in addition to NImages and NExposures. Each external trigger pulse causes the Pilatus to collect one image -at the programmed exposure time. This mode works well with a trigger source like the Newport motor controllers -or the SIS380x multichannel scaler, -that put out a short trigger pulse for each image. One only needs to take care that the time between external trigger -pulses is at least 4msec longer than the programmed exposure time, to allow time for the detector to read out before -the next trigger pulse arrives. - -
When using the External Enable mode, we use an inexpensive analog pulse generator -to convert the trigger pulses from the MM4005 and XPS to a form suitable for External Enable mode -with the Pilatus. This is the solution we have developed that seems to be reliable: -
-Dectris has since informed me that they have increased the power supply voltage on all new Pilatus systems, -so this should no longer be an issue. - - -
- -
+ This is a driver for the Pilatus pixel array detectors + Dectris. It inherits from ADDriver and implements many of the parameters in + ADStdDriverParams.h. It also implements a number of parameters that are specific + to the Pilatus detectors.
++ The interface to the detector is via a TCP/IP socket interface to the camserver + server that Dectris provides. The camserver program must be started before the areaDetector + software is started, typically by running the camonly script provided by + Dectris. +
++ The camserver program saves the data to disk as TIFF files. The areaDetector software + reads these disk files in order to read the data, because camserver does not provide + another mechanism to access the data. +
++ The following table describes how the Pilatus driver implements some of the standard + driver parameters. +
+| + Parameter Definitions in pilatusDetector.cpp and EPICS Record Definitions in pilatus.template | +||
| + Enum name | ++ EPICS record name | ++ Description | +
|---|---|---|
| + ADTriggerMode | ++ $(P$(R)TriggerMode | +
+ The driver redefines the choices for the ADTriggerMode parameter (record $(P)$(R)TriggerMode)
+ from ADStdDriverParams.h. The choices for the Pilatus are:
+
Exposure,
+ ExtEnable, ExtTrigger, and ExtMTrigger respectively.
+ Alignment mode uses the Exposure command as well, but continuously
+ takes images into the same temporary file (alignment.tif).
+ |
+
| + ADExposureTime | ++ $(P$(R)ExposureTime | ++ In External Enable mode this value is not used by camserver. However, it should + be set larger than the maximum time exposure time from the external source, so that + pilatusROI.st can estimate how long to wait for the data files to be created before + timing out. | +
| + ADNumImages | ++ $(P$(R)NumImages | ++ Controls the number of images to acquire. It applies in all trigger modes except + Alignment. | +
| + ADExposurePeriod | ++ $(P$(R)ExposurePeriod | ++ Controls the exposure period in seconds. It is only in Internal or External Trigger + modes when NumImages > 1. | +
| + ADNumExposures | ++ $(P$(R)NumExposures | ++ Controls the number of exposures per image. It is only used in External Enable mode. | +
| + ADAquire | ++ $(P$(R)Acquire | ++ Controls the acquisition. Setting this to 1 starts image acquisition. The driver + sets the record to 0 when acquisition is complete. This means an entire acquisition + series if NImages > 1. Setting this to 0 aborts an acquisition. If the driver + was currently acquiring imges then this record will cause the "Stop" and "K" (Kill) + commands to be sent to camserver. | +
| + ADFilePath | ++ $(P$(R)FilePath | ++ Controls the path for saving images. It must be a valid path for camserver and + for the areaDetector driver, which is normally running in an EPICS IOC. If camserver + and the EPICS IOC are not running on the same machine then soft links will typically + be used to make the paths look identical. | +
| + ADFileFormat | ++ $(P)$(R)FileFormat | +
+ camserver uses the file extension to determine what format to save the files in.
+ The areaDetector Pilatus driver only supports TIFF files, so the extension should
+ be .tif. When saving multiple images (NImages>1) camserver has its own rules for
+ creating the names of the individual files. The rules are as follows. The name constructed
+ using the algorithm described for ADFileTemplate in
+ areaDetectorDoc.html is used as a basename. The following examples show the
+ interpretation of the basename.
+ Basename Files produced + + test6.tif test6_00000.tif, test6_00001.tif, ... + test6_.tif test6_00000.tif, test6_00001.tif, ... + test6_000.tif test6_000.tif, test6_001.tif, ... + test6_014.tif test6_014.tif, test6_015.tif, ... + test6_0008.tif test6_0008.tif, test6_0009.tif, ... + test6_2_0035.tif test6_2_0035.tif, test6_2_0036.tif, ... ++ The numbers following the last '_' are taken as a format template, and as a start + value. The minimum format is 3; there is no maximum; the default is 5. The format + is also constrained by the requested number of images. |
+
+ It is useful to use NDPluginROI to define an ROI containing the entire Pilatus detector. + This ROI can be monitored to make sure that the 20-bit limit of 1,048,575 is not + being approached in any pixel. +
++ The Pilatus driver implements the following parameters in addition to those in ADStdDriverParams.h: +
+| + Parameter Definitions in pilatusDetector.cpp and EPICS Record Definitions in pilatus.template | +||||||
| + Enum name | ++ asyn interface | ++ Access | ++ Description | ++ drvUser string | ++ EPICS record name | ++ EPICS record type | +
|---|---|---|---|---|---|---|
| + PilatusDelayTime | ++ asynFloat64 | ++ r/w | ++ Delay in seconds between the external trigger and the start of image acquisition. + It only applies in External Trigger mode | ++ DELAY_TIME | ++ $(P)$(R)DelayTime | ++ ao | +
| + PilatusThreshold | ++ asynFloat64 | ++ r/w | ++ Threshold energy in keV | ++ THRESHOLD | ++ $(P)$(R)ThresholdEnergy | ++ ao | +
| + N/A | ++ N/A | ++ r/w | +
+ Gain menu. Controls the value of Vrf, which determines the shaping time and gain
+ of the input amplifiers. The allowed values are:
+
|
+ + N/A | ++ $(P)$(R)GainMenu | ++ mbbo | +
| + PilatusArmed | ++ asynInt32 | ++ r/o | ++ Flag to indicate when the Pilatus is ready to accept external trigger signals (0=not + ready, 1=ready). This should be used by clients to indicate when it is OK to start + sending trigger pulses to the Pilatus. If pulses are send before Armed=1 then the + Pilatus may miss them, leading to DMA timeout errors from camserver | ++ ARMED | ++ $(P)$(R)Armed | ++ bi | +
| + PilatusTiffTimeout | ++ asynFloat64 | ++ r/w | ++ Timeout in seconds when reading a TIFF file. It should be set to several seconds, + because there can be delays for various reasons. One reason is that there is sometimes + a delay between when an External Enable acquisition is started and when the first + external pulse occurs. Another is that it can take some time for camserver processes + to finish writing the files. | ++ TIFF_TIMEOUT | ++ $(P)$(R)ReadTiffTimeout | ++ ao | +
| + PilatusBadPixelFile | ++ asynOctet | ++ r/w | +
+ Name of a file to be used to replace bad pixels. If this record does not point to
+ a valid bad pixel file then no bad pixel mapping is performed. The bad pixel map
+ is used before making the NDArray callbacks. It does not modify the data in the
+ files that camserver writes. This is a simple ASCII file with the following format:
+ badX1,badY1 replacementX1,replacementY1 + badX2,badY2 replacementX2,replacementY2 + ... ++ The X and Y coordinates range from 0 to NXPixels-1 and NYPixels-1. Up to 100 bad + pixels can be defined. The bad pixel mapping simply replaces the bad pixels with + another pixel's value. It does not do any averaging. It is felt that this is sufficient + for the purpose for which pilatusROI was written, namely fast on-line viewing of + ROIs and ImageData. More sophisticated algorithms can be used for offline analysis + of the image files themselves. The following is an example bad pixel file for a + GSECARS detector: + 263,3 262,3 + 264,3 266,3 + 263,3 266,3 + 300,85 299,85 + 300,86 299,86 + 471,129 472,129 ++ |
+ + BAD_PIXEL_FILE | ++ $(P)$(R)BadPixelFile | ++ waveform | +
| + PilatusNumBadPixels | ++ asynInt32 | ++ r/o | ++ The number of bad pixels defined in the bad pixel file. Useful for seeing if the + bad pixel file was read correctly. | ++ NUM_BAD_PIXELS | ++ $(P)$(R)NumBadPixels | ++ longin | +
| + PilatusFlatFieldFile | ++ asynOctet | ++ r/w | +
+ Name of a file to be used to correct for the flat field. If this record does not
+ point to a valid flat field file then no flat field correction is performed. The
+ flat field file is simply a TIFF file collected by the Pilatus that is used to correct
+ for spatial non-uniformity in the response of the detector. It should be collected
+ with a spatially uniform intensity on the detector at roughly the same energy as
+ the measurements being corrected. When the flat field file is read, the average
+ pixel value (averageFlatField) is computed using all pixels with intensities > PilatusMinFlatField.
+ All pixels with intensity < PilatusMinFlatField in the flat field are replaced with
+ averageFlatField. When images are collected before the NDArray callbacks are performed
+ the following per-pixel correction is applied:
+ ImageData[i] = (averageFlatField * ImageData[i])/flatField[i]; ++ |
+ + FLAT_FIELD_FILE | ++ $(P)$(R)FlatFieldFile | ++ waveform | +
| + PilatusMinFlatField | ++ asynInt32 | ++ r/w | ++ The mimimum valid intensity in the flat field. This value must be set > 0 to prevent + divide by 0 errors. If the flat field was collected with some pixels having very + low intensity then this value can be used to replace those pixels with the average + response. | ++ MIN_FLAT_FIELD | ++ $(P)$(R)MinFlatField | ++ longout | +
| + PilatusFlatFieldValid | ++ asynInt32 | ++ r/o | ++ This record indicates if a valid flat field file has been read. 0=No, 1=Yes. | ++ FLAT_FIELD_VALID | ++ $(P)$(R)FlatFieldValid | ++ bi | +
| + N/A | ++ N/A | ++ N/A | +
+ asyn record to control debugging communication with camserver. Setting the CNCT
+ field in this record to Disconnect causes the drvAsynIPPort server
+ to disconnect from camserver. This can be used to allow another program, such as
+ TVX, to temporarily take control of camserver, without restarting the EPICS IOC.
+ Set CNCT to Connect to reconnect the IOC to camserver, or simply process
+ any record which communicates with camserver, because the driver will automatically
+ reconnect. |
+ + N/A | ++ $(P)$(R)CamserverAsyn | ++ asyn | +
+ The Pilatus driver is created with the following command, either from C/C++ or from + the EPICS IOC shell. +
+pilatusDetectorConfig(const char *portName, const char *camserverPort, + int maxSizeX, int maxSizeY, int maxBuffers, size_t maxMemory); ++
| + Argument | ++ Description | +
|---|---|
+ portName |
+ + The name of the asyn port for this detector. + | +
+ camserverPort |
+
+ The name of the asyn TCP/IP port to communicate with camserver. This must have
+ been previously created with drvAsynIPPortConfig(),
+ |
+
+ maxSizeX |
+ + The number of pixels in the X direction on the detector. This is 487 for the Pilatus + 100K. | +
+ maxSizeY |
+ + The number of pixels in the Y direction on the detector. This is 195 for the Pilatus + 100K. | +
+ maxBuffers |
+ + Maximum number of buffers to be created for plugin callbacks. Passed to the constructor + for the ADDriver base class. | +
+ maxMemory |
+ + Maximum number of bytes of memory to be allocated for plugin callbacks. Passed to + the constructor for the ADDriver base class. | +
+ The following is an example st.cmd startup script: +
+< envPaths
+errlogInit(20000)
+
+dbLoadDatabase("$(AREA_DETECTOR)/dbd/pilatusDetectorApp.dbd")
+pilatusDetectorApp_registerRecordDeviceDriver(pdbbase)
+
+###
+# Create the asyn port to talk to the Pilatus on port 41234.
+drvAsynIPPortConfigure("camserver","gse-pilatus2:41234")
+# Set the input and output terminators.
+asynOctetSetInputEos("camserver", 0, "\030")
+asynOctetSetOutputEos("camserver", 0, "\n")
+
+pilatusDetectorConfig("Pil", "camserver", 487, 195, 50, 200000000)
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/ADBase.template", "P=13PIL1:,R=cam1:,PORT=Pil,ADDR=0,TIMEOUT=1")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/pilatus.template","P=13PIL1:,R=cam1:,PORT=Pil,ADDR=0,TIMEOUT=1,CAMSERVER_PORT=camserver")
+
+# Create a standard arrays plugin
+drvNDStdArraysConfigure("PilImage", 5, 0, "Pil", 0, -1)
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDPluginBase.template","P=13PIL1:,R=image1:,PORT=PilImage,ADDR=0,TIMEOUT=1,NDARRAY_PORT=Pil,NDARRAY_ADDR=0")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDStdArrays.template", "P=13PIL1:,R=image1:,PORT=PilImage,ADDR=0,TIMEOUT=1,SIZE=32,FTVL=LONG,NELEMENTS=94965")
+
+# Create an ROI plugin with 8 ROIs
+drvNDROIConfigure("PilROI", 5, 0, "Pil", 0, 8, -1)
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDPluginBase.template","P=13PIL1:,R=ROI1:, PORT=PilROI,ADDR=0,TIMEOUT=1,NDARRAY_PORT=Pil,NDARRAY_ADDR=0")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDROI.template", "P=13PIL1:,R=ROI1:, PORT=PilROI,ADDR=0,TIMEOUT=1")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDROIN.template", "P=13PIL1:,R=ROI1:0:,PORT=PilROI,ADDR=0,TIMEOUT=1,HIST_SIZE=256")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDROIN.template", "P=13PIL1:,R=ROI1:1:,PORT=PilROI,ADDR=1,TIMEOUT=1,HIST_SIZE=256")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDROIN.template", "P=13PIL1:,R=ROI1:2:,PORT=PilROI,ADDR=2,TIMEOUT=1,HIST_SIZE=256")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDROIN.template", "P=13PIL1:,R=ROI1:3:,PORT=PilROI,ADDR=3,TIMEOUT=1,HIST_SIZE=256")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDROIN.template", "P=13PIL1:,R=ROI1:4:,PORT=PilROI,ADDR=3,TIMEOUT=1,HIST_SIZE=256")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDROIN.template", "P=13PIL1:,R=ROI1:5:,PORT=PilROI,ADDR=3,TIMEOUT=1,HIST_SIZE=256")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDROIN.template", "P=13PIL1:,R=ROI1:6:,PORT=PilROI,ADDR=3,TIMEOUT=1,HIST_SIZE=256")
+dbLoadRecords("$(AREA_DETECTOR)/ADApp/Db/NDROIN.template", "P=13PIL1:,R=ROI1:7:,PORT=PilROI,ADDR=3,TIMEOUT=1,HIST_SIZE=256")
+
+# Create "fastSweep" drivers for the MCA record to do on-the-fly scanning of ROI data
+initFastSweep("PilSweepTotal", "PilROI", 8, 2048, "TOTAL_ARRAY", "CALLBACK_PERIOD")
+initFastSweep("PilSweepNet", "PilROI", 8, 2048, "NET_ARRAY", "CALLBACK_PERIOD")
+
+# Load MCA records for the fast sweep drivers
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:0:TotalArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepTotal 0)")
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:1:TotalArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepTotal 1)")
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:2:TotalArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepTotal 2)")
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:3:TotalArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepTotal 3)")
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:4:TotalArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepTotal 4)")
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:5:TotalArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepTotal 5)")
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:6:TotalArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepTotal 6)")
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:7:TotalArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepTotal 7)")
+
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:0:NetArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepNet 0)")
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:1:NetArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepNet 1)")
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:2:NetArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepNet 2)")
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:3:NetArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepNet 3)")
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:4:NetArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepNet 4)")
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:5:NetArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepNet 5)")
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:6:NetArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepNet 6)")
+dbLoadRecords("$(MCA)/mcaApp/Db/mca.db", "P=13PIL1:,M=ROI1:7:NetArray,DTYP=asynMCA,NCHAN=2048,INP=@asyn(PilSweepNet 7)")
+
+
+#asynSetTraceMask("Pil",0,255)
+#asynSetTraceMask("PilROI",0,3)
+#asynSetTraceIOMask("PilROI",0,4)
+
+# Load scan records for scanning energy threshold
+dbLoadRecords("$(SSCAN)/sscanApp/Db/scan.db", "P=13PIL1:cam1:,MAXPTS1=2000,MAXPTS2=200,MAXPTS3=20,MAXPTS4=10,MAXPTSH=10")
+
+set_requestfile_path("./")
+set_savefile_path("./autosave")
+set_requestfile_path("$(AREA_DETECTOR)/ADApp/Db")
+set_requestfile_path("$(SSCAN)/sscanApp/Db")
+set_pass0_restoreFile("auto_settings.sav")
+set_pass1_restoreFile("auto_settings.sav")
+save_restoreSet_status_prefix("13PIL1:")
+dbLoadRecords("$(AUTOSAVE)/asApp/Db/save_restoreStatus.db", "P=13PIL1:")
+
+iocInit()
+
+# save things every thirty seconds
+create_monitor_set("auto_settings.req", 30,"P=13PIL1:,D=cam1:")
+
+
+ + The following show the MEDM screens that are used to control the Pilatus debtector. + Note that the general purpose screen ADBase.adl can be used, but it exposes many + controls that are not applicable to the Pilatus.
+
+ pilatusDetector.adl is the main screen used to control the pilatusROI
+ SNL program. All records except those for ROIs are accessed through this screen.
+
+ NDROI8.adl is used to define the ROIs, and to display the statistics
+ for each ROI. In this example there are 3 valid ROIs defined. ROI 0 is the entire
+ detector. ROI 1 is a 100x50 rectangle starting at [300,60], and ROI 2 is a
+ 50x30 rectangle starting at [320,70]..
+ mca.adl can be used to plot the net or total counts in an ROI when
+ NImages>1. In this example the plot is the net counts in ROI 1 as the diffractometer
+ chi was scanned +- 1 degree with 1000 points at .02 seconds/point. This was done
+ with the SPEC command
+
lup chi -1 1 1000 .02 ++
+ using trajectory scanning on a Newport kappa diffractometer. This was a compound + motor scan with the Newport XPS putting out pulses every .02 seconds. These pulses + triggered the Pilatus in External Enable mode. The Pilatus driver read each + TIFF file as it was created and updated this plot every 0.2 seconds. The total time + to collect this scan with 1000 images was 20 seconds.
+
+
+ scan_more.adl is used to define a scan. In this example the sscan record
+ is set up to scan the ThresholdEnergy PV and to collect the total counts in ROI2,
+ which was defined to include the entire detector.
+ scanDetPlot.adl is used to plot the results of a scan after it is complete.
+ In this example the total counts in ROI 2 are plotted as a function of the ThresholdEnergy
+ as it was scanned from 3000 to 10000 eV in 250 eV steps. The source was Fe55, and
+ the cut-off is at 6 keV, as expected for the Mn Ka and Mn Kb x-rays that this source
+ produces.
+ asynRecord.adl is used to control the debugging information printed
+ by the asyn TCP/IP driver (asynTraceIODriver) and the SNL program (asynTraceIODevice).
+ asynOctet.adl can be used to send any command to camserver and display
+ the response. It can be loaded from the More menu in asynRecord.adl above.
+ At the GSECARS beamlines (13-ID-C and 13-BM-C) at the APS we use SPEC to control + our Newport diffractometers. We have added and modified SPEC macros to use the pilatusDetector + areaDetector driver to treat the Pilatus detector as a SPEC counter. This works in both traditional + step-scanning mode, as well as in + trajectory scanning mode. Here are some snippets from the SPEC macros for + the Pilatus. We can supply the source files on request.
+# need some more globals (kludge)
+global PILATUS_ROI_PV
+global PILATUS_imgPATH_PV
+global PILATUS_FNAME_PV
+global PILATUS_FILENUMBER_PV
+global PILATUS_FILEFORMAT_PV
+global PILATUS_EXPSRTM_PV
+global PILATUS_NFRAME_PV
+global PILATUS_EXPPRD_PV
+global PILATUS_NEXPFRM_PV
+global PILATUS_ACQ_PV
+global PILATUS_ACQMODE_PV
+
+###############################################################
+def _setup_img '{
+ local j, str
+
+ # PILATUS_PREFIX should be detector aquisition pv (GSE-PILATUS1:)
+ if ( PILATUS_PREFIX == "") PILATUS_PREFIX = "GSE-PILATUS1:"
+ PILATUS_PREFIX = getval("Enter PILATUS pv prefix",PILATUS_PREFIX)
+
+ # rois pvs
+ PILATUS_ROI_PV = PILATUS_PREFIX "ROI1NetCounts"
+ PILATUS_imgPATH_PV = PILATUS_PREFIX "FilePath"
+ PILATUS_FNAME_PV = PILATUS_PREFIX "Filename"
+ PILATUS_FILENUMBER_PV = PILATUS_PREFIX "FileNumber"
+ PILATUS_FILEFORMAT_PV = PILATUS_PREFIX "FileFormat"
+ PILATUS_EXPSRTM_PV = PILATUS_PREFIX "ExposureTime"
+ PILATUS_NFRAME_PV = PILATUS_PREFIX "NImages"
+ PILATUS_EXPPRD_PV = PILATUS_PREFIX "ExposurePeriod"
+ PILATUS_NEXPFRM_PV = PILATUS_PREFIX "NExposures"
+ PILATUS_ACQ_PV = PILATUS_PREFIX "Acquire"
+ PILATUS_ACQMODE_PV = PILATUS_PREFIX "AcquireMode"
+...
+
+def epics_pilatus_count '{
+...
+ # write to data base fields
+ # Need to convert path from string to byte array
+ # Note: we use the "wait" parameter in epics_put here (new to spec5.7.02) so that
+ # it uses ca_put_callback, to know that all PVs have been processed
+ # before we start counting. Use 1 second timeout, will actually be
+ # much faster than this unless something is wrong.
+ array _temp[256]
+ _temp = PILATUS_IMAGE_DIR
+ # Do not change path for now
+ #epics_put(PILATUS_imgPATH_PV,_temp, 1)
+ epics_put(PILATUS_FNAME_PV,img_fname, 1)
+ epics_put(PILATUS_FILENUMBER_PV,NPTS, 1)
+ epics_put(PILATUS_FILEFORMAT_PV,_fileformat, 1)
+ epics_put(sc_prtm_pv,cnt_time_val, 1)
+ epics_put(PILATUS_EXPSRTM_PV,cnt_time_val, 1)
+ epics_put(PILATUS_ACQMODE_PV,0, 1) # Internal trigger
+ epics_put(PILATUS_NFRAME_PV, 1, 1)
+ epics_put(PILATUS_NEXPFRM_PV, 1, 1)
+
+
+def user_getcounts '{
+ local pv_roi, j, pv
+
+...
+ # using image_count routine
+ } else if ( EPICS_COUNT == 4 ) {
+ S[iroi] = 0
+ S[iroi] = epics_get(PILATUS_ROI_PV)
+
+ + The following measurements were done to demonstrate the performance that can be + obtained with pilatusROI.
+lup chi -2 2 1000 .015 ++ This tells SPEC to do a relative scan of the chi axis from -2 degrees to +2 degrees + with 1000 points at .015 seconds/point. On our kappa diffractometer this entails + a coordinated motion of the phi, kappa and omega axes. The EPICS trajectory scanning + software downloads the non-linear trajectory that SPEC computes into the XPS controller, + which executes it. As the motors are moving the XPS outputs synchronization pulses + at the period of the collection time, .015 seconds in this case. These pulses are + stretched (see Hardware notes below) and used as the + external input to the Pilatus. The time to execute this scan should be 15.0 seconds. + The actual time was 16.3 seconds, measured using camonitor on the Acquire PV. Again, + this includes the time for camserver to save all 1000 images to disk (366 MB), and + for pilatusROI to read each file, correct the bad pixels and flat field, compute + the ROIs, and post the ROIs to EPICS. It also posted the images to EPICS at 1Hz + (15 images total). The total additional time was less than 1.3 seconds for all 1000 + images. As soon as the acquisition was complete SPEC plotted the net counts in the + first ROI (containing the Bragg peak) as follows: +
+
+ For comparison this identical scan was executed in traditional step-scanning mode, + where the motors stopped at each point in the scan. The Pilatus was run in Internal + mode with NImages=1. The total time for the scan was 870 seconds (more than 14 minutes), + compared to 16.3 seconds in trajectory mode. Most of this overhead is the settling + time for the motors, with only a small fraction due to the Pilatus single-exposure + mode. The trajectory scanning mode is thus more than 50 times faster to execute + the identical SPEC scan.+ The Pilatus supports 3 types of external triggering. In External Trigger mode (the + camserver ExtTrigger command) the Pilatus uses the programmed values of ExposureTime, + ExposurePeriod, NImages and NExposures. It waits for a single external trigger, + then waits for Delay seconds and then collects the entire sequence. It is very similar + to Internal mode with NImages>1, except that it waits for a trigger to begin collecting + the sequence.
++ In External Enable mode (the camserver ExtEnable command) the Pilatus uses the external + signal to control acquisition. Only NImages and NExposures are used, ExposureTime + and ExposurePeriod are not used. When the signal is high the detector counts, and + on the transition to low it begins its readout.
++ In External MultiTrigger Mode (the camserver ExtMTrigger command) the Pilatus uses + the programmed ExposureTime, in addition to NImages and NExposures. Each external + trigger pulse causes the Pilatus to collect one image at the programmed exposure + time. This mode works well with a trigger source like the Newport motor controllers + or the SIS380x multichannel scaler, that put out a short trigger pulse for each + image. One only needs to take care that the time between external trigger pulses + is at least 4msec longer than the programmed exposure time, to allow time for the + detector to read out before the next trigger pulse arrives.
++ When using the External Enable mode, we use an inexpensive analog pulse generator + to convert the trigger pulses from the MM4005 and XPS to a form suitable for External + Enable mode with the Pilatus. This is the solution we have developed that seems + to be reliable:
+The Tenma TGP110 seems to be currently called a Tenma 72-6860, and lists for about + $350 new at Newark. +
++ When we were initially testing the Pilatus in the lab, we had many errors in External + Enable mode, where it did not seem to be seeing the external pulses. camserver would + get DMA timeouts, and need to be restarted. Dectris said these were happening because + the cables on our detector are longer than normal, and the voltage drop from the + power supply to the detector was leading to marginal voltage values. They suggested + shortening the cables or increasing the supply voltage slightly. When moving the + detector to the hutch these problems initially went away. However, they then recurred, + and we fixed the problem by increasing the power supply voltage from 4.4 to 4.7 + volts at the detector.
++ Dectris has since informed me that they have increased the power supply voltage + on all new Pilatus systems, so this should no longer be an issue.
++ The following are some current restrictions of the pilatusROI SNL program:
+- -
-
-
-class NDPluginDriver : public asynNDArrayDriver {
+
+
+ areaDetector Plugins
+
+
+
+
+ areaDetector Plugins
+
+ September 5, 2008
+
+ Mark Rivers
+
+ University of Chicago
+
+
+
+
+ Contents
+
+ + A powerful feature of the areaDetector module + is the concept of plugins. A plugin is code that is called by a driver that passes + NDArray data in a callback. Plugins can be used to process array data in real time. + Existing plugins convert data to standard asyn arrays (NDPluginStdArrays) save data + to disk (NDPluginFile), and select regions-of-interest (NDPluginROI). New plugins + could be written to perform functions like finding the centroid of a beam, etc. + Once a plugin is written it will work with any areaDetector driver. Plugins have + the the following properties: +
++ NDPluginDriver inherits from asynNDArrayDriver. + NDPluginDriver is the class from which actual plugins are directly derived. The + NDPluginDriver class handles most of the details of processing NDArray callbacks + from the driver. Plugins derived from this class typically need to implement the + processCallbacks method, the drvUser method, and one or more of the write(Int32, Float64, Octet) methods. The NDPluginDriver + public interface is defined in NDPluginDriver.h as follows: +
+class NDPluginDriver : public asynNDArrayDriver {
public:
NDPluginDriver(const char *portName, int queueSize, int blockingCallbacks,
const char *NDArrayPort, int NDArrayAddr, int maxAddr, int paramTableSize,
@@ -98,218 +113,353 @@ public:
int createFileName(int maxChars, char *fullFileName);
...
}
-
-The methods of the NDPluginDriver class are:
-NDPluginDriver This is the constructor for the class. All parameters except queueSize,
- blockingCallbacks, NDArrayPort, and NDArrayAddr
- are just passed to the constructor for asynNDArrayDriver. NDArrayPort and NDArrayAddr, and blockingCallbacks
- are the initial values
- for the NDPluginDriverArrayPort, NDPluginDriverArrayAddr and NDPluginDriverBlockingCallbacks
- parameters described in the table below.
- drvUserCreate This method returns one of the enum values for the parameters defined in
- NDPluginDriver.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
- plugin. If a parameter is not matched, then NDPluginDriver->drvUserCreate() will be called to see if it
- is a standard plugin parameter (defined in NDPluginDriver.h).
- processCallbacks This method is called each time a driver calls the plugin with a new NDArray object.
- Derived classes typically call this base class method, which handles some bookkeeping chores, and then they perform
- whatever operations are specific to that plugin.
- createFileName This is a convenience function that constructs a complete file name in
- the ADFullFileName parameter from the
- ADFilePath, ADFileName, ADFileNumber, and ADFileTemplate parameters.
--
| Parameter Definitions in NDPluginDriver.h and EPICS Record Definitions in NDPluginBase.template | -||||||
| Enum name | -asyn interface | -Access | -Description | -drvUser string | -EPICS record name | -EPICS record type | -
|---|---|---|---|---|---|---|
| asyn NDArray driver doing callbacks | -||||||
| NDPluginDriverArrayPort | -asynOctet | -r/w | -asyn port name for NDArray driver that will make callbacks to this plugin. - This port can be changed at run time, connecting the plugin to a different NDArray driver. | -NDARRAY_PORT | -$(P)$(R)NDArrayPort (P)$(R)NDArrayPort_RBV |
- stringout stringin |
-
| NDPluginDriverArrayAddr | -asynInt32 | -r/w | -asyn port address for NDArray driver that will make callbacks to this plugin. - This address can be changed at run time, connecting the plugin to a different address in the NDArray driver. | -NDARRAY_ADDR | -$(P)$(R)NDArrayAddress (P)$(R)NDArrayAddress_RBV |
- longout longin |
-
| Callback enable, minimum time, and statistics | -||||||
| NDPluginDriverEnableCallbacks | -asynInt32 | -r/w | -Enable (1) or disable (0) callbacks from the driver to this plugin. If callbacks are disabled then the plugin - will normally be idle and consume no CPU resources. | -ENABLE_CALLBACKS | -$(P)$(R)EnableCallbacks (P)$(R)EnableCallbacks_RBV |
- bo bi |
-
| NDPluginDriverMinCallbackTime | -asynFloat64 | -r/w | -The minimum time in seconds between calls to processCallbacks. Any callbacks occuring before this minimum - time has elapsed will be ignored. 0 means no minimum time, i.e. process all callbacks. | -MIN_CALLBACK_TIME | -$(P)$(R)MinCallbackTime (P)$(R)MinCallbackTime_RBV |
- ao ai |
-
| NDPluginDriverArrayCounter | -asynInt32 | -r/w | -Counter that increments by 1 each time an NDArray callback is processed | -ARRAY_COUNTER | -$(P)$(R)ArrayCounter (P)$(R)ArrayCounter_RBV |
- longout longin |
-
| N/A | -N/A | -r/o | -Rate (Hz) at which ArrayCounter is incrementing. Computed in database. | -N/A | -$(P)$(R)ArrayRate_RBV | -calc | -
| NDPluginDriverDroppedArrays | -asynInt32 | -r/w | -Counter that increments by 1 each time an NDArray callback occurs when NDPluginDriverBlockingCallbacks=0 - and the plugin driver queue is full, so the callback cannot be processed. | -DROPPED_ARRAYS | -$(P)$(R)DroppedArrays (P)$(R)DroppedArrays_RBV |
- longout longin |
-
| Information about last NDArray callback data | -||||||
| NDPluginDriverNDimensions | -asynInt32 | -r/o | -Number of dimensions in last NDArray callback data | -ARRAY_NDIMENSIONS | -$(P)$(R)NDimensions_RBV | -longin | -
| NDPluginDriverDimensions | -asynInt32Array | -r/o | -Dimensions in last NDArray callback data | -ARRAY_DIMENSIONS | -$(P)$(R)Dimensions_RBV | -waveform | -
| N/A | -N/A | -r/o | -First dimension of NDArray callback data | -N/A | -$(P)$(R)ArraySize0_RBV | -longin | -
| N/A | -N/A | -r/o | -Second dimension of NDArray callback data | -N/A | -$(P)$(R)ArraySize1_RBV | -longin | -
| NDPluginDriverDataType | -asynInt32 | -r/o | -Data type of last NDArray callback data (NDDataType_t). | -DATA_TYPE | -$(P)$(R)DataType_RBV | -mbbi | -
| NDPluginDriverUniqueId | -asynInt32 | -r/o | -Unique ID number of last NDArray callback data | -UNIQUE_ID | -$(P)$(R)UniqueId_RBV | -longin | -
| NDPluginDriverTimeStamp | -asynFloat64 | -r/o | -Time stamp number of last NDArray callback data | -TIME_STAMP | -$(P)$(R)TimeStamp_RBV | -ai | -
| Debugging control | -||||||
| N/A | -N/A | -N/A | -asyn record to control debugging (asynTrace) | -N/A | -$(P)$(R)AsynIO | -asyn | -
-
-class NDPluginStdArrays : public NDPluginDriver {
+
+ + The methods of the NDPluginDriver class are: +
+NDPluginDriver This is the constructor for the class. All parameters
+ except queueSize, blockingCallbacks, NDArrayPort, and NDArrayAddr are just passed
+ to the constructor for asynNDArrayDriver. NDArrayPort and NDArrayAddr, and blockingCallbacks
+ are the initial values for the NDPluginDriverArrayPort, NDPluginDriverArrayAddr
+ and NDPluginDriverBlockingCallbacks parameters described in the table below.drvUserCreate This method returns one of the enum values for the
+ parameters defined in NDPluginDriver.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 plugin. If
+ a parameter is not matched, then NDPluginDriver->drvUserCreate() will be called
+ to see if it is a standard plugin parameter (defined in NDPluginDriver.h).processCallbacks This method is called each time a driver calls the
+ plugin with a new NDArray object. Derived classes typically call this base class
+ method, which handles some bookkeeping chores, and then they perform whatever operations
+ are specific to that plugin.createFileName This is a convenience function that constructs a complete
+ file name in the ADFullFileName parameter from the ADFilePath, ADFileName, ADFileNumber,
+ and ADFileTemplate parameters.+ NDPluginDriver defines parameters that all plugin drivers should implement if possible. + These parameters are defined by enum values with an associated asyn interface, and + access (read-only or read-write). The EPICS database NDPluginBase.template provides + access to these standard plugin parameters, listed in the following table. +
+| + Parameter Definitions in NDPluginDriver.h and EPICS Record Definitions in NDPluginBase.template | +||||||
| + Enum name | ++ asyn interface | ++ Access | ++ Description | ++ drvUser string | ++ EPICS record name | ++ EPICS record type | +
|---|---|---|---|---|---|---|
| + asyn NDArray driver doing callbacks | +||||||
| + NDPluginDriverArrayPort | ++ asynOctet | ++ r/w | ++ asyn port name for NDArray driver that will make callbacks to this plugin. This + port can be changed at run time, connecting the plugin to a different NDArray driver. | ++ NDARRAY_PORT | +
+ $(P)$(R)NDArrayPort + (P)$(R)NDArrayPort_RBV |
+
+ stringout + stringin |
+
| + NDPluginDriverArrayAddr | ++ asynInt32 | ++ r/w | ++ asyn port address for NDArray driver that will make callbacks to this plugin. This + address can be changed at run time, connecting the plugin to a different address + in the NDArray driver. | ++ NDARRAY_ADDR | +
+ $(P)$(R)NDArrayAddress + (P)$(R)NDArrayAddress_RBV |
+
+ longout + longin |
+
| + Callback enable, minimum time, and statistics | +||||||
| + NDPluginDriverEnableCallbacks | ++ asynInt32 | ++ r/w | ++ Enable (1) or disable (0) callbacks from the driver to this plugin. If callbacks + are disabled then the plugin will normally be idle and consume no CPU resources. | ++ ENABLE_CALLBACKS | +
+ $(P)$(R)EnableCallbacks + (P)$(R)EnableCallbacks_RBV |
+
+ bo + bi |
+
| + NDPluginDriverMinCallbackTime | ++ asynFloat64 | ++ r/w | ++ The minimum time in seconds between calls to processCallbacks. Any callbacks occuring + before this minimum time has elapsed will be ignored. 0 means no minimum time, i.e. + process all callbacks. | ++ MIN_CALLBACK_TIME | +
+ $(P)$(R)MinCallbackTime + (P)$(R)MinCallbackTime_RBV |
+
+ ao + ai |
+
| + NDPluginDriverArrayCounter | ++ asynInt32 | ++ r/w | ++ Counter that increments by 1 each time an NDArray callback is processed | ++ ARRAY_COUNTER | +
+ $(P)$(R)ArrayCounter + (P)$(R)ArrayCounter_RBV |
+
+ longout + longin |
+
| + N/A | ++ N/A | ++ r/o | ++ Rate (Hz) at which ArrayCounter is incrementing. Computed in database. | ++ N/A | ++ $(P)$(R)ArrayRate_RBV | ++ calc | +
| + NDPluginDriverDroppedArrays | ++ asynInt32 | ++ r/w | ++ Counter that increments by 1 each time an NDArray callback occurs when NDPluginDriverBlockingCallbacks=0 + and the plugin driver queue is full, so the callback cannot be processed. | ++ DROPPED_ARRAYS | +
+ $(P)$(R)DroppedArrays + (P)$(R)DroppedArrays_RBV |
+
+ longout + longin |
+
| + Information about last NDArray callback data | +||||||
| + NDPluginDriverNDimensions | ++ asynInt32 | ++ r/o | ++ Number of dimensions in last NDArray callback data | ++ ARRAY_NDIMENSIONS | ++ $(P)$(R)NDimensions_RBV | ++ longin | +
| + NDPluginDriverDimensions | ++ asynInt32Array | ++ r/o | ++ Dimensions in last NDArray callback data | ++ ARRAY_DIMENSIONS | ++ $(P)$(R)Dimensions_RBV | ++ waveform | +
| + N/A | ++ N/A | ++ r/o | ++ First dimension of NDArray callback data | ++ N/A | ++ $(P)$(R)ArraySize0_RBV | ++ longin | +
| + N/A | ++ N/A | ++ r/o | ++ Second dimension of NDArray callback data | ++ N/A | ++ $(P)$(R)ArraySize1_RBV | ++ longin | +
| + NDPluginDriverDataType | ++ asynInt32 | ++ r/o | ++ Data type of last NDArray callback data (NDDataType_t). | ++ DATA_TYPE | ++ $(P)$(R)DataType_RBV | ++ mbbi | +
| + NDPluginDriverUniqueId | ++ asynInt32 | ++ r/o | ++ Unique ID number of last NDArray callback data | ++ UNIQUE_ID | ++ $(P)$(R)UniqueId_RBV | ++ longin | +
| + NDPluginDriverTimeStamp | ++ asynFloat64 | ++ r/o | ++ Time stamp number of last NDArray callback data | ++ TIME_STAMP | ++ $(P)$(R)TimeStamp_RBV | ++ ai | +
| + Debugging control | +||||||
| + N/A | ++ N/A | ++ N/A | ++ asyn record to control debugging (asynTrace) | ++ N/A | ++ $(P)$(R)AsynIO | ++ asyn | +
+ NDPluginStdArrays inherits from NDPluginDriver. NDPluginStdArrays converts the NDArray + data from a callback into the 1-dimensional arrays supported by the standard asyn + array interfaces, i.e. asyn[Int8, Int16, Int32, Float32, Float64]Array. These interfaces + are supported by the EPICS waveform record using standard asyn device support. This + plugin is thus the tool for converting the NDArray data produced by asynNDArrayDriver + drivers into a form that can be accessed by EPICS. Because this plugin inherits + from NDPluginDriver it also provides additional information on the array data (e.g. + number of dimensions and dimension data described above) that are made available + as EPICS PVs so that clients can correctly interpret the array data. The NDPluginStdArrays + public interface is defined in NDPluginStdArrays.h as follows:
+class NDPluginStdArrays : public NDPluginDriver {
public:
NDPluginStdArrays(const char *portName, int queueSize, int blockingCallbacks,
const char *NDArrayPort, int NDArrayAddr,
@@ -331,73 +481,200 @@ public:
const char **pptypeName, size_t *psize);
...
}
-
-NDPluginStdArrays defines the following parameters. It also implements all of the standard plugin parameters from NDPlugDriver
-listed above. The EPICS database
-NDStdArrays.template provides access to these parameters, listed in the following table.
--
| Parameter Definitions in NDPluginStdArrays.h and EPICS Record Definitions in NDStdArrays.template | -||||||
| Enum name | -asyn interface | -Access | -Description | -drvUser string | -EPICS record name | -EPICS record type | -
|---|---|---|---|---|---|---|
| NDPluginStdArraysData | -asyn[Int8, Int16, Int32, Float32, Float64]Array | -r/o | -Array data as a 1-D array, possibly converted in data type from that in the NDArray object to the specific asyn interface. | -STD_ARRAY_DATA | -$(P)$(R)ArrayData | -waveform | -
-The following is the MEDM screen that provides access to the parameters in NDPluginDriver.h and NDPluginStdArrays.h through -records in NDPluginBase.template and NDStdArrays.template. This is the MEDM screen that is normally used to control the -display of images via EPICS channel access. -
-
-
-The NDArray callback data can be written to disk in 1 of 3 modes: -
- -/* Note that the file format enum must agree with the mbbo/mbbi records in the NDFile.template file */ ++
+ NDPluginStdArrays defines the following parameters. It also implements all of the + standard plugin parameters from NDPlugDriver listed above. The EPICS database NDStdArrays.template + provides access to these parameters, listed in the following table. +
+| + Parameter Definitions in NDPluginStdArrays.h and EPICS Record Definitions in NDStdArrays.template | +||||||
| + Enum name | ++ asyn interface | ++ Access | ++ Description | ++ drvUser string | ++ EPICS record name | ++ EPICS record type | +
|---|---|---|---|---|---|---|
| + NDPluginStdArraysData | ++ asyn[Int8, Int16, Int32, Float32, Float64]Array | ++ r/o | ++ Array data as a 1-D array, possibly converted in data type from that in the NDArray + object to the specific asyn interface. | ++ STD_ARRAY_DATA | ++ $(P)$(R)ArrayData | ++ waveform | +
+ If the array data contains more than 16,000 bytes then in order for EPICS clients + to receive this data they must be built with EPICS R3.14 (not R3.13), and the environment + variable EPICS_CA_MAX_ARRAY_BYTES on both the EPICS IOC computer and EPICS client + computer must be set to a value at least as large as the array size in bytes.
++ The following is the MEDM screen that provides access to the parameters in NDPluginDriver.h + and NDPluginStdArrays.h through records in NDPluginBase.template and NDStdArrays.template. + This is the MEDM screen that is normally used to control the display of images via + EPICS channel access. +
+
+ + The NDPluginStdArrays plugin is created with the following command, either from + C/C++ or from the EPICS IOC shell. +
+drvNDStdArraysConfigure(const char *portName, int queueSize, int blockingCallbacks, + const char *NDArrayPort, int NDArrayAddr, size_t maxMemory) ++
| + Argument | ++ Description | +
|---|---|
+ portName |
+ + The name of the asyn port for this plugin. + | +
+ queueSize |
+ + The maximum number of NDArray objects that can be queued for processing. Passed + to the NDPluginDriver base class constructor. + | +
+ blockingCallbacks |
+ + Flag controlling whether callbacks block. Passed to the NDPluginDriver base class + constructor. + | +
+ NDArrayPort |
+ + The name of the asyn port of the driver that will provide the NDArray data. Passed + to the NDPluginDriver base class constructor. + | +
+ NDArrayAddr |
+ + The asyn addr of the asyn port of the driver that will provide the NDArray data. + Passed to the NDPluginDriver base class constructor. + | +
+ maxMemory |
+ + Maximum number of bytes of memory to be allocated from the NDArrayPool. Passed to + the constructor for the NDPluginDriver base class. The NDStdArrays plugin allocates + 2 NDArray objects, so this should be at least twice the size of the largest NDArray + to be used. | +
+ There is an IDL program called epics_ad_display that can be used to
+ display 2-dimensional ArrayData that the NDStdArrays plugin sends to EPICS. This
+ IDL client is available as source code (which requires an IDL license), and also
+ as a pre-built IDL .sav file that can be run for free under the IDL Virtual Machine.
+ This IDL program can run on any machine that IDL runs on, and that has the ezcaIDL
+ shareable library built for it. This includes Windows, Linux, Solaris, and Mac.
+ epics_ad_display is included in the
+ CARS IDL imaging software.
+
+ The control window for epics_ad_display is shown below. It has fields
+ to input the base name of the EPICS PVs with the image data. The client uses the
+
+ epics_ad_display uses the routine
+ image_display.pro to display the images. This routine displays row and column
+ profiles as the cursor is moved. It allows changing the color lookup tables, and
+ zooming in and out with the left and right mouse buttons. The following is an example
+ of image_display displaying a Pilatus image with an Fe55 source in
+ front of the detector.
+ NDPluginFile inherits from NDPluginDriver. NDPluginFile saves the NDArray data from + a callback to a disk file. This plugin currently saves data in the + netCDF file format, which is a portable self-describing binary file format + supported by UniData at + UCAR (University Corporation for Atmospheric Research). Additional file formats, + such as TIFF and HDF may be supported in the future. +
++ The NDArray callback data can be written to disk in 1 of 3 modes: +
++ The NDPluginFile public interface is defined in NDPluginFile.h as follows: +
+/* Note that the file format enum must agree with the mbbo/mbbi records in the NDFile.template file */
typedef enum {
NDFileFormatNetCDF,
} NDPluginFileFormat_t;
@@ -423,41 +700,116 @@ public:
...
}
-
-NDPluginFile also supports all of the file saving parameters defined in ADStdDriverParams.h described above, e.g.ADFilePath, ADFileName, etc. -Thus, the same interface that is used for saving files directly in a driver are used for this plugin. -
-The following is the MEDM screen that provides access to the parameters in NDPluginDriver.h and NDPluginFile.h through -records in NDPluginBase.template and NDFile.template. This is the MEDM screen that is used to control the -saving of images to disk for drivers that do not support saving files to disk themselves. -
-
-Each NDPluginROI can handle any number of ROIs. The maximum number of ROIs that the plugin can support is defined when -the plugin is created. 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 definition of the ROI is currently limited to 2-D. This limitation will -be removed in a future release. -
-The NDPluginROI public interface is defined in NDPluginROI.h as follows: -
-
-class NDPluginROI : public NDPluginDriver {
+
+ + NDPluginFile also supports all of the file saving parameters defined in ADStdDriverParams.h + described above, e.g.ADFilePath, ADFileName, etc. Thus, the same interface that + is used for saving files directly in a driver are used for this plugin. +
++ The following is the MEDM screen that provides access to the parameters in NDPluginDriver.h + and NDPluginFile.h through records in NDPluginBase.template and NDFile.template. + This is the MEDM screen that is used to control the saving of images to disk for + drivers that do not support saving files to disk themselves. +
+
+ + The NDPluginFile plugin is created with the following command, either from C/C++ + or from the EPICS IOC shell. +
+drvNDFileConfigure(const char *portName, int queueSize, int blockingCallbacks, + const char *NDArrayPort, int NDArrayAddr) ++
| + Argument | ++ Description | +
|---|---|
+ portName |
+ + The name of the asyn port for this plugin. + | +
+ queueSize |
+ + The maximum number of NDArray objects that can be queued for processing. Passed + to the NDPluginDriver base class constructor. + | +
+ blockingCallbacks |
+ + Flag controlling whether callbacks block. Passed to the NDPluginDriver base class + constructor. + | +
+ NDArrayPort |
+ + The name of the asyn port of the driver that will provide the NDArray data. Passed + to the NDPluginDriver base class constructor. + | +
+ NDArrayAddr |
+ + The asyn addr of the asyn port of the driver that will provide the NDArray data. + Passed to the NDPluginDriver base class constructor. + | +
+ + NDPluginROI inherits from NDPluginDriver. 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 does 3 things with these ROIs: +
++ Each NDPluginROI can handle any number of ROIs. The maximum number of ROIs that + the plugin can support is defined when the plugin is created. 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 definition of the ROI + is currently limited to 2-D. This limitation will be removed in a future release. +
++ The NDPluginROI public interface is defined in NDPluginROI.h as follows: +
+class NDPluginROI : public NDPluginDriver {
public:
NDPluginROI(const char *portName, int queueSize, int blockingCallbacks,
const char *NDArrayPort, int NDArrayAddr, int maxROIs, size_t maxMemory);
@@ -471,338 +823,681 @@ public:
asynStatus readFloat64Array(asynUser *pasynUser, epicsFloat64 *value,
size_t nelements, size_t *nIn);
-
--The readFloat64Array method is used to read the histogram data for the ROI. -
-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 NDPlugDriver -listed above. The EPICS database -NDROI.template provide access to these parameters, listed in the following table. -
-
| Parameter Definitions in NDPluginROI.h and EPICS Record Definitions in NDROI.template | -||||||
| Enum name | -asyn interface | -Access | -Description | -drvUser string | -EPICS record name | -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 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. -
-
| 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 | -
|---|---|---|---|---|---|---|
| NDPluginROIName | -asynOctet | -r/w | -Name of this ROI | -NAME | -$(P)$(R)Name $(P)$(R)Name_RBV |
- stringout stringin |
-
| NDPluginROIUse | -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 | -||||||
| NDPluginROIDim0Bin | -asynInt32 | -r/w | -Binning in the X direction | -DIM0_BIN | -$(P)$(R)BinX $(P)$(R)BinX_RBV |
- longout longin |
-
| NDPluginROIDim1Bin | -asynInt32 | -r/w | -Binning in the Y direction | -DIM1_BIN | -$(P)$(R)BinY $(P)$(R)BinY_RBV |
- longout longin |
-
| NDPluginROIDim0Min | -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 |
-
| NDPluginROIDim1Min | -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 |
-
| NDPluginROIDim0Size | -asynInt32 | -r/w | -Size of the ROI in the X direction | -DIM0_SIZE | -$(P)$(R)SizeX $(P)$(R)SizeX_RBV |
- longout longin |
-
| NDPluginROIDim0Size | -asynInt32 | -r/w | -Size of ROI in the Y direction | -DIM1_SIZE | -$(P)$(R)SizeY $(P)$(R)SizeY_RBV |
- longout longin |
-
| NDPluginROIDim0Reverse | -asynInt32 | -r/w | -Reverse ROI in the X direction (0=No, 1=Yes) |
- DIM0_REVERSE | -$(P)$(R)ReverseX $(P)$(R)ReverseX_RBV |
- longout longin |
-
| NDPluginROIDim0Reverse | -asynInt32 | -r/w | -Reverse ROI in the Y direction (0=No, 1=Yes) |
- DIM1_REVERSE | -$(P)$(R)ReverseY $(P)$(R)ReverseY_RBV |
- longout longin |
-
| NDPluginROIDataType | -asynInt32 | -r/w | -Data type of the ROI (NDDataType_t). This can be different from the data type of the NDArray callback data. | -DATA_TYPE | -$(P)$(R)DataType $(P)$(R)DataType_RBV |
- mbbo mbbi |
-
| NDPluginROIBgdWidth | -asynInt32 | -r/w | -Width of the background in pixels to use when computing net counts. 0=no background subtraction. | -BGD_WIDTH | -$(P)$(R)BgdWidth $(P)$(R)BgdWidth_RBV |
- longout longin |
-
| ADImageSizeX | -asynInt32 | -r/o | -Size of the ROI data in the X direction | -IMAGE_SIZE_X | -$(P)$(R)ImageSizeX_RBV | -longin | -
| ADImageSizeY | -asynInt32 | -r/o | -Size of the ROI data in the Y direction | -IMAGE_SIZE_Y | -$(P)$(R)ImageSizeY_RBV | -longin | -
| ROI statistics | -||||||
| NDPluginROIComputeStatistics | -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 |
-
| NDPluginROIMinValue | -asynFloat64 | -r/o | -Minimum value in any element in the ROI | -MIN_VALUE | -$(P)$(R)MinValue_RBV | -ai | -
| NDPluginROIMaxValue | -asynFloat64 | -r/o | -Maximum value in any element in the ROI | -MAX_VALUE | -$(P)$(R)MaxValue_RBV | -ai | -
| NDPluginROIMeanValue | -asynFloat64 | -r/o | -Mean value in the ROI | -MEAN_VALUE | -$(P)$(R)MeanValue_RBV | -ai | -
| NDPluginROITotal | -asynFloat64 | -r/o | -Sum (total) of all elements in the ROI | -TOTAL | -$(P)$(R)Total_RBV | -ai | -
| NDPluginROINet | -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 border of width NDPluginROIBgdWidth. This average background counts per element - is then subtracted from all elements inside the ROI. | -NET | -$(P)$(R)Net_RBV | -ai | -
| ROI histogram | -||||||
| NDPluginROIComputeHistogram | -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 |
-
| NDPluginROIHistSize | -asynInt32 | -r/w | -Number of elements (bins) in the histogram | -HIST_SIZE | -$(P)$(R)HistSize $(P)$(R)HistSize_RBV |
- longout longin |
-
| NDPluginROIHistMin | -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 |
-
| NDPluginROIHistMax | -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 |
-
| NDPluginROIHistEntropy | -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 | -ai | -
| NDPluginROIHistArray | -asynFloat64Array | -r/o | -Histogram array, i.e. counts in each histogram bin. | -HIST_ARRAY | -$(P)$(R)Histogram_RBV | -waveform | -
-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. -
-
-The following is the MEDM screen that provides access to the parameters for in NDPluginROI.h through -records in NDROIN.template. This is the MEDM screen that is used to control the behavior of a specific ROI. -
-
-The following is another MEDM screen that provides access to the parameters for 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. -
-
-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. -
-
+ The readFloat64Array method is used to read the histogram data for the ROI. +
++ 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 NDPlugDriver + listed above. The EPICS database NDROI.template provide access to these parameters, + listed in the following table. +
+| + Parameter Definitions in NDPluginROI.h and EPICS Record Definitions in NDROI.template | +||||||
| + Enum name | ++ asyn interface | ++ Access | ++ Description | ++ drvUser string | ++ EPICS record name | ++ 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 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. +
+| + 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 | +
|---|---|---|---|---|---|---|
| + NDPluginROIName | ++ asynOctet | ++ r/w | ++ Name of this ROI | ++ NAME | +
+ $(P)$(R)Name + $(P)$(R)Name_RBV |
+
+ stringout + stringin |
+
| + NDPluginROIUse | ++ 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 | +||||||
| + NDPluginROIDim0Bin | ++ asynInt32 | ++ r/w | ++ Binning in the X direction | ++ DIM0_BIN | +
+ $(P)$(R)BinX + $(P)$(R)BinX_RBV |
+
+ longout + longin |
+
| + NDPluginROIDim1Bin | ++ asynInt32 | ++ r/w | ++ Binning in the Y direction | ++ DIM1_BIN | +
+ $(P)$(R)BinY + $(P)$(R)BinY_RBV |
+
+ longout + longin |
+
| + NDPluginROIDim0Min | ++ 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 |
+
| + NDPluginROIDim1Min | ++ 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 |
+
| + NDPluginROIDim0Size | ++ asynInt32 | ++ r/w | ++ Size of the ROI in the X direction | ++ DIM0_SIZE | +
+ $(P)$(R)SizeX + $(P)$(R)SizeX_RBV |
+
+ longout + longin |
+
| + NDPluginROIDim0Size | ++ asynInt32 | ++ r/w | ++ Size of ROI in the Y direction | ++ DIM1_SIZE | +
+ $(P)$(R)SizeY + $(P)$(R)SizeY_RBV |
+
+ longout + longin |
+
| + NDPluginROIDim0Reverse | ++ asynInt32 | ++ r/w | +
+ Reverse ROI in the X direction + (0=No, 1=Yes) |
+ + DIM0_REVERSE | +
+ $(P)$(R)ReverseX + $(P)$(R)ReverseX_RBV |
+
+ longout + longin |
+
| + NDPluginROIDim0Reverse | ++ asynInt32 | ++ r/w | +
+ Reverse ROI in the Y direction + (0=No, 1=Yes) |
+ + DIM1_REVERSE | +
+ $(P)$(R)ReverseY + $(P)$(R)ReverseY_RBV |
+
+ longout + longin |
+
| + NDPluginROIDataType | ++ asynInt32 | ++ r/w | ++ Data type of the ROI (NDDataType_t). This can be different from the data type of + the NDArray callback data. | ++ DATA_TYPE | +
+ $(P)$(R)DataType + $(P)$(R)DataType_RBV |
+
+ mbbo + mbbi |
+
| + NDPluginROIBgdWidth | ++ 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 |
+
| + ADImageSizeX | ++ asynInt32 | ++ r/o | ++ Size of the ROI data in the X direction | ++ IMAGE_SIZE_X | ++ $(P)$(R)ImageSizeX_RBV | ++ longin | +
| + ADImageSizeY | ++ asynInt32 | ++ r/o | ++ Size of the ROI data in the Y direction | ++ IMAGE_SIZE_Y | ++ $(P)$(R)ImageSizeY_RBV | ++ longin | +
| + ROI statistics | +||||||
| + NDPluginROIComputeStatistics | ++ 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 |
+
| + NDPluginROIMinValue | ++ asynFloat64 | ++ r/o | ++ Minimum value in any element in the ROI | ++ MIN_VALUE | ++ $(P)$(R)MinValue_RBV | ++ ai | +
| + NDPluginROIMaxValue | ++ asynFloat64 | ++ r/o | ++ Maximum value in any element in the ROI | ++ MAX_VALUE | ++ $(P)$(R)MaxValue_RBV | ++ ai | +
| + NDPluginROIMeanValue | ++ asynFloat64 | ++ r/o | ++ Mean value in the ROI | ++ MEAN_VALUE | ++ $(P)$(R)MeanValue_RBV | ++ ai | +
| + NDPluginROITotal | ++ asynFloat64 | ++ r/o | ++ Sum (total) of all elements in the ROI | ++ TOTAL | ++ $(P)$(R)Total_RBV | ++ ai | +
| + NDPluginROINet | ++ 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 border of width NDPluginROIBgdWidth. This average background counts per + element is then subtracted from all elements inside the ROI. | ++ NET | ++ $(P)$(R)Net_RBV | ++ ai | +
| + ROI histogram | +||||||
| + NDPluginROIComputeHistogram | ++ 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 |
+
| + NDPluginROIHistSize | ++ asynInt32 | ++ r/w | ++ Number of elements (bins) in the histogram | ++ HIST_SIZE | +
+ $(P)$(R)HistSize + $(P)$(R)HistSize_RBV |
+
+ longout + longin |
+
| + NDPluginROIHistMin | ++ 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 |
+
| + NDPluginROIHistMax | ++ 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 |
+
| + NDPluginROIHistEntropy | ++ 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 | ++ ai | +
| + NDPluginROIHistArray | ++ asynFloat64Array | ++ r/o | ++ Histogram array, i.e. counts in each histogram bin. | ++ HIST_ARRAY | ++ $(P)$(R)Histogram_RBV | ++ waveform | +
+ The NDPluginROI plugin is created with the following command, either from C/C++ + or from the EPICS IOC shell. +
+drvNDROIConfigure(const char *portName, int queueSize, int blockingCallbacks, + const char *NDArrayPort, int NDArrayAddr, int maxROIs, + size_t maxMemory) - - ++
| + Argument | ++ Description | +
|---|---|
+ portName |
+ + The name of the asyn port for this plugin. + | +
+ queueSize |
+ + The maximum number of NDArray objects that can be queued for processing. Passed + to the NDPluginDriver base class constructor. + | +
+ blockingCallbacks |
+ + Flag controlling whether callbacks block. Passed to the NDPluginDriver base class + constructor. + | +
+ NDArrayPort |
+ + The name of the asyn port of the driver that will provide the NDArray data. Passed + to the NDPluginDriver base class constructor. + | +
+ NDArrayAddr |
+ + The asyn addr of the asyn port of the driver that will provide the NDArray data. + Passed to the NDPluginDriver base class constructor. + | +
+ maxROIs |
+ + Maximum number of ROIs that this plugin will support. + | +
+ maxMemory |
+ + Maximum number of bytes of memory to be allocated from the NDArrayPool. Passed to + the constructor for the NDPluginDriver base class. The NDPluginROI plugin allocates + one NDArray object for each ROI, so this should be at least maxROIs times the size + of the largest NDArray to be used. | +
+ 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. +
+
+
+ The following is the MEDM screen that provides access to the parameters for in NDPluginROI.h
+ through records in NDROIN.template. This is the MEDM screen that is used to control
+ the behavior of a specific ROI.
+
+
+ + The following is another MEDM screen that provides access to the parameters for + 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. +
+
+ + 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. +
+- -
-The vendor library supports saving individual frames as TIFF files, and this is implemented in the driver. The NDPluginFile -plugin can be used to capture or stream images much more rapidly in the netCDF file format. -
-The driver redefines the choices for 2 of the parameters defined in ADStdDriverParams.h. The ADTriggerMode choices for the -Prosilica are: -
The Prosilica supports additional hardware timing signals that may be supported in a future release. -
-The ADFileFormat choices for the Prosilica are: -
-
| Parameter Definitions in prosilica.cpp and EPICS Record Definitions in prosilica.template | -||||||
| Enum name | -asyn interface | -Access | -Description | -drvUser string | -EPICS record name | -EPICS record type | -
|---|---|---|---|---|---|---|
| PSReadStatistics | -asynInt32 | -r/w | -Read the Gigabit Ethernet statistics when 1 | -PS_READ_STATISTICS | -$(P)$(R)PSReadStatistics | -longout | -
| PSStatDriverType | -asynOctet | -r/o | -Driver type | -PS_DRIVER_TYPE | -$(P)$(R)PSDriverType_RBV | -stringin | -
| PSStatFilterVersion | -asynOctet | -r/o | -Packet filter version | -PS_FILTER_VERSION | -$(P)$(R)PSFilterVersion_RBV | -stringin | -
| PSStatFrameRate | -asynFloat64 | -r/o | -Frame rate (Hz) | -PS_FRAME_RATE | -$(P)$(R)PSFrameRate_RBV | -ai | -
| PSStatFramesCompleted | -asynInt32 | -r/o | -Number of frames completed | -PS_FRAMES_COMPLETED | -$(P)$(R)PSFramesCompleted_RBV | -longin | -
| PSStatFramesDropped | -asynInt32 | -r/o | -Number of frames dropped | -PS_FRAMES_DROPPED | -$(P)$(R)PSFramesDropped_RBV | -longin | -
| PSStatPacketsErroneous | -asynInt32 | -r/o | -Number of erroneous packets | -PS_PACKETS_ERRONEOUS | -$(P)$(R)PSPacketsErroneous_RBV | -longin | -
| PSStatPacketsMissed | -asynInt32 | -r/o | -Number of missed packets | -PS_PACKETS_MISSED | -$(P)$(R)PSPacketsMissed_RBV | -longin | -
| PSStatPacketsReceived | -asynInt32 | -r/o | -Number of received packets | -PS_PACKETS_RECEIVED | -$(P)$(R)PSPacketsReceived_RBV | -longin | -
| PSStatPacketsRequested | -asynInt32 | -r/o | -Number of packets requested | -PS_PACKETS_RESENT | -$(P)$(R)PSPacketsRequested_RBV | -longin | -
| PSStatPacketsResent | -asynInt32 | -r/o | -Number of packets resent | -PS_PACKETS_RESENT | -$(P)$(R)PSPacketsResent_RBV | -longin | -
| PSBadFrameCounter | -asynInt32 | -r/o | -Number of bad frames | -PS_BAD_FRAME_COUNTER | -$(P)$(R)PSBadFrameCounter_RBV | -longin | -
-The following is the MEDM screen ADBase.adl connected to a Prosilica camera. -
-
-The following is the MEDM screen that provides access to the specific parameters for the Prosilica detector. -
-
-The following is an IDL epics_ad_display screen (discussed below) illustrating the Prosilica detector images. -
-
- - - + +
++
++ This is a driver for Gigabit Ethernet and Firewire cameras from + Prosilica. It inherits from ADDriver and implements nearly all of the parameters + in ADStdDriverParams.h. It also implements a number of parameters that are specific + to the Prosilica cameras. The driver is currently only supported under Windows (EPICS + win32-x86 architecture) because the vendor library is provided as a Windows DLL. + The vendor library provided by Prosilica does callbacks to a user-supplied function + each time there is a new frame. Thus, it is not necessary to create a thread for + callbacks in this driver. +
++ The vendor library supports saving individual frames as TIFF files, and this is + implemented in the driver. The NDPluginFile plugin can be used to capture or stream + images much more rapidly in the netCDF file format. +
++ The driver redefines the choices for 2 of the parameters defined in ADStdDriverParams.h. + The ADTriggerMode choices for the Prosilica are: +
++ The Prosilica supports additional hardware timing signals that may be supported + in a future release. +
++ The ADFileFormat choices for the Prosilica are: +
++ The Prosilica driver implements the following parameters in addition to those in + ADStdDriverParams.h: +
+| + Parameter Definitions in prosilica.cpp and EPICS Record Definitions in prosilica.template | +||||||
| + Enum name | ++ asyn interface | ++ Access | ++ Description | ++ drvUser string | ++ EPICS record name | ++ EPICS record type | +
|---|---|---|---|---|---|---|
| + PSReadStatistics | ++ asynInt32 | ++ r/w | ++ Read the Gigabit Ethernet statistics when 1 | ++ PS_READ_STATISTICS | ++ $(P)$(R)PSReadStatistics | ++ longout | +
| + PSStatDriverType | ++ asynOctet | ++ r/o | ++ Driver type | ++ PS_DRIVER_TYPE | ++ $(P)$(R)PSDriverType_RBV | ++ stringin | +
| + PSStatFilterVersion | ++ asynOctet | ++ r/o | ++ Packet filter version | ++ PS_FILTER_VERSION | ++ $(P)$(R)PSFilterVersion_RBV | ++ stringin | +
| + PSStatFrameRate | ++ asynFloat64 | ++ r/o | ++ Frame rate (Hz) | ++ PS_FRAME_RATE | ++ $(P)$(R)PSFrameRate_RBV | ++ ai | +
| + PSStatFramesCompleted | ++ asynInt32 | ++ r/o | ++ Number of frames completed | ++ PS_FRAMES_COMPLETED | ++ $(P)$(R)PSFramesCompleted_RBV | ++ longin | +
| + PSStatFramesDropped | ++ asynInt32 | ++ r/o | ++ Number of frames dropped | ++ PS_FRAMES_DROPPED | ++ $(P)$(R)PSFramesDropped_RBV | ++ longin | +
| + PSStatPacketsErroneous | ++ asynInt32 | ++ r/o | ++ Number of erroneous packets | ++ PS_PACKETS_ERRONEOUS | ++ $(P)$(R)PSPacketsErroneous_RBV | ++ longin | +
| + PSStatPacketsMissed | ++ asynInt32 | ++ r/o | ++ Number of missed packets | ++ PS_PACKETS_MISSED | ++ $(P)$(R)PSPacketsMissed_RBV | ++ longin | +
| + PSStatPacketsReceived | ++ asynInt32 | ++ r/o | ++ Number of received packets | ++ PS_PACKETS_RECEIVED | ++ $(P)$(R)PSPacketsReceived_RBV | ++ longin | +
| + PSStatPacketsRequested | ++ asynInt32 | ++ r/o | ++ Number of packets requested | ++ PS_PACKETS_RESENT | ++ $(P)$(R)PSPacketsRequested_RBV | ++ longin | +
| + PSStatPacketsResent | ++ asynInt32 | ++ r/o | ++ Number of packets resent | ++ PS_PACKETS_RESENT | ++ $(P)$(R)PSPacketsResent_RBV | ++ longin | +
| + PSBadFrameCounter | ++ asynInt32 | ++ r/o | ++ Number of bad frames | ++ PS_BAD_FRAME_COUNTER | ++ $(P)$(R)PSBadFrameCounter_RBV | ++ longin | +
+ The following is the MEDM screen ADBase.adl connected to a Prosilica camera. +
++ The following is the MEDM screen that provides access to the specific parameters + for the Prosilica detector. +
++ The following is an IDL epics_ad_display screen (discussed below) illustrating the + Prosilica detector images. +
+