From b44383824ff345a2a2972fa9d6eb5f2ebee97abf Mon Sep 17 00:00:00 2001 From: rivers Date: Fri, 15 May 2009 12:01:20 +0000 Subject: [PATCH] Documentation additions git-svn-id: https://subversion.xor.aps.anl.gov/synApps/areaDetector/trunk@8948 dc6c5ff5-0b8b-c028-a01f-ffb33f00fc8b --- documentation/Doxyfile | 3 +- documentation/areaDetector.html | 83 ++++- documentation/areaDetectorDoc.html | 362 ++------------------ documentation/areaDetectorReleaseNotes.html | 135 ++++++-- documentation/todo.txt | 58 ++-- 5 files changed, 256 insertions(+), 385 deletions(-) diff --git a/documentation/Doxyfile b/documentation/Doxyfile index 4102815..5c121f5 100755 --- a/documentation/Doxyfile +++ b/documentation/Doxyfile @@ -656,7 +656,8 @@ EXCLUDE_SYMLINKS = NO # against the file with absolute path, so to exclude all test directories # for example use the pattern */test/* -EXCLUDE_PATTERNS = */CDocFile40.h */CExpSetup20.h */CROIRect0.h */CWinx32App20.h +EXCLUDE_PATTERNS = */CDocFile40.h */CExpSetup20.h */CROIRect0.h */CWinx32App20.h \ + */tiny* # The EXCLUDE_SYMBOLS tag can be used to specify one or more symbol names # (namespaces, classes, functions, etc.) that should be excluded from the diff --git a/documentation/areaDetector.html b/documentation/areaDetector.html index 3e3627c..4ba218f 100755 --- a/documentation/areaDetector.html +++ b/documentation/areaDetector.html @@ -79,7 +79,7 @@ From Perkin Elmer

Please email any comments and bug reports to @@ -95,7 +95,7 @@ You can download the software from the links in the table below. The software is available both in source code form, and in pre-built form so that it can be used without an EPICS build system. The pre-built form includes binaries for linux-x86, - win32-x86, solaris-sparc and some vxWorks archtectures.

+ win32-x86, cygwin-x86, solaris-sparc, and some vxWorks archtectures.

@@ -114,6 +114,22 @@ + + + + + + + + + @@ -210,6 +226,64 @@ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + @@ -497,9 +571,8 @@

This software was originally developed by Mark Rivers.

diff --git a/documentation/areaDetectorDoc.html b/documentation/areaDetectorDoc.html index 69cf36e..7153b39 100755 --- a/documentation/areaDetectorDoc.html +++ b/documentation/areaDetectorDoc.html @@ -83,9 +83,10 @@
  • Provide a mechanism for device-independent real-time data analysis such as regions-of-interest and statistics.
  • Provide detector drivers for commonly used detectors in synchrotron applications. - These include Prosilica GigE video cameras, MAR-CCD x-ray detectors, MAR-345 online - imaging plate detectors, the Pilatus pixel-array detector, and the Roper Scientific - CCD cameras.
    • + These include Prosilica GigE video cameras, IEEE 1394 (Firewire) cameras, + MAR-CCD x-ray detectors, MAR-345 online + imaging plate detectors, the Pilatus pixel-array detector, Roper Scientific + CCD cameras, and the Perkin-Elmer amorphous silicon detector.

     

    @@ -102,11 +103,12 @@ hardware. It is usually provided by the detector vendor. It may consist of a library or DLL, of a socket protocol to a driver, a Microsoft COM interface, etc.
  • Layer 2. This is the driver that is written for the areaDetector application to - control a particular detector. It is normally written in C++ and inherits from the + control a particular detector. It is written in C++ and inherits from the ADDriver class. It uses the standard asyn interfaces for control and status information. - Each time it receives a new data array it passes it as an NDArray object to all - Layer 3 clients that have registered for callbacks. This is the only code that needs - to be written to implement a new detector. Existing drivers range from 650 to 1050 + Each time it receives a new data array it can pass it as an NDArray object to all + Layer 3 clients that have registered for callbacks. + This is the only code that needs + to be written to implement a new detector. Existing drivers range from 800 to 1800 lines of code.
  • Layer 3. Code running at this level is called a "plug-in". This code registers with a driver for a callback whenever there is a new data array. The existing plugins @@ -114,7 +116,7 @@ color mode conversion (NDPluginColorConvert), and conversion of detector data to standard EPICS array types for use by Channel Access clients (NDPluginStdArrays). Plugins are normally written in C++ and inherit from NDPluginDriver. Existing plugins - range from 300 to 700 lines of code.
    • + range from 300 to 800 lines of code.
  • Layer 4. This is standard asyn device support that comes with the EPICS asyn module.
  • Layer 5. These are standard EPICS records, and EPICS database (template) files that define records to communicate with drivers at Layer 2 and plugins at Layer @@ -122,7 +124,7 @@
  • Layer 6. These are EPICS channel access clients, such as MEDM that communicate with the records at Layer 5. There is a free IDL client that can display images using EPICS waveform and other records communicating with the NDPluginStdArrays - plugin at Layer 3.
    • + plugin at Layer 3. Other clients are being developed, including an ImageJ plugin.

    The code in Layers 1-3 is essentially independent of EPICS. There are only 2 EPICS @@ -153,7 +155,7 @@ to displaying this subregion. Similarly, the NDPluginFile plugin can be switched at run-time from saving the entire image to saving a selected ROI, just by changing its input source. Plugins can be used to form an image processing pipeline, for - example with a detector providing data to a color convert plugin, which feed an + example with a detector providing data to a color convert plugin, which feeds an ROI plugin, which feeds a file saving plugin. Each plugin can run in its own thread, and hence in its own core on a modern multi-core CPU.

    @@ -166,10 +168,7 @@

    What follows is a detailed description of the software, working from the bottom - up. Most of the code is object oriented, and written in C++. The parts of the code - that depend on anything from EPICS except libCom and asyn have been kept in in separate - C files, so that it should be easy to build applications that do not run as part - of an EPICS IOC. + up. Most of the code is object oriented, and written in C++.

    Implementation details

    @@ -187,347 +186,60 @@ Detector drivers and plugins are asyn port drivers, meaning that they implement one or more of the standard asyn interfaces. They register themselves as interrupt sources, so that they do callbacks to registered asyn clients when values change. - They inherit from the asynPortDriver - base C++ class that is provided in the asyn module. That base class handles + They inherit from the asynPortDriver + base C++ class that is provided in the asyn module. (The previous link is temporary + until asyn R4-11 is release). That base class handles all of the details of registering the port driver, registering the supported interfaces, - and registering the required interrupt sources. + and registering the required interrupt sources. There is also + detailed source documentation for asynPortDriver.

    NDArray

    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
-#define ND_SUCCESS 0
-#define ND_ERROR -1
-
-/* Enumeration of array data types */
-typedef enum
-{
-    NDInt8,
-    NDUInt8,
-    NDInt16,
-    NDUInt16,
-    NDInt32,
-    NDUInt32,
-    NDFloat32,
-    NDFloat64
-} NDDataType_t;
-
-/* Enumeration of color modes */
-typedef enum
-{
-    NDColorModeMono,
-    NDColorModeBayer,
-    NDColorModeRGB1,
-    NDColorModeRGB2,
-    NDColorModeRGB3,
-    NDColorModeYUV444,
-    NDColorModeYUV422,
-    NDColorModeYUV421
-} NDColorMode_t;
-
-typedef enum
-{
-    NDBayerRGGB        = 0,    /* First line RGRG, second line GBGB... */
-    NDBayerGBRG        = 1,    /* First line GBGB, second line RGRG... */
-    NDBayerGRBG        = 2,    /* First line GRGR, second line BGBG... */
-    NDBayerBGGR        = 3     /* First line BGBG, second line GRGR... */
-} NDBayerPattern_t;
-
-typedef struct NDDimension {
-    int size;
-    int offset;
-    int binning;
-    int reverse;
-} NDDimension_t;
-
-typedef struct NDArrayInfo {
-    int nElements;
-    int bytesPerElement;
-    int totalBytes;
-} NDArrayInfo_t;
-
-class NDArray {
-public:
-    /* Data: NOTE this must come first because ELLNODE must be first, i.e. same address as object */
-    /* The first 2 fields are used for the freelist */
-    ELLNODE node;
-    int referenceCount;
-    /* The NDArrayPool object that created this array */
-    void *owner;
-
-    int uniqueId;
-    double timeStamp;
-    int ndims;
-    NDDimension_t dims[ND_ARRAY_MAX_DIMS];
-    NDDataType_t dataType;
-    NDColorMode_t colorMode;
-    NDBayerPattern_t bayerPattern;
-    int dataSize;
-    void *pData;
-
-    /* Methods */
-    NDArray();
-    int          initDimension   (NDDimension_t *pDimension, int size);
-    int          getInfo         (NDArrayInfo_t *pInfo);
-    int          reserve(); 
-    int          release();
-};
-
    -

    + data from drivers to plugins. An NDArray is a general purpose class for handling array data. An NDArray object is self-describing, meaning it contains enough information to describe the data - itself. It is not intended to contain meta-data describing how the data was collected, - etc. + itself. It can optionally contain "attributes" (class NDAttribute) which + contain meta-data describing how the data was collected, etc.

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

    - + number of dimensions. Each dimension of the array is described by an + NDDimension structure. + The + NDArray class documentation describes this class in detail.

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

    - -

    - The methods of the NDArray class are: -

    -

    NDArrayPool

    - The NDArrayPool class manages a free list (pool) of NDArray objects (described above). + The NDArrayPool class manages a free list (pool) of NDArray objects. Drivers allocate NDArray objects from the pool, and pass these objects to plugins. Plugins increase the reference count on the object when they place the object on their queue, and decrease the reference count when they are done processing the array. When the reference count reaches 0 again the NDArray object is placed back on the free list. This mechanism minimizes the copying of array data in plugins. - The public interface of the NDArrayPool class is defined as follows: -

    - 
    class NDArrayPool {
-public:
-                 NDArrayPool   (int maxBuffers, size_t maxMemory);
-    NDArray*     alloc         (int ndims, int *dims, NDDataType_t dataType, int dataSize, void *pData);
-    NDArray*     copy          (NDArray *pIn, NDArray *pOut, int copyData);
-    int          reserve       (NDArray *pArray); 
-    int          release       (NDArray *pArray);
-    int          convert       (NDArray *pIn, 
-                                NDArray **ppOut,
-                                NDDataType_t dataTypeOut,
-                                NDDimension_t *outDims);
-    int          report        (int details);   
-
    -

    - The methods of the NDArrayPool class are: -

    - + The + NDArrayPool class documentation describes this class in detail. +

    asynNDArrayDriver

    asynNDArrayDriver inherits from asynPortDriver. It implements the asynGenericPointer - functions, assuming that these reference NDArray objects. This is the class from - which both plugins and area detector drivers are indirectly derived. Its public - interface is defined as follows: + functions, for NDArray objects. This is the class from + which both plugins and area detector drivers are indirectly derived. + The + asynNDArrayDriver class documentation describes this class in detail.

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

    -

    ADDriver

    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 */
-    virtual asynStatus writeInt32(asynUser *pasynUser, epicsInt32 value);
-    int createFileName(int maxChars, char *fullFileName);
-    void setShutter(int open)
-
    -

    - The methods of the ADDriver class are: -

    - + drivers are directly derived. + The + ADDriver class documentation describes this class in detail. +

    ADStdDriverParams

    diff --git a/documentation/areaDetectorReleaseNotes.html b/documentation/areaDetectorReleaseNotes.html index d38f8f4..6c488be 100755 --- a/documentation/areaDetectorReleaseNotes.html +++ b/documentation/areaDetectorReleaseNotes.html @@ -9,31 +9,118 @@

    areaDetector Release Notes

    - Release 1-5 (xxx-April-2009)

    + Release 1-5 (xxx-May-2009)

    Release 1-4 (30-January-2009)

    diff --git a/documentation/todo.txt b/documentation/todo.txt index 217cf8d..152303c 100644 --- a/documentation/todo.txt +++ b/documentation/todo.txt @@ -1,48 +1,46 @@ +For R1-5 + +- Update documentation to link to doxygen files and remove details of code + from HTML files. + +- Include TIFF and JPEG libraries in all applications so the plugins will work. + +- Load the TIFF and JPEG drivers, databases and adl screens for all drivers. + +- Make all writeXXX methods invoke the base class in the case where the +parameter is not recognized and the number is less than the first parameter +for this class. + +- Implement portNameSelf in asynPortDriver (but leave it in ADBase.template). + +- Test all drivers. + + +Longer term: + General -- Look at Marty's comments, respond -- Documentation - Performance measurements - Implement and improve connection management -- Make any asynBusy record, same as bo, except: - - Does not call recGblFwdLink until VAL=0. - - Soft device support is same as bo record. - - Flag indicating callback from device support, don't write output. - asynParamBase + asynPortDriver - Make it handle array interfaces with pointers? NDPluginBase -- Add all 10 dimensions to database +- Add all 10 dimensions to database? - drvNDFile -- Test reading - - drvNDStdArrays + File plugins +- Implement reading drvNDROI -- Add cross-sections +- Add cross-sections? +- Add scaling and offset, useful when converting data types? - drvSimDetector driver -- Test all image data types with all waveform data types -- Add connection state drvProsilica driver - Connection management - Sense disconnect, autoreconnect - Implement link callback. When matches uniqueID, call Disconnect or Connect -- Support color - Other drivers -- Roper using WinView/OLE -- Pilatus -- MAR-CCD -- MAR-345 - IDL -- Fix image_display - - Make TVSCL image - Resizeable; - - Change table widgets to text widgets or CW_field widgets - - Use rotate rather than order keyword on tv - - Check if data is byte and scaling is 0 to 255 don't scale the image -- Data saving? +- Get Stephen Mudie's code included and fixed +- Change image_display table widgets to text widgets or CW_field widgets
    Known Problems
    + 1-5 + xxx-May-2009 + areaDetectorR1-5.tgz + areaDetectorPrebuilt_R1-5.tgz + areaDetectorDoc + Release notes + See release notes
    1-4 Required for
    + 1-5 + EPICS base + 3.14.10 + Base support
    + asyn + 4-11 + Socket and interface support
    + busy + 1-2 + busy record. This was formerly included in sscan, but now has its own support module.
    + calc + 2-7 + scalcout record, needed by sscan database and useful for other databases
    + sscan + 2-6-3 + sscan record
    + mca + 6-11 + mca record for getting time sequence of ROI counts
    + autosave + 4-5 + Save/restore
    1-4