MATLAB: How to configure a hardware-triggered acquisition from a GigE Vision camera

Image Acquisition Toolbox

How can I configure a hardware-triggered acquisition from a GigE Vision camera?

Best Answer

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 an  instrument 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.
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 usermanual 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 = 
% 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 and timestamps from acquisition input buffer 


% into workspace


[data, ts] = getdata(v, v.FramesAvailable);
Display acquired frames and plot acquisition timestamps.
figure;
imaqmontage(data)
figure;
plot(ts, '.')
xlabel('Frame index');
ylabel('Timestamp (s)');
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 timestamps
figure;
imaqmontage(data2)
figure;
plot(ts2, '.')
xlabel('Frame index');
ylabel('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 control of the exposure time each frame by the external signal pulse 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 file attachments.
% 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 timestamps
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.
Related Question