Trigger

A trigger is a mechanism that synchronizes image capture with an external event or condition. This feature is crucial in applications where precise timing is needed to capture images at the right moment. More...

Topics
	Trigger edge property
	The trigger edge refers to the specific transition of a trigger signal that triggers capturing a frame.
	Trigger delay property
	Trigger delay refers to the time interval between the receipt of a trigger signal and the actual moment the camera captures an image.
	Trigger divider property
	A trigger divider is a setting that allows you to control the frequency of trigger signals by dividing the incoming trigger signal.
	Trigger burst property
	A burst trigger is a feature that allows the camera to capture multiple images in quick succession after receiving a single trigger signal.

Data Structures
struct	peak_trigger_mode
	peak Trigger mode More...

Macros
#define	PEAK_TRIGGER_MODE_SOFTWARE_TRIGGER
	peak Trigger mode preset: Frame start by software trigger

Enumerations
enum	peak_trigger_target { PEAK_TRIGGER_TARGET_INVALID , PEAK_TRIGGER_TARGET_FRAME_START , PEAK_TRIGGER_TARGET_LEVEL_CONTROLLED_EXPOSURE }
	peak Trigger target More...

Functions
peak_access_status	peak_Trigger_GetAccessStatus (peak_camera_handle hCam)
	Query the trigger feature access status.
peak_status	peak_Trigger_Enable (peak_camera_handle hCam, peak_bool enabled)
	Enable/Disable the trigger.
peak_bool	peak_Trigger_IsEnabled (peak_camera_handle hCam)
	Get the enabled status of the trigger.
peak_bool	peak_Trigger_IsExecutable (peak_camera_handle hCam)
	Check whether the trigger is executable or not.
peak_status	peak_Trigger_Execute (peak_camera_handle hCam)
	Execute the trigger.
peak_access_status	peak_Trigger_Mode_GetAccessStatus (peak_camera_handle hCam, peak_trigger_mode triggerMode)
	Query the trigger mode access status.
peak_status	peak_Trigger_Mode_Set (peak_camera_handle hCam, peak_trigger_mode triggerMode)
	Set the trigger mode.
peak_status	peak_Trigger_Mode_Config_Get (peak_camera_handle hCam, peak_trigger_mode *triggerMode)
	Get the trigger mode.

Detailed Description

A trigger is a mechanism that synchronizes image capture with an external event or condition. This feature is crucial in applications where precise timing is needed to capture images at the right moment.

By using external signals — such as from sensors or actuators — the camera only captures images when necessary, conserving processing power and bandwidth. Triggers are key to optimizing performance, efficiency and precision in these systems.

Types of Triggers:

Hardware Trigger:
The camera captures an image upon receiving an electrical signal (e.g., a pulse) from an external device. Software Trigger:
A trigger initiated by software to command the camera to capture an image at a specified time.

Hardware Trigger

To obtain a list of available input channels, call peak_IOChannel_GetListForDirection with PEAK_IO_DIRECTION_INPUT as the direction parameter (see example).

The example code below demonstrates how to configure and activate a hardware trigger on line 0 for frame start.

peak_access_status access = peak_Trigger_GetAccessStatus(hCam);
if (access != PEAK_ACCESS_READWRITE)
{
    // camera does not support trigger
}
 
peak_trigger_mode trigger_mode = { PEAK_TRIGGER_TARGET_FRAME_START, PEAK_IO_CHANNEL_LINE_0 };
 
access = peak_Trigger_Mode_GetAccessStatus(hCam, trigger_mode);
if (access != PEAK_ACCESS_READWRITE)
{
    // this trigger mode is not available, check input channels
}
 
peak_status status =     peak_Trigger_Mode_Set(hCam, trigger_mode);
if (PEAK_ERROR(status))
{
    // handle error
}
 
status = peak_Trigger_Enable(hCam, PEAK_TRUE);
if (PEAK_ERROR(status))
{
    // handle error
}
 
// start the image acquisition to acquire images with the hardware trigger

Software Trigger

Unlike a hardware trigger, which is activated by an external signal, a software trigger is controlled by the application.

The example code below illustrates how to configure and enable a software trigger for FrameStart, start the image acquisition and execute the software trigger three times to capture frames.

peak_trigger_mode trigger_mode = { PEAK_TRIGGER_TARGET_FRAME_START, PEAK_IO_CHANNEL_SOFTWARE };
 
peak_access_status access = peak_Trigger_Mode_GetAccessStatus(hCam, trigger_mode);
if (access != PEAK_ACCESS_READWRITE)
{
    // the software trigger mode is not available
}
 
peak_status status =     peak_Trigger_Mode_Set(hCam, trigger_mode);
if (PEAK_ERROR(status))
{
    // handle error
}
 
status = peak_Trigger_Enable(hCam, PEAK_TRUE);
if (PEAK_ERROR(status))
{
    // handle error
}
 
// start the image acquisition to acquire images with the hardware trigger
 
status = peak_Acquisition_Start(hCam,  PEAK_INFINITE);
if (PEAK_ERROR(status))
{
    // handle error
}
 
int received_frames = 0;
for (int i = 0; i < 3; i++)
{
    // execute the software trigger to capture a frame
    status = peak_Trigger_Execute(hCam);
    if (PEAK_ERROR(status))
    {
        // handle error
    }
 
    peak_frame_handle frame = PEAK_INVALID_HANDLE;
    status = peak_Acquisition_WaitForFrame(hCam, 5000, &frame);
    if (PEAK_SUCCESS(status))
    {
        // do something with frame
        received_frames++;
        peak_Frame_Release(hCam, frame);
    }
}
 
status = peak_Acquisition_Stop(hCam);
if (PEAK_ERROR(status))
{
    // handle error
}

Configuration Options

Additional configuration options for the trigger include

the trigger edge, that initializes the image capture, the delay between the physical signal and the image capture, the trigger divider to ignore a specific number of trigger signals until the next image capture and the number of captured images on each trigger signal using a burst trigger.

Note

The availability of these options depends on the camera model and firmware version. It is highly recommended to verify the access status before executing the corresponding function.

Macro Definition Documentation

PEAK_TRIGGER_MODE_SOFTWARE_TRIGGER

#define PEAK_TRIGGER_MODE_SOFTWARE_TRIGGER

peak Trigger mode preset: Frame start by software trigger

Initialize a peak_trigger_mode with this preset and pass it to peak_Trigger_Mode_Set to configure a software trigger for frame start.
See the following example code.

const peak_trigger_mode triggerMode = PEAK_TRIGGER_MODE_SOFTWARE_TRIGGER;
peak_status status = peak_Trigger_Mode_Set(cameraHandle, triggerMode);

Enumeration Type Documentation

peak_trigger_target

enum peak_trigger_target

peak Trigger target

The trigger target specifies which operation a trigger signal initiates or defines.

Enumerator
PEAK_TRIGGER_TARGET_INVALID	Invalid trigger target. Use this value for the initialization of variables of type peak_trigger_target.
PEAK_TRIGGER_TARGET_FRAME_START	Frame start. A trigger signal will initiate the start of a frame acquisition.
PEAK_TRIGGER_TARGET_LEVEL_CONTROLLED_EXPOSURE	Level controlled exposure. The trigger signal will define the exposure duration.

Function Documentation

peak_Trigger_Enable()

peak_status peak_Trigger_Enable	(	peak_camera_handle	hCam,
		peak_bool	enabled )

Enable/Disable the trigger.

Sets the trigger to enabled or disabled.

A trigger can be enabled or disabled if there is no running acquisition only.

Parameters

[in]	hCam	The camera handle.
[in]	enabled	The desired enabled status. PEAK_TRUE for enabled, PEAK_FALSE for disabled.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The trigger feature is not accessible for write. Check the access status of the trigger feature via peak_Trigger_GetAccessStatus.

PEAK_STATUS_INVALID_HANDLE hCam is an invalid camera handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.0

peak_Trigger_Execute()

peak_status peak_Trigger_Execute

(

peak_camera_handle

hCam

)

Execute the trigger.

Executes the trigger.

If a trigger is executed the configured trigger target is issued.
For a hardware trigger this means that an appropriate signal on the configured io channel is simulated.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The trigger is not enabled or it is not executable or the trigger feature is not accessible. Check for the trigger to be enabled via peak_Trigger_IsEnabled. Check for the trigger to be executable via peak_Trigger_IsExecutable. Check the access status of the trigger feature via peak_Trigger_GetAccessStatus.

PEAK_STATUS_INVALID_HANDLE hCam is an invalid camera handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.0

peak_Trigger_GetAccessStatus()

peak_access_status peak_Trigger_GetAccessStatus

(

peak_camera_handle

hCam

)

Query the trigger feature access status.

Provides the current access status for the trigger feature.

This function implements the Access Status Query principle.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_ACCESS_READWRITE The trigger feature is readable and writeable.

PEAK_ACCESS_READONLY The trigger feature is readable only.

PEAK_ACCESS_GFA_LOCK The trigger feature is not accessible because the GFA write access is enabled.

PEAK_ACCESS_NONE The trigger feature is not accessible. Check for a running acquisition.

PEAK_ACCESS_NOT_SUPPORTED The trigger feature is not supported.

PEAK_ACCESS_INVALID The function failed. Call peak_Library_GetLastError to get the error code and description.

If the function indicates an error by returning PEAK_ACCESS_INVALID, these are the possible errors:

• PEAK_STATUS_INVALID_HANDLE hCam is an invalid camera handle.
• PEAK_STATUS_NOT_INITIALIZED The library is not initialized.
• PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.0

peak_Trigger_IsEnabled()

peak_bool peak_Trigger_IsEnabled

(

peak_camera_handle

hCam

)

Get the enabled status of the trigger.

Queries whether the trigger is currently enabled or disabled.

This function implements the Enabled Status Query principle.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_TRUE The trigger is currently enabled.

PEAK_FALSE The trigger is currently disabled or the query failed.

Since

1.0

peak_Trigger_IsExecutable()

peak_bool peak_Trigger_IsExecutable

(

peak_camera_handle

hCam

)

Check whether the trigger is executable or not.

Queries whether the trigger is executable or not.

If a trigger is executable it can be issued via peak_Trigger_Execute.

This function implements the Boolean Status Queries principle.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_TRUE The trigger is executable.

PEAK_FALSE The trigger is not executable or the query failed.

Since

1.0

peak_Trigger_Mode_Config_Get()

peak_status peak_Trigger_Mode_Config_Get	(	peak_camera_handle	hCam,
		peak_trigger_mode *	triggerMode )

Get the trigger mode.

Reads the current trigger mode.

Parameters

[in]	hCam	The camera handle.
[out]	triggerMode	The trigger mode.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The trigger mode is not available for read access. Check the access status of the trigger mode via peak_Trigger_Mode_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER triggerMode is an invalid pointer.

PEAK_STATUS_INVALID_HANDLE hCam is an invalid camera handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.11

peak_Trigger_Mode_GetAccessStatus()

peak_access_status peak_Trigger_Mode_GetAccessStatus	(	peak_camera_handle	hCam,
		peak_trigger_mode	triggerMode )

Query the trigger mode access status.

Provides the access status for the given trigger mode.

This function implements the Access Status Query principle.

Parameters

[in]	hCam	The camera handle.
[in]	triggerMode	The trigger mode.

Returns

PEAK_ACCESS_READWRITE The trigger mode is readable and writeable.

PEAK_ACCESS_READONLY The trigger mode is readable only.

PEAK_ACCESS_GFA_LOCK The trigger mode is not accessible because the GFA write access is enabled.

PEAK_ACCESS_NONE The trigger mode is not accessible.

PEAK_ACCESS_NOT_SUPPORTED The trigger mode is not supported.

PEAK_ACCESS_INVALID The function failed. Call peak_Library_GetLastError to get the error code and description.

If the function indicates an error by returning PEAK_ACCESS_INVALID, these are the possible errors:

• PEAK_STATUS_ACCESS_DENIED The trigger feature is not accessible. Check the access status of the trigger feature via peak_Trigger_GetAccessStatus.
• PEAK_STATUS_INVALID_PARAMETER triggerMode is an invalid trigger mode. Check peak_trigger_target and peak_io_channel.
• PEAK_STATUS_INVALID_HANDLE hCam is an invalid camera handle.
• PEAK_STATUS_NOT_INITIALIZED The library is not initialized.
• PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.0

peak_Trigger_Mode_Set()

peak_status peak_Trigger_Mode_Set	(	peak_camera_handle	hCam,
		peak_trigger_mode	triggerMode )

Set the trigger mode.

Changes the trigger mode.

The properties of the trigger will be reset to the following default values:

• The trigger edge will be set to PEAK_TRIGGER_EDGE_RISING.
• The trigger delay will be set to 0.
• The trigger divider will be set to 1.
• The trigger burst size will be set to 1.

Parameters

[in]	hCam	The camera handle.
[in]	triggerMode	The trigger mode.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The trigger mode is not available for write access or the io channel is not available for write access. Check the access status of the trigger mode via peak_Trigger_Mode_GetAccessStatus. Check the access status of the io channel via peak_IOChannel_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER triggerMode is an invalid trigger mode. Check peak_trigger_target and peak_io_channel.

PEAK_STATUS_INVALID_HANDLE hCam is an invalid camera handle.

PEAK_STATUS_NOT_INITIALIZED The library is not initialized.

PEAK_STATUS_ERROR An unexpected internal error occurred.

Since

1.0