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 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 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_SET_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.

Multi AOI function of the UI-124x/UI-324x/UI-524x models

The sensor of the UI-124x/UI-324x/UI-524x models supports multiple AOIs in one image capture. The AOIs are transferred together as one image. In this mode you can create 2 or 4 AOIs, which have either the same X axis or the same Y axis (see also uEye Cockpit: Multi AOI). The sensor is faster in this mode.

It is possible to switch the AOI in the horizontal direction.

Sequence AOI mode for camera models UI-124x/UI-324x/UI-524x

The camera models UI-124x/UI-324x/UI-524x have a special AOI mode. In this mode you can define besides the normal AOI (AOI 1) up to 3 further AOI on the sensor (see uEye Cockpit: Sequence AOI). When activating the sequence mode, note that only the following combinations are possible:

1.All additional AOIs are off. AOI 1 is always active.

2.AOI 2 (+ AOI 1)

3.AOI 2 and 3 (+ AOI 1)

4.AOI 2, 3 and 4 (+ AOI 1)

It is not possible to have a combination e.g. of AOI 2 and AOI 4.

The parameters of AOI 2, 3 and 4 are defined by the AOI_SEQUENCE_PARAMS structure. In the version 4.00 binning, subsampling and scaler are not supported.

Input parameters

Contents of the IS_RECT Structure

Contents of the IS_POINT_2D Structure

Contents of the IS_SIZE_2D Structure

Content of the AOI_SEQUENCE_PARAMS 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

  }

}

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

Sample 1 for multi AOI

// Set Multi AOI. The axes are passed in an UINT array of length 8.

UINT nAxes[8];

 

nAxes[0] = 100;

nAxes[1] = 120;

...

 

INT nRet = is_AOI(hCam, IS_AOI_MULTI_SET_AOI | IS_AOI_MULTI_MODE_AXES, (void*)nAxes, sizeof(nAxes));

Sample 2 for multi AOI

// Read Multi AOI

UINT nAxes[8];

 

INT nRet = is_AOI(hCam, IS_AOI_MULTI_GET_AOI | IS_AOI_MULTI_MODE_AXES, (void*)nAxes, sizeof(nAxes));

Sample 3 for multi AOI

// Disable Multi AOI

UINT nAxes[8];

 

INT nRet = is_AOI(hCam, IS_AOI_MULTI_DISABLE_AOI | IS_AOI_MULTI_MODE_AXES, NULL, NULL);

Sample 1 for sequence AOI mode

INT nSequenceAOI = 0;

if (is_AOI(m_hCam, IS_AOI_SEQUENCE_GET_SUPPORTED,

          (void*)&nSequenceAOI, sizeof(nSequenceAOI)) == IS_SUCCESS)

{

// Sequence AOI 2 is supported

if ((nSequenceAOI & IS_AOI_SEQUENCE_INDEX_AOI_2) != 0);

}

Sample 2 for sequence AOI mode

AOI_SEQUENCE_PARAMS Param;

 

// Set parameters of AOI 2

Param.s32AOIIndex = IS_AOI_SEQUENCE_INDEX_AOI_2;

Param.s32NumberOfCycleRepetitions = 1;

Param.s32X = 100;

Param.s32Y = 200;

...

 

INT nRet = is_AOI(m_hCam, IS_AOI_SEQUENCE_SET_PARAMS, (void*)&Param, sizeof(Param));

 

// Get parameters of AOI 2

Param.s32AOIIndex = IS_AOI_SEQUENCE_INDEX_AOI_2;

 

nRet = is_AOI(m_hCam, IS_AOI_SEQUENCE_GET_PARAMS, (void*)&Param, sizeof(Param));

Sample 3 for sequence AOI mode

INT nMask = 0;

 

// Enable AOI 1, Disable AOI 2, 3 and 4

nMask = IS_AOI_SEQUENCE_INDEX_AOI_1;

 

INT nRet = is_AOI(m_hCam, IS_AOI_SEQUENCE_SET_ENABLE, (void*)&nMask, sizeof(nMask));

 

// Enable AOI 1 and 2

nMask = IS_AOI_SEQUENCE_INDEX_AOI_1 |

      IS_AOI_SEQUENCE_INDEX_AOI_2;

 

nRet = is_AOI(m_hCam, IS_AOI_SEQUENCE_SET_ENABLE, (void*)&nMask, sizeof(nMask));

 

// Enable AOI 1, 2 and 3

nMask = IS_AOI_SEQUENCE_INDEX_AOI_1 |

      IS_AOI_SEQUENCE_INDEX_AOI_2 |

      IS_AOI_SEQUENCE_INDEX_AOI_3;

 

nRet = is_AOI(m_hCam, IS_AOI_SEQUENCE_SET_ENABLE, (void*)&nMask, sizeof(nMask));

 

// Enable AOI 1, 2, 3 and 4

nMask = IS_AOI_SEQUENCE_INDEX_AOI_1 |

      IS_AOI_SEQUENCE_INDEX_AOI_2 |

      IS_AOI_SEQUENCE_INDEX_AOI_3 |

      IS_AOI_SEQUENCE_INDEX_AOI_4;

 

nRet = is_AOI(m_hCam, IS_AOI_SEQUENCE_SET_ENABLE, (void*)&nMask, sizeof(nMask));

 

// Get current AOI mask

INT nRet = is_AOI(m_hCam, IS_AOI_SEQUENCE_GET_ENABLE, (void*)&nMask, sizeof(nMask));

---

Suggestion for improvement? Send us your short Feedback on this chapter. Thank you very much!

For technical questions please contact you local distributor or use the support form on our website.

---

© 2012 IDS Imaging Development Systems GmbH
http://www.ids-imaging.com