# areaDetector Release Notes

## Release 1-6 (xxx-March-2010???)

- General
  - Converted to be compatible with asynPortDriver in asyn R4-13, which changes parameter handling.
  - Changes to support 64-bit architectures, including linux-x86_64. This also required changes to the synApps modules on which areaDetector applications depend (autosave, busy, etc.)
  - Changes in Makefiles to support the win32-x86-debug architecture.
- Drivers
  - Fixed a bug in the Roper driver. There was a buffer overflow problem in the function that converts C strings to Windows BSTR strings. This would cause the IOC to crash when saving SPE files with Comment PVs longer than 40 characters.
  - Many fixes to Windows Firewire driver:
    - Added dropped frame counter.
    - Fixed timeout problem with acquire times > 1 second.
    - Fixed logic when acquisition was turned off
    - Fixed problem with constructor when it encountered a minor error; was causing capture thread not to be started for some cameras.
    - Implemented AcquireTime parameter, previously the time could only be changed via a Firewire feature.
    - Fixed bug when setting a feature value in non-absolute mode after it was set in absolute mode.
    - Removed the ability to change video modes, formats or rates when acquiring because it is too complex to stop and wait for it to be done.
    - Report details for all supported Firewire "features" in report() function, called by asynReport() and dbior().
- Plugins
  - NDPluginROI. Major rewrite. Previously the ROI plugin supported multiple ROIs, performed statistics calculations, and highlighted the ROIs. The new version is much simpler; it supports only a single ROI, and does not calculate statistics or do highlighting. Those functions have been moved to new plugins. One new function has been added, the ability to divide the array by a scale factor, which is useful for avoiding overflow when binning.
  - Added new NDPluginStats plugin. This plugin calculates statistics on an array. It replaces the statistics calculations that were previously performed in the ROI plugin. It also adds new statistics, including the centroid position and width. Thanks to Stephen Mudie from the Australian Synchrotron and John Dobbins from Cornell for the initial versions of these calculations.
  - Added new NDPluginProcess plugin. This plugin does arithmetic processing on arrays:
    - Dark current subtraction.
    - Flat field normalization.
    - Scale and offset.
    - Low and high clipping.
    - Recursive filtering in the time domain.
    - Conversion to a different output data type.
- Internals
  - Added new form of NDArrayPool::convert that only changed data type, does not take dims argument.

## Release 1-5 (23-August-2009)

- General
  - Added "attributes" to NDArray. Attributes are used to contain metadata about the array. Each attribute has a name, description, datatype and value. Attributes can be added by drivers or plugins, and travel with the array through the plugin chain, and can ultimately be written with the array data to a file. Attributes can come from driver or plugin parameters, or from EPICS PVs anywhere on the network.
  - Separated parameters and functions which are general to NDArray data (asynNDArrayDriver base class) from those which are specific to areaDetector data (ADDriver base class). This makes it easy and clean to use asynNDArray driver for future applications beyond areaDetector, such as drivers for the XIA xMAP digital spectroscopy system.
- Drivers
  - New driver for mar345 online image plate detector. This driver communicates via a TCP/IP socket with the mar345dtb program, which must be used to control the detector.
  - New driver for Firewire IIDC/DCAM cameras under Windows. This driver uses the Windows 1394 camera driver from Carnegie Mellon University.
  - New driver for the Perkin-Elmer amorphous silicon flat panel detectors. Thanks to Brian Tieman and John Hammonds for this driver.
  - New driver for the Roper Scientific detectors using the PVCAM library. Thanks to Brian Tieman for this driver.
  - Added support for color to the simulation detector driver. It now supports color modes Mono, RGB1, RGB2 and RGB3.
  - Fixed 2 serious bugs in the Roper driver. It was not selecting ROI mode correctly. When NumAcquisitions was > 1 it was only collecting the first frame correctly, subsequent frames were the same as a first one. This has been isolated to a bug in the WinView COM interface, and a workaround for the problem has been implemented.
  - Solved problem of Prosilica driver crashing on Linux. The problem was with the SIGALARM signal handlers in EPICS base (R3.14.10 and earlier). There is a patch for base to fix this problem, and this fix will be included in EPICS base 3.14.11.
  - Added an additional state, "Initializing" to DetectorState_RBV record.
  - Added support for ADTriggerMode=External in marCCD driver. In this mode the AcquireTime is not used to stop acquisition; acquisition must be stopped by external software settings Acquire=0. The AcquireTime PV is written to the marCCD TIFF file header as usual. This allows an external timing control of the shutter but with the actual exposure time written to the header. Fixed minor problem with marCCD driver. If Acquire was set to Stop when it was not acquiring then the next time acquisition was started it would stop immediately.
- Plugins
  - Changed NDPluginFile from directly supporting netCDF to be a base class from which actual file plugins derive.
  - Changed netCDF file support to be derived class inheriting from NDPluginFile. Added support for writing NDArray attributes to the netCDF file.
  - New file plugin for TIFF files. The TIFF support includes 8, 16 and 32-bit integers. It supports monochrome and color images, including all 3 color interleave modes (RGB1, RGB2 and RGB3. areaDetector contains all required support files to build and run the TIFF file plugin on win32-x86, cygwin-x86 and Linux. To build on other operating systems it is necessary to install the libtiff and libtiffstatic packages. Thanks to John Hammonds for the initial work on this plugin.
  - New file plugin for JPEG files. The JPEG support is limited to 8-bit integers, but it supports monochrome and color images, including all 3 color interleave modes (RGB1, RGB2 and RGB3). Control is provided for the JPEG quality (compression) on a scale of 0 (worst) to 100 (best). areaDetector contains all required support files to build and run the JPEG file plugin on win32-x86, cygwin-x86, and Linux. To build on other operating systems it is necessary to install the libjpeg and libjpegstatic packages.
  - New file plugin for NeXus HDF files written by John Hammonds. The NeXus support has not been extensively tested, and is currently limited to writing a single array per file. Support for multiple arrays per file will be added in a future release. areaDetector contains all required support files to build and run the NeXus file plugin on win32-x86, cygwin-x86 and Linux. To build on other operating systems it is necessary to install the Nexus, HDF4, HDF5, and MXML packages.
  - Fixed bug in NDPluginFile: was not closing file properly when stream mode was stopped before the requested number of frames.
  - Fixed logic problem with FileNumber record in NDFile.template database. The previous logic that kept the ao record in sync with the ai record was causing the ao record to process when it should not have been, causing an extra call to the driver.
  - Added an additional record to NDPluginBase.template, PluginType_RBV. All plugins set this to a unique string to identify the plugin type.
- medm displays
  - Added new top-level detector-specific displays for Prosilica (prosilica.adl), Firewire (firewire.adl), and simDetector (simDetector.adl). ADBase.adl should no longer be used for these cameras.
- Viewers
  - Added new ImageJ plugin viewer. This was begun by Tim Madden from APS, and now includes support for all NDArray data types and color modes, i.e. Mono, RGB1 (pixel interleave), RGB2 (row interleave) and RGB3 (plane interleave). The plugin directory includes a plugin written elsewhere for reading and writing netCDF files, so ImageJ can be used to display images and image sequences (movies) saved with the NDFileNetCDF plugin. It also includes a dynamic profile plugin written elsewhere for line profiles that update in real time as new images are displayed.
  - Improved IDL epics_ad_display viewer. The last image is now stored in the program, and it is now redisplayed if the view mode is changed (TVSCL to iimage, etc.) or if the display parameters are changed (autoscale, flip Y, minimum, maximum, etc.).
- Documentation
  - Documented the source code with comments that doxygen can process to produce HTML documentation directly from the source. This provides documentation for each class, as well as the class inheritance tree. Thanks to John Hammonds for starting this.
- Internals
  - Moved the asynPortDriver base C++ class from the areaDetector module to the asyn module. The asynPortDriver base class was modified slightly to make it more general. In particular the constructor no longer hardcodes ASYN_CANBLOCK, ASYN_MULTIDEVICE, epicsThreadPriorityMedium, and epicsThreadStackMedium. This requires that asyn R4-11 or later be used, and requires 2 additional arguments to the constructor (priority and stackSize) for all areaDetector drivers and plugins.
  - Removed mutexId from asynPortDriver base class, and added lock() and unlock() methods. This hides the implementation of the locking, since we might want to implement these with asynManager->lockPort in the future.
  - Removed the file ADStdParams.h. Moved the definition of parameters that are general to NDArray drivers into asynNDArrayDriver.h, and those that are specific to areaDetector drivers into ADDriver.h.
  - Added an XML parser which is used for attribute definition files.
  - Fixed Makefiles to instantiate templates on vxWorks.
  - Moved createFileName() from ADDriver and NDPluginDriver to their base class, asynNDArrayDriver.
  - Changed colorMode and bayerPattern from being properties of NDArray to being attributes, since they are not general to NDArray but are specific to areaDetector.
  - Added new method asynPortDriver::drvUserCreateParam, which simplifies drvUserCreate code in all drivers and plugins.
  - Reduced number of files for all plugins and drivers. Previously there was an XXX.cpp, drvXXX.h, and drvXXXEpics.c. The .h and .c files were used to keep the drivers and plugins independent of EPICS IOC code. It was decided that that extra 2 files per driver and plugin were not worth the added complexity. If it is desired to run drivers and plugins outside of an IOC it could be done with conditional compilation of the IOC dependent code, which is all at the end of the .cpp file. The iocsh commands to create plugins have been changed from drvNDxxxConfigure to NDxxxConfigure, for example drvNDStdArraysConfigure was changed to NDStdArraysConfigure. This requires changes to all st.cmd files.
  - Renamed a few parameters and the drvInfo strings to logically separate things that are general to NDArrays and things that are specific to area detectors. For example, the drvInfo fields IMAGE_SIZE_xxx were renamed to ARRAY_SIZE_xxx, and IMAGE_COUNTER was renamed to ARRAY_COUNTER.
  - Added call to epicsExit() to all driver IOC main programs. This is important for allowing EPICS to exit cleanly. Without this on Linux it was often necessary to kill the IOC with ^C, rather than just typing "exit".
  - NDStdArrays.template had the DTYP field of the waveform record changed from asynInt$(SIZE)ArrayIn to asyn$(TYPE)ArrayIn. This was needed to allow it to be used with asynFloat32 and asynFloat64 data types. This requires a change to all iocBoot st.cmd files that load this template file.
  - Plugins can now add attributes to an NDArray, which means they can modify the array and hence need to make a copy of it. This requires that NDArray->release() must be called in the plugin itself, rather than in the NDPluginDriver base class as was done previously.

## Release 1-4 (30-January-2009)

- Added a driver for Roper Scientific (i.e. Princeton Instruments and Photometrics) detectors. It uses the Microsoft COM interface to control the WinView or WinSpec programs. The previous support in the "ccd" module used a Visual Basic socket server and an SNL program to accomplish this. It was hard to maintain, because Visual Basic changed incompatibly from one release of Visual Studio to the next, and because it could not be built with the EPICS build system. The new driver is written in C++, and is built entirely with the EPICS build system. It also supports more WinView features than the ccd version, and makes the detector data available via callbacks. This allows detector data to be displayed with EPICS clients, permits ROI or other plugin calculations, and allows saving in other file formats if desired.
- Added support for color:
  - Added NDColorMode_t and NDBayerPattern_t to NDArray.h. Added new fields colorMode and bayerPattern to NDArray structure to indicate the color mode.
  - Added new parameter ADColorMode to ADStdDriverParams.h and new record ColorMode to ADBase.template.
  - Added new parameter NDColorMode and NDBayerPattern to NDPluginBase.h and new records ColorMode and BayerPattern to NDPluginBase.template. Added these records to all plugin medm screens.
  - Added a new plugin NDPluginColorConvert to convert colors. It currently converts Bayer to RGB1, RGB2 or RGB3, RGB1 to RGB2 or RGB3 and RGB3 to RGB1 or RGB2.
  - The Prosilica driver now supports color. It supports RGB1 and Bayer directly, and RGB2 and RGB3 through the NDPluginColorConvert plugin.
  - The NDPluginFile driver now saves the ColorMode and BayerPattern to the netCDF files.
- Added a Viewers directory. This contains an IDL viewer for displaying images. The viewer supports color and several different viewing modes. It can be run for free under the IDL Virtual Machine, and should work on any platform with a version of ezcaIDL.so or ezcaIDL.dll built with EPICS 3.14. This directory also contains IDL class libraries for accessing areaDetector. These classes are used by the viewers, but can also be used for other IDL applications.
- Added new parameters in ADStdDriverParams.h
  - ADTemperature
  - ADReadStatus
  - ADImageSizeZ
  - ADNumExposuresCounter
  - ADColorMode
  - ADPortNameSelf
- Pilatus driver
  - Send the imgpath command to camserver when the ADFilePath parameter is changed. camserver will then create directories if they do not exist, whereas specifying a path with non-existant directories in the "exposure" or acquire commands will not create directories.
- Prosilica driver
  - Added support for color.
  - Added support for the external sync in, sync out and strobe signals. The sync signals can also be used for general-purpose digital I/O.
  - Made minor changes to the code and to the build system to add support for running the driver under Linux. There are some issues with this drivers use of SIGARLM via Posix Timer library and EPICS signal handlers. I have made some minor modifications to EPICS base 3.14.10 to allow the IOC to run. Prosilica is working on a new version of their driver that should fix these issues, but it is not yet working. The prebuilt binary version of this release of areaDetector includes the fixes to EPICS base and does work satisfactorily.
- NDPluginROI
  - Fixed bug with missing roi argument to setIntegerParam call, some parameters not updating correctly.
  - Added maxBuffers argument to constructor and to iocsh configuration command. This was a serious oversight in the previous versions. maxROIs was being used where the missing maxBuffers parameter should have been used. Unfortunately it requires a new argument to the iocsh drvNDROIConfigure command, which is not backwards compatible with previous startup scripts.
- NDArray
  - Changed the NDArray::copy() methods to NDArrayPool::copy(). Previously the copy was being allocated from the NDArrayPool of the copy source, rather than from the caller's array pool.
  - Added colorMode and bayerPattern fields to NDArray class.
  - Fixed a bug in the NDArray::convertDim function that could cause an array bounds error if a dimension was reversed.
- asynPortDriver
  - Renamed the pasynUser member to pasynUserSelf. This avoids a name conflict with the local variable pasynUser used in many derived classes. Unfortunately this requires changes to derived class code where this->pasynUser was used.
- Added simulation code to ADSC driver. This allows it to be built and tested on systems that do not have the ADSC hardware or software installed.
- Added $(P)$(R)AutoSave to the save/restore settings in NDFile_settings.req so it will be restored on reboot. This requires care when using drivers such as the Prosilica which can rapidly save very large data files, since file saving may be resumed on reboot.
- Removed abusy record, replaced with new version of busy record from new busy module.
- Renamed ADPlugin library to NDPlugin, because it is really N-dimensional.
- Renamed marCCD library to marCCD_AD, because marCCD is already used in the ccd module, and it conflicts. Changed marCCDSupport.dbd to marCCD_ADSupport.dbd, name of register command, etc.
- Added PortName_RBV record to ADBase.template and NDPluginBase.template and to all driver and plugin medm screens. This allows the user to see the asyn port name of the driver or plugin, which is useful when switching the NDArray callback source.
- Modified the detector medm screens to contain links to the plugins that are normally loaded for that driver, e.g. a single instance each of NDStdArrays, NDROI, NDFile and NDColorConvert (for detectors that support color).

## Release 1-3 (24-November-2008)

- Added a driver for MarCCD detectors. Compared to the previous support in the "ccd" module, this driver uses the faster Version 1 protocol for the Mar server. It also makes the detector data available via callbacks (by reading the TIFF files as soon as they are written). This allows detector data to be displayed with EPICS clients, and for ROI calculations.
- Added support for shutter control. Supports shutters that are driven directly from the detector hardware, as well as shutters controlled by EPICS records. Shutter support is implemented for the MarCCD, Pilatus, and simulation detectors.
- Added new methods for shutter support to the detector base class ADDriver.cpp
  - ADDriver::setShutter()
  - ADDriver::writeInt32
- Reorganized the file I/O parameters, template files and medm screens
  - Moved the file capture parameters from NDPluginFile.h and NDPluginFile.cpp to ADStdDriverParams.h. This allows a detector driver to use these capture parameters if desired.
  - Removed all of the file I/O records from ADBase.template and ADBase_settings.req. These previously duplicated the records in NDFile.template and NDFile_settings.req, which was hard to maintain. IOCs for detector drivers that can do file I/O now need to load NDFile.template, while those that cannot no longer need to load these records. They also need to have NDFile_settings.req added to auto_settings.req. This does not effect the file plugin support, only drivers that directly do file I/O.
  - Removed the file I/O PVs from ADBase.adl. Added a related display link to NDFile.adl.
  - NDFile.adl now contains only the file related PVs, not the plugin related PVs. The new file NDPluginFile.adl replaces the previous version of NDFile.adl, and contains both the file PVs and the plugin PVs.
- Added new enums in ADStdDriverParams.h
  - ADFrameType_t
  - ADShutterMode_t
  - ADFileMode_t
- Added new parameters in ADStdDriverParams.h
  - ADShutterControl (replaces ADShutter)
  - ADShutterControlEPICS
  - ADShutterStatus
  - ADShutterMode
  - ADShutterOpenDelay
  - ADShutterCloseDelay
  - ADTimeRemaining
  - ADNumImagesCounter
  - ADFrameType
  - ADArrayCallbacks
  - ADFileWriteMode
  - ADFileNumCapture
  - ADFileNumCaptured
  - ADFileCapture
  ADArrayCallbacks can be set to 0 to disable callbacks with detector data. For the MarCCD and Pilatus detectors setting this to 0 will disable reading the disk files after collection. This can be used to reduce overhead when EPICS is being used just for control, rather than to access the data.
- Added variant of NDPluginDriver::createFileName that returns the filePath and fileName separately, rather than a complete file name including the path.

## Release 1-2 (24-October-2008)

- Major update to documentation
- Significant enhancement to ROI plugin. Added net counts, ROI highlighting.
- Added driver for Pilatus detectors. This has undergone limited testing.
- Added driver for ADSC detectors (done by Lewis Muir, IMCA-CAT)
- Removed separate readback parameters in drivers and template files
- Changed from mbbi/mbbo records to bi/bo records where possible now that the asynInt32 interface supports bi/bo records.
- Internals
  - Renamed asynParamBase to asynPortDriver.
  - Renamed NDArrayBase to NDArrayDriver
  - Renamed NDPluginBase to NDPluginDriver
  - Renamed NDArrayBuff to NDArrayPool, now in NDArray.cpp.
  - Renamed ADDriverBase to ADDriver
  - Removed ADUtils
  - The asynHandle interface in asyn was renamed to asynGenericPointer, many changes to incorporate this.
  - Base class constructor no longer initializes all asyn interfaces, only the selected ones.
  - NDArray pool is no longer global, each server creates its own pool if needed.
  - Implemented real routines for writeInt32, writeFloat64, and writeOctet in asynPortDriver.cpp, removed them from ADDriver.cpp where they were not needed.

## Release 1-1 (10-May-2008)

- Major rewrite. Converted device drivers and plugins from C to C++ with C++ base classes that handle many of the details of asyn and of callbacks and threading for plugins.
- Everything except device drivers and top-level EPICS databases and channel access clients are now fully N-dimensional, not restricted to 2-D.
- NDPluginFile now uses netCDF format, which is a portable self-describing binary file format.
- Added NDPluginROI which implements region-of-interest.

## Release 1-0 (11-Apr-2008)

- Initial release, still many things remaining to be done.