You are here: Technical Reference > Auto Algorithm Control
FLIR

Blackfly®S

BFS-U3-04S2

 

Auto Algorithm Control

Auto Exposure (AE)

Auto exposure (AE) control is designed to automatically determine the exposure time and gain of the camera so that the resulting image looks as bright as expected. In general, the camera supports various auto exposure features, and these features produce different results in the final image. In addition, the camera allows users to control how fast the exposure and gain get settled.

Note that for AE to work, Exposure Auto and/or Gain Auto must be set to Once or Continuous.

Auto Exposure Features

To enable AE, Exposure Auto and/or Gain Auto must be set to Once or Continuous. AE automatically determines the exposure time and/or gain according to the target image average.

The target image average can be manually or automatically controlled.

For manual control, set Target Grey Value Auto to Continuous and then set the desired image average in Target Grey Value. This value is a percentage of the maximum pixel value.

For automatic control, set Target Grey Value Auto to Off. The target image average is then automatically determined according to user-defined AE modes and other AE features.

By default, AE uses the full range of exposure time and/or gain and target grey value, but these can be limited.

Exposure Time Lower Limit / Exposure Time Upper Limit - the lower and upper values in microseconds (µs) that the exposure time may reach when exposure is set to Once or Continuous.

Gain Lower Limit / Gain Upper Limit - the lower and upper values in decibels (dB) that the gain may reach when gain is set to Once or Continuous.

Target Grey Value Lower Limit / Target Grey Value Upper Limit - the lower and upper values in percent (%) that the target image average may reach.

Auto Exposure Damping controls how fast the exposure and gain get settled. A small damping value may result in the system being unstable. The range is from 0.0 - 1.0. The default value is 0.5.

If both exposure time and gain are set to Once or Coninuous AE determines which to adjust first by the Auto Exposure Control Priority.

If gain priority is selected, the camera sets the gain to 0 dB, and the exposure is adjusted according to the target grey level. If the maximum exposure is reached before the target grey level is hit, the gain starts to change to meet the target. This mode is used to have the minimum noise.

If exposure priority is selected, the camera sets the exposure to a small value (default is 5 ms). The gain is adjusted according to the target grey level. If maximum gain is reached before the target grey level is hit, the exposure starts to change to meet the target. This mode is used to capture fast motion.

AE Lighting Mode can compensate for strong light sources in front or behind an object. The options are: Backlight, Frontlight, or Normal. The default lighting mode is Normal. Use the Lighting Mode feature to select depending on your conditions.

Backlight Compensation

The backlight compensation mode isused when a strong light is coming from the back of the object. For example, people standing in the shade with the bright sky at the back. A regular auto exposure algorithmmakes the object underexposed in such lighting conditions. Backlight compensation is able to properly expose the object when a strong backlight occurs, regardless of the locations of the object relative to the frame.

Excessive Frontlight Compensation

The excessive frontlight compensation mode isused when a strong light is shining in the front of the object while the background is dark. For example, a parking spot that has lights on at night while its surrounding areas are very dark. A regular auto exposure algorithm makes the object overexposed in such lighting conditions. Frontlight compensation is able to properly expose the object when a strong front light and a dark background appear, regardless of the locations of the object relative to the frame.

Normal Lighting

If the object of interest in the frame is not under backlight or frontlight conditions, then normal lighting should be used. Select Normal lighting mode to make Metering Mode available.

AE Metering Mode is available only if Lighting Mode is set to Normal. The options are: Average, Spot, and Partial. The default AE metering mode is Average. Use the Metering Mode feature to select depending on your conditions.

Average Metering

This mode measures the light from the entire scene uniformly to determine the final exposure value. Every portion of the exposed area has the same contribution.

Spot Metering

This mode measures the light from a small area (about 3%) in the center of the scene while the rest of the scene is ignored. This mode isused when the scene has a high contrast and the object of interest is relatively small.

Partial Metering

This mode measures the light from a larger area (about 11%) in the center of the scene. This mode is used when very dark or bright regions appear at the edge of the frame.

A region of interest (ROI) can be applied to the auto exposure features. This AE ROI can be equal to or smaller than the area of the captured ROI. To use AE ROI:

1. Set the ROI Selector to Auto Exposure.

2. Turn on ROI Enable.

3. Set the horizontal and vertical offsets (relative to the ROI being captured) with ROI Offset X and ROI Offset Y.

4. Set the width and height with ROI Width and ROI Height.

EV Compensation allows you to adjust the resultant image intensity with one control. Positive EV compensation makes the image brighter while negative EV compensation makes the image darker. The range is from -3 to 3 with a step of 1/3. The default value is 0.

Auto White Balance

When White Balance Auto is set to Continuous or Once the camera automatically adjusts the values of Balance Ratio Red and Blue to achieve good color balance. It is used to compensate for color shifts in the image caused by different lighting conditions.

There are two profiles of auto white balance: Indoor and Outdoor. These are selected with White Balance Auto Profile.

In the Outdoor profile, the values of the red and blue balance ratios are restricted to a set of expected values for normal outdoor lighting conditions (i.e., daylight).

In the Indoor profile, the values of the red and blue balance ratios can take any values within specified limits. This allows auto white balance to compensate for artificial lighting such as fluorescent lights that are more greenish than daylight. The Indoor profile can also be used for outdoor conditions, since it does not place restrictions on the white balance solution.

By default, auto white balance uses the full range of balance ratios, but these can be limited.

White Balance Auto Damping controls the speed at which auto white balance adjusts the values of the red and blue balance ratios. The range is from 0 to 1. Higher values of damping result in the white balance changing more gradually.

By default auto white balance examines all of the pixels in the image, but it can also use a region of interest (ROI). A common use for an auto white balance ROI is placing a white object in the image and then specifying the ROI on that object. To use ROI:

  1. Set the ROI Selector to Auto White Balance.
  2. Turn on ROI Enable.
  3. Set the horizontal and vertical offsets (relative to the ROI being captured) with ROI Offset X and ROI Offset Y.
  4. Set the width and height with ROI Width and ROI Height.

Summary Table

Name Interface Access Visibility Description
ROI Selector IEnumeration Beginner Selects which Auto Algorithm is controlled by the RoiEnable, OffsetX, OffsetY, Width, Height features.
ROI Enable [ROI Selector] IBoolean Guru Controls whether a user-specified ROI is used for auto algorithm that is currently selected by the AutoAlgorithmSelector feature.
ROI Offset X [ROI Selector] IInteger Guru Controls the x-offset of the ROI used by the auto algorithm that is currently selected by the AutoAlgorithmSelector feature.
ROI Offset Y [ROI Selector] IInteger Guru Controls the y-offset of the ROI used by the auto algorithm that is currently selected by the AutoAlgorithmSelector feature.
ROI Width [ROI Selector] IInteger Guru Controls the width of the ROI used by the auto algorithm that is currently selected by the AutoAlgorithmSelector feature.
ROI Height [ROI Selector] IInteger Guru Controls the width of the ROI used by the auto algorithm that is currently selected by the AutoAlgorithmSelector feature.
White Balance Auto Profile IEnumeration RW Expert Selects the profile used by BalanceWhiteAuto.
White Balance Auto Lower Limit IFloat Expert Controls the minimum value Auto White Balance can set for the Red/Blue BalanceRatio.
White Balance Auto Upper Limit IFloat Expert Controls the maximum value Auto White Balance can set the Red/Blue BalanceRatio.
White Balance Auto Damping IFloat Expert Controls how quickly 'BalanceWhiteAuto' adjusts the values for Red and Blue BalanceRatio in response to changing conditions. Higher damping means the changes are more gradual.
Target Grey Value Auto IEnumeration Beginner This indicates whether the target image grey level is automatically set by the camera or manually set by the user. Note that the target grey level is in the linear domain before gamma correction is applied.
Target Grey Value IFloat RW This is the user-specified target grey level (image mean) to apply to the current image. Note that the target grey level is in the linear domain before gamma correction is applied.
Lighting Mode IEnumeration RW Beginner Selects a lighting mode: Backlight, Frontlight or Normal (default). a. Backlight compensation: used when a strong light is coming from the back of the object. b. Frontlight compensation: used when a strong light is shining in the front of the object while the background is dark. c. Normal lighting: used when the object is not under backlight or frontlight conditions. When normal lighting is selected, metering modes are available.
Metering Mode IEnumeration RW Beginner Selects a metering mode: average, spot, or partial metering. a. Average: Measures the light from the entire scene uniformly to determine the final exposure value. Every portion of the exposed area has the same contribution. b. Spot: Measures a small area (about 3%) in the center of the scene while the rest of the scene is ignored. This mode is used when the scene has a high contrast and the object of interest is relatively small. c. Partial: Measures the light from a larger area (about 11%) in the center of the scene. This mode is used when very dark or bright regions appear at the edge of the frame. Note: Metering mode is available only when Lighting Mode Selector is Normal.
Exposure Time Lower Limit IFloat RW The smallest exposure time that auto exposure can set.
Exposure Time Upper Limit IFloat RW The largest exposure time that auto exposure can set.
Gain Lower Limit IFloat RW The smallest gain that auto exposure can set.
Gain Upper Limit IFloat RW The largest gain that auto exposure can set.
Target Grey Value Lower Limit IFloat RW The lowest value in percentage that the target mean may reach.
Target Grey Value Upper Limit IFloat RW The highest value in percentage that the target mean may reach.
EV Compensation IFloat RW Beginner The EV compensation value used in the exposure compensation. This allows you to adjust the resultant image intensity with one control. A positive value makes the image brighter. A negative value makes the image darker. Range from -3 to 3 with a step of 1/3. Default = 0.
Auto Exposure Damping IFloat RW Beginner It controls how fast the exposure and gain get settled. If the value is too small, it may cause the system to be unstable. Range is from 0.0 to 1.0. Default = 0.2.
Auto Exposure Control Priority IEnumeration RW Beginner Selects whether to adjust gain or exposure first. When gain priority is selected, the camera fixes the gain to 0 dB, and the exposure is adjusted according to the target grey level. If the maximum exposure is reached before the target grey level is hit, the gain starts to change to meet the target. This mode is used to have the minimum noise. When exposure priority is selected, the camera sets the exposure to a small value (default is 5 ms). The gain is adjusted according to the target grey level. If maximum gain is reached before the target grey level is hit, the exposure starts to change to meet the target. This mode is used to capture fast motion.

Auto Algorithm Control Features


ROI Selector

Selects which Auto Algorithm is controlled by the RoiEnable, OffsetX, OffsetY, Width, Height features.

Property Value
Name AutoAlgorithmSelector
Interface IEnumeration
Access
Visibility Beginner

Enumeration Values
Awb
Ae

ROI Enable

Controls whether a user-specified ROI is used for auto algorithm that is currently selected by the AutoAlgorithmSelector feature.

Property Value
Name AasRoiEnable [ROI Selector]
Interface IBoolean
Access
Visibility Guru

ROI Offset X

Controls the x-offset of the ROI used by the auto algorithm that is currently selected by the AutoAlgorithmSelector feature.

Property Value
Name AasRoiOffsetX [ROI Selector]
Interface IInteger
Access
Unit
Visibility Guru

ROI Offset Y

Controls the y-offset of the ROI used by the auto algorithm that is currently selected by the AutoAlgorithmSelector feature.

Property Value
Name AasRoiOffsetY [ROI Selector]
Interface IInteger
Access
Unit
Visibility Guru

ROI Width

Controls the width of the ROI used by the auto algorithm that is currently selected by the AutoAlgorithmSelector feature.

Property Value
Name AasRoiWidth [ROI Selector]
Interface IInteger
Access
Unit
Visibility Guru

ROI Height

Controls the width of the ROI used by the auto algorithm that is currently selected by the AutoAlgorithmSelector feature.

Property Value
Name AasRoiHeight [ROI Selector]
Interface IInteger
Access
Unit
Visibility Guru

White Balance Auto Profile

Selects the profile used by BalanceWhiteAuto.

Property Value
Name BalanceWhiteAutoProfile
Interface IEnumeration
Access RW
Visibility Expert

Enumeration Values
Indoor
Outdoor

White Balance Auto Lower Limit

Controls the minimum value Auto White Balance can set for the Red/Blue BalanceRatio.

Property Value
Name BalanceWhiteAutoLowerLimit
Interface IFloat
Access
Unit
Visibility Expert

White Balance Auto Upper Limit

Controls the maximum value Auto White Balance can set the Red/Blue BalanceRatio.

Property Value
Name BalanceWhiteAutoUpperLimit
Interface IFloat
Access
Unit
Visibility Expert

White Balance Auto Damping

Controls how quickly 'BalanceWhiteAuto' adjusts the values for Red and Blue BalanceRatio in response to changing conditions. Higher damping means the changes are more gradual.

Property Value
Name BalanceWhiteAutoDamping
Interface IFloat
Access
Unit
Visibility Expert

Target Grey Value Auto

This indicates whether the target image grey level is automatically set by the camera or manually set by the user. Note that the target grey level is in the linear domain before gamma correction is applied.

Property Value
Name AutoExposureTargetGreyValueAuto
Interface IEnumeration
Access
Visibility Beginner

Enumeration Values
Off
Continuous

Target Grey Value

This is the user-specified target grey level (image mean) to apply to the current image. Note that the target grey level is in the linear domain before gamma correction is applied.

Property Value
Name AutoExposureTargetGreyValue
Interface IFloat
Access RW
Unit %
Visibility

Lighting Mode

Selects a lighting mode: Backlight, Frontlight or Normal (default). a. Backlight compensation: used when a strong light is coming from the back of the object. b. Frontlight compensation: used when a strong light is shining in the front of the object while the background is dark. c. Normal lighting: used when the object is not under backlight or frontlight conditions. When normal lighting is selected, metering modes are available.

Property Value
Name AutoExposureLightingMode
Interface IEnumeration
Access RW
Visibility Beginner

Enumeration Values
AutoDetect
Backlight
Frontlight
Normal

Metering Mode

Selects a metering mode: average, spot, or partial metering. a. Average: Measures the light from the entire scene uniformly to determine the final exposure value. Every portion of the exposed area has the same contribution. b. Spot: Measures a small area (about 3%) in the center of the scene while the rest of the scene is ignored. This mode is used when the scene has a high contrast and the object of interest is relatively small. c. Partial: Measures the light from a larger area (about 11%) in the center of the scene. This mode is used when very dark or bright regions appear at the edge of the frame. Note: Metering mode is available only when Lighting Mode Selector is Normal.

Property Value
Name AutoExposureMeteringMode
Interface IEnumeration
Access RW
Visibility Beginner

Enumeration Values
Average
Spot
Partial
CenterWeighted
HistgramPeak

Exposure Time Lower Limit

The smallest exposure time that auto exposure can set.

Property Value
Name AutoExposureExposureTimeLowerLimit
Interface IFloat
Access RW
Unit us
Visibility

Exposure Time Upper Limit

The largest exposure time that auto exposure can set.

Property Value
Name AutoExposureExposureTimeUpperLimit
Interface IFloat
Access RW
Unit us
Visibility

Gain Lower Limit

The smallest gain that auto exposure can set.

Property Value
Name AutoExposureGainLowerLimit
Interface IFloat
Access RW
Unit dB
Visibility

Gain Upper Limit

The largest gain that auto exposure can set.

Property Value
Name AutoExposureGainUpperLimit
Interface IFloat
Access RW
Unit dB
Visibility

Target Grey Value Lower Limit

The lowest value in percentage that the target mean may reach.

Property Value
Name AutoExposureGreyValueLowerLimit
Interface IFloat
Access RW
Unit %
Visibility

Target Grey Value Upper Limit

The highest value in percentage that the target mean may reach.

Property Value
Name AutoExposureGreyValueUpperLimit
Interface IFloat
Access RW
Unit %
Visibility

EV Compensation

The EV compensation value used in the exposure compensation. This allows you to adjust the resultant image intensity with one control. A positive value makes the image brighter. A negative value makes the image darker. Range from -3 to 3 with a step of 1/3. Default = 0.

Property Value
Name AutoExposureEVCompensation
Interface IFloat
Access RW
Unit
Visibility Beginner

Auto Exposure Damping

It controls how fast the exposure and gain get settled. If the value is too small, it may cause the system to be unstable. Range is from 0.0 to 1.0. Default = 0.2.

Property Value
Name AutoExposureControlLoopDamping
Interface IFloat
Access RW
Unit
Visibility Beginner

Auto Exposure Control Priority

Selects whether to adjust gain or exposure first. When gain priority is selected, the camera fixes the gain to 0 dB, and the exposure is adjusted according to the target grey level. If the maximum exposure is reached before the target grey level is hit, the gain starts to change to meet the target. This mode is used to have the minimum noise. When exposure priority is selected, the camera sets the exposure to a small value (default is 5 ms). The gain is adjusted according to the target grey level. If maximum gain is reached before the target grey level is hit, the exposure starts to change to meet the target. This mode is used to capture fast motion.

Property Value
Name AutoExposureControlPriority
Interface IEnumeration
Access RW
Visibility Beginner

Enumeration Values
Gain
ExposureTime

 

11/15/2017
© 2015-2017 FLIR® Integrated Imaging Solutions Inc.
All rights reserved.
Legal
| Contact Support

Blackfly®S BFS-U3-04S2
Camera Reference

FLIR Camera and API References