IDS Software Suite 4.96.1

Syntax

INT is_AOI (HIDS hCam, UINT nCommand, void* pParam, UINT nSizeOfParam)

Description

is_AOI() can be used to set the size and position of an area of interest (AOI) within an image. The AOI is always referred to the sensor. The following AOIs can be defined:

•Image AOI – display of an image portion

•Auto Brightness AOI – reference area of interest for automatic brightness control

•Auto Whitebalance AOI – reference area of interest for automatic white balance control

The available step widths for the position and size of image AOIs depend on the sensor. The values defining the position and size of an AOI have to be integer multiples of the allowed step widths. For details on the AOI grids of the individual camera models, please see Camera and sensor data.

The nCommand input parameter is used to select the function mode. The pParam input parameter depends on the selected function mode. If you select functions for setting or returning a value, pParam contains a pointer to a variable of the UINT type. The size of the memory area to which pParam refers is specified in the nSizeOfParam input parameter.

AOI for automatic image control

The AOI for automatic brightness control (AES/AGC) and automatic white balance (AWB) defaults to the same size as the current image (i.e. the image AOI).

After changes to the image geometry (by resetting an image AOI, by binning or subsampling), the AOIs for automatic image control will always be reset to the image AOI value. This means that it might be necessary to set the AOIs for auto brightness/auto white balance again manually.

Fast changes of AOI position

Using the IS_AOI_IMAGE_SET_POS_FAST command, you can change the positions of AOIs very quickly. Executing this command takes just a few milliseconds. When using this command, a few special requirements have to be met:

•The command is currently not supported by all uEye cameras. With the IS_AOI_IMAGE_GET_POS_FAST_SUPPORTED command, you can check whether your sensor supports fast position changes.

•Hot pixel correction has to be disabled (see is_HotPixel()).

•Image capture is not suspended for fast AOI position changes. As a result, when you call the command, a number of images might still be transferred with the old AOI position if they were in the driver buffer at that moment.

Changing the image size

When changing the size of the AOI, please make sure that the selected image memory is large enough. If it isn't, allocate a new image memory (see is_AllocImageMem()).

Changes to the image size affect the value ranges of the frame rate and exposure time. After executing is_AOI(), calling the following functions is recommended in order to keep the defined camera settings:

•is_SetFrameRate()

•is_Exposure()

•If you are using the flash function: is_IO()

More AOI functions

For some uEye camera models, you can set further special AOI functions:

Using the multi AOI function

Using the sequence AOI mode

Configuring the IDS line scan ("AOI merge mode")

Input parameters

Contents of the IS_RECT structure

Contents of the IS_POINT_2D structure

Contents of the IS_SIZE_2D structure

Return values

Related functions

•is_ImageFormat()

•is_SetBinning()

•is_SetSubSampling()

Sample 1 for AOI

// Sets the position and size of the image by using an object of the IS_RECT type.
IS_RECT rectAOI;
 
rectAOI.s32X     = 100;
rectAOI.s32Y     = 100;
rectAOI.s32Width = 200;
rectAOI.s32Height = 100;
 
INT nRet = is_AOI( hCam, IS_AOI_IMAGE_SET_AOI, (void*)&rectAOI, sizeof(rectAOI));

Sample 2 for AOI

// Returns the AOI position and size by using an object of the IS_RECT type.
IS_RECT rectAOI;
 
INT nRet = is_AOI(hCam, IS_AOI_IMAGE_GET_AOI, (void*)&rectAOI, sizeof(rectAOI));
if (nRet == IS_SUCCESS)
{
  INT x     = rectAOI.s32X;
  INT y     = rectAOI.s32Y;
  INT width = rectAOI.s32Width;
  INT height = rectAOI.s32Height;
}

Sample 3 for AOI

// Returns an UINT object indicating whether IS_AOI_IMAGE_POS_ABSOLUTE is set for the X position.
UINT nAbsPos = 0;
 
INT nRet = is_AOI(hCam, IS_AOI_IMAGE_GET_POS_X_ABS, (void*)&nAbsPos , sizeof(nAbsPos ));
if (nRet == IS_SUCCESS)
{
  if (nAbsPos == IS_AOI_IMAGE_POS_ABSOLUTE)
  {
      // set
  }
  else if (nAbsPos == 0)
  {
      // not set
  }
}

Sample 4 for AOI

// Query if fast AOI position changes are suppported
unsigned int fastAOIsupport = 0;
int nRet = is_AOI(m_hCam, IS_AOI_IMAGE_GET_POS_FAST_SUPPORTED, (void*)&fastAOIsupport, sizeof(fastAOIsupport));

Examples for setting absolute AOI positions in memory

x = 100

y = 100

x = 100 | IS_AOI_IMAGE_POS_ABSOLUTE

y = 100

x = 100 | IS_AOI_IMAGE_POS_ABSOLUTE

y = 100 | IS_AOI_IMAGE_POS_ABSOLUTE