is_SetAutoParameter

USB 2.0

USB 3.0

GigE

USB 2.0

USB 3.0

GigE

Syntax

INT is_SetAutoParameter (HIDS hCam, INT param, double* pval1, double* pval2)

Description

Using is_SetAutoParameter(), you can control the automatic gain, exposure shutter, frame rate and white balance control values. For HDR camera models UI-112x/UI-512x, you can use the IS_SET_ENABLE_AUTO_GAIN parameter to enable automatic white level adjustment (see also UI-112x/UI-512x application notes)

For further information on automatic control, please refer to the Automatic image control chapter.

Hinweis

•Control is only active as long as the camera is capturing images.

•A manual change of the exposure time and gain settings disables the auto functions.

•When the auto exposure shutter function is enabled, you cannot modify the pixel clock frequency.

•The auto frame rate function is only available when the auto shutter control is on. Auto frame rate and auto gain control cannot be used simultaneously.

•The auto gain function can only be used for cameras with master gain control. Auto white balance is only available for cameras with hardware RGB gain control.

•The sensor's internal auto features are only supported by the sensors of the following camera models.
Please also read the notes on using these sensors.

oUI-112x/UI-512x (HDR sensor)

oUI-122x/UI-322x/UI-522x

oUI-1008XS (uEye XS)

•The following functions are currently only supported by the USB uEye XS:
Sensor's internal white balance, photometry, auto contrast correction, backlight compensation, and anti flicker mode (see Automatic image control).

Hinweis

Notes on models with HDR sensor

In the UI-112x/UI-512x models with HDR sensor, some auto features have a different functionality or are not available:

•The HDR sensor has no gain. The AUTO_GAIN/AUTO_SENSOR_GAIN parameters control the white level adjustment (see UI-112x/UI-512x application notes chapter).

•The AUTO_SHUTTER/AUTO_SENSOR_SHUTTER, AUTO_FRAMERATE/AUTO_SENSOR_FRAMERATE and AUTO_SENSOR_WHITEBALANCE parameters are not available for this sensor.

Achtung

Notes on the sensor's internal control functionality

Automatic control by the sensor and the software is not possible simultaneously. To use the sensor's internal control functionality, disable software control, and vice versa.

Achtung

Notes on the USB uEye XS

•The auto contrast correction and backlight compensation functions cannot be used simultaneously.

•When the anti flicker function is active, the auto exposure shutter settings must not be changed.

Achtung

Note on automatic controls when using very high frame rates

Using very high frame rates can cause that too many control commands are sent to the camera. When using frame rates higher than 100 fps you should increase the value for IS_SET_AUTO_SKIPFRAMES. Thus, less image will be used for the automatic controls which takes load off the camera.

Input parameters

hCam

Camera handle

param

Configure auto function

IS_SET_ENABLE_AUTO_GAIN

Enables/disables the auto gain control function or, in case of HDR sensors, the white level adjustment

pval1 = 1 enables control, 0 disables control

IS_GET_ENABLE_AUTO_GAIN

Returns the current auto gain setting or white level adjustment

pval1: returns the current setting

IS_SET_ENABLE_AUTO_SENSOR_GAIN

Enables/disables the internal auto gain control function or, in case of HDR sensors, the white level adjustment of the sensor*1

pval1 = 1 enables control, 0 disables control

IS_GET_ENABLE_AUTO_SENSOR_GAIN

Returns the current auto gain setting or white level adjustment of the sensor*1

pval1: returns the current setting

IS_SET_ENABLE_AUTO_SHUTTER

Enables/disables the auto exposure shutter function.

pval1 = 1 enables control, 0 disables control

IS_GET_ENABLE_AUTO_SHUTTER

Returns the current auto exposure shutter setting.

pval1: returns the current setting

IS_SET_ENABLE_AUTO_SENSOR_SHUTTER

Enables/disables the sensor's internal auto exposure shutter function*1

pval1 = 1 enables control, 0 disables control

IS_GET_ENABLE_AUTO_SENSOR_SHUTTER

Returns the sensor's current auto exposure shutter setting*1

pval1: returns the current setting

IS_SET_ENABLE_AUTO_WHITEBALANCE

Enables/disables the auto white balance function.

pval1 = 1 enables control, 0 disables control

IS_GET_ENABLE_AUTO_WHITEBALANCE

Returns the current auto white balance setting.

pval1: returns the current setting

IS_SET_ENABLE_AUTO_SENSOR_WHITEBALANCE

Enables/disables the sensor's internal auto white balance function*1

pval1: white balance mode (see is_GetAutoInfo()):

•WB_MODE_DISABLE

•WB_MODE_AUTO

•WB_MODE_ALL_PULLIN

•WB_MODE_INCANDESCENT_LAMP

•WB_MODE_FLUORESCENT_DL

•WB_MODE_OUTDOOR_CLEAR_SKY

•WB_MODE_OUTDOOR_CLOUDY

IS_GET_ENABLE_AUTO_SENSOR_WHITEBALANCE

Returns the sensor's current auto white balance setting*1

pval1: returns the current setting

IS_SET_ENABLE_AUTO_FRAMERATE

Enables/disables the auto frame rate function.

pval1 = 1 enables control, 0 disables control

IS_GET_ENABLE_AUTO_FRAMERATE

Returns the current auto frame rate setting.

pval1: returns the current setting

IS_SET_ENABLE_AUTO_SENSOR_FRAMERATE

Enables/disables the sensor's internal auto frame rate function*1

pval1 = 1 enables control, 0 disables control

IS_GET_ENABLE_AUTO_SENSOR_FRAMERATE

Returns the sensor's current auto frame rate setting*1

pval1: returns the current setting

IS_SET_AUTO_REFERENCE

Sets the setpoint for auto gain control/auto exposure shutter.

pval1: defines the setpoint (average brightness of the image); the following rule applies independently of the image bit depth:

•0 = black

•128 = 50% gray (default)

•255 = white

When using the sensor's internal control functionality, you can only used values in a range between [44...235]. The increment in this range is 4. Smaller values are automatically set to 44, larger values to 235.

IS_GET_AUTO_REFERENCE

Returns the setpoint for auto gain control/auto exposure shutter.

pval1: returns the current setting

IS_SET_AUTO_GAIN_MAX

Sets the upper limit for auto gain control.

pval1: valid value for gain (0...100)

IS_GET_AUTO_GAIN_MAX

Returns the upper limit for auto gain control.

pval1: returns the current setting

IS_SET_AUTO_SHUTTER_MAX

Sets the upper limit for auto exposure shutter.

pval1: valid exposure value (0 sets the value continuously to max. exposure)

IS_GET_AUTO_SHUTTER_MAX

Returns the upper limit for auto exposure shutter.

pval1: returns the current setting

IS_SET_AUTO_BRIGHTNESS_ONCE

Enables/disables the automatic disable for automatic brightness control (gain and exposure time)*2

pval1 = 1 enables control, 0 disables control

IS_GET_AUTO_BRIGHTNESS_ONCE

Returns the automatic disable status*2

pval1: returns the current setting

Speed and hysteresis

IS_SET_AUTO_SPEED

Sets the speed value for the auto function.

pval1: defines the control speed (0...100)

IS_GET_AUTO_SPEED

Returns the speed value for the auto function.

pval1: returns the current setting

IS_SET_AUTO_SKIPFRAMES

Sets the number of frames to be skipped during automatic control.

pval1: defines the number of frames to be skipped during automatic control (default: 4)

IS_GET_AUTO_SKIPFRAMES

Returns the number of frames to be skipped during automatic control.

pval1: returns the current setting

IS_GET_AUTO_SKIPFRAMES_RANGE

Returns the permissible range for the number of frames to be skipped.

•pval1: returns the minimum permitted value

•pval2: returns the maximum permitted value

IS_SET_AUTO_HYSTERESIS

Sets the hysteresis value for auto exposure shutter and auto gain control.

pval1: defines the hysteresis value (default: 2)

IS_GET_AUTO_HYSTERESIS

Returns the hysteresis value for auto exposure shutter and auto gain control.

pval1: returns the current setting

IS_GET_AUTO_HYSTERESIS_RANGE

Returns the permissible range for the hysteresis value.

•pval1: returns the minimum permitted value

•pval2: returns the maximum permitted value

Auto contrast correction (with face detection)/backlight compensation/anti flicker (USB uEye XS only)

IS_SET_SENS_AUTO_CONTRAST_CORRECTION

Sets the value for auto contrast correction.

pval1: EV value

IS_GET_SENS_AUTO_CONTRAST_CORRECTION

Returns the value for auto contrast correction.

pval1: returns the current setting

IS_GET_SENS_AUTO_CONTRAST_CORRECTION_RANGE

Returns the permissible range for auto contrast correction.

•pval1: returns the minimum permitted value

•pval2: returns the maximum permitted value

IS_GET_SENS_AUTO_CONTRAST_CORRECTION_INC

Returns the increment for auto contrast correction.

pval1: returns the increment

IS_GET_SENS_AUTO_CONTRAST_CORRECTION_DEF

Returns the default value for auto contrast correction.

pval1: returns the default

IS_SET_SENS_AUTO_CONTRAST_FDT_AOI_ENABLE

Enables the use of face detection as field of view for automatic brightness control. If face detection is disabled, this setting will not become effective until face detection is enabled. The auto exposure shutter and auto gain control functions have to be enabled.

pval1 = 1 enables, 0 disables the function

IS_GET_SENS_AUTO_CONTRAST_FDT_AOI_ENABLE

Returns the status of using face detection as field of view for automatic brightness control.

pval1: returns the current setting

IS_SET_SENS_AUTO_BACKLIGHT_COMP

Enables backlight compensation for automatic brightness control.

pval1 = 1 enables, 0 disables the function

IS_GET_SENS_AUTO_BACKLIGHT_COMP

Returns the backlight compensation status.

pval1: returns the current setting

IS_SET_ANTI_FLICKER_MODE

Sets the anti flicker mode.

pval1: Anti flicker mode (see is_GetAutoInfo()):

•ANTIFLCK_MODE_OFF

•ANTIFLCK_MODE_SENS_AUTO

•ANTIFLCK_MODE_SENS_50_FIXED

•ANTIFLCK_MODE_SENS_60_FIXED

IS_GET_ANTI_FLICKER_MODE

Returns the anti flicker mode.

pval1: returns the current mode.

IS_GET_ANTI_FLICKER_MODE_DEF

Returns the default anti flicker mode.

pval1: returns the default

IS_SET_SENS_AUTO_SHUTTER_PHOTOM

Sets the photometry mode for auto exposure shutter.

pval1: defines which fields of view are used for auto exposure shutter (see is_GetAutoInfo()):

•AS_PM_NONE

•AS_PM_SENS_CENTER_WEIGHTED

•AS_PM_SENS_CENTER_SPOT

•AS_PM_SENS_PORTRAIT

•AS_PM_SENS_LANDSCAPE

IS_GET_SENS_AUTO_SHUTTER_PHOTOM

Returns the photometry mode for auto exposure shutter.

pval1: returns the current setting

IS_GET_SENS_AUTO_SHUTTER_PHOTOM_DEF

Returns the default photometry mode for auto exposure shutter.

pval1: returns the default

IS_SET_SENS_AUTO_GAIN_PHOTOM

Sets the photometry mode for auto gain control.

pval1: defines which fields of view are used for auto gain control (see is_GetAutoInfo()):

•AG_PM_NONE

•AG_PM_SENS_CENTER_WEIGHTED

•AG_PM_SENS_CENTER_SPOT

•AG_PM_SENS_PORTRAIT

•AG_PM_SENS_LANDSCAPE

IS_GET_SENS_AUTO_GAIN_PHOTOM

Returns the photometry mode for auto gain control.

pval1: returns the current setting

IS_GET_SENS_AUTO_GAIN_PHOTOM_DEF

Returns the default photometry mode for auto gain control.

pval1: returns the default

IS_SET_AUTO_WB_OFFSET

Sets the offset values for the red and blue channels.

•pval1: defines the red level offset (-50...50)

•pval2: defines the blue level offset (-50...50)

IS_GET_AUTO_WB_OFFSET

Returns the offset values for the red and blue channels.

•pval1: returns the red level offset (-50...50)

•pval2: returns the blue level offset (-50...50)

IS_SET_AUTO_WB_GAIN_RANGE

Sets the color gain limits for auto white balance.

•pval1: sets the lowest gain value

•pval2: sets the highest gain value

IS_GET_AUTO_WB_GAIN_RANGE

Returns the color gain limits for auto white balance.

•pval1: returns the minimum permitted gain value

•pval2: returns the maximum permitted gain value

IS_SET_AUTO_WB_ONCE

Sets automatic disabling of auto white balance*2

pval1 = 1 enables control, 0 disables control

IS_GET_AUTO_WB_ONCE

Returns the automatic disable status*2

pval1: returns the current setting

Speed and hysteresis

IS_SET_AUTO_WB_SPEED

Sets the speed for auto white balance.

pval1: defines the control speed (0...100)

IS_GET_AUTO_WB_SPEED

Returns the speed for auto white balance.

pval1: returns the current setting

IS_SET_AUTO_WB_HYSTERESIS

Sets the hysteresis value for auto white balance.

pval1: defines the hysteresis value (default: 2)

IS_GET_AUTO_WB_HYSTERESIS

Returns the hysteresis value for auto white balance.

pval1: returns the current setting

IS_GET_AUTO_WB_HYSTERESIS_RANGE

Returns the permissible range for the hysteresis value.

•pval1: returns the minimum permitted value

•pval2: returns the maximum permitted value

IS_SET_AUTO_WB_SKIPFRAMES

Sets the number of frames to be skipped during automatic control.

pval1: defines the number (default: 4)

IS_GET_AUTO_WB_SKIPFRAMES

Returns the number of frames to be skipped during automatic control.

pval1: returns the current setting

IS_GET_AUTO_WB_SKIPFRAMES_RANGE

Returns the permissible range for the number of frames to be skipped.

•pval1: returns the minimum permitted value

•pval2: returns the maximum permitted value

NULL is passed for the pval1, pval2 parameters.
IS_DEFAULT_AUTO_BRIGHT_REFERENCE	Default setpoint for auto gain control and auto exposure shutter.
IS_MIN_AUTO_BRIGHT_REFERENCE	Minimum setpoint for auto gain control and auto exposure shutter.
IS_MAX_AUTO_BRIGHT_REFERENCE	Maximum setpoint for auto gain control and auto exposure shutter.
IS_DEFAULT_AUTO_SPEED	Default value for auto speed.
IS_MAX_AUTO_SPEED	Maximum value for auto speed

NULL is passed for the pval1, pval2 parameters.
IS_MIN_WB_OFFSET	Minimum value for auto white balance offset.
IS_MAX_WB_OFFSET	Maximum value for auto white balance offset.
IS_DEFAULT_AUTO_WB_SPEED	Default value for auto white balance speed.
IS_MIN_AUTO_WB_SPEED	Minimum value for auto white balance speed.
IS_MAX_AUTO_WB_SPEED	Maximum value for auto white balance speed.

pval1

Control parameter, can have a variable value depending on the corresponding auto function

pval2

Control parameter, can have a variable value depending on the corresponding auto function

*1 Not all sensors support this feature (see information box)

*2 Not with use of sensor's internal control functionality

Return values

IS_CANT_COMMUNICATE_WITH_DRIVER	Communication with the driver failed because no driver has been loaded.
IS_CANT_OPEN_DEVICE	An attempt to initialize or select the camera failed (no camera connected or initialization error).
IS_INCOMPATIBLE_SETTING	Because of other incompatible settings the function is not possible.
IS_INVALID_CAMERA_TYPE	The camera type defined in the .ini file does not match the current camera model.
IS_INVALID_CAMERA_HANDLE	Invalid camera handle
IS_INVALID_MODE	Camera is in standby mode, function not allowed
IS_INVALID_PARAMETER	One of the submitted parameters is outside the valid range or is not supported for this sensor or is not available in this mode.
IS_INVALID_WB_BINNING_MODE	Mono binning/mono sub-sampling do not support automatic white balance.
IS_IO_REQUEST_FAILED	An IO request from the uEye driver failed. Possibly the versions of the ueye_api.dll (API) and the driver file (ueye_usb.sys or ueye_eth.sys) do not match.
IS_NO_SUCCESS	General error message
IS_NOT_CALIBRATED	The camera does not contain any calibration data.
IS_NOT_SUPPORTED	The camera model used here does not support this function or setting.
IS_NULL_POINTER	Invalid array
IS_SUCCESS	Function executed successfully
IS_TIMED_OUT	A timeout occurred. An image capturing process could not be terminated within the allowable period.