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).


Note: You can use the following equation to calculate the voltage applied to the lens for any focus score:


Vrms = N x 0.001 + 24 (in Volts)


Where:

Vrms = the rms value of the voltage seen by the Liquid Lens (AC voltage)

N = the focus value (from 0 to 46000)


API Control


PxLGetFeaturePxLSetFeature


Feature IDNumber of ParamsParametersUnitsRestrictions
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 2fValueLens dependantGenerally, 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



CameraPresenceRead OnlyAutoManualOne-time AutoOffSettable While StreamingPersistableCiD
Lens dependantYesNoNoYesYesNoYesYesNo


Parameters


CameraParameterUnitTypeMinMaxDefaultStep SizeComments
PL-D
only
FocusLens
Dependant
AbsoluteLens
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.



CameraParameterUnitTypeMinMaxDefaultStep SizeComments
Some 
PL-D's
Auto-focus 
lower limit
Lens 
dependent
AbsoluteLens
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 limitLens dependentAbsoluteLens dependentLens dependentLens dependentLens dependentOnly used when initiating an auto-focus operation (PxLSetFeature with Auto or One-time auto Feature Flag set).