ILFlatField Interface Reference

This interface provide functionalities of flat field calibration and correction. More...

Inheritance diagram for ILFlatField:

Public Member Functions
LPVErrorCode	FixImage (ILImage *image, ILImage *fixedImage)
void	GetFlatField (ILImage *previewImage)
BOOL	IsCalibrated ()
LPVErrorCode	SetDarkFrame (ILImage *image)
LPVErrorCode	Train (ILImage *image, ILRegion *region)
Public Member Functions inherited from ILObject
ILObject *	Copy ()
LPVErrorCode	Load (LString filename)
void	Reset ()
LPVErrorCode	Save (LString filename)
BOOL	Valid ()

Properties
LPVImageFormat	ColorMode [get, set]
	The mode of the flat field tool, either handling grayscale or color image.
LColor	FromColor [get, set]
	The raw sourcing color before flat field correction, for color mode.
int	FromGray [get, set]
	The raw sourcing grayscale value before flat field correction, for grayscale mode.
int	KernelWidth [get, set]
	The kernel size, it affects the updating range of the foreground and flat field during training and the smoothness of the result flat field. It should be an odd number, say, 3, 5, 7, etc. By default, it's 121.
LColor	ToColor [get, set]
	The expected targeting color after flat field correction, for color mode.
int	ToGray [get, set]
	The expected targeting grayscale value after flat field correction, for grayscale mode.
int	Tolerance [get, set]
	The tolerance range of the color or grayscale value in image, in 1 ~ 50. By default, it's 10. 0 is the special value to make use of the entire image as foreground. It helps to build the color range of the foreground object of interest.
double	UpdateRate [get, set]
	The learning rate to control how the flat field image is updated, in 0 ~ 1. The larger value means the higher weights in updating for the new input image. It is recommended to use a higher updating rate in the first some iterations, then lower it in the laters. By default, it's 0, indicates the update rate is calculated on the fly based on the ratio of known foreground pixels.

Detailed Description

This interface provide functionalities of flat field calibration and correction.

Flat field correction is used to compensate for the non-uniformity characteristics of the camera and lens combination such as:

• the inhomogeneous illumination intensities in the field-of-view
• the differences of light sensitivity between the pixels on the camera sensor
• the shading of lens, which is a generic form of lens vignetting, where light falloff can be asymmetrical and can have a color cast

The standard way to do flat field calibration is with a uniform target covering the whole field-of-view, usually a gray or white card. You may then obtain the flat field image:

1. Place the target to cover the whole view
2. Adjust the lens aperture and the illumination intensity to obtain the brightest possible image providing that no pixels are saturated.
3. Acquire several frames and blend them into one denoised image then pass it to the LFlatField object for training.

Another optional way is to use the target object in the actual inspection. The advantage of this method is that the real light reflection on the target object's surface is collected, making the correction more suitable for the material. To obtain the flat field image:

1. Adjust the lens aperture and the illumination intensity to obtain the brightest possible image providing that no pixels are saturated and the inspected components are clear.
2. Configure LFlatField for the raw and expected color or grayscale value, to extract the foreground pixels. You may alternatively adopt other locating tools to detect then generate the foreground regions or masks.
3. Place then capture the image of the target on any possible location in the view, make sure the whole view is almost covered. Pass those images (and their foreground regions or masks) to LFlatField for training

To use this interface, you should create a LFlatField object.

Example Code

C++

Code snippets: snippets/FlatFieldWhiteBoard.cpp, snippets/FlatFieldSolar.cpp

ILFlatFieldPtr ffc = LFlatField::Create();
// with white board
ffc->ColorMode = LPVImageFormat::LPVImageFormatGrayscale8;
ffc->ToGray = 160; // correct the white board to 160 gray
ffc->Tolerance = 0; // make use of the entire image as foreground
LPVErrorCode err = ffc->SetDarkFrame(darkImg); // set dark frame
if (err != LPVErrorCode::LPVNoError) return;
err = ffc->Train(wbImg, NULL); // train the white board image
if (err != LPVErrorCode::LPVNoError) return;
ILImagePtr correctedImg = LImage::Create();
err = ffc->FixImage(rawImg, correctedImg); // do flat field correction
if (err != LPVErrorCode::LPVNoError) return;

C#

Code snippets: snippets/FlatFieldWhiteBoard.cs, snippets/FlatFieldSolar.cs

LFlatField ffc = new LFlatField();
// with white board
ffc.ColorMode = LPVImageFormat.LPVImageFormatGrayscale8;
ffc.ToGray = 160; // correct the white board to 160 gray
ffc.Tolerance = 0; // make use of the entire image as foreground
LPVErrorCode err = ffc.SetDarkFrame(darkImg); // set dark frame
if (err != LPVErrorCode.LPVNoError) return;
err = ffc.Train(wbImg, null); // train the white board image
if (err != LPVErrorCode.LPVNoError) return;
LImage correctedImg = new LImage();
err = ffc.FixImage(rawImg, correctedImg); // do flat field correction
if (err != LPVErrorCode.LPVNoError) return;

COM

ILFlatFieldPtr ffc = LFlatField::Create();
// or, ILFlatFieldPtr ffc(__uuidof(LFlatField)), for absence of built-in Create functions (before 2.2.0)
// with white board
ffc->ColorMode = LPVImageFormat::LPVImageFormatGrayscale8;
ffc->ToGray = 160; // correct the white board to 160 gray
ffc->Tolerance = 0; // make use of the entire image as foreground
LPVErrorCode err = ffc->SetDarkFrame(darkImg); // set dark frame
if (err != LPVErrorCode::LPVNoError) return;
err = ffc->Train(wbImg, NULL); // train the white board image
if (err != LPVErrorCode::LPVNoError) return;
ILImagePtr correctedImg = LImage::Create();
// or, ILImagePtr correctedImg(__uuidof(LImage)), for absence of built-in Create functions (before 2.2.0)
err = ffc->FixImage(rawImg, correctedImg); // do flat field correction
if (err != LPVErrorCode::LPVNoError) return;

Member Function Documentation

FixImage()

LPVErrorCode FixImage	(	ILImage *	image,
		ILImage *	fixedImage
	)

Fix the image to remove shading or lens cast or affect of inhomogeneous light.
The correction works with a calibrated flat field, if not it returns the LPVErrCalibNotCalib error.

Parameters

[in]	image	The input image, with the same color format as the flat field.
[out]	fixedImage	Output the fixed result image.

Return values

error

Return error code if anything is wrong.

See also

Train(), GetFlatField()

GetFlatField()

void GetFlatField

(

ILImage *

previewImage

)

Get the flat field image for preview. The brighter pixels indicate the light intensity there are stronger.

Parameters

[out]

previewImage

Output the flat field image for preview.

IsCalibrated()

BOOL IsCalibrated

(

)

Check whether the flat field is well-calibrated.

Return values

val	Return True if it's calibrated, otherwise, return False.

SetDarkFrame()

LPVErrorCode SetDarkFrame

(

ILImage *

image

)

Set the dark frame, which represents the dark current of the sensor and should be eliminated from the corrected image. To obtain the dark frame, you may cover the lens with a cap, acquire several images then adopt multi-frame image blending to get the denoised result.

Parameters

image

The input dark image, with the same color format as the flat field.

Return values

error

Return error code if anything is wrong.

Train()

LPVErrorCode Train	(	ILImage *	image,
		ILRegion *	region
	)

Train the flat field using the given image. Foreground pixels are extracted in the given image, based on the raw sourcing color or grayscale range and the tolerance, then update to the result flat field image. If Tolerance is set to 0, then all the pixels in the input image and region is considered as foreground then contributes to the flat field.

Parameters

[in]	image	The input image, with the same color format as the flat field.
[in]	region	The optional input region, to specify the possible foreground locations.

Return values

error

Return error code if anything is wrong.

See also

FixImage(), SetDarkFrame(), GetFlatField(), Tolerance