Focus settings for uEye LE USB 3.1 Gen 1 AF


uEye LE USB 3.1 Gen 1 AF	uEye LE USB 3.1 Gen 1 AF

Syntax

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

Description

The focus measure window of uEye LE USB 3.1 Gen 1 AF is an AOI that can be moved, enlarged or reduced.

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.

Input parameters

hCam

Camera handle

Autofocus algorithms
FOC_CMD_GET_AUTOFOCUS_SUPPORTED_SHARPNESS_CALCULATION_ALGORITHM	Returns the algorithms for sharpness calculation of the autofocus (AUTOFOCUS_SHARPNESS_CALCULATION_ALGORITHM) supported by the camera. •pParam: Pointer to variable of type UINT. The bit mask returns: AUTOFOCUS_SHARPNESS_CALCULATION_ALGORITHM_TENENGRAD AUTOFOCUS_SHARPNESS_CALCULATION_ALGORITHM_MEAN_SCORE AUTOFOCUS_SHARPNESS_CALCULATION_ALGORITHM_HISTOGRAM_VARIANCE •nSizeOfParam: 4
FOC_CMD_SET_AUTOFOCUS_SHARPNESS_CALCULATION_ALGORITHM	Sets the algorithm for sharpness calculation of the autofocus. •pParam: Pointer to variable of type Typ UINT •nSizeOfParam: 4
FOC_CMD_GET_AUTOFOCUS_SHARPNESS_CALCULATION_ALGORITHM	Returns the set algorithm for sharpness calculation of the autofocus. •pParam: Pointer to variable of type UINT •nSizeOfParam: 4
FOC_CMD_GET_AUTOFOCUS_SHARPNESS_CALCULATION_ALGORITHM_DEFAULT	Returns the default algorithm for sharpness calculation of the autofocus. •pParam: Pointer to variable of type UINT •nSizeOfParam: 4
FOC_CMD_GET_AUTOFOCUS_ONCE_SUPPORTED_PEAK_SEARCH_ALGORITHM	Returns the peak search algorithms (AUTOFOCUS_ONCE_PEAK_SEARCH_ALGORITHM) supported by the camera for the autofocus. •pParam: Pointer to variable of type UINT. The bit mask returns: AUTOFOCUS_ONCE_PEAK_SEARCH_ALGORITHM_GOLDEN_RATIO_SEARCH AUTOFOCUS_ONCE_PEAK_SEARCH_ALGORITHM_HILL_CLIMBING_SEARCH AUTOFOCUS_ONCE_PEAK_SEARCH_ALGORITHM_GLOBAL_SEARCH AUTOFOCUS_ONCE_PEAK_SEARCH_ALGORITHM_FULL_SCAN •nSizeOfParam: 4
FOC_CMD_SET_AUTOFOCUS_ONCE_PEAK_SEARCH_ALGORITHM	Sets the peak search algorithm for the autofocus. •pParam: Pointer to variable of type UINT •nSizeOfParam: 4
FOC_CMD_GET_AUTOFOCUS_ONCE_PEAK_SEARCH_ALGORITHM	Returns the set peak search algorithm for the autofocus. •pParam: Pointer to variable of type UINT •nSizeOfParam: 4
FOC_CMD_GET_AUTOFOCUS_ONCE_PEAK_SEARCH_ALGORITHM_DEFAULT	Returns the default peak search algorithm for the autofocus. •pParam: Pointer to variable of type UINT •nSizeOfParam: 4
Autofocus AOI
FOC_CMD_GET_AUTOFOCUS_NUMBER_OF_SUPPORTED_AOIS	Returns the number of supported focus AOIs. •pParam: Pointer to variable of type UINT •nSizeOfParam: 4
FOC_CMD_SET_AUTOFOCUS_AOI	Sets the focus AOI for the autofocus. •pParam: Pointer to structure of type AUTOFOCUS_AOI •nSizeOfParam: 24
FOC_CMD_GET_AUTOFOCUS_AOI	Returns the set focus AOI for the autofocus. •pParam: Pointer to structure of type AUTOFOCUS_AOI •nSizeOfParam: 24
FOC_CMD_GET_AUTOFOCUS_AOI_SIZE_MIN	Returns the minimum focus AOI for the autofocus. •pParam: Pointer to structure of type IS_SIZE_2D •nSizeOfParam: 8
FOC_CMD_SET_AUTOFOCUS_AOI_PRESET	Sets a predefined set (AUTOFOCUS_AOI_PRESET) of supported focus AOI. •pParam: Pointer to variable of type UINT. The bit mask returns: AUTOFOCUS_AOI_PRESET_CENTER •nSizeOfParam: 4
Autofocus parameters
FOC_CMD_SET_AUTOFOCUS_LIMIT	Sets the minimum and maximum limit for the focus search range. •pParam: Pointer to structure of type AUTOFOCUS_LIMIT •nSizeOfParam: 8
FOC_CMD_GET_AUTOFOCUS_LIMIT	Returns the minimum and maximum limit for the focus search range. •pParam: Pointer to structure of type AUTOFOCUS_LIMIT •nSizeOfParam: 8
FOC_CMD_GET_AUTOFOCUS_LIMIT_DEFAULT	Returns the minimum and maximum limit for the default focus search range. •pParam: Pointer to structure of type AUTOFOCUS_LIMIT •nSizeOfParam: 8
FOC_CMD_SET_AUTOFOCUS_LENS_RESPONSE_TIME	Sets the response time of the lens (positioning time) in milliseconds. •pParam: Pointer to variable of type WORD •nSizeOfParam: 2
FOC_CMD_GET_AUTOFOCUS_LENS_RESPONSE_TIME	Returns the response time of the lens (positioning time) in milliseconds. •pParam: Pointer to variable of type WORD •nSizeOfParam: 2
FOC_CMD_GET_AUTOFOCUS_LENS_RESPONSE_TIME_DEFAULT	Returns the default response time of the lens (positioning time) in milliseconds. •pParam: Pointer to variable of type WORD •nSizeOfParam: 2
FOC_CMD_SET_AUTOFOCUS_HYSTERESIS	Sets the hysteresis value ("search accuracy"). •pParam: Pointer to variable of type BYTE •nSizeOfParam: 1
FOC_CMD_GET_AUTOFOCUS_HYSTERESIS	Returns the hysteresis value ("search accuracy"). •pParam: Pointer to variable of type BYTE •nSizeOfParam: 1
FOC_CMD_GET_AUTOFOCUS_HYSTERESIS_DEFAULT	Returns the default hysteresis value ("search accuracy"). •pParam: Pointer to variable of type BYTE •nSizeOfParam: 1
Callback function
FOC_CMD_SET_AUTOFOCUS_CALLBACK	Callback function: If manual focus and a once-only automatic control are active, the function registered via the pfFunc parameter is called with the arguments focus value, the corresponding sharpness value and the value specified during registration for the pContext parameter. •pParam: Pointer to structure of type AUTOFOCUS_CALLBACK •nSizeOfParam: 16 Note: Only short and non-blocking code should be executed in the registered function.

pParam

Pointer to a function parameter, whose function depends on nCommand.

nSizeOfParam

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

Contents of the AUTOFOCUS_AOI structure

UNIT

uNumberAOI

Number of the focus measure window

IS_RECT

rcAOI

Defines the upper left corner (s32X, s32Y) as well as the width (s23Width) and height (s32Height) of the focus measure window.

AUTOFOCUS_AOI_WEIGHT

eWeight

Defines the weighting of the zone:

•AUTOFOCUS_AOI_WEIGHT_MIDDLE

Contents of the IS_SIZE_2D structure

INT	s32Width	AOI width
INT	s32Height	AOI height

Contents of the AUTOFOCUS_LIMIT structure

UINT	uMin	Defines the minimum limit of the focus search range for the peak search algorithm.
UINT	uMax	Defines the maximum limit of the focus search range for the peak search algorithm.

Contents of the AUTOFOCUS_CALLBACK structure

IS_AUTOFOCUS_CALLBACK_FUNC

pfFunc

•Focus value of the type UINT

•Sharpness value of the type INT

void*

pContext

•pContext of the type void*

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_INVALID_CAPTURE_MODE	The function can not be executed in the current camera operating mode (free run, trigger or standby).
IS_INVALID_CAMERA_HANDLE	Invalid camera handle
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_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_SUPPORTED	The camera model used here does not support this function or setting.
IS_SUCCESS	Function executed successfully

Example 1

UINT supported_sharpness_calculation_algorithm;
INT nRet = is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_SUPPORTED_SHARPNESS_CALCULATION_ALGORITHM, &supported_sharpness_calculation_algorithm, sizeof(supported_sharpness_calculation_algorithm));

if (IS_SUCCESS == nRet)
{
UINT sharpness_calculation_algorithm;
if (AUTOFOCUS_SHARPNESS_CALCULATION_ALGORITHM_MEAN_SCORE == (supported_sharpness_calculation_algorithm & AUTOFOCUS_SHARPNESS_CALCULATION_ALGORITHM_MEAN_SCORE))
{
sharpness_calculation_algorithm = AUTOFOCUS_SHARPNESS_CALCULATION_ALGORITHM_MEAN_SCORE;
}
else
{
is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_SHARPNESS_CALCULATION_ALGORITHM_DEFAULT, &sharpness_calculation_algorithm, sizeof(sharpness_calculation_algorithm));
}

nRet = is_Focus(m_hCam, FOC_CMD_SET_AUTOFOCUS_SHARPNESS_CALCULATION_ALGORITHM, &sharpness_calculation_algorithm, sizeof(sharpness_calculation_algorithm));
if (IS_SUCCESS == nRet)
{
sharpness_calculation_algorithm = 0;
nRet = is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_SHARPNESS_CALCULATION_ALGORITHM, &sharpness_calculation_algorithm, sizeof(sharpness_calculation_algorithm));

if (IS_SUCCESS == nRet)
{
// print sharpness_calculation_algorithm
...
}
}
}

Example 2

UINT supported_search_peak_algorithm;
INT nRet = is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_ONCE_SUPPORTED_PEAK_SEARCH_ALGORITHM, &supported_search_peak_algorithm, sizeof(supported_search_peak_algorithm));

if (IS_SUCCESS == nRet)
{
UINT search_peak_algorithm;
if (AUTOFOCUS_ONCE_PEAK_SEARCH_ALGORITHM_HILL_CLIMBING == (supported_search_peak_algorithm & AUTOFOCUS_ONCE_PEAK_SEARCH_ALGORITHM_HILL_CLIMBING_SEARCH))
{
search_peak_algorithm = AUTOFOCUS_ONCE_PEAK_SEARCH_ALGORITHM_HILL_CLIMBING_SEARCH;
}
else
{
is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_ONCE_PEAK_SEARCH_ALGORITHM_DEFAULT, &search_peak_algorithm, sizeof(search_peak_algorithm));
}

nRet = is_Focus(m_hCam, FOC_CMD_SET_AUTOFOCUS_ONCE_PEAK_SEARCH_ALGORITHM, &search_peak_algorithm, sizeof(search_peak_algorithm));
if (IS_SUCCESS == nRet)
{
search_peak_algorithm = 0;
nRet = is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_ONCE_PEAK_SEARCH_ALGORITHM, &search_peak_algorithm, sizeof(search_peak_algorithm));

if (IS_SUCCESS == nRet)
{
// print search_peak_algorithm
...
}
}
}

Example 3

UINT number_of_supported_focus_aois;
INT nRet = is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_NUMBER_OF_SUPPORTED_AOIS, &number_of_supported_focus_aois, sizeof(number_of_supported_focus_aois));

if ((IS_SUCCESS == nRet) && (0 < number_of_supported_focus_aois))
{
IS_SIZE_2D focus_aoi_min_size;
nRet = is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_AOI_SIZE_MIN, &focus_aoi_min_size, sizeof(focus_aoi_min_size));

AUTOFOCUS_AOI focus_aoi;
focus_aoi.uNumberAOI = 1;
focus_aoi.rcAOI.s32X = 200;
focus_aoi.rcAOI.s32Y = 200;
focus_aoi.rcAOI.s32Width = focus_aoi_min_size.s32Width;
focus_aoi.rcAOI.s32Height = focus_aoi_min_size.s32Height;
focus_aoi.eWeight = AUTOFOCUS_AOI_WEIGHT_MIDDLE;

nRet = is_Focus(m_hCam, FOC_CMD_SET_AUTOFOCUS_AOI, &focus_aoi, sizeof(focus_aoi));

if (IS_SUCCESS == nRet)
{
memset(&focus_aoi, 0, sizeof(focus_aoi));
nRet = is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_AOI, &focus_aoi, sizeof(focus_aoi));

if (IS_SUCCESS == nRet)
{
// print focus_aoi
...
}
}

AUTOFOCUS_AOI_PRESET aoi_preset = AUTOFOCUS_AOI_PRESET_CENTER;
nRet = is_Focus(m_hCam, FOC_CMD_SET_AUTOFOCUS_AOI_PRESET, &aoi_preset, sizeof(aoi_preset));

if (IS_SUCCESS == nRet)
{
AUTOFOCUS_AOI focus_aoi_preset;
nRet = is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_AOI, &focus_aoi_preset, sizeof(focus_aoi_preset));

if (IS_SUCCESS == nRet)
{
// print focus_aoi_preset
...
}
}
}

Example 4

AUTOFOCUS_LIMIT autofocus_limit_default;
INT nRet = is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_LIMIT_DEFAULT, &autofocus_limit_default, sizeof(autofocus_limit_default));

if (IS_SUCCESS == nRet)
{
AUTOFOCUS_LIMIT autofocus_limit;
autofocus_limit.sMin = -1;
autofocus_limit.sMax = 500;

nRet = is_Focus(m_hCam, FOC_CMD_SET_AUTOFOCUS_LIMIT, &autofocus_limit, sizeof(autofocus_limit));

if (IS_SUCCESS == nRet)
{
autofocus_limit.sMin = 0;
autofocus_limit.sMax = 0;

nRet = is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_LIMIT, &autofocus_limit, sizeof(autofocus_limit));

if (IS_SUCCESS == nRet)
{
// print autofocus_limit
...
}
}
}

Example 5

WORD autofocus_lens_response_time_default;
INT nRet = is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_LENS_RESPONSE_TIME_DEFAULT, &autofocus_lens_response_time_default, sizeof(autofocus_lens_response_time_default));

if (IS_SUCCESS == nRet)
{
nRet = is_Focus(m_hCam, FOC_CMD_SET_AUTOFOCUS_LENS_RESPONSE_TIME, &autofocus_lens_response_time_default, sizeof(autofocus_lens_response_time_default));

if (IS_SUCCESS == nRet)
{
WORD autofocus_lens_response_time;
nRet = is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_LENS_RESPONSE_TIME, &autofocus_lens_response_time, sizeof(autofocus_lens_response_time));

if (IS_SUCCESS == nRet)
{
// print autofocus_lens_response_time
...
}
}
}

Example 6

WORD autofocus_hysteresis_default;
INT nRet = is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_HYSTERESIS_DEFAULT, &autofocus_hysteresis_default, sizeof(autofocus_hysteresis_default));

if (IS_SUCCESS == nRet)
{
nRet = is_Focus(m_hCam, FOC_CMD_SET_AUTOFOCUS_HYSTERESIS, &autofocus_hysteresis_default, sizeof(autofocus_hysteresis_default));

if (IS_SUCCESS == nRet)
{
WORD autofocus_hysteresis;
nRet = is_Focus(m_hCam, FOC_CMD_GET_AUTOFOCUS_HYSTERESIS, &autofocus_hysteresis, sizeof(autofocus_hysteresis));

if (IS_SUCCESS == nRet)
{
// print autofocus_hysteresis
...
}
}
}

Example 7

// callback function
void print_focus_sharpness(UINT focus, INT sharpness, void*)
{
// print focus, sharpness
...
}

AUTOFOCUS_CALLBACK autofocus_callback;
autofocus_callback.pfFunc = print_focus_sharpness;
autofocus_callback.pContext = NULL;

INT nRet = is_Focus(m_hCam, FOC_CMD_SET_AUTOFOCUS_CALLBACK, &autofocus_callback, sizeof(autofocus_callback));

if (IS_SUCCESS == nRet)
{
is_Focus(m_hCam, FOC_CMD_SET_ENABLE_AUTOFOCUS_ONCE, NULL, 0);
}

Suggestion for improvement? Send us your short Feedback on this chapter. Thank you very much!
For technical questions please contact your local distributor or use the support form on our website.