IDS Peak comfortSDK, genericSDK, IPL, and AFL developer manuals are external documents. Please contact us if you need them.
The image size determines how large the buffers must be for the image data required by IDS peak during image acquisition. Resizing during image acquisition may cause problems if, for example, old buffers are too small after resizing. Therefore, resizing is only possible when image acquisition is stopped.
So before starting the image acquisition, you should free all previous buffers and create new buffers according to the newly set image size (see Preparing image acquisition: create buffer).
If you change the binning or decimation (subsampling) settings, the image size will also change. Also in this case, you must recreate the buffers before image acquisition.
|
The maximum possible image position depends on the set image size. The X position + width can never be outside the right image area, i.e. OffsetX + MaxWidth <= MaxSensorWidth. This applies analogously to the Y-position and the image height. See also Region of interest.
|
By default, OffsetX and OffsetY are set to 0. This means that the maximum possible image width and image height are identical to the image width and image height of the sensor. The return value of the following Maximum() functions takes this into account and changes with OffsetX/OffsetY.
If you want to reset the sensor to the maximum width and height, you must first set OffsetX and OffsetY to 0. Otherwise, setting the maximum width/height will result in an error because the values are larger than the set offset allows.
How to set any ROI
1.Query and set the minimum ROI. This removes the restriction on the offset.
2.Query the maximum ROI. The values are required for checking the maximum possible image position and image size.
3.Check sizes and cancel if necessary.
4.Set the desired ROI.
Example: Querying the minimum value, maximum value and increment of the image position and image size
peak_status status = PEAK_STATUS_SUCCESS;
peak_access_status accessStatus = peak_ROI_GetAccessStatus(hCam);
if (PEAK_IS_READABLE(accessStatus))
{
// ROI is readable
peak_position offsetMin = { 0, 0 };
peak_position offsetMax = { 0, 0 };
peak_position offsetInc = { 0, 0 };
peak_size sizeMin = { 0, 0 };
peak_size sizeMax = { 0, 0 };
peak_size sizeInc = { 0, 0 };
// Query the minimum, maximum and increment of ROI offsets
status = peak_ROI_Offset_GetRange(hCam, &offsetMin, &offsetMax, &offsetInc);
if (PEAK_ERROR(status)) { /* Error handling ... */ }
// Query the minimum, maximum and increment of ROI size
status = peak_ROI_Size_GetRange(hCam, &sizeMin, &sizeMax, &sizeInc);
if (PEAK_ERROR(status)) { /* Error handling ... */ }
}
|
// Query the minimum
int64_t x_min = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetX")->Minimum();
int64_t y_min = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetY")->Minimum();
int64_t width_min = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Width")->Minimum();
int64_t height_min = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Height")->Minimum();
// Query the maximum
int64_t x_max = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetX")->Maximum();
int64_t y_max = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetY")->Maximum();
int64_t width_max = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Width")->Maximum();
int64_t height_max = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Height")->Maximum();
// Query the increment
int64_t x_inc = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetX")->Increment();
int64_t y_inc = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetY")->Increment();
int64_t width_inc = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Width")->Increment();
int64_t height_inc = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Height")->Increment();
|
Example: Querying the current image position and size
peak_status status = PEAK_STATUS_SUCCESS;
peak_roi roi = { { 0, 0 }, { 0, 0 } };
peak_access_status accessStatus = peak_ROI_GetAccessStatus(hCam);
if (PEAK_IS_READABLE(accessStatus))
{
// Get the current ROI
status = peak_ROI_Get(hCam, &roi);
}
|
int64_t x = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetX")->Value();
int64_t y = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetY")->Value();
int64_t width = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Width")->Value();
int64_t height = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Height")->Value();
|
Complete example
peak_status status = PEAK_STATUS_SUCCESS;
peak_roi roi = { { 0, 0 }, { 0, 0 } };
peak_access_status accessStatus = peak_ROI_GetAccessStatus(hCam);
if (PEAK_IS_READABLE(accessStatus))
{
// Get the current ROI
status = peak_ROI_Get(hCam, &roi);
}
if (PEAK_IS_WRITEABLE(accessStatus))
{
peak_position offsetMin = { 0, 0 };
peak_position offsetMax = { 0, 0 };
peak_position offsetInc = { 0, 0 };
peak_size sizeMin = { 0, 0 };
peak_size sizeMax = { 0, 0 };
peak_size sizeInc = { 0, 0 };
// Query the minimum, maximum and increment of ROI offsets (possible size restrictions)
status = peak_ROI_Offset_GetRange(hCam, &offsetMin, &offsetMax, &offsetInc);
if (PEAK_ERROR(status)) { /* Error handling ... */ }
// Query the minimum, maximum and increment of ROI size (possible size restrictions)
status = peak_ROI_Size_GetRange(hCam, &sizeMin, &sizeMax, &sizeInc);
if (PEAK_ERROR(status)) { /* Error handling ... */ }
// Set the minimum ROI. This removes any size restrictions due to previous ROI settings
peak_roi roiMin = { offsetMin, sizeMin };
status = peak_ROI_Set(hCam, roiMin);
if (PEAK_ERROR(status)) { /* Error handling ... */ }
// Query the minimum, maximum and increment of ROI offsets
status = peak_ROI_Offset_GetRange(hCam, &offsetMin, &offsetMax, &offsetInc);
if (PEAK_ERROR(status)) { /* Error handling ... */ }
// Query the minimum, maximum and increment of ROI size
status = peak_ROI_Size_GetRange(hCam, &sizeMin, &sizeMax, &sizeInc);
if (PEAK_ERROR(status)) { /* Error handling ... */ }
roi.offset.x = 128;
roi.offset.y = 128;
roi.size.width = 600;
roi.size.height = 600;
// Check that the ROI parameters are within their valid range
if ((roi.offset.x % offsetInc.x) || (roi.offset.y % offsetInc.y) || (roi.size.width % sizeInc.width) || (roi.size.height % sizeInc.height))
{
// adjust offset and size parameters to be divisible by their increment or break
}
if ((roi.offset.x < offsetMin.x) || (roi.offset.y < offsetMin.y) || (roi.offset.x > offsetMax.x) || (roi.offset.y > offsetMax.y))
{
// adjust the offsets to be within the valid range or break
}
if ((roi.size.width < sizeMin.width) || (roi.size.height < sizeMin.height) || ((roi.offset.x + roi.size.width) > sizeMax.width) || ((roi.offset.y + roi.size.height) > sizeMax.height))
{
// adjust the ROI to be within the valid bounds or break
}
// Set the valid ROI
status = peak_ROI_Set(hCam, roi);
if (PEAK_ERROR(status)) { /* Error handling ... */ }
}
|
try
{
// Get the current ROI
int64_t x = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetX")->Value();
int64_t y = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetY")->Value();
int64_t width = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Width")->Value();
int64_t height = nodemapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Height")->Value();
// Get the minimum ROI
int64_t x_min = nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetX")->Minimum();
int64_t y_min = nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetY")->Minimum();
int64_t w_min = nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Width")->Minimum();
int64_t h_min = nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Height")->Minimum();
// Set the minimum ROI. This removes any size restrictions due to previous ROI settings
nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetX")->SetValue(x_min);
nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetY")->SetValue(y_min);
nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Width")->SetValue(w_min);
nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Height")->SetValue(h_min);
// Get the maximum ROI values
int64_t x_max = nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetX")->Maximum();
int64_t y_max = nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetY")->Maximum();
int64_t w_max = nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Width")->Maximum();
int64_t h_max = nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Height")->Maximum();
// Get the increment
int64_t x_inc = nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetX")->Increment();
int64_t y_inc = nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetY")->Increment();
int64_t w_inc = nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Width")->Increment();
int64_t h_inc = nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Height")->Increment();
// New ROI values
x = 128;
y = 128;
width = 600;
height = 600;
// Check that the ROI parameters are within their valid range
if ((x % x_inc) || (y % y_inc) || (width % w_inc) || (height % h_inc))
{
// adjust offset and size parameters to be divisible by their increment or break
}
if ((x < x_min) || (y < y_min) || (x > x_max) || (y > y_max))
{
// adjust the offsets to be within the valid range or break
}
if ((width < w_min) || (height < h_min) || ((x + width) > w_max) || ((y + height) > h_max))
{
// adjust the ROI to be within the valid bounds or break
}
// Set the valid ROI
nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetX")->SetValue(x);
nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("OffsetY")->SetValue(y);
nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Width")->SetValue(width);
nodeMapRemoteDevice->FindNode<peak::core::nodes::IntegerNode>("Height")->SetValue(height);
}
catch (const std::exception& e)
{
// ...
}
|
try
{
// Get the current ROI
var x = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("OffsetX").Value();
var y = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("OffsetY").Value();
var w = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("Width").Value();
var h = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("Height").Value();
// Get the minimum ROI
var x_min = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("OffsetX").Minimum();
var y_min = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("OffsetY").Minimum();
var w_min = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("Width").Minimum();
var h_min = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("Height").Minimum();
// Set the minimum ROI. This removes any size restrictions due to previous ROI settings
nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("OffsetX").SetValue(x_min);
nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("OffsetY").SetValue(y_min);
nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("Width").SetValue(w_min);
nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("Height").SetValue(h_min);
// Get the maximum ROI values
var x_max = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("OffsetX").Maximum();
var y_max = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("OffsetY").Maximum();
var w_max = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("Width").Maximum();
var h_max = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("Height").Maximum();
// Get the increment
var x_inc = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("OffsetX").Increment();
var y_inc = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("OffsetY").Increment();
var w_inc = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("Width").Increment();
var h_inc = nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("Height").Increment();
// New ROI values
x = 128;
y = 128;
width = 600;
height = 600;
// Check that the ROI parameters are within their valid range
if ((x % x_inc) || (y % y_inc) || (width % w_inc) || (height % h_inc))
{
// adjust offset and size parameters to be divisible by their increment or break
}
if ((x < x_min) || (y < y_min) || (x > x_max) || (y > y_max))
{
// adjust the offsets to be within the valid range or break
}
if ((width < w_min) || (height < h_min) || ((x + width) > w_max) || ((y + height) > h_max))
{
// adjust the ROI to be within the valid bounds or break
}
// Set the valid ROI
nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("OffsetX").SetValue(x);
nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("OffsetY").SetValue(y);
nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("Width").SetValue(width);
nodeMapRemoteDevice.FindNode<peak.core.nodes.IntegerNode>("Height").SetValue(height);
}
catch (Exception e)
{
// ...
}
|
try:
# Get the current ROI
x = node_map_remote_device.FindNode("OffsetX").Value()
y = node_map_remote_device.FindNode("OffsetY").Value()
w = node_map_remote_device.FindNode("Width").Value()
h = node_map_remote_device.FindNode("Height").Value()
# Get the minimum ROI
x_min = node_map_remote_device.FindNode("OffsetX").Minimum()
y_min = node_map_remote_device.FindNode("OffsetY").Minimum()
w_min = node_map_remote_device.FindNode("Width").Minimum()
h_min = node_map_remote_device.FindNode("Height").Minimum()
# Set the minimum ROI. This removes any size restrictions due to previous ROI settings
node_map_remote_device.FindNode("OffsetX").SetValue(x_min)
node_map_remote_device.FindNode("OffsetY").SetValue(y_min)
node_map_remote_device.FindNode("Width").SetValue(w_min)
node_map_remote_device.FindNode("Height").SetValue(h_min)
# Get the maximum ROI values
x_max = node_map_remote_device.FindNode("OffsetX").Maximum()
y_max = node_map_remote_device.FindNode("OffsetY").Maximum()
w_max = node_map_remote_device.FindNode("Width").Maximum()
h_max = node_map_remote_device.FindNode("Height").Maximum()
# Get the increment
x_inc = node_map_remote_device.FindNode("OffsetX").Increment()
y_inc = node_map_remote_device.FindNode("OffsetY").Increment()
w_inc = node_map_remote_device.FindNode("Width").Increment()
h_inc = node_map_remote_device.FindNode("Height").Increment()
// New ROI values
x = 128
y = 128
width = 600
height = 600
# Check that the ROI parameters are within their valid range
if (x mod x_inc) or (y mod y_inc) or (width mod w_inc) or (height mod h_inc):
# adjust offset and size parameters to be divisible by their increment or break
if (x < x_min) or (y < y_min) or (x > x_max) or (y > y_max):
# adjust the offsets to be within the valid range or break
if (width < w_min) or (height < h_min) or ((x + width) > w_max) or ((y + height) > h_max):
# adjust the ROI to be within the valid bounds or break
# Set the valid ROI
node_map_remote_device.FindNode("OffsetX").SetValue(x)
node_map_remote_device.FindNode("OffsetY").SetValue(y)
node_map_remote_device.FindNode("Width").SetValue(width)
node_map_remote_device.FindNode("Height").SetValue(height)
except Exception as e:
# ...
str_error = e.what()
|
Consider the following notes when you change the ROI during runtime:
•PayloadSize changes.
•Re-create the buffers.
•Garbage Collection C#
•Release the IDS peak IPL buffer pool.
A similar procedure is needed for the following functions:
•Binning and decimation
•PixelFormat
•Chunks (metadata): PayloadSize changes
