Point Grey areaDetector driver

Table of Contents

• Introduction
• Camera firmware
• Video modes
• Format7 modes
• Pixel formats
• Frame rates
• Properties
• Standard driver parameters
• Point Grey specific driver parameters
• Configuration
• MEDM screens

Introduction

This is an EPICS areaDetector driver for cameras from Point Grey. These include IEEE 1394 Firewire DCAM, GigE, USB 2.0, and USB 3.0 cameras. The driver should work with any Point Grey camera. It has been tested on Firewire (Flea2), GigE (BlackFly, Flea3, Grasshopper3), and USB 3.0 (Grasshopper3) cameras. The driver has been tested on Windows and Linux with all 3 of these cameras. Note that Point Grey Firewire cameras can also be controlled by the generic areaDetector Windows Firewire driver and the areaDetector Linux Firewire driver, which work with Firewire cameras from any vendor. However, this Point Grey driver provides access to some vendor-specific features like strobe outputs that are not available in the generic drivers.

On Linux the Point Grey FlyCap2 SDK requires glibc version 2.14. This means it cannot be used on RHEL 6, but it can be used on RHEL 7, and Fedora 15 and higher. For USB 3.0 cameras kernel version 3.5.0 or higher is required. This means USB 3.0 cameras require Fedora 18 or higher, or RHEL 7.0 or higher.

This driver inherits from ADDriver. It implements many of the parameters in asynNDArrayDriver.h and in ADArrayDriver.h. It also implements a number of parameters that are specific to the Point Grey cameras. The pointGrey class documentation describes this class in detail.

The Point Grey cameras use the IIDC/DCAM model for controlling features like shutter time, white balance, frame sizes, shutter time, frame rates, etc. This model is used not only for the IEEE 1394 Firewire cameras, for which the IIDC/DCAM model was developed, but also for their USB and GigE cameras. The Point Grey driver thus has many similarities to the generic areaDetector Windows Firewire driver and the areaDetector Linux Firewire driver. The FlyCapture2 SDK abstracts this model to a certain extent, which facilitates writing a driver that works with all of the Point Grey cameras.

Camera firmware

Point Grey frequently updates the available firmware for each camera to add features and fix bugs. However, they are not very good about putting the link to the latest firmware on their Web site. They claim this is because they only put the firmware on the Web site once it has been tested on all camera models in the camera family on which that firmware runs. In practice the firmware version listed on the Web site is often old and buggy. I have encouraged them to make the latest firmware more easily available. At present one must e-mail the support team (support@ptgrey.com) and ask them if newer firmware is available for a particular camera, and if so to provide access to it. They normally do this by sending a link to a Dropbox folder.

Video modes

The DCAM specification defines standard video formats, and a set of video modes for each video format. Point Grey combines the video format and video mode into a single quantity they call VideoMode. The following table lists these standard video modes.

Video mode Format7 is special. It allows defining an ROI on the camera to read out. The pixel resolution with which the size and position of this ROI can be defined can be queried, and is not necessarily a single pixel. In Format 7 the frame rate settings do not apply, and there is a another setting called PixelFormat that controls the video format, e.g. Mono8, Mono16, RGB8, etc.

Most cameras only support a small subset of these standard modes. The EPICS record $(P)$(R)VideoMode is an mbbo record that only has choices for the video modes actually available on the specific camera in use. Since mbbo records only allow a maximum of 16 choices and there are 24 standard video modes, it is conceivable that all available videos modes would not be presented. In practice this is not a problem since no existing camera supports more than 16 video modes.

Format7 modes

When the video mode is Format7 then there is an available selection of Format7 modes. These modes are not defined in the IIDC/DCAM standard, but are specific to each vendor and camera. Typically Format7 mode 0 is the entire chip unbinned, and mode 1 is often the entire chip with 2x2 binning. The supported Format7 modes are listed in the Point Grey Technical Reference Manual for each camera. The EPICS Format7Mode record is used to select the Format7 mode to use. This is an mbbo record and the enum choices are only those supported by the camera in use. The enum strings are of the form "Format7 mode # (NYxNY)", for example "0 (1920x1200)" or "1 (960x600)" for Format7 modes 0 and 1 respectively on a camera with 1920 x 1200 pixels.

Pixel formats

When the video mode is Format7 then there is an available selection of PixelFormats. The available PixelFormats depend on the selected Format7 mode. Selection of a PixelFormat is done with the EPICS PixelFormat record. This is an mbbo record that only has choices that are valid for the currently selected Format7 mode. The enum values in this record are thus dynamic, and it is displayed in a separate GUI window that must be closed and re-opened when the Format7 mode changes in order to guarantee that it is displaying the currently valid PixelFormat choices.

The following tables lists the standard pixel formats for video mode Format7. Note that typically only a few of these pixel formats are supported on a particular camera with a specific Format7 mode.

Frame rates

The following tables lists the standard IIDC/DCAM frame rates for video modes other than Format7. Selecting a video mode (other than Format7) defines the choice of available standard frame rates. Selecting a standard frame rate actually defines a range of frame rates that are available, and the actual frame rate can be adjusted within this range with the FrameRate property. The FrameRate property is controlled with the EPICS FrameRateAbsVal or AcquirePeriod records.

Selection of a standard frame rate is done with the EPICS FrameRate record. This is an mbbo record that only has choices that are valid for the currently selected video mode. The enum values in this record are thus dynamic, and it is displayed in a separate GUI window that must be closed and re-opened when the video mode changes in order to guarantee that it is displaying the currently valid FrameRate choices. Note that not all frame rates are supported by the IIDC standard for every video mode, and even when a frame rate is supported by the standard it may not be implemented for a particular camera.

In Format 7 the frame rate settings do not apply, and the frame rate is controlled solely by the FrameRate property.

Properties

The DCAM specification defines a number of standard features, which control things such as the brightness, white balance, shutter time, etc. For each feature the standard defines control in both device units (12-bit integers) and absolute units (floating point). For example shutter time may support absolute seconds, as well as device units. A feature may or may not be supported on a particular camera. If it is supported it may or may not permit control in absolute units. Each feature may support both manual control and automatic control (e.g. automatic gain control).

Point Grey supports 18 of these DCAM features, which they call Properties.

GigE Properties

Point Grey supports 4 properties that are specific to GigE cameras.

Standard areaDetector parameters

The following table describes how the Point Grey driver implements some of the standard driver parameters.

Point Grey specific driver parameters

The Point Grey driver implements the following parameters in addition to those in asynNDArrayDriver.h and ADDriver.h. The database file is pointGrey.template for all records except the property records, which are in pointGreyProperty.template.

Configuration

The Point Grey driver is created with the pointGreyConfig command, either from C/C++ or from the EPICS IOC shell.

pointGreyConfig(const char *portName, const char* cameraId, int traceMask, int memoryChannel,
              int maxBuffers, size_t maxMemory, 
              int priority, int stackSize)
  

The cameraId parameter can either be an index of the camera in the list of available cameras (e.g. 0 if there is only a single Point Grey camera available) or the serial number of the camera to use. For additional details on the meaning of the parameters to this function refer to the detailed documentation on the pointGreyConfigConfig function in the pointGrey.cpp documentation and in the documentation for the constructor for the pointGrey class.

The traceMask can be set to a value > 1 to enable asynTrace debugging during initialization, before the value can be set from the IOC shell or via the asynRecord. Set this to 0x21 to enable ASYN_TRACE_WARNING, which will trace all calls to the Point Grey FlyCap2 library.

The memoryChannel can be set to a value > 0 to load the initial camera parameters from non-volatile memory in the camera. Setting memoryChannel to N loads from memoryChannel N-1, i.e. 1 loads memory channel 0. There is currently a problem with Linux and for BlackFly GigE cameras. If the IOC is run a second time after it has been used to acquire any images the driver loses communication with the camera. The problem appears to be that there is a corrupt setting in the camera, which causes it to malfunction the next time the program is run. Setting memoryChannel 1 will work around this problem by replacing the settings in the camera with a default set. Since the EPICS IOC sets nearly all the camera settings to save/restore values at startup anyway, this is not a serious limitation.

There an example IOC boot directory and startup script (iocBoot/iocPointGrey/st.cmd) provided with areaDetector.

MEDM screens

The following show the MEDM screens that are used to control the Point Grey cameras.

pointGrey.adl is the main screen used to control Point Grey cameras.

pointGrey.adl

pointGreyProperties.adl is the screen used to control the properties of Point Grey cameras. Note that some of these properties, such as Shutter, FrameRate, and Gain can also be controlled by standard areaDetector records, like AcquireTime, AcquirePeriod, and Gain. The widgets on the medm screen are hidden if the corresponding feature is not available.

pointGreyProperties.adl for a BlackFly GigE color camera in RGB mode

pointGreyProperties.adl for a Grasshopper3 monochrome camera

pointGreyFrameRate.adl is the screen used to control the frame rate in standard video modes. This is a separate screen because the valid enum strings for the Framerate record can change when the standard video mode is changed. When that is changed it is necessary to close this screen and re-open it in order for the new menus to be displayed. This is a limitation of the EPICS Channel Access which does not send monitor events for changes in enum fields. Note that the readback of the FrameRate on the main pointGrey.adl screen can also be incorrect, so it may be necessary to close and re-open that main screen as well.

pointGreyFrameRate.adl

pointGreyPixelFormat.adl is the screen used to control the pixel format in Format7 mode. This is a separate screen because the valid enum strings for the PixelFormat can change when the Format7 mode is changed. When that is changed it is necessary to close this screen and re-open it in order for the new menus to be displayed. This is a limitation of the EPICS Channel Access which does not send monitor events for changes in enum fields. Note that the readback of the PixelFormat on the main pointGrey.adl screen can also be incorrect, so it may be necessary to close and re-open that main screen as well.

pointGreyPixelFormat.adl