ROI (Region Of Interest)

Functions
peak_access_status	peak_ROI_GetAccessStatus (peak_camera_handle hCam)
	Query the ROI access status.
peak_status	peak_ROI_Offset_GetRange (peak_camera_handle hCam, peak_position *minROIOffset, peak_position *maxROIOffset, peak_position *incROIOffset)
	Get the current range of valid ROI offsets.
peak_access_status	peak_ROI_Offset_GetAccessStatus (peak_camera_handle hCam)
	Query the ROI offset access status.
peak_status	peak_ROI_Offset_Set (peak_camera_handle hCam, peak_position position)
	Set the ROI offset.
peak_status	peak_ROI_Offset_Get (peak_camera_handle hCam, peak_position *position)
	Get the ROI offset.
peak_status	peak_ROI_Size_GetRange (peak_camera_handle hCam, peak_size *minROISize, peak_size *maxROISize, peak_size *incROISize)
	Get the current range of valid ROI sizes.
peak_access_status	peak_ROI_Size_GetAccessStatus (peak_camera_handle hCam)
	Query the ROI size access status.
peak_status	peak_ROI_Size_Set (peak_camera_handle hCam, peak_size size)
	Set the ROI size.
peak_status	peak_ROI_Size_Get (peak_camera_handle hCam, peak_size *size)
	Get the ROI size.
peak_status	peak_ROI_Set (peak_camera_handle hCam, peak_roi roi)
	Set the ROI.
peak_status	peak_ROI_Get (peak_camera_handle hCam, peak_roi *roi)
	Get the ROI.

Detailed Description

ROI (Region Of Interest) related functions and types.

Region of interest

Using this functions, you can set the size and position of an region of interest (ROI) within an image. The ROI is always referred to the sensor. In this case, only data included in this ROI will be read out and transferred to the computer. The smaller partial image enables the camera to use a higher frame rate.

For information on the ROI position grid and if the frame rates is increased when using a ROI, see the corresponding data sheet.

ROI readout on monochrome sensors

 

ROI readout on color sensors

Note

The available step widths for the position and size of image ROI depend on the sensor. The values defining the position and size of an ROI have to be integer multiples of the allowed step widths.

 

Function Documentation

peak_ROI_Get()

peak_status peak_ROI_Get	(	peak_camera_handle	hCam,
		peak_roi *	roi )

Get the ROI.

Reads the current image ROI.

Parameters

[in]	hCam	The camera handle.
[out]	roi	The ROI.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The ROI feature is not available for read access. Check the access status via peak_ROI_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER roi 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.0

peak_ROI_GetAccessStatus()

peak_access_status peak_ROI_GetAccessStatus

(

peak_camera_handle

hCam

)

Query the ROI access status.

Provides the current access status for the ROI feature.

This function implements the Access Status Query principle.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_ACCESS_READWRITE The ROI feature is readable and writeable.

PEAK_ACCESS_READONLY The ROI feature is readable only.

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

PEAK_ACCESS_NONE The ROI feature is not accessible.

PEAK_ACCESS_NOT_SUPPORTED The ROI 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_ROI_Offset_Get()

peak_status peak_ROI_Offset_Get	(	peak_camera_handle	hCam,
		peak_position *	position )

Get the ROI offset.

Reads the current image ROI offset.

Parameters

[in]	hCam	The camera handle.
[out]	position	The ROI offset.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The ROI offset feature is not available for read access. Check the access status via peak_ROI_Offset_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER position 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.0

peak_ROI_Offset_GetAccessStatus()

peak_access_status peak_ROI_Offset_GetAccessStatus

(

peak_camera_handle

hCam

)

Query the ROI offset access status.

Provides the current access status for the ROI offset.

This function implements the Access Status Query principle.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_ACCESS_READWRITE The ROI offset is readable and writeable.

PEAK_ACCESS_READONLY The ROI offset is readable only.

PEAK_ACCESS_GFA_LOCK The ROI offset is not accessible because the GFA write access is enabled.

PEAK_ACCESS_NONE The ROI offset is not accessible.

PEAK_ACCESS_NOT_SUPPORTED The ROI offset 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.9

peak_ROI_Offset_GetRange()

peak_status peak_ROI_Offset_GetRange	(	peak_camera_handle	hCam,
		peak_position *	minROIOffset,
		peak_position *	maxROIOffset,
		peak_position *	incROIOffset )

Get the current range of valid ROI offsets.

Queries the current range of valid values for the ROI offset.

The range of valid ROI offset values may depend on the camera configuration and the camera status.
In special the current setting of the ROI size has an impact on the range of valid ROI offset values.

Parameters

[in]	hCam	The camera handle.
[out]	minROIOffset	The minimum ROI offset values.
[out]	maxROIOffset	The maximum ROI offset values.
[out]	incROIOffset	The ROI offset values increments.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The ROI feature is not accessible. Check the access status via peak_ROI_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER At least one of minROIOffset, maxROIOffset, and incROIOffset 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.0

peak_ROI_Offset_Set()

peak_status peak_ROI_Offset_Set	(	peak_camera_handle	hCam,
		peak_position	position )

Set the ROI offset.

Writes the desired image ROI offset.

Parameters

[in]	hCam	The camera handle.
[in]	position	The ROI offset to set.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_OUT_OF_RANGE roi offset is out of range. Check the range of valid values via peak_ROI_Offset_GetRange.

PEAK_STATUS_ACCESS_DENIED The ROI offset feature is not available for write access. Check the access status via peak_ROI_Offset_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.9

peak_ROI_Set()

peak_status peak_ROI_Set	(	peak_camera_handle	hCam,
		peak_roi	roi )

Set the ROI.

Writes the desired image ROI.

Parameters

[in]	hCam	The camera handle.
[in]	roi	The ROI to set.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_OUT_OF_RANGE roi is out of range. Check the range of valid values via peak_ROI_Offset_GetRange and peak_ROI_Size_GetRange.

PEAK_STATUS_ACCESS_DENIED The ROI feature is not available for write access. Check the access status via peak_ROI_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_ROI_Size_Get()

peak_status peak_ROI_Size_Get	(	peak_camera_handle	hCam,
		peak_size *	size )

Get the ROI size.

Reads the current image ROI size.

Parameters

[in]	hCam	The camera handle.
[out]	size	The ROI size.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The ROI size feature is not available for read access. Check the access status via peak_ROI_Size_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER size 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.0

peak_ROI_Size_GetAccessStatus()

peak_access_status peak_ROI_Size_GetAccessStatus

(

peak_camera_handle

hCam

)

Query the ROI size access status.

Provides the current access status for the ROI size.

This function implements the Access Status Query principle.

Parameters

[in]

hCam

The camera handle.

Returns

PEAK_ACCESS_READWRITE The ROI size is readable and writeable.

PEAK_ACCESS_READONLY The ROI size is readable only.

PEAK_ACCESS_GFA_LOCK The ROI size is not accessible because the GFA write access is enabled.

PEAK_ACCESS_NONE The ROI size is not accessible.

PEAK_ACCESS_NOT_SUPPORTED The ROI size 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.9

peak_ROI_Size_GetRange()

peak_status peak_ROI_Size_GetRange	(	peak_camera_handle	hCam,
		peak_size *	minROISize,
		peak_size *	maxROISize,
		peak_size *	incROISize )

Get the current range of valid ROI sizes.

Queries the current range of valid values for the ROI dimensions.

The range of valid ROI size values may depend on the camera configuration and the camera status.
In special the current setting of the ROI offset has an impact on the range of valid ROI size values.

Parameters

[in]	hCam	The camera handle.
[out]	minROISize	The minimum ROI size values.
[out]	maxROISize	The maximum ROI size values.
[out]	incROISize	The ROI size values increments.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_ACCESS_DENIED The ROI feature is not accessible. Check the access status via peak_ROI_GetAccessStatus.

PEAK_STATUS_INVALID_PARAMETER At least one of minROISize, maxROISize, and incROISize 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.0

peak_ROI_Size_Set()

peak_status peak_ROI_Size_Set	(	peak_camera_handle	hCam,
		peak_size	size )

Set the ROI size.

Writes the desired image ROI size.

Parameters

[in]	hCam	The camera handle.
[in]	size	The ROI size to set.

Returns

PEAK_STATUS_SUCCESS Operation was successful; no error occurred.

PEAK_STATUS_OUT_OF_RANGE roi size is out of range. Check the range of valid values via peak_ROI_Size_GetRange.

PEAK_STATUS_ACCESS_DENIED The ROI size feature is not available for write access. Check the access status via peak_ROI_Size_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.9