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.	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
M_ON_FOCUS	Specifies that the optimum focus position was found and is specified by the Position parameter.	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s

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.	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
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...)	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s

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.	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
Value >= 0	Specifies the position, in lens motor steps.	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s

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.	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
MinPosition <= Value <= MaxPosition	Specifies the position, in lens motor steps.	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s

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.	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
Value > MinPosition	Specifies the position, in lens motor steps.	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s

Specifies the positional increment to use in 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 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...)	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
Value > 0	Specifies the position, in lens motor steps.	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s

Specifies the operation mode used by this function. It can be set to:

For specifying the optimum focus position search strategy
Value	Description	MIL system-specific tooltip (†)
M_DEFAULT	Same as M_SMART_SCAN.	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
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. (summarize) Specifies that the bisection search strategy will be used. (more details...)	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
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. (summarize) Specifies that the refocus search strategy will be used. (more details...)	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
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 and returns the position which produced the highest focus indicator. (summarize) Specifies that the scan-all search strategy will be used. (more details...)	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
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. (summarize) Specifies that the smart-scan search strategy will be used. (more details...)	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s

Combination constant 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. 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...)	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s

To calculate only the focus indicator value for a given image or for the image grabbed at the current lens position, set the ProcMode 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...)	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s

Combination constants for any of the possible values of the ProcMode 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.

For specifying additional information about the mode of operation
Combination value	Description	MIL system-specific tooltip (†)
M_NO_FILTER	Skips the filtering of each image to analyze.	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s
M_NO_SUBSAMPLING	Skips the subsampling of each image to analyze.	†		b	c		e	f	g	h	i	j	k	l	m	n	o	p	q	r	s

Specifies the address in which to return either the focus indicator (after performing the calculation on a single image with M_EVALUATE) or the optimum focus position (after performing the calculation on one or more images with one of the optimum focus position search strategies). If you do not want to return the focus indicator or the optimum focus position, you can set this parameter to M_NULL.