# areaDetector Viewers

## August 3, 2009

## 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 the entire directory Viewers/ImageJ/EPICS_areaDetector to the plugins/ directory in the ImageJ installation location.
- If you installed areaDetector from the prebuilt binary distribution you will already have the necessary .class files in that directory, and do not need to compile the Java source code. If you installed areaDetector from source code you will need to compile the Java code. On Windows 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. If the default EPICS Channel Access settings are appropriate then it is not necessary to configure the Java Channel Access library. If configuration is needed then it is important to realize that the pure Java Channel Access code does not use the environment variables for configuring EPICS that are used by the standard C Channel Access code. Java Channel Access configuration is explained in the CosyLab CAJ documentation. The simplest way to do this is to create the file <jre home>/lib/JCALibrary.properties, containing lines like the following

          gov.aps.jca.Context.addr_list=localhost 164.54.160.255
          gov.aps.jca.Context.auto_addr_list=false
          gov.aps.jca.Context.max_array_bytes=100000000

  With the Windows installation of ImageJ <jre home> will typically be C:\Program Files\ImageJ\jre\lib. On Linux it will be wherever the jre/lib directory for Java is located. Note that it should be necessary to create such a configuration file on almost all areaDetector clients because the CAJ default value of max_array_bytes is 16384, which will be too small for almost any detector. However, the the CAJ library dynamically changes the maximum array size if the server array is larger than max_array_bytes, so it is not actually necessary to set its value for the EPICS_AD_Viewer plugin.
- 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 exectute 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 IDL client is running on before IDL is started. It is not used by the ImageJ client, as discussed above.