Home > C: Programming > Function Descriptions > History back  Previous chapter  Next chapter  Print  

is_AOI

uEye Camera Manual Version 3.80

is_AOI

Windows_Logo

Linux_Logo

USB 2.0

GigE

USB 2.0

GigE

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.

Hinweis

Note on previous AOI functions

The is_AOI() function comprises all the functions for setting and positioning an AOI. The following uEye API commands are therefore obsolete:

is_SetAOI()
is_SetImageAOI()
is_SetImageSize()
is_SetImagePos()

See also Obsolete Functions.

Achtung

Note on 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:
oIf you are using the uEye's flash function: is_SetFlashStrobe()

Achtung

Note on step widths for AOI definition (position grid)

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 and click a camera model.

Hinweis

Note on 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.

Hinweis

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

The sensor of the UI-124x/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 Demo: Multi AOI). The sensor is faster in this mode.

Hinweis

Note on fast AOI position changes

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.

Input Parameters

hCam

Camera handle

nCommand

 

IS_AOI_IMAGE_SET_AOI

Sets the position and size of the image by using an object of the IS_RECT type. You can define the start position of the AOI in the memory by ORing IS_AOI_IMAGE_POS_ABSOLUTE with the X or Y position.

Code sample

IS_AOI_IMAGE_GET_AOI

Returns the AOI in an IS_RECT object.

Code sample

IS_AOI_IMAGE_SET_POS

Sets the AOI position by using an object of the IS_POINT_2D type. IS_AOI_IMAGE_POS_ABSOLUTE can be ORed here, as well.

IS_AOI_IMAGE_GET_POS

Returns the position in an IS_POINT_2D object.

IS_AOI_IMAGE_SET_SIZE

Sets the AOI size by using an object of the IS_SIZE_2D type.

IS_AOI_IMAGE_GET_SIZE

Returns the size in an IS_SIZE_2D object.

IS_AOI_IMAGE_GET_POS_MIN

Returns the minimum possible position in an IS_POINT_2D object.

IS_AOI_IMAGE_GET_SIZE_MIN

Returns the smallest possible size in an IS_SIZE_2D object.

IS_AOI_IMAGE_GET_POS_MAX

Returns the maximum possible position in an IS_POINT_2D object.

IS_AOI_IMAGE_GET_SIZE_MAX

Returns the largest possible size in an IS_SIZE_2D object.

IS_AOI_IMAGE_GET_POS_INC

Returns the increment for the position in an IS_POINT_2D object.

IS_AOI_IMAGE_GET_SIZE_INC

Returns the increment for the size in an IS_SIZE_2D object.

IS_AOI_IMAGE_GET_POS_X_ABS

Returns an UINT object indicating whether IS_AOI_IMAGE_POS_ABSOLUTE is set for the X position.

Code sample

IS_AOI_IMAGE_GET_POS_Y_ABS

Returns an UINT object indicating whether IS_AOI_IMAGE_POS_ABSOLUTE is set for the Y position.

IS_AOI_IMAGE_GET_ORIGINAL_AOI

Returns the AOI in an IS_RECT object without binning, subsampling or scaling.

IS_AOI_IMAGE_SET_POS_FAST

Allows changing the AOI position very quickly by using an IS_POINT_2D object. Hot pixel correction has to be disabled (see information box above).

IS_AOI_IMAGE_SET_POS_FAST_SUPPORTED

Returns an UINT object indicating whether fast AOI position changes are supported. The passed variable returns 0 if the function is not supported by the sensor.

IS_AOI_AUTO_BRIGHTNESS_SET_AOI

Sets the AOI for automatic brightness control (similar to IS_AOI_IMAGE_SET_AOI).

IS_AOI_AUTO_BRIGHTNESS_GET_AOI

Returns the AOI for automatic brightness control (similar to IS_AOI_IMAGE_GET_AOI).

IS_AOI_AUTO_WHITEBALANCE_SET_AOI

Sets the AOI for automatic white balance (similar to IS_AOI_IMAGE_SET_AOI).

IS_AOI_AUTO_WHITEBALANCE_GET_AOI

Returns the AOI for automatic white balance (similar to IS_AOI_IMAGE_GET_AOI).

IS_AOI_MULTI_GET_SUPPORTED_MODES

Returns the supported Multi AOI modes in an UINT object.

IS_AOI_MULTI_SET_AOI

Sets the Multi AOI mode. The mode you want to use has to be ORed with IS_AOI_MULTI_SET_AOI.

Code sample

IS_AOI_MULTI_GET_AOI

Returns the set Multi AOI mode. The mode that is used has to be ORed with IS_AOI_MULTI_SET_AOI.

Code sample

IS_AOI_MULTI_DISABLE_AOI

Disables Multi AOI. The mode that is used has to be ORed with IS_AOI_MULTI_SET_AOI.

Code sample

pParam

Pointer to a function parameter; which function parameter is referred to here depends on nCommand.

nSizeOfParam

Size (in bytes) of the memory area to which pParam refers.

Contents of the IS_RECT Structure

INT

s32X

X position of the AOI

INT

s32Y

Y position of the AOI

INT

s32Width

Width of the AOI

INT

s32Height

Height of the AOI

Contents of the IS_POINT_2D Structure

INT

s32X

X position of the AOI

INT

s32Y

Y position of the AOI

Contents of the IS_SIZE_2D Structure

INT

s32Width

Width of the AOI

INT

s32Height

Height of the AOI

Return Values

IS_SUCCESS

Function executed successfully

IS_NO_SUCCESS

General error message

Related Functions

is_ImageFormat()
is_SetBinning()
is_SetSubSampling()

Code Samples for AOI

// Sets the position and size of the image by using an object of the IS_RECT type.

IS_RECT rectAOI;

 

sizeAOI.s32X     = 100;

sizeAOI.s32Y     = 100;

rectAOI.s32Width = 200;

rectAOI.s32Height = 100;

 

INT nRet = is_AOI( hCam, IS_AOI_IMAGE_SET_AOI, (void*)&rectAOI, sizeof(rectAOI));

 

// Returns the AOI position by using an object of the IS_POINT_2D 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;

}

 

// 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

  }

}

Funktion_is_SetImagePos_1

Funktion_is_SetImagePos_2

Figure 148: Examples of setting the AOI position in the memory

Figure 148: Examples of setting the AOI position in the memory

Code Samples 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));

 

// 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));

 

// Disable Multi AOI

UINT nAxes[8];

 

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

 


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


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