MdigFocus

Specifies the identifier of the digitizer. If you want to provide the image (that is, either have the user-defined function perform the grab, or use an existing image) set this parameter to M_NULL. The provided image must be stored in the destination image buffer.

Specifies the identifier of the buffer that contains the image to analyze or in which to grab. This buffer should be of an appropriate type to hold the image. This buffer cannot be a signed 3-band buffer, a 32-bit buffer, or a 1-bit buffer.

This image buffer must not have a region of interest (ROI) associated with it. Using an image buffer with an ROI will cause an error.

Specifies the identifier of a child buffer of the destination buffer. Analysis of each grabbed image is limited to the region specified by this buffer. To analyze the entire image, set this parameter to M_DEFAULT.

You should pass a child buffer when there are objects at different distances within the camera's field of view; this is because in this case, each object will have a different optimum focus position.

This child buffer must not have a region of interest (ROI) associated with it. Using a child buffer with an ROI will cause an error.

Specifies the address of the user-defined function to call before each grab. When only calculating the focus indicator (that is, using the M_EVALUATE operation mode), this parameter is not used, and must be set to M_NULL.

The user-defined function must be declared as follows:

MIL_INT MFTYPE FocusHook(

MIL_INT HookType,

MIL_INT Position,

void *UserDataPtr

)

Parameters

HookType

Indicates whether the optimum focus position was found or whether a new position needs to be analyzed.

For determining whether the optimum focus position was found or a new position needs to be analyzed
Value	Description	MIL system-specific tooltip (‡)
M_CHANGE	Specifies that the lens position must change to the position specified by the Position parameter, and a new position needs to be analyzed.	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
M_ON_FOCUS	Specifies that the optimum focus position was found and is specified by the Position parameter.	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa

Position

Focus position.

UserDataPtr

Pointer to data.

Upon successful completion, the user-defined function should return M_NULL. Otherwise, the user-defined function should return M_STOP_FOCUS to abort the MdigFocus() operation. In this case, the value returned by MdigFocus() will be undetermined.

Specifies the address of the data that you want to make available to the user-defined function. When only calculating the focus indicator (that is, using the M_EVALUATE operation mode), this parameter is not used, and must be set to M_NULL.

For specifying the address of the data
Value	Description	MIL system-specific tooltip (‡)
M_NULL	Specifies that the function does not require data.	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
Value	Specifies the address of the data. This address is passed to the user-defined function, through its UserDataPtr parameter, when the user-defined function is called. (summarize) Specifies the address of the data. (more details...)	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa

Specifies the minimum focus position of the search. When only calculating the focus indicator (that is, using the M_EVALUATE operation mode), this parameter is not used, and must be set to M_DEFAULT.

For specifying the minimum focus position of the search
Value	Description		MIL system-specific tooltip (‡)
M_DEFAULT	Specifies the default value; the default value is 0.		‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
Value >= 0	Specifies the position, in lens motor steps. (summarize) Specifies the position, in lens motor steps. (more details...)		‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
		MIL system specific
		For a smart camera with the Variopic Caspian C-39NO-160-I2C lens, the valid range of focus positions is from 0 to 1023. If using an auto-focus lens from another manufacturer, to determine the hardware-specific minimum focus position of the search, use MdigInquire() with M_FOCUS + M_MIN_VALUE.	‡													t U28

Specifies the starting focus position of the search. When only calculating the focus indicator (that is, using the M_EVALUATE operation mode), this parameter is not used, and must be set to M_DEFAULT.

For specifying the starting focus position of the search
Value	Description		MIL system-specific tooltip (‡)
M_DEFAULT	Specifies the default value; the default value is MinPosition.		‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
MinPosition <= Value <= MaxPosition	Specifies the position, in lens motor steps. (summarize) Specifies the position, in lens motor steps. (more details...)		‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
		MIL system specific
		For a smart camera with the Variopic Caspian C-39NO-160-I2C lens, the valid range of focus positions is from 0 to 1023. If using an auto-focus lens from another manufacturer, to determine the hardware-specific minimum and maximum focus positions of the search, use MdigInquire() with M_FOCUS + M_MIN_VALUE and M_FOCUS + M_MAX_VALUE, respectively.	‡													t U28

Specifies the maximum focus position of the search. When only calculating the focus indicator (that is, using the M_EVALUATE operation mode), this parameter is not used, and must be set to M_DEFAULT.

For specifying the maximum focus position of the search
Value	Description		MIL system-specific tooltip (‡)
M_DEFAULT	Specifies the default value; the default value is 255.		‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
Value > MinPosition	Specifies the position, in lens motor steps. (summarize) Specifies the position, in lens motor steps. (more details...)		‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
		MIL system specific
		For a smart camera with the Variopic Caspian C-39NO-160-I2C lens, the valid range of focus positions is from 0 to 1023. If using an auto-focus lens from another manufacturer, you can determine the hardware-specific maximum focus position of the search, use MdigInquire() with M_FOCUS + M_MAX_VALUE.	‡													t U28

Specifies the positional increment to use in the search. When only calculating the focus indicator (that is, using the M_EVALUATE operation mode), or when performing a M_SCAN_ALL or M_REFOCUS operation, this parameter is not used, and must be set to M_DEFAULT.

When performing a smart scan operation (using M_SMART_SCAN), this parameter is used during the first pass. The second pass uses the square root of this value. Each subsequent pass uses a progressively smaller value, with the last pass using a value of 1.

For specifying the positional increment
Value	Description	MIL system-specific tooltip (‡)
M_DEFAULT	Specifies the default value. The default value is equal to 1/16 of the value specified by MaxPosition. (summarize) Specifies the default value. (more details...)	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
Value > 0	Specifies the position, in lens motor steps.	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa

Specifies the operation mode used by this function.

Each operation mode provides a different strategy to find the optimum focus position. These strategies determine how the position is updated (in which direction and by how much) between grabs. They can affect the speed and accuracy of the operation. The default search strategy used by MIL is the smart-scan strategy.

The operation mode can be set to one of the following values.

For specifying the optimum focus position search strategy
Value	Description	MIL system-specific tooltip (‡)
M_DEFAULT	Same as M_SMART_SCAN.	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
M_BISECTION +	Specifies that the bisection search strategy will be used. This strategy breaks down the given positional range, step-by-step, until it finds the optimum focus position. In general, the bisection strategy processes the fewest amount of images. However, it is most sensitive to noise and requires that the lens motor travel the greatest distance. (summarize) Specifies that the bisection search strategy will be used. (more details...)	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
M_REFOCUS +	Specifies that the refocus search strategy will be used. This strategy scans upward or downward until it finds the optimum focus position or until it reaches the minimum or maximum position. The refocus strategy is the best strategy to use when the current focus position is close to optimum. (summarize) Specifies that the refocus search strategy will be used. (more details...)	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
M_SCAN_ALL +	Specifies that the scan-all search strategy will be used. This strategy scans, by 1, all positions between the minimum and maximum. The scan-all strategy is the slowest but most accurate. (summarize) Specifies that the scan-all search strategy will be used. (more details...)	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
M_SMART_SCAN +	Specifies that the smart-scan search strategy will be used. This strategy performs three refocus searches, each with a smaller positional increment. The smart-scan strategy is a compromise between the speed of a bisection and the accuracy of a scan-all. (summarize) Specifies that the smart-scan search strategy will be used. (more details...)	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa

Combination value for M_REFOCUS; M_SMART_SCAN.

You can add the following value to the above-mentioned values to specify the number of focus positions at which to compare the focus indicator when a potential optimum focus position (a peak in focus indicator values) is found.

When a potential optimum focus position is found, the process repeats the specified number of times to examine positions beyond that peak. This verifies that the peak focus indicator is truly the optimum focus position.

For specifying the number of focus positions at which to compare the focus indicator
Combination value	Description	MIL system-specific tooltip (‡)
1 <= Value <= 255	Specifies the required number of focus positions. By default, the value is 2. Note that this number cannot be greater than the difference between the maximum and minimum positions specified by MaxPosition and MinPosition, respectively. (summarize) Specifies the required number of focus positions. (more details...)	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa

To calculate only the focus indicator value for a given image or for the image grabbed at the current lens position, set the Operation parameter to the following:

For specifying that only the focus indicator is calculated
Value	Description	MIL system-specific tooltip (‡)
M_EVALUATE +	Specifies to only calculate the focus indicator. The user-defined function and all position parameters are unused (but must be set to the specific values mentioned previously). Instead, this operation mode grabs an image and uses it to calculate the focus indicator value. Note that, if you don't specify a digitizer identifier, the image contained in the specified destination buffer is used. (summarize) Specifies to only calculate the focus indicator. (more details...)	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa

Combination values for any of the possible values of the Operation parameter.

You can add one or more of the following values to the above-mentioned values to specify additional information about the mode of operation.

If both M_NO_FILTER and M_NO_SUBSAMPLING are specified, the source image is used directly without filtering or subsampling.

For specifying additional information about the mode of operation
Combination value	Description	MIL system-specific tooltip (‡)
M_NO_FILTER	Specifies to not perform a smoothing convolution. Instead, a subsampling operation is performed (using a nearest neighbor interpolation), with a scaling factor of 4. (summarize) Specifies to not perform a smoothing convolution. (more details...)	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa
M_NO_SUBSAMPLING	Specifies to not perform a subsampling operation (using a nearest neighbor interpolation), with a scaling factor of 4. Instead, a smoothing convolution is performed. (summarize) Specifies to not perform a subsampling operation (using a nearest neighbor interpolation), with a scaling factor of 4. (more details...)	‡		c M10	g	h	i	j	k M10	l	m	o	p	r U27	t U28	u U36	v		y U75		aa

Specifies the address in which to return the resulting value from the focusing operation.

If performing a focus operation on a single image (that is, using the M_EVALUATE operation mode), only the focus indicator is returned.

If performing a focus operation on multiple grabbed images (that is, not using the M_EVALUATE operation mode), then the optimum focus position is returned. Alternatively, if you do not want to return the optimum focus position, you can set this parameter to M_NULL.