Supported by...


Cameras equipped with a (supported) lens that has automated focus control.  Use PxLGetCameraFeatures to see if the camera is equipped with such a lens.  Specific lens information can be obtained via PxLGetCameraInfoEx.


Description


Controls the amount of focus being applied to the lens on the camera.  Specific units of the fValue parameter are lens dependant – but higher values will focus the lens on objects that are closer to the camera.  The feature FEATURE_SHARPNESS_SCORE, and the SharpnessScore returned with each frames FRAME_DESC, can be used to assess focus quality of an image, and allow an application to adjust the focus of the lens.


When performing auto-focus operations, some cameras will allow the application to specify a lower and upper limit to be used when selecting a focus value (parameter 1 and 2 respectively). Supplying these limits is optional, but doing so may speed up the auto-focus operation. Cameras that support specification of auto-focus limits, will indicate that FEATURE_FOCUS supports 2 parameters when a calling PxLGetCameraFeatures (as opposed to just 1 parameter).


API Control

PxLGetFeaturePxLSetFeature


Feature ID
Number of Params
Parameters
Units
Restrictions
FEATURE_FOCUS


If supported, controls the amount of focus being applied to lens with automated focus control. Larger values focuses on objects closer to the camera.
1 or 2
fValue
Lens dependant
Generally, only 1 parameter is supported, specifying the ‘Focus’ value used by the lens. However, certain camera modes will allow the application to specify 2 parameters when initiating an auto-focus operation. In these instances, the parameters specify the lower and upper focal values to use when performing the auto-focus.


Feature Flags



Camera
Presence
Read Only
Auto
Manual
One-time Auto
Off
Settable While Streaming
Persistable
CiD
Lens dependant
Yes
No
Yes
Yes
Yes
No
Yes
Yes
No


Parameters


Camera
Parameter
Unit
Type
Min
Max
Default
Step Size
Comments
PL-D only
Focus
Lens Dependant
Absolute
Lens Dependant
Lens Dependant
Manual. Note that in this instance, manual means the application is controlling the focus via this feature-not the focus is being controlled by mechanical adjustments being done by the user on the physical lens.
Lens dependant
Higher values will focus the lens on objects closer to the camera. The minimum, maximum value and step size vary with the lens type. PxLGetCameraFeatures will determine the minimum and maximum focus values. The step size can be determined empirically, as camera will always auto-adjust any user set focus value to one that is acceptable to the lens.



Camera
Parameter
Unit
Type
Min
Max
Default
Step Size
Comments
Some PL-D's
Auto-focus lower limit
Lens dependent
Absolute
Lens dependent
Lens dependent
Lens dependent
Lens dependent
Only used when initiating an auto-focus operation (PxLSetFeature with Auto or One-time auto Feature Flag set).

Some PL-D's
Auto-focus upper limit
Lens dependent
Absolute
Lens dependent
Lens dependent
Lens dependent
Lens dependent
Only used when initiating an auto-focus operation (PxLSetFeature with Auto or One-time auto Feature Flag set).