Librraew 1.1

API documentation

librraew version 1.1 API documentation is available online.

Librraew Overview

Collecting Statistics

As part of the automatic adjustments, the librraew library uses statistics captured by the H3A hardware. Each image is divided into regions called windows. The number of windows in the image is first determined by the segmentation factor as a percentage of the maximum number of windows allowed by the hardware. Then the window's width and height are determined. If less than 98% of the image is covered by the calculated windows, the number of windows and their size is adjusted to cover more of the image area.

For each window, the hardware calculates the average, maximum and minimum value on a per color channel (RGB) basis.

Auto White Balance

The librraew supports three AWB algorithms:

Gray World

The Gray World algorithm is based on the assumption that given an image with sufficient amount of color variation, the average reflectance of the scene is achromatic (gray). To be achromatic, the mean of the red, green, and blue channels in a given scene should be roughly equal. If the scene has a color that dominates, the results of the algorithm may not be satisfactory.

White Patch

The White Patch algorithm assumes that the maximum response in an image is caused by a perfect reflector, that represents the color of the illumination. White balancing attempts to equalize the maximum value of the three channels to produce a white patch. This algorithm will only produce satisfactory results if the captured image does not include saturated pixels.

White Patch 2

This variation of the White Patch algorithm aims to resolve the problems with the saturated pixels. White Patch 2 gets an average of local maximums instead of an absolute maximum. The results can change depending of the number of sample windows used in processing the image.

Auto Exposure

Librraew includes one AE algorithm that can use four brightness metering methods. The algorithm uses an electronic-centric approach based on the mid-tone idea. The algorithm purpose is to get an image with the optimal brightness defined as the value of the mid-tone (the middle of the brightness range). To accomplish this, the algorithm gets metrics from the sensor capture image as light metering. Then the algorithm calculates the required exposure time to get an optimal image brightness, using an expression that relates current scene brightness, current exposure time and the defined optimal image brightness. If the scene is too dark the exposure time tends to increase a lot affecting the video frame rate. Therefore the electronic centric algorithm takes into account an exposure maximum limit, given by the user or by the camera sensor driver. When this limit is reached the algorithm sets the maximum exposure time and switches from using exposure time to using sensor gain. As for the exposure time, the sensor global gain is calculated to get an optimal image brightness. In this situation if the scene illumination becomes brighter, the sensor gain will be decreasing when the minimal gain is reached (generally 1) the algorithms switch again, from using sensor gain to using exposure time.

All the brightness metering systems define a pixel brightness as the average of the red, blue and green components. Librraew offers four metering system choices:

Partial

Average the pixel's brightness in a frame region called rectangle of interest, the rest of the frame is ignored. The region's size and position is defined when rraew is initialized. It is generally used when very bright or very dark areas of the frame would otherwise degrade the scene illumination. Also it can be used when a specific region of the frame is the photographer's center of attention and the surrounding area is less important.

The Fig.1 represents the partial metering system. The Region 0 is the rectangle of interest located on the image's center. Only the illumination in region 0 is taken into account for the brightness calculation.

Fig.1: Representation of the partial metering system

Weighted

Average the light information coming from the entire frame with emphasis placed on the rectangle of interest. This metering system uses the brightness average of to regions: the pixels in a frame's portion called rectangle of interest and the pixels in the rest of the frame called background. The rectangle of interest's size and position is defined when rraew is initialized. The total brightness is calculated with emphasis placed on the rectangle of interest. 75% of the total brightness is given by the rectangle of interest and 30% by the background. This algorithm can be used when you want that the whole scene be well illuminated and not be affected for the small edges brightness variations.

The Fig.2 represents the weighted metering system, the Region 0 is the rectangle of interest located on the image's center and the Region 1 is the background.

Fig.2: Representation of the weighted metering system

Average

Average the light information coming from the entire frame without weighting any particular portion of the metered area. This algorithm can be used on scenes that not have a principal object and you want an average illumination. If the scene has a high contrast, the algorithm cause under or over exposure on parts of the scene.

The figure represents the average metering system, the Region 0 is the rectangle of interest corresponding to the entire image.

Fig.3: Representation of the average metering system

Segmented

This metering system is designed for scenes that have a principal object in a backlit condition. The frame is divided into five regions. This algorithm assumes that background region is located in the upper part of the scene and the main object is in the center of the scene. The metering systems organizes the regions into two groups: main object region and background region. The luminance difference between the background and the main object region is called degree of backlighting. According to the degree of backlighting, the metering system emphasize the luminance of the main object to get the frame total brightness. The center's region is defined by the rectangle of interest's parameters on the rraew initialization.

The figure represents the segmented metering system, the main object region = Region 3 + Region 1 and the background region = Region 0 + Region 2 + Region 4.

Fig.4: Representation of the segmented metering system

Rectangle of interest

Some metering systems use a rectangle of interest. The rectangle of interest is a frame's area used for algorithm specific interest, generally represents the most important zone in the scene. Librraew allows the user to define its size and position.

Rectangle of interest's size is defined as a percentage of the image size defined by the parameter rect_percentage. So rectangle of interest's width is rect_percentage * (image width) and the rectangle of interest's height is rect_percentage * (image height). The rect_percentage must be between 1% and 100%.

The position of the rectangle of interest's is defined by its center point. It could be placed in any pixel inside the image where the upper left pixel is (0,0). However, the image's statistics are collected by windows, so the center of the rectangle of interest will be the window that contains the selected pixel.

Installation and building

Documentation about installation and building of librraew library is available on librraew-README. It contains: the use conditions, software and hardware requirements, an example application, etc. Besides, you can download README file here.

Using librraew library

ipiped using librraew library

Two applications are used to support the auto exposure and auto white-balance (AEW) library in the RidgeRun's SDK:

• ipiped, a D-Bus server for controlling and configuring the camera sensor, the dm365 video processor, and the librraew library.
• ipipe-client, a D-Bus client that can be used to invoke any of the methods supported by ipiped.

More information about these applications can be found in Image Pipe Daemon Documentation. This library version is supported by ipiped 1.1.

Using other software rather than ipiped

librraew is a plain C library and can be re-used and integrated with any custom application capable of making C function calls. librraew version 1.1 API documentation is available online.