Image ROI#

The Image ROI camera feature allows you to specify the part of the sensor array that you want to use for image acquisition.

ROI is short for region of interest (formerly AOI = area of interest).

If an image ROI has been specified, the camera will only transmit pixel data from within that region. On most cameras, this increases the camera's maximum frame rate significantly.

The image ROI settings are independent from the auto function ROI settings.

Using the Feature#

Changing Position and Size of an Image ROI#

With the factory settings enabled, the camera is set to a default resolution. However, you can change the position and size as required.

To change the position and size of the image ROI:

Make sure the camera is idle, i.e., not capturing images.
If you are using an ace Classic/U/L camera, set the CenterX and CenterY parameters to false.
Use the following parameters to specify the size of the image ROI:
- Width
- Height
Use the following parameters to specify the position of the image ROI:
- OffsetX
- OffsetY

The origin of the image ROI is in the top left corner of the sensor array (column 0, row 0).

Example: Assume that you have specified the following settings:

Width = 16
Height = 10
OffsetX = 2
OffsetY = 6

This creates the following image ROI:

Image ROI Example

Info

For area scan cameras:

On most cameras, decreasing the size (especially the height) of the image ROI increases the camera's maximum frame rate significantly.
If the Binning feature is enabled, the settings for the image ROI refer to the binned lines and columns and not to the physical lines in the sensor.
On boA5120-230cc and boA5120-230cm cameras, the OffsetY parameter is not available. The position of the image ROI is always centered in vertically.
On boA13440-17cm cameras, the position of the image ROI is always centered horizontally and vertically. If you change the width of the image ROI, the OffsetX parameter value adapts automatically so that the image ROI stays centered horizontally. If you change the height of the image ROI, the OffsetY parameter value adapts automatically so that the image ROI stays centered vertically.
Both the OffsetX and OffsetY parameters are read-only.

Info

For line scan cameras:

For line scan cameras having more than one sensor line, the following applies:
If you set the image ROI height to 1, the camera output on aquisition depends on the number of camera sensor lines:
- Cameras with 2 sensor lines:
  The camera will output the color channels as follows:
  G in one line, R and B alternating in the other.
- Cameras with 3 sensor lines:
  The camera will output all three channels (R, G, and B) on acquisition.
  For information about the number of sensor lines available in a camera model, see the General Specifications table in the corresponding camera topic.
On all racer 2 cameras, the OffsetY parameter is not available.
On racer 2 cameras with CXP interface, the Height parameter is automatically set to 1 and can't be changed. For these cameras, the single lines are transmitted to the frame grabber individually. The frame grabber then combines them into a frame.
On racer 2 S cameras with GigE or 5GigE interface, you can add several lines to build a frame. Use the Height parameter to define the height of the image ROI, i.e., the height of the resulting frame that is transmitted to the host computer.
Minimum number of lines per frame: 1
Depending on the host computer, a low frame height (i.e. < 10 lines) may increase the CPU load of the host computer significantly.
The maximum number of lines per frame depends on the camera model:
- For r2L2048-29gc, r2L2048-58gm, r2L2048-62g5c, r2L2048-172g5m, r2L4096-29gm, and r2L4096-84g5m cameras: 12000
- For r2L4096-14gc and r2L4096-42g5c cameras: 10000

Info

For racer 2 S GigE cameras, you can use the Counter and Data Chunks features, in combination with the trigger settings, to specify which lines belong to a frame and which frames belong to the correct test object.

Guidelines#

When you are specifying an image ROI, follow these guidelines:

Guideline	Example
`OffsetX` + `Width` ≤ `WidthMax`	Camera with a 1920 x 1080 pixel sensor: `OffsetX` + `Width` ≤ 1920
`OffsetY` + `Height` ≤ `HeightMax`	Camera with a 1920 x 1080 pixel sensor: `OffsetY` + `Height` ≤ 1080

The WidthMax and HeightMax parameter values adapt to the current settings for Binning, Decimation, or Scaling (if available).

Specifics#

Image ROI Sizes#

Show all camera models

Camera Model	Minimum Width	Minimum Height
a2A640-240gmSWIR	4	1
a2A640-240umSWIR	4	1
a2A1280-80gmSWIR	4	1
a2A1280-125umSWIR	4	1
a2A1920-51gcBAS	4	2
a2A1920-51gcPRO	4	2
a2A1920-51gmBAS	4	1
a2A1920-51gmPRO	4	1
a2A1920-160ucBAS	4	2
a2A1920-160ucPRO	4	2
a2A1920-160umBAS	4	1
a2A1920-160umPRO	4	1
a2A1920-165g5cBAS	4	2
a2A1920-165g5mBAS	4	1
a2A2048-35gmSWIR	4	1
a2A2048-37gcBAS	4	2
a2A2048-37gcPRO	4	2
a2A2048-37gmBAS	4	1
a2A2048-37gmPRO	4	1
a2A2048-110umSWIR	4	1
a2A2048-114g5cBAS	4	2
a2A2048-114g5mBAS	4	1
a2A2048-114ucBAS	4	2
a2A2048-114ucPRO	4	2
a2A2048-114umBAS	4	1
a2A2048-114umPRO	4	1
a2A2440-98g5cBAS	4	4
a2A2440-98g5mBAS	4	4
a2A2448-23gcBAS	4	2
a2A2448-23gcPRO	4	2
a2A2448-23gmBAS	4	1
a2A2448-23gmPRO	4	1
a2A2448-75ucBAS	4	2
a2A2448-75ucPRO	4	2
a2A2448-75umBAS	4	1
a2A2448-75umPRO	4	1
a2A2448-105g5cBAS	4	2
a2A2448-105g5mBAS	4	1
a2A2448-120cc	48	2
a2A2448-120cm	48	2
a2A2448-210cc	48	2
a2A2448-210cm	48	2
a2A2560-20gmSWIR	4	1
a2A2560-70umSWIR	4	1
a2A2590-22gcBAS	4	2
a2A2590-22gcPRO	4	2
a2A2590-22gmBAS	4	1
a2A2590-22gmPRO	4	1
a2A2590-60ucBAS	4	2
a2A2590-60ucPRO	4	2
a2A2590-60umBAS	4	1
a2A2590-60umPRO	4	1
a2A2600-20gcBAS	4	2
a2A2600-20gcPRO	4	2
a2A2600-20gmBAS	4	1
a2A2600-20gmPRO	4	1
a2A2600-64ucBAS	4	2
a2A2600-64ucPRO	4	2
a2A2600-64umBAS	4	1
a2A2600-64umPRO	4	1
a2A2840-14gcBAS	4	2
a2A2840-14gcPRO	4	2
a2A2840-14gmBAS	4	1
a2A2840-14gmPRO	4	1
a2A2840-14gmUV	4	1
a2A2840-48ucBAS	4	2
a2A2840-48ucPRO	4	2
a2A2840-48umBAS	4	1
a2A2840-48umPRO	4	1
a2A2840-48umUV	4	1
a2A2840-67g5cBAS	4	2
a2A2840-67g5mBAS	4	1
a2A2840-67g5mUV	4	1
a2A2840-86cc	48	2
a2A2840-86cm	48	2
a2A3536-9gcBAS	4	2
a2A3536-9gcPRO	4	2
a2A3536-9gmBAS	4	2
a2A3536-9gmPRO	4	2
a2A3536-31ucBAS	4	2
a2A3536-31ucPRO	4	2
a2A3536-31umBAS	4	2
a2A3536-31umPRO	4	2
a2A3536-42g5cBAS	4	4
a2A3536-42g5mBAS	4	4
a2A3840-13gcBAS	4	2
a2A3840-13gcPRO	4	2
a2A3840-13gmBAS	4	1
a2A3840-13gmPRO	4	1
a2A3840-45ucBAS	4	2
a2A3840-45ucPRO	4	2
a2A3840-45umBAS	4	1
a2A3840-45umPRO	4	1
a2A4096-9gcBAS	4	2
a2A4096-9gcPRO	4	2
a2A4096-9gmBAS	4	1
a2A4096-9gmPRO	4	1
a2A4096-30ucBAS	4	2
a2A4096-30ucPRO	4	2
a2A4096-30umBAS	4	1
a2A4096-30umPRO	4	1
a2A4096-44g5cBAS	4	2
a2A4096-44g5mBAS	4	1
a2A4096-67cc	48	2
a2A4096-67cm	48	2
a2A4200-12gcBAS	4	2
a2A4200-12gcPRO	4	2
a2A4200-12gmBAS	4	1
a2A4200-12gmPRO	4	1
a2A4200-40ucBAS	4	2
a2A4200-40ucPRO	4	2
a2A4200-40umBAS	4	1
a2A4200-40umPRO	4	1
a2A4504-5gcBAS	4	2
a2A4504-5gcPRO	4	2
a2A4504-5gmBAS	4	1
a2A4504-5gmPRO	4	1
a2A4504-18ucBAS	4	2
a2A4504-18ucPRO	4	2
a2A4504-18umBAS	4	1
a2A4504-18umPRO	4	1
a2A4504-27g5cBAS	4	2
a2A4504-27g5mBAS	4	1
a2A4504-42cc	48	2
a2A4504-42cm	48	2
a2A4508-6gcBAS	4	2
a2A4508-6gcPRO	4	2
a2A4508-6gmBAS	4	1
a2A4508-6gmPRO	4	1
a2A4508-20ucBAS	4	2
a2A4508-20ucPRO	4	2
a2A4508-20umBAS	4	1
a2A4508-20umPRO	4	1
a2A5060-4gcBAS	4	2
a2A5060-4gmBAS	4	1
a2A5060-15ucBAS	4	2
a2A5060-15umBAS	4	1
a2A5060-21g5cBAS	4	2
a2A5060-21g5mBAS	4	1
a2A5060-35cc	48	2
a2A5060-35cm	48	2
a2A5320-7gcBAS	4	2
a2A5320-7gcPRO	4	2
a2A5320-7gmBAS	4	1
a2A5320-7gmPRO	4	1
a2A5320-23ucBAS	4	2
a2A5320-23ucPRO	4	2
a2A5320-23umBAS	4	1
a2A5320-23umPRO	4	1
a2A5320-34g5cBAS	4	2
a2A5320-34g5mBAS	4	1
a2A5320-52cc	48	2
a2A5320-52cm	48	2
a2A5328-4gcBAS	4	2
a2A5328-4gcPRO	4	2
a2A5328-4gmBAS	4	1
a2A5328-4gmPRO	4	1
a2A5328-15ucBAS	4	2
a2A5328-15ucPRO	4	2
a2A5328-15umBAS	4	1
a2A5328-15umPRO	4	1
a2A5328-22g5cBAS	4	2
a2A5328-22g5mBAS	4	1
a2A5328-35cc	48	2
a2A5328-35cm	48	2
acA640-121gm	1	1
acA640-300gc	16	2
acA640-300gm	16	1
acA640-750uc	16	2
acA640-750um	16	1
acA720-290gc	2	2
acA720-290gm	1	1
acA720-520uc	2	2
acA720-520um	1	1
acA800-200gc	16	2
acA800-200gm	16	1
acA800-510uc	16	2
acA800-510um	16	1
acA1280-60gc	2	2
acA1280-60gm	1	1
acA1300-60gc	2	2
acA1300-60gm	1	1
acA1300-60gmNIR	1	1
acA1300-75gc	16	2
acA1300-75gm	16	1
acA1300-200uc	16	2
acA1300-200um	16	1
acA1440-73gc	2	2
acA1440-73gm	1	1
acA1440-220uc	2	2
acA1440-220um	1	1
acA1600-20gc	2	2
acA1600-20uc	2	2
acA1600-60gc	2	2
acA1600-60gm	1	1
acA1920-25gc	64	64
acA1920-25gm	64	64
acA1920-25uc	64^a	64^a
acA1920-25um	64^a	64^a
acA1920-40gc	2	2
acA1920-40gm	1	1
acA1920-40uc	4	2
acA1920-40ucMED	4	2
acA1920-40um	4	1
acA1920-40umMED	4	1
acA1920-48gc	32	2
acA1920-48gm	32	1
acA1920-50gc	2	2
acA1920-50gm	1	1
acA1920-150uc	32	2
acA1920-150um	32	1
acA1920-155uc	4	2
acA1920-155ucMED	4	2
acA1920-155um	4	1
acA1920-155umMED	4	1
acA2000-50gc	2	2
acA2000-50gm	1	1
acA2000-165uc	8	2
acA2000-165um	8	1
acA2040-25gc	2	2
acA2040-25gm	1	1
acA2040-25gmNIR	1	1
acA2040-35gc	2	2
acA2040-35gm	1	1
acA2040-55uc	4	2
acA2040-55um	4	1
acA2040-90uc	8	2
acA2040-90um	8	1
acA2040-90umNIR	8	1
acA2040-120uc	4	2
acA2040-120um	4	1
acA2440-20gc	2	2
acA2440-20gm	1	1
acA2440-35uc	4	2
acA2440-35ucMED	4	2
acA2440-35um	4	1
acA2440-35umMED	4	1
acA2440-75uc	4	2
acA2440-75ucMED	4	2
acA2440-75um	4	1
acA2440-75umMED	4	1
acA2500-14gc	64	64
acA2500-14gm	64	64
acA2500-14uc	64^a	64^a
acA2500-14um	64^a	64^a
acA2500-20gc	32	2
acA2500-20gcMED	32	2
acA2500-20gm	32	1
acA2500-20gmMED	32	1
acA2500-60uc	32	1
acA2500-60um	32	1
acA3088-16gc	376	320
acA3088-16gm	376	320
acA3088-57uc	376	320
acA3088-57ucMED	376	320
acA3088-57um	376	320
acA3088-57umMED	376	320
acA3800-10gc	64	64
acA3800-10gm	64	64
acA3800-14uc	64	64
acA3800-14um	64^a	64^a
acA4024-8gc	8	6
acA4024-8gm	8	5
acA4024-29uc	8	6
acA4024-29um	8	5
acA4096-11gc	16	2
acA4096-11gm	16	1
acA4096-30uc	4	2
acA4096-30ucMED	4	2
acA4096-30um	4	1
acA4096-30umMED	4	1
acA4096-40uc	4	2
acA4096-40ucMED	4	2
acA4096-40um	4	1
acA4096-40umMED	4	1
acA4112-8gc	16	2
acA4112-8gm	16	1
acA4112-20uc	4	2
acA4112-20ucMED	4	2
acA4112-20um	4	1
acA4112-20umMED	4	1
acA4112-30uc	4	2
acA4112-30ucMED	4	2
acA4112-30um	4	1
acA4112-30umMED	4	1
acA5472-5gc	8	6
acA5472-5gm	8	5
acA5472-17uc	8	6
acA5472-17ucMED	8	6
acA5472-17um	8	5
acA5472-17umMED	8	5
boA1936-400cc	48	2
boA1936-400cm	48	2
boA2448-250cc	96 / 48^b	2
boA2448-250cm	48	2
boA2832-190cc	96 / 48^b	2
boA2832-190cm	48	2
boA4096-93cc	48	2
boA4096-93cm	48	2
boA4096-180cc	96 / 48^b	2
boA4096-180cm	48	2
boA4112-68cc	48	2
boA4112-68cm	48	2
boA4500-45cc	48	2
boA4500-45cm	48	2
boA4504-100cc	96 / 48^b	2
boA4504-100cm	96 / 48^b	2
boA5120-150cc	256	4
boA5120-150cm	256	4
boA5120-230cc	256	32
boA5120-230cm	256	32
boA5320-150cc	96 / 48^b	2
boA5320-150cm	96 / 48^b	2
boA5328-100cc	96 / 48^b	2
boA5328-100cm	96 / 48^b	2
boA6500-36cc	48	2
boA6500-36cm	48	2
boA8100-16cc	48	2
boA8100-16cm	48	2
boA9344-30cc	256	4
boA9344-30cm	256	4
boA9344-70cc	256	4
boA9344-70cm	256	4
boA13440-17cm	96 / 48^b	2
daA720-520uc	2	6
daA720-520um	4	3
daA1280-54uc	16	8
daA1280-54um	16	8
daA1440-220uc	2	6
daA1440-220um	4	3
daA1600-60uc	16	8
daA1600-60um	16	8
daA1920-15um	16	8
daA1920-30uc	16	8
daA1920-30um	16	8
daA1920-160uc	2	6
daA1920-160um	4	1
daA2448-70uc	2	6
daA2448-70um	4	3
daA2500-14uc	16	8
daA2500-14um	16	8
daA3840-45uc	2	6
daA3840-45um	4	4
dmA720-290gc	4	2
dmA720-290gm	4	1
dmA1440-73gc	4	2
dmA1440-73gm	4	1
dmA1920-51gc	4	2
dmA1920-51gm	4	1
dmA2048-37gc	4	2
dmA2048-37gm	4	1
dmA2448-23gc	4	2
dmA2448-23gm	4	1
dmA2840-14gc	4	2
dmA2840-14gm	4	1
dmA3536-9gc	4	2
dmA3536-9gm	4	2
dmA4096-9gc	4	2
dmA4096-9gm	4	1
puA1280-54uc	16	8
puA1280-54um	16	8
puA1600-60uc	16	8
puA1600-60um	16	8
puA1920-30uc	4	4
puA1920-30um	4	4
puA2500-14uc	4	4
puA2500-14um	4	4
r2L2048-29gc	4	1
r2L2048-58gm	4	1
r2L2048-62cc	48	1
r2L2048-62g5c	4	1
r2L2048-172cm	48	1
r2L2048-172g5m	4	1
r2L4096-14gc	4	1
r2L4096-29gm	4	1
r2L4096-42cc	48	1
r2L4096-42g5c	4	1
r2L4096-84cm	48	1
r2L4096-84g5m	4	1
r2L8192-200cm	64	1
r2L16384-120cm	64	1

When binning is enabled, the minimum width and minimum height are reduced. Values are rounded up to the nearest integer. Example: If you have configured horizontal binning by 3, the effective minimum width is 64 / 3 = 21.333 ≈ 22.
10-bit pixel formats / other pixel formats

Sample Code#

ace Classic/U/L GigE Cameras#

C++ (Native)C++ (Generic)C#C (Generic)Python

// Set the width to the maximum value
int64_t maxWidth = camera.Width.GetMax();
camera.Width.SetValue(maxWidth);
// Set the height to 500
camera.Height.SetValue(500);
// Set the offset to 0,0
camera.OffsetX.SetValue(0);
camera.OffsetY.SetValue(0);

INodeMap& nodemap = camera.GetNodeMap();
// Set the width to the maximum value
int64_t maxWidth = CIntegerParameter(nodemap, "Width").GetMax();
CIntegerParameter(nodemap, "Width").SetValue(maxWidth);
// Set the height to 500
CIntegerParameter(nodemap, "Height").SetValue(500);
// Set the offset to 0,0
CIntegerParameter(nodemap, "OffsetX").SetValue(0);
CIntegerParameter(nodemap, "OffsetY").SetValue(0);

// Set the width to the maximum value
Int64 maxWidth = camera.Parameters[PLCamera.Width].GetMaximum();
camera.Parameters[PLCamera.Width].SetValue(maxWidth);
// Set the height to 500
camera.Parameters[PLCamera.Height].SetValue(500);
// Set the offset to 0,0
camera.Parameters[PLCamera.OffsetX].SetValue(0);
camera.Parameters[PLCamera.OffsetY].SetValue(0);

/* Macro to check for errors */
#define CHECK(errc) if (GENAPI_E_OK != errc) printErrorAndExit(errc)
GENAPIC_RESULT errRes = GENAPI_E_OK;  /* Return value of pylon methods */
int64_t maxWidth = 0;
/* Set the width to the maximum value */
errRes = PylonDeviceGetIntegerFeatureMax(hdev, "Width", &maxWidth);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "Width", maxWidth);
CHECK(errRes);
/* Set the height to 500 */
errRes = PylonDeviceSetIntegerFeature(hdev, "Height", 500);
CHECK(errRes);
/* Set the offset to 0,0 */
errRes = PylonDeviceSetIntegerFeature(hdev, "OffsetX", 0);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "OffsetY", 0);
CHECK(errRes);

# Set the width to the maximum value
maxWidth = camera.Width.Max
camera.Width.Value = maxWidth
# Set the height to 500
camera.Height.Value = 500
# Set the offset to 0,0
camera.OffsetX.Value = 0
camera.OffsetY.Value = 0

Other Cameras#

C++ (Native)C++ (Generic)C#C (Generic)Python

// Set the width to the maximum value
int64_t maxWidth = camera.WidthMax.GetValue();
camera.Width.SetValue(maxWidth);
// Set the height to 500
camera.Height.SetValue(500);
// Set the offset to 0
camera.OffsetX.SetValue(0);
camera.OffsetY.SetValue(0);

INodeMap& nodemap = camera.GetNodeMap();
// Set the width to the maximum value
int64_t maxWidth = CIntegerParameter(nodemap, "WidthMax").GetValue();
CIntegerParameter(nodemap, "Width").SetValue(maxWidth);
// Set the height to 500
CIntegerParameter(nodemap, "Height").SetValue(500);
// Set the offset to 0
CIntegerParameter(nodemap, "OffsetX").SetValue(0);
CIntegerParameter(nodemap, "OffsetY").SetValue(0);

// Set the width to the maximum value
Int64 maxWidth = camera.Parameters[PLCamera.WidthMax].GetValue();
camera.Parameters[PLCamera.Width].SetValue(maxWidth);
// Set the height to 500
camera.Parameters[PLCamera.Height].SetValue(500);
// Set the offset to 0
camera.Parameters[PLCamera.OffsetX].SetValue(0);
camera.Parameters[PLCamera.OffsetY].SetValue(0);

/* Macro to check for errors */
#define CHECK(errc) if (GENAPI_E_OK != errc) printErrorAndExit(errc)
GENAPIC_RESULT errRes = GENAPI_E_OK;  /* Return value of pylon methods */
int64_t maxWidth = 0;
/* Set the width to the maximum value */
errRes = PylonDeviceGetIntegerFeature(hdev, "WidthMax", &maxWidth);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "Width", maxWidth);
CHECK(errRes);
/* Set the height to 500 */
errRes = PylonDeviceSetIntegerFeature(hdev, "Height", 500);
CHECK(errRes);
/* Set the offset to 0 */
errRes = PylonDeviceSetIntegerFeature(hdev, "OffsetX", 0);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "OffsetY", 0);
CHECK(errRes);

# Set the width to the maximum value
maxWidth = camera.WidthMax.Value
camera.Width.Value = maxWidth
# Set the height to 500
camera.Height.Value = 500
# Set the offset to 0
camera.OffsetX.Value = 0
camera.OffsetY.Value = 0

You can also use the pylon Viewer to easily set the parameters.