|
|
|
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.
•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-3013XC
Sensor's internal white balance, photometry, backlight compensation, and anti flicker mode (see Automatic image control).
oUI-1007XS
Sensor's internal white balance
|
|
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.
|
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.
USB 3 uEye XC
•The auto contrast correction and backlight compensation functions cannot be used simultaneously.
•When the anti flicker mode is active, the auto exposure shutter settings must not be changed.
|
|
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_SENSOR_GAIN_SHUTTER
|
USB uEye XS: Enables/disables the auto exposure time/auto gain function. For the USB uEye XS the automatic control of the exposure time and gain can only be enabled/disabled together.
Note: If you want to set the exposure time manually, you must first disable the auto function (Example 3).
pval1 = 1 enables control, 0 disables control
|
|
IS_GET_ENABLE_AUTO_SENSOR_GAIN_SHUTTER
|
Returns the current auto exposure time/auto gain.
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_FLUORESCENT_NL •WB_MODE_FLUORESCENT_LAMP •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.
For the USB uEye XS the setpoint for auto gain control/auto exposure shutter is not a quantitavie setpoint for the middle image brightness but a qualitative one.
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.
For the USB uEye XS the auto brightness control may adjust the gain up before the maximum exposure time is achieved. Therefore, the auto gain value can exceed the set maximum value.
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 (UI-3013XC only)
|
IS_SET_SENS_AUTO_CONTRAST_CORRECTION
|
Sets the value for auto contrast correction.
|
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
|
|
Anti flicker mode (UI-3013XC only)
|
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 mode
|
|
Backlight compensation (UI-3013XC only)
|
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_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_AVERAGE •AS_PM_SENS_CENTER_WEIGHTED •AS_PM_SENS_CENTER_SPOT |
|
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 •AS_PM_SENS_CENTER_AVERAGE •AG_PM_SENS_CENTER_WEIGHTED •AG_PM_SENS_CENTER_SPOT |
|
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 •pval2: defines the blue level offset |
|
IS_GET_AUTO_WB_OFFSET
|
Returns the offset values for the red and blue channels.
•pval1: returns the red level offset •pval2: returns the blue level offset |
|
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
|
|
IS_GET_AUTO_WB_OFFSET_DEF
|
Returns the default offset for red and blue (Example 2).
|
IS_GET_AUTO_WB_OFFSET_MIN
|
Returns the minimum offset for red and blue (Example 2).
|
IS_GET_AUTO_WB_OFFSET_MAX
|
Returns the maximum offset for red and blue (Example 2).
|
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_MIN_AUTO_SPEED
|
Minimum value for auto speed
|
IS_MAX_AUTO_SPEED
|
Maximum value for auto speed
|
|
NULL is passed for the pval1, pval2 parameters.
|
IS_DEFAULT_AUTO_WB_OFFSET
|
Default value for auto white balance offset.
|
IS_MIN_AUTO_WB_OFFSET
|
Minimum value for auto white balance offset.
|
IS_MAX_AUTO_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
|
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.
|
Related functions
•is_ParameterSet()
•is_GetAutoInfo()
•is_SetHardwareGain()
•is_SetHWGainFactor()
•is_Exposure()
•is_SetFrameRate()
•is_AOI()
Example 1
//Enable auto gain control:
double dEnable = 1;
int ret = is_SetAutoParameter (hCam, IS_SET_ENABLE_AUTO_GAIN, &dEnable, 0);
//Set brightness setpoint to 128:
double nominal = 128;
int ret = is_SetAutoParameter (hCam, IS_SET_AUTO_REFERENCE, &nominal, 0);
//Return shutter control limit:
double maxShutter;
int ret = is_SetAutoParameter (hCam, IS_GET_AUTO_SHUTTER_MAX, &maxShutter, 0);
Example 2
// Query default offset of the XS
double dOffsetRDefault, dOffsetBDefault;
int ret = is_SetAutoParameter (hCam, IS_GET_AUTO_WB_OFFSET_DEF, &dOffsetRDefault, &dOffsetBDefault);
// Query minimum offset of the XS
double dOffsetRMin, dOffsetBMin;
int ret = is_SetAutoParameter (hCam, IS_GET_AUTO_WB_OFFSET_MIN, &dOffsetRMin, &dOffsetBMin);
// Query maximum offset of the XS
double dOffsetRMax, dOffsetBMax;
int ret = is_SetAutoParameter (hCam, IS_GET_AUTO_WB_OFFSET_MAX, &dOffsetRMax, &dOffsetBMax);
Example 3
// Disable auto exposure
double dblEnable = 0;
double dblDummy = 0;
ret = is_SetAutoParameter(m_hCam, IS_SET_ENABLE_AUTO_SENSOR_GAIN_SHUTTER, &dblEnable, &dblDummy);
// Set exposure manually
double newExposure = 50.0;
ret = is_Exposure(m_hCam, IS_EXPOSURE_CMD_SET_EXPOSURE, &newExposure, 8);
Suggestion for improvement? Send us your short
Feedback on this chapter.
Thank you very much!
