Optic Control#

The Optic Control feature allows you to control an optic device, e.g., Lenses.

The feature is based on the SLP protocol that enables cameras, light devices, and optic devices (e.g., a lens) to communicate directly with each other.

Using the Feature#

To use the Optic Control feature, you need the following:

• A Basler Lens with autofocus functionality.
  For information about a suitable lens, see the Optotune Lenses in the Partner Liquid Lens topic or the Computar LensConnect Series with Variable Focal Length section in the Partner Motorized Lenses topic.
• A suitable Basler Lens Sync Cable to connect an optic lens to a camera. The sync cable allows you to attach a light device and a lens, and control them via a single GPIO port of the camera. Which Basler Sync Cable you need depends on the peripheral devices you want to operate.
  For information about the available cable variants and their supported use cases, see Basler Sync Cables.
• A compatible camera running firmware that includes the Peripheral Device Control feature.

Initializing Optic Devices#

Before you can use an optic device, it needs to be initialized.

To initialize your optic device:

1. Follow the steps described in Preparing Peripheral Devices and Checking and Clearing Errors.
2. Select the optic device you want to control.
   For the first optic device, set OpticControllerSelector to Optic1.
3. Execute the OpticControllerInitialize command to initialize the attached lens.
   Depending on the lens type, you may notice its internal motors moving. Initialization time also depends on the lens type.
4. Monitor the OpticControllerStatus parameter. When initialization is complete, the parameter should have the value Ready. If it doesn't, see Checking and Clearing Errors below.

Depending on the connected lens, only the parameters supported by that lens are available for configuration.

The table below provides an overview of the possible statuses the optic controller inside the optic device can have.

Configuring the Focus#

Manual Focus#

Manual focus is best when you need to switch repeatedly between predefined settings. Unlike autofocus, it does not need to analyze multiple images, so it operates quickly. The speed depends on the lens type:

• Liquid lenses typically switch to a new focus in about 20 milliseconds.
• For motorized lenses, the speed depends on the size of the change:
  Moving from the nearest to the furthest focus position takes significantly longer than switching between intermediate positions.

All lenses mentioned in Using the Feature above support focus control using the FocusStepper parameter. The parameter value has no direct physical meaning. Instead, the lens's supported focus range is mapped to an integer range, where 0 corresponds to the nearest focus distance and the maximum FocusStepper corresponds to the furthest focus distance.

Some calibrated lenses also support focus control using the FocalPower parameter. This parameter is a floating-point value that specifies the lens's optical power in diopters.

Autofocus#

The camera can automatically adjust the lens focus to achieve the best focus in the image. It uses images captured by the camera's image sensor.

To use autofocus:

1. The autofocus parameters are in the Auto Function Control category of the feature tree.
   Open this category to adjust them.
2. On a color camera, use the BslAutoFocusColorSelect parameter to select the color channel used for autofocus.
   Because a lens's focal length also depends on the wavelength of the light, the best focus setting differs slightly for red, green, and blue light. For most applications, the default setting, Green, is a good choice.
3. Use BslAutoFocusStepperLowerLimit and BslAutoFocusStepperUpperLimit to restrict the focus range that the camera searches.
   If you know the distance range in which your objects will appear, set both limits to the corresponding FocusStepper values. This can significantly speed up autofocus.
4. Use the FocusAutoMode parameter to select how the camera controls focus automatically.
   • In modes whose names start with ImageBased, the camera analyzes image data to evaluate the focus of the current scene. ImageBased is the default mode and is suitable for most situations. The camera captures images while stepping through focus positions to find the optimum.
   • ImageBasedFast reduces the number of images captured, so autofocus finishes sooner, but it's less accurate and may miss the optimum under unfavorable conditions.
   • ImageBasedAccurate can improve accuracy, especially when used with the upper and lower focus limits.
5. Use the Auto Function ROI feature to select ROI 3 used for autofocus.
   ROI 3 for autofocus is limited to a maximum size of 256 x 256 pixels. A smaller value is possible.
6. Start grabbing images.
   Autofocus requires image acquisition.
7. Set FocusAuto to Once to start autofocus.
   The camera adjusts the focus while grabbing images. When the operation is complete, it sets FocusStepper to the best value found and resets FocusAuto to Off.

Increasing Autofocus Speed#

To reduce the time required for autofocus, consider the following recommendations:

• Set focus limits (BslAutoFocusStepperLowerLimit and BslAutoFocusStepperUpperLimit) to restrict the range over which autofocus searches for the optimal focus position.
• Reduce the Image ROI during autofocus operation to maximize the achievable frame rate and allow autofocus to complete more quickly.
• Use a fast lens that supports rapid focus adjustments.

Configuring Aperture#

If the lens supports aperture control, you can use the ApertureStepper parameter to adjust the iris opening. The parameter value does not represent a physical aperture (f-number). Instead, it maps the lens's supported aperture range to an integer range, where a value of 0 corresponds to the widest aperture opening and the maximum ApertureStepper value represents the minimum aperture opening.

Configuring Focal Length#

If the lens supports focal-length control, use the FocalLengthStepper parameter to adjust its focal length, i.e., the zoom. The parameter value has no direct physical meaning. Instead, it maps the lens's supported focal-length range to an integer range, where 0 corresponds to the shortest focal length and the maximum the FocalLengthStepper value corresponds to the longest focal length supported by the lens.

After changing the focal length, the focus position may shift, so you may need to readjust the focus.

Checking and Clearing Errors#

Error Statuses#

The BslPeripheralDeviceErrorStatus parameter can take the following values:

Sample Code#

ace 2, boost R, dart M Cameras#

// Select and initialize the optic controller.
camera.OpticControllerSelector.SetValue(OpticControllerSelector_Optic1);
camera.OpticControllerInitialize.Execute();

// Set focus position manually using stepper (0 = nearest focus position).
camera.FocusStepper.SetValue(1000);

// Set focus position manually using focal power (0 = nearest focus position).
camera.FocalPower.SetValue(1.0);

// Set aperture (0 = maximum aperture opening).
camera.ApertureStepper.SetValue(50);

// Set focal length (0 = shortest focal length).
camera.FocalLengthStepper.SetValue(200);

// Configure the autofocus ROI.
camera.AutoFunctionROISelector.SetValue(AutoFunctionROISelector_ROI3);
camera.AutoFunctionROIUseFocus.SetValue(true);
camera.AutoFunctionROIWidth.SetValue(128);
camera.AutoFunctionROIHeight.SetValue(128);
camera.AutoFunctionROIOffsetX.SetValue(840);
camera.AutoFunctionROIOffsetY.SetValue(480);

// Use the green color channel for focus evaluation.
camera.BslAutoFocusColorSelect.SetValue(BslAutoFocusColorSelect_Green);

// Restrict the autofocus search range.
// Limiting the range speeds up the focusing process.
camera.BslAutoFocusStepperLowerLimit.SetValue(800);
camera.BslAutoFocusStepperUpperLimit.SetValue(1200);

// Configure autofocus behavior.
camera.FocusAutoMode.SetValue(FocusAutoMode_ImageBased);

// Start autofocus.
camera.FocusAuto.SetValue(FocusAuto_Once);

INodeMap& nodemap = camera.GetNodeMap();
// Select and initialize the optic controller.
CEnumParameter(nodemap, "OpticControllerSelector").SetValue("Optic1");
CCommandParameter(nodemap, "OpticControllerInitialize").Execute();

// Set focus position manually using stepper (0 = nearest focus position).
CIntegerParameter(nodemap, "FocusStepper").SetValue(1000);

// Set focus position manually using focal power (0 = nearest focus position).
CFloatParameter(nodemap, "FocalPower").SetValue(1.0);

// Set aperture (0 = maximum aperture opening).
CIntegerParameter(nodemap, "ApertureStepper").SetValue(50);

// Set focal length (0 = shortest focal length).
CIntegerParameter(nodemap, "FocalLengthStepper").SetValue(200);

// Configure autofocus ROI.
CEnumParameter(nodemap, "AutoFunctionROISelector").SetValue("ROI3");
CBooleanParameter(nodemap, "AutoFunctionROIUseFocus").SetValue(true);
CIntegerParameter(nodemap, "AutoFunctionROIWidth").SetValue(128);
CIntegerParameter(nodemap, "AutoFunctionROIHeight").SetValue(128);
CIntegerParameter(nodemap, "AutoFunctionROIOffsetX").SetValue(840);
CIntegerParameter(nodemap, "AutoFunctionROIOffsetY").SetValue(480);

// Use the green color channel for focus evaluation.
CEnumParameter(nodemap, "BslAutoFocusColorSelect").SetValue("Green");

// Restrict the autofocus search range.
// Limiting the range speeds up the focusing process.
CIntegerParameter(nodemap, "BslAutoFocusStepperLowerLimit").SetValue(800);
CIntegerParameter(nodemap, "BslAutoFocusStepperUpperLimit").SetValue(1200);

// Configure autofocus behavior.
CEnumParameter(nodemap, "FocusAutoMode").SetValue("ImageBased");

// Start autofocus.
CEnumParameter(nodemap, "FocusAuto").SetValue("Once");

// Select and initialize the optic controller.
camera.Parameters[PLCamera.OpticControllerSelector].SetValue(PLCamera.OpticControllerSelector.Optic1);
camera.Parameters[PLCamera.OpticControllerInitialize].Execute();

// Set focus position manually using stepper (0 = nearest focus position).
camera.Parameters[PLCamera.FocusStepper].SetValue(1000);

// Set focus position manually using focal power (0 = nearest focus position).
camera.Parameters[PLCamera.FocalPower].SetValue(1.0);

// Set aperture (0 = maximum aperture opening).
camera.Parameters[PLCamera.ApertureStepper].SetValue(50);

// Set focal length (0 = shortest focal length).
camera.Parameters[PLCamera.FocalLengthStepper].SetValue(200);

// Configure autofocus ROI.
camera.Parameters[PLCamera.AutoFunctionROISelector].SetValue(PLCamera.AutoFunctionROISelector.ROI3);
camera.Parameters[PLCamera.AutoFunctionROIUseFocus].SetValue(true);
camera.Parameters[PLCamera.AutoFunctionROIWidth].SetValue(128);
camera.Parameters[PLCamera.AutoFunctionROIHeight].SetValue(128);
camera.Parameters[PLCamera.AutoFunctionROIOffsetX].SetValue(840);
camera.Parameters[PLCamera.AutoFunctionROIOffsetY].SetValue(480);

// Use the green color channel for focus evaluation.
camera.Parameters[PLCamera.BslAutoFocusColorSelect].SetValue(PLCamera.BslAutoFocusColorSelect.Green);

// Restrict the autofocus search range.
// Limiting the range speeds up the focusing process.
camera.Parameters[PLCamera.BslAutoFocusStepperLowerLimit].SetValue(800);
camera.Parameters[PLCamera.BslAutoFocusStepperUpperLimit].SetValue(1200);

// Configure autofocus behavior.
camera.Parameters[PLCamera.FocusAutoMode].SetValue(PLCamera.FocusAutoMode.ImageBased);

// Start autofocus.
camera.Parameters[PLCamera.FocusAuto].SetValue(PLCamera.FocusAuto.Once);

/* Macro to check for errors */
#define CHECK(errc) if (GENAPI_E_OK != errc) printErrorAndExit(errc)
GENAPIC_RESULT errRes = GENAPI_E_OK;  /* Return value of pylon methods */
/* Select and initialize the optic controller. */
errRes = PylonDeviceFeatureFromString(hdev, "OpticControllerSelector", "Optic1");
CHECK(errRes);
errRes = PylonDeviceExecuteCommandFeature(hdev, "OpticControllerInitialize");
CHECK(errRes);

/* Set focus position manually using stepper (0 = nearest focus position). */
errRes = PylonDeviceSetIntegerFeature(hdev, "FocusStepper", 1000);
CHECK(errRes);

/* Set focus position manually using focal power (0 = nearest focus position). */
errRes = PylonDeviceSetFloatFeature(hdev, "FocalPower", 1.0);
CHECK(errRes);

/* Set aperture (0 = maximum aperture opening). */
errRes = PylonDeviceSetIntegerFeature(hdev, "ApertureStepper", 50);
CHECK(errRes);

/* Set focal length (0 = shortest focal length). */
errRes = PylonDeviceSetIntegerFeature(hdev, "FocalLengthStepper", 200);
CHECK(errRes);

/* Configure autofocus ROI. */
errRes = PylonDeviceFeatureFromString(hdev, "AutoFunctionROISelector", "ROI3");
CHECK(errRes);
errRes = PylonDeviceSetBooleanFeature(hdev, "AutoFunctionROIUseFocus", 1);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionROIWidth", 128);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionROIHeight", 128);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionROIOffsetX", 840);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "AutoFunctionROIOffsetY", 480);
CHECK(errRes);

/* Use the green color channel for focus evaluation. */
errRes = PylonDeviceFeatureFromString(hdev, "BslAutoFocusColorSelect", "Green");
CHECK(errRes);

/* Restrict the autofocus search range. */
/* Limiting the range speeds up the focusing process. */
errRes = PylonDeviceSetIntegerFeature(hdev, "BslAutoFocusStepperLowerLimit", 800);
CHECK(errRes);
errRes = PylonDeviceSetIntegerFeature(hdev, "BslAutoFocusStepperUpperLimit", 1200);
CHECK(errRes);

/* Configure autofocus behavior. */
errRes = PylonDeviceFeatureFromString(hdev, "FocusAutoMode", "ImageBased");
CHECK(errRes);

/* Start autofocus. */
errRes = PylonDeviceFeatureFromString(hdev, "FocusAuto", "Once");
CHECK(errRes);

# Select and initialize the optic controller.
camera.OpticControllerSelector.Value = "Optic1"
camera.OpticControllerInitialize.Execute()

# Set focus position manually using stepper (0 = nearest focus position).
camera.FocusStepper.Value = 1000

# Set focus position manually using focal power (0 = nearest focus position).
camera.FocalPower.Value = 1.0

# Set aperture (0 = maximum aperture opening).
camera.ApertureStepper.Value = 50

# Set focal length (0 = shortest focal length).
camera.FocalLengthStepper.Value = 200

# Configure autofocus ROI.
camera.AutoFunctionROISelector.Value = "ROI3"
camera.AutoFunctionROIUseFocus.Value = True
camera.AutoFunctionROIWidth.Value = 128
camera.AutoFunctionROIHeight.Value = 128
camera.AutoFunctionROIOffsetX.Value = 840
camera.AutoFunctionROIOffsetY.Value = 480

# Use the green color channel for focus evaluation.
camera.BslAutoFocusColorSelect.Value = "Green"

# Restrict the autofocus search range.
# Limiting the range speeds up the focusing process.
camera.BslAutoFocusStepperLowerLimit.Value = 800
camera.BslAutoFocusStepperUpperLimit.Value = 1200

# Configure autofocus behavior.
camera.FocusAutoMode.Value = "ImageBased"

# Start autofocus.
camera.FocusAuto.Value = "Once"

You can also use the pylon Viewer to easily set the parameters.