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 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 =
% 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 attached Arduino sketch file (outputPulseSequence.ino).
% 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)')
To obtain a high dynamic range (HDR) image, use the makehdr function in Image Processing Toolbox for each acquired multiple-exposure image sequence.
