MATLAB Examples

Hardware-Triggered Acquisition with a GigE Vision Camera

Image Acquisition Toolbox provides functionality for hardware-triggered acquisition from GigE Vision cameras. This is useful in applications where camera acquisition needs to be synchronized with another device (such as a DAQ device or another camera) by means of an external triggering signal. Other applications include controlling the acquisition frame rate with an external signal, or acquiring a multiple-exposure image sequence for high dynamic range (HDR) imaging. This example shows how to use the videoinput gige interface to configure a camera acquisition to allow external triggering-signal control over the frame rate and over the exposure time.

Contents

Requirements and hardware setup

  • MATLAB R2016a or later, Image Acquisition Toolbox, and "GigE Vision Hardware" support package.
  • GigE Vision compliant camera with hardware triggering capability; this example uses a Basler acA1300.
  • Gigabit Ethernet adapter, which provides a direct camera network connection, configured as described in the "GigE Vision Quick Start Configuration Guide".
  • External triggering setup, which can provide a triggering signal to the camera trigger line input. For example, a DAQ device with digital output, an Arduino board, or a function generator instrument can be used to output a custom triggering signal. Refer to the camera user manual for triggering signal voltage level / current requirements and for correct signal connections to the camera input lines.

Connect to camera

Create a videoinput with the desired video format and get access to the camera device specific properties. When using the videoinput gige adaptor, the camera GenICam features and parameter values are represented as videoinput source properties.

v = videoinput('gige', 1, 'Mono8');
s = v.Source;

% Determine optimum streaming parameters as described in the
% "GigE Vision Quick Start Configuration Guide"
s.PacketSize = 9000;
% s.PacketDelay =

Immediate acquisition

By default, an immediate acquisition takes place when videoinput start function is executed, if a hardware triggering configuration is not explicitly specified. For simplicity, this example performs an acquisition of a finite number of frames, and stores them in MATLAB base workspace.

% Set exposure time and mode
s.ExposureMode = 'Timed';
s.ExposureTimeAbs = 4000;

% The default videoinput trigger type is 'immediate', which is explicitly
% configured here for clarity.
triggerconfig(v, 'immediate');

% Specify number of frames to acquire
v.FramesPerTrigger = 30;
v.TriggerRepeat = 0;

% Start continuous buffered acquisition and wait for acquisition to complete
start(v);
wait(v, 10);

% Transfer acquired frames from acquisition input buffer into workspace.
data = getdata(v, v.FramesAvailable);

Display acquired frames.

figure;
imaqmontage(data)

FrameStart trigger

Most GigE Vision cameras support a FrameStart hardware trigger mode, which is used to configure the camera to acquire a frame for each rising edge (or falling edge) signal applied to a camera line input. In this example, a function generator instrument is used to supply a 25 Hz external periodic square wave signal applied to camera 'Line1' input, and the signal frequency effectively controls the camera frame rate.

When using the gige adaptor, to configure a hardware triggered acquisition, the videoinput trigger type needs to be set to 'hardware', while the remaining configuration is done via the videoinput source properties, which represent the corresponding camera GenICam features/parameters.

% Specify total number of frames to be acquired
% One frame is acquired for each external signal pulse.
numFrames = 30;
v.FramesPerTrigger = 1;
v.TriggerRepeat = numFrames - 1;

% Specify 'hardware' videoinput trigger type
triggerconfig(v, 'hardware', 'DeviceSpecific', 'DeviceSpecific');

Configure camera for FrameStart trigger mode and specify external triggering signal input line and desired trigger condition.

% This requires setting the TriggerSelector first; once a TriggerSelector
% value is selected, setting a trigger property (for example,
% TriggerMode to 'on') applies only to the specified trigger mode (FrameStart).
s.TriggerSelector = 'FrameStart';
s.TriggerSource = 'Line1';
s.TriggerActivation = 'RisingEdge';
s.TriggerMode = 'on';

% Specify a constant exposure time for each frame
s.ExposureMode = 'Timed';
s.ExposureTimeAbs = 4000;

% Start hardware-triggered buffered continuous acquisition, and wait for
% acquisition to complete
start(v)
wait(v, 10)

% Transfer acquired frames and timestamps from acquisition input buffer
% into workspace
[data2, ts2] = getdata(v, v.FramesAvailable);

Display acquired frames and plot timestamp differences, which correspond to the 25 Hz frequency of the external triggering signal.

figure;
imaqmontage(data2)

figure;
plot(diff(ts2), '.')
xlabel('Frame index');
ylabel('diff(Timestamp) (s)');

Note: Some camera models also support an AcquisitionStart trigger, which, depending on the camera model and configuration, could be used as a start trigger for a multi-frame acquisition, or as an enabler for a FrameStart trigger.

Exposure time control

Certain GigE Vision camera models support controlling the exposure time of each frame by external signal pulse-width duration. This configuration can be achieved with a FrameStart hardware trigger mode and a TriggerWidth exposure mode.

Possible applications include high dynamic range (HDR) imaging, where the external triggering signal can be a sequence of pulses of different pulse width durations. For a simple example on how to generate a custom triggering signal using an Arduino board refer to the following URL: <http://www.mathworks.com/matlabcentral/answers/289155>

% Specify total number of frames to be acquired
% One frame is acquired for each external signal pulse.
numFrames = 30;
v.FramesPerTrigger = 1;
v.TriggerRepeat = numFrames - 1;

% Specify 'hardware' videoinput trigger type
triggerconfig(v, 'hardware', 'DeviceSpecific', 'DeviceSpecific');

Configure camera for FrameStart trigger mode and specify external triggering signal input line and desired trigger condition.

% This requires setting the TriggerSelector first; once a TriggerSelector
% value is selected, setting a trigger property (for example,
% TriggerMode to 'on') applies only to the specified trigger mode (FrameStart).
s.TriggerSelector = 'FrameStart';
s.TriggerSource = 'Line1';
s.TriggerActivation = 'RisingEdge';
s.TriggerMode = 'on';

% For exposure time control, configure a TriggerWidth exposure mode.
s.ExposureMode = 'TriggerWidth';
% Specify camera ExposureOverlapTimeMaxAbs in microseconds
s.ExposureOverlapTimeMaxAbs = 5000;

% Start hardware-triggered buffered continuous acquisition, and wait for
% acquisition to complete
start(v)
wait(v, 10)

% Transfer acquired frames and timestamps from acquisition input buffer
% into workspace
[data3, ts3] = getdata(v, v.FramesAvailable);

Display acquired frames and plot timestamp differences.

figure;
imaqmontage(data3)

figure;
plot(ts3, '.')
xlabel('Frame index');
ylabel('Timestamp (s)');

figure;
plot(diff(ts3), '-x');
xlabel('Frame index');
ylabel('diff(Timestamp) (s)');

Each acquired multiple-exposure image sequence can be further processed to obtain a high dynamic range image.