The AdjustExposureAndGain command allows you to run a single cycle of the internal auto exposure and auto gain algorithm with custom starting values for exposure and gain, and a manually measured brightness value. The resulting exposure and gain will directly be set on the specified camera.
This command allows you to adapt the internal auto exposure and gain algorithm in the following ways:
Custom auto exposure AOI
By default the internal auto exposure functions use the full captured image area. If you want to regulate the brightness in a smaller area (maybe even of complex shape) you can simply compute the brightness in this area by yourself after the image was captured and call AdjustExposureAndGain with the Brightness parameter set to your measured brightness. The command will then adjust the exposure and/or gain values on the camera accordingly to reach the TargetBrightness for this camera.
Separate exposure regulation in different locations
Assume you have mounted the camera on a robot and you are capturing images in a very bright picking zone and a very dark dropping zone. If you run normal auto exposure the exposure will be turned down after getting an image of the picking zone, which will be inadequate if your next image will be taken on the drop zone and vice versa.
Using the AdjustExposureAndGain command you can simply remember the exposure, gain and image brightness of the last image for each location separately in your application program. Before capturing an image in the dark drop zone you can simply supply the values of Exposure, Gain and Brightness from the last image of the drop zone to AdjustExposureAndGain, and the exposure and gain parameters of the camera will be adjusted only based on the supplied values from the last image in the dark scene. Thus you can still benefit from automatic exposure regulation in each location, but the regulation runs independently for each location resulting in correct image brightness instantly even after moving between scenes of very different brightness, distance or reflectivity.
The regulation will always try to use the smallest possible gain factor, i.e. when increasing brightness it will first try to increase exposure until MaxFlashTime is reached, when decreasing brightness it will first decrease gain until the gain factor has reached 1.0.
Sometimes the granularity of possible exposure values accepted by the sensor prevents the algorithm to reach the target brightness exactly. In these cases it will produce intermediate steps by choosing the exposure step below the targeted exact exposure and compensates the remaining brightness with a small gain factor (usually between 1 and 1.1).
Due to the brightness linearity of image sensors the algorithm tries to directly guess the correct exposure and gain values from the given exposure, gain and brightness. Under ideal conditions the adaption should be completed in a single adjustment cycle, but there are of course effects reducing this theoretical regulation speed:
Image brightness does not behave linearly in dark regions due to noise and black level uncertainties
Image brightness does not behave linearly in overexposed regions due to clipping
Some image sensors have delay of one frame between setting and applying the exposure (see Exposure parameter of stereo cameras)