# areaDetector Viewers

## October 1, 2012

## Mark Rivers

## University of Chicago

## Contents

- Overview
- ImageJ Viewer
- IDL Viewer
- Troubleshooting

## Overview

One of the advantages of areaDetector is that it enables the use of generic image display clients that obtain their data via EPICS Channel Access and work with any detector. There are currently two such generic clients provided with the areaDetector distribution. The first is a plugin for the popular ImageJ Java-based image processing program. The second is an IDL-based viewer which can be run without an IDL license under the IDL Virtual Machine. Because ImageJ is free and more widely available and used than IDL, future enhancements are more likely to be done on the ImageJ plugin rather than the IDL viewer.

## ImageJ Viewer

This is a plugin for the popular ImageJ program that can be used to display 2-dimensional array data that the NDStdArrays plugin sends to EPICS. This plugin is contained in the areaDetector distribution in the Viewers/ImageJ/EPICS_areaDetector directory. This plugin 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.

To use this ImageJ plugin do the following:

- Install ImageJ from ImageJ download site. If installing on Windows I recommend installing the version bundled with Java.
- Copy the entire directory Viewers/ImageJ/EPICS_areaDetector to the plugins/ directory in the ImageJ installation location. On OS X this can be done with the command:

          cp -r Viewers/ImageJ/EPICS_areaDetector /Applications/ImageJ/plugins

- The ImageJ plugin is supplied as Java source code, so you will need to compile the Java code. This can be done in the ImageJ Plugins/Compile and Run menu. Browse for EPICS_AD_Viewer.java to compile and run it. The compilation step only needs to be done once, creating the required .class files.
- EPICS_AD_Viewer uses the pure-Java libraries for EPICS Channel Access. This means that unlike the IDL Viewer, no C-based shareable-libraries or DLLs are needed. Prior to areaDetector R1-9 the ImageJ plugin used the standard Java mechanism for setting the EPICS Channel Access settings using a JCALibrary.properties file. This was often confusing because it uses a different mechanism than all C-based Channel Access clients, and because multiple JCALibrary.Properties files might be found in the Java search path, making it hard to figure out where a setting was coming from. Starting with areaDetector R1-9 the ImageJ plugin uses the same EPICS environment variables as Channel Access clients that use the C Channel Access library. Note that the environment variable EPICS_CA_MAX_ARRAY_BYTES almost always needs to be set, because the default value of 16KB is rarely large enough for images. EPICS_CA_MAX_ARRAY_BYTES must be at least as large as the largest image size in bytes that you want to display. However, it is important not to set EPICS_CA_MAX_ARRAY_BYTES to an unnecessarily large value like 100 MB, because the EPICS CA library allocates buffers of size EPICS_CA_MAX_ARRAY_BYTES whenever the required buffer size is larger than 16KB. Remember also that EPICS_CA_MAX_ARRAY_BYTES must be set for both the IOC process and for the ImageJ client process.
- Start ImageJ and go to the Plugins/EPICS_areaDetector/EPICS_AD_Viewer to run the plugin
- Type in the prefix for the NDStdArrays plugin for the detector to be viewed (e.g. 13SIM1:image1:). You should get a message saying that the PVs have connected. If you don't the most likely problem is a firewall.
- Press the Start button to begin displaying images.

The control window for `EPICS_AD_Viewer` is shown below. The PVPrefix field is used to input the base name of the EPICS PVs with the image data. The array dimensions and the number of frames per second actually being displayed by ImageJ is shown. There is a status window that shows whether the EPICS PVs are connected and the number of arrays received since the last update, which is every 2 seconds.

Press the Snap button to make a copy of the current frame in a new window. ImageJ can then be used to process, annotate, etc. that image.

To capture a sequence of images into an ImageJ "stack" select "Capture To Stack". The image sequence will be stored in the ImageJ buffer and a scroll bar will appear to allow you to scroll through the images. The stack can be saved to disk in a large number of formats, including AVI.

The following is the main ImageJ window.

### ImageJ main window.

The following is the EPICS_AD_Viewer plugin control, located in the ImageJ "Plugins/EPICS_areaDetector/EPICS AD Viewer" menu.

### ImageJ EPICS_AD_Viewer plugin control window

The following is the EPICS_AD_Viewer image display window, which will appear when the Start button is pressed in the EPICS_AD_Viewer control window.

### ImageJ EPICS_AD_Viewer plugin display window with line selection

Recent versions of ImageJ come with a Dynamic Line Profile tool in the Graphics plugin menu. This tool can be used to plot a live line profile through an image which updates as new images are displayed. It also updates when the line position is changed. The version of this plugin that is supplied with the version of ImageJ current as of this writing (1.42q) does not obey the "Fixed Y-axis scale" property on the Edit/Options/Profile Plot Options menu in ImageJ. There is a newer version of this plugin available on the Web and also in the EPICS_areaDetector plugin folder that does obey the "Fixed Y-axis scale" property. Compile this version and replace the Dynamic_Profiler.class file in the ImageJ Graphics/ plugin folder to use the newer version.

### ImageJ EPICS_AD_Viewer dynamic line profile of the above image

## IDL Viewer

There is an IDL procedure called epics_ad_display that can be used to display 2-dimensional array data 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. It is also available in the Viewers/IDL directory in the areaDetector application.

The Viewers/IDL directory contains both the IDL source code and a standalone IDL file, epics_ad_display.sav, for the epics_ad_display GUI to display images from areaDetector detectors. This file can be run for free on any Linux or Windows system under the IDL Virtual Machine, which can be downloaded free of charge from ITT VIS. That directory also contains the shareable libraries used to call EPICS Channel Access from IDL (ezcaIDL.dll for Windows and libezcaIDL.so for Linux). Before using the IDL source code or .sav file it is necessary to define the environment variable EZCA_IDL_SHARE to point to the complete path to ezcaIDL.dll or libezcaIDL.so. For example on Linux:

    setenv EZCA_IDL_SHARE /home/epics/support/areaDetector/1-5/Viewers/IDL/libezcaIDL.so

On Windows use

    My Computer/Properties/Advanced/Environment Variables/

to add a new environment variable EZCA_IDL_SHARE to point to the location of ezcaIDL.dll on your system. To run the standalone IDL epics_ad_display.sav file without an IDL license execute the following on Linux:

    idl -32 -vm=epics_ad_display.sav

On Windows simply double-click on the icon for the epics_ad_display.sav file.

When the GUI comes up type the base PV name for the NDStdArrays plugin for your detector in the "Base PV" widget. For example with the simulation detector supplied with the areaDetector application this is "13SIM1:image1:" (without the quotes). Once the detector begins acquiring images they should be displayed in the IDL window.

To run the GUI from the IDL command line on a system with an IDL license type the epics_ad_display command followed by the base PV name of the NDStdArrays plugin. For example:

      IDL> epics_ad_display, '13SIM1:image1:'

The control window for `epics_ad_display` is shown below. It has a field to input the base name of the EPICS PVs with the image data. It also has fields to enable/display the IDL display update, to change the display mode, to autoscale the intensity, and to invert the image in the Y direction. If autoscale is set to No then manual scaling can be entered in the Min and Max fields. The number of frames per second actually being displayed by IDL is shown. There is a status window that shows whether the EPICS PVs are connected and the time the last was array received, updated once per second.

### Main window for IDL epics_ad_display

`epics_ad_display` can use the simple IDL routine `tv` to display the images. This is the fastest mode, and results in a non-scalable unadorned window.

### IDL epics_ad_display using the IDL `tv` routine.

`epics_ad_display` can also use 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 (right mouse click) and out (left mouse click). Note that image_display is not currently capable of displaying color data i.e., RGB1, RGB2, or RGB3 NDArrays). It can however, display Mono data in false color. The following is an example of `image_display` displaying an image from the simulation detector.

### epics_ad_display using the image_display routine

The Viewers/IDL directory also contains an IDL function to read the areaDetector netCDF files. This is described in the NDPluginFile netCDF documentation.

Stephen Mudie at the Australian Synchrotron has written a very nice IDL client to display the EPICS images from the Flea Firewire cameras. This client is being converted to display the data from this areaDetector plugin, and will be provided in a future release of areaDetector.

## Troubleshooting

If the ImageJ or IDL viewer is not displaying new images as the detector collects them check the following:

- If other EPICS channel access clients (e.g. medm, caget) running on the same machine as the viewer cannot connect to the IOC then check the following:
  - There may be a firewall blocking EPICS channel access either on the server (IOC) machine or the client (viewer) machine.
  - The environment variable EPICS_CA_ADDR_LIST may need to be set to allow the client to find the IOC if the IOC is not on the same subnet as the viewer or if other EPICS channel access settings do not have their default values.
- If other EPICS channel access clients (e.g. medm, caget) running on the same machine as the viewer can connect to the IOC then check the following:
  - The detector is actually collecting images, and the ArrayCallbacks PV is set to Enable.
  - The image plugin (NDStdArrays) has the EnableCallbacks PV set to Yes, and that the MinCallbackTime PV is not set too large.
  - The environment variable EPICS_CA_MAX_ARRAY_BYTES is set to a value at least as large as the size of the arrays to be sent to the viewer. This environment variable must be set on the machine that the IOC is running on before the IOC is started. It must also be set on the machine that the ImageJ or IDL viewer is running on before ImageJ or IDL is started.