MIL_ID DigId, | //in |
MIL_ID DestImageBufId, | //in |
MIL_ID FocusImageRegionBufId, | //in |
MIL_FOCUS_HOOK_FUNCTION_PTR FocusHookPtr, | //in |
void *UserDataPtr, | //in-out |
MIL_INT MinPosition, | //in |
MIL_INT StartPosition, | //in |
MIL_INT MaxPosition, | //in |
MIL_INT MaxPositionVariation, | //in |
MIL_INT64 Operation, | //in |
MIL_INT *ResultPtr | //out |
This function adjusts a camera's lens motor to a position that produces optimum focus, or only calculates an indicator of the focus quality (focus indicator) of a specified image or an image grabbed at the current lens motor position. The operation mode establishes which is performed.
To adjust a camera's lens motor to a position that produces optimum focus, this function calls a user-defined function to move the lens motor to a specified initial position, grabs an image, calculates the focus indicator of the grabbed image, and based on the focus indicator and the specified optimum focus search strategy, calculates a new position for the lens motor. The process repeats, calling the user-defined function to move the lens motor to the newly calculated position and comparing the new focus indicator with the old. The process continues repeating until the optimum focus position is found. You can optionally have the user-defined function perform the grab, instead of having MdigFocus() directly perform the grab.
Regardless of the operation mode, the image is subsampled by a factor of 4, by default using a bilinear interpolation operation, before the focus indicator is calculated; you can override this default.
This function establishes the focus indicator of an image by analyzing the edges within a specified focus region (a child image of the grabbed or provided image). An image with a good focus indicator has a sharp intensity transition between its edges and their background. The resulting optimal focus position is an position between the specified minimum and maximum lens position.
Alternatively, this function can evaluate the current position and calculate the focus indicator (using the M_EVALUATE operation mode). In this case, the focus indicator ranges from 0 to a very large number, based on the number of edges found in the grabbed image.
In either case, as the returned value increases, your camera's focus also increases, resulting in future grabbed image becoming more in focus.
The specified search strategy (set using the operation mode parameter) determines how each new position of the lens motor is calculated between grabs. For more information, see the Auto-focusing section of Chapter 25: Grabbing with your digitizer.
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:
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
|
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description |
MIL system-specific tooltip (‡) |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
||||||||||||||||||
![]() ![]() |
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 | |||||||||||||||||||||
![]() ![]() |
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 |
Focus position.
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.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description |
MIL system-specific tooltip (‡) |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
||||||||||||||||||
![]() ![]() |
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 | |||||||||||||||||||||
![]() ![]() |
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.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description |
MIL system-specific tooltip (‡) |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
||||||||||||||||||
![]() ![]() |
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 | |||||||||||||||||||||
![]() ![]() |
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.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description |
MIL system-specific tooltip (‡) |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
||||||||||||||||||
![]() ![]() |
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 | |||||||||||||||||||||
![]() ![]() |
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.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description |
MIL system-specific tooltip (‡) |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
||||||||||||||||||
![]() ![]() |
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 | |||||||||||||||||||||
![]() ![]() |
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.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description |
MIL system-specific tooltip (‡) |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
||||||||||||||||||
![]() ![]() |
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 | |||||||||||||||||||||
![]() ![]() |
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.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description |
MIL system-specific tooltip (‡) |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
||||||||||||||||||
![]() ![]() |
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 | |||||||||||||||||||||
![]() ![]() |
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 | |||||||||||||||||||||
![]() ![]() |
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 | |||||||||||||||||||||
![]() ![]() |
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 | |||||||||||||||||||||
![]() ![]() |
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 |
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.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description |
MIL system-specific tooltip (‡) |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
||||||||||||||||||
![]() ![]() |
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:
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description |
MIL system-specific tooltip (‡) |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
||||||||||||||||||
![]() ![]() |
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 |
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.
![]() |
|||||||||||||||||||||||||||||||||||||||
![]() ![]() |
Description |
MIL system-specific tooltip (‡) |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
||||||||||||||||||
![]() ![]() |
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 | |||||||||||||||||||||
![]() ![]() |
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.
Header | Include mil.h. |
Library | Use mil.lib; milim.lib. |
DLL | Requires mil.dll; milim.dll. |