Overview

The Lenscal DLL provides functions to quickly find lens correction register settings that will best correct the image brightness and color shading distortion caused by the camera's optical system. For sensors with phase detect auto focus (PDAF), this includes the spacial calibration as well.
The library supports all Bayer sensors with built-in lens correction, including SOC sensors.

Sensors not supported are: MT9P001 (A-5100) and MT9P006 (A-51HD-plus).

The input to the calibration is an image of a flat, gray field. The output is a list of the lens correction registers and their values. To get a good calibration requires careful setup of the camera system under test and correct use of the Lenscal functions and their parameters. Contact your ON Semiconductor field application engineer for assistance.
Two kinds of lens correction circuits are in use on ON Semiconductor sensors, what I'll call the orthogonal type and the polynomial type. The orthogonal type uses sets of horizontal and vertical gain curves added together to create a two-dimensional gain. The polynomial type uses a two-dimensional polynomial function. The calibration algorithms and parameters are different for each. The orthogonal type sensors are MT9D111 (SOC2010), MT9D112 (SOC2020), MT9D012 (A-2020). All others are polynomial type.

Quick Start

Here is partial C/C++ code to calibrate an AR1337 sensor from a raw Bayer image file, and write the register values to a file in the DevWare .ini file format. Error checking removed for brevity:
#include "midlib2.h"
#include "lenscal.h"
void *lc;
CalibParams params = {sizeof(params), 100, 24, 1, 400, 300, 0.0, 1.0, 0};
params.nXedgeIgnore = -1;
params.nYedgeIgnore = -1;
lc = lc_Create(lc_SensorType("AR1337"), 1, -1);
lc_LoadInputImageFile(lc, "capture0001.raw", 0, -1, -1, -1);
lc_FindSolution(lc, &params);
lc_DumpRegFile(lc, "lenscal-AR1337.ini", REGFMT_DEVWARE_INI, NULL, NULL);
lc_Destroy(lc);

Here is partial C/C++ code to run a simulation of the AR1337 lens correction on a captured raw Bayer image using register settings loaded from an ini file, and write the simulated image to a file:
#include "midlib2.h"
#include "lenscal.h"
void *lc;
lc = lc_Create(lc_SensorType("AR1337"), 1, -1);
lc_LoadInputImageFile(lc, "capture0002.raw", 0, -1, -1, -1);
lc_LoadInputIniFile(lc, "lenscal-AR1337.ini", NULL);
lc_SimulateCorrectedImage(lc, "corrected.raw", RAW_UNKNOWN, -1);
lc_Destroy(lc);

lenscal API Functions

The functions provided by the lenscal API are described below.
All library functions use the Windows standard calling convention. A C/C++ header file is provided.
Lenscal, and other ON Semiconductor tools, internally represent sensor registers by their symbolic name and depend on the sensor data (*.sdat, *.xsdat) files in the sensor_data directory to translate between the symbolic names and numerical register addresses on the sensors. In order for functions that load and save register settings to work, the sensor data file for the selected sensor must be on the computer (or a mapped drive). The lc_Create() function will search the normal installation directory for the sensor data file. As long as you have installed the software and the sensor data files with the installation wizards provided by ON Semiconductor, everything is properly set up. The lc_Create2() function lets you provide the path or filename of a sensor data file if you have a custom configuration.

lc_Create()

Definition:
void *lc_Create(mi_sensor_types sensorType, int nRev, int nPolynomialOrder);
Summary:
Create a lenscal object and initialize it with the given parameters. Pass the return value to all other lenscal functions. Do not dereference the pointer.
The sensorType may be MI_UNKNOWN_SENSOR, in which case the input image will be corrected using the polynomial algorithm (you can get simulated output), but there will not be any meaningful register settings.
Parameters:

Returns:

The lenscal object can be reused to calibrate any number of images, as long as they are all for the same sensor type.

lc_Create2()

Definition:
void *lc_Create2(const char *szSensorDataPath, mi_sensor_types sensorType, int nRev, int nPolynomialOrder);
Summary:
Like lc_Create(), except also takes a file name for a sensor data file, or directory name to search for the sensor data file to use for translating register symbolic names into numerical addresses.
If you pass a full path and filename for the sensor data file, you can pass MI_UNKNOWN_SENSOR for sensorType and the library will use the sensor type and revision from the sensor data file. If another value is passed for sensorType then that parameter and the nRev parameter override the values from the sensor data file.
Parameters:

Returns:

lc_SensorType()

Definition:
void lc_SensorType(const char *szPartNumber)
Summary:
Convert a device part number string into a sensor type enum (mi_sensor_types) value suitable for lc_Create(). Enum symbols for very new parts may not be in the released header files. This function can generate the correct parameter without the symbol.
Parameters:

Returns:

lc_Destroy()

Definition:
void lc_Destroy(void *lc)
Summary:
Free all memory associated with the object. The pointer is invalid after this call, and so are any other associated pointers allocated by Lenscal functions.
Parameters:

Returns:

lc_LoadInputImageFile()

Definition:
short *lc_LoadInputImageFile(void *lc, const char *szInFileName, int nBayerPattern, int nBlack, int nCropLeft, int nCropTop)
Summary:
Load an image from a file and subtract the black pedestal value from the pixels if it's Bayer data.
Parameters:

Returns:

The returned pointer is provided so you may access the pixel values. Do not free the buffer. It will be freed automatically when the lc is destroyed or when you load a new image.
The Bayer data file may be in any of a variety of formats including raw binary, ASCII text, or monochrome PNG. The filename parameter may be NULL, in which case the function will fill the buffer with gray pixels.
The Bayer pattern codes are: 0 – GR/BG; 1 – RG/GB; 2 – BG/GR; 3 – GB/RG. Unless you are using some unusual register settings, the Bayer pattern should be 0. The lenscal library requires that the image be captured without flip or mirror modes. If the image was captued with flip or mirror on then you must re-orient the image before using it with lenscal.
The raw Bayer pixel data from an ON Semiconductor sensor has an offset (black pedestal) added to all pixels so there is a small blacker-than-black margin. This value must be subtracted off correctly in order for the calibration to be accurate. The black pedestal is programmed by a register on the sensor, but there is rarely any reason to change it from its default. Assuming the sensor black pedestal register has not been changed from the default and you have not altered the data, pass -1 for nBlack. If you have already subtracted the black pedestal pass 0. If you know that the black pedestal is some specific value, pass that value.

lc_LoadInputImageFileYcbcr()

Definition:
short *lc_LoadInputImageFileYcbcr(void *lc, const char *szInFileName, YCbCrParams *ycbcrParams, int nCropLeft, int nCropTop)
Summary:
Load a YCbCr image from a file and convert it to Bayer or RGB if the calibration is for MT9D111 (SOC2010). There are several variations on YCbCr data, so the ycbcrParams structure contains the remaining parameters needed to convert the YCbCr data to RGB. Take care to fill in the parameters correctly or else the calibration will be incorrect.
Except for the MT9D111 (SOC2010), it is recommended to use raw Bayer data instead of YCbCr data for lens calibration. This function is provided only for those cases where it is impossible to get raw Bayer data from the camera system.
Parameters:

Returns:

The returned pointer is provided so you may access the pixel values. The returned image will be Bayer format data generated from the YCbCr input image. Do not free the buffer. It will be freed automatically when the lc is destroyed or when you load a new image.
The YCbCr data file should be a binary .raw file. The filename parameter may be NULL, in which case the function will fill the buffer with gray pixels.
The lenscal library requires that the image be captured without flip or mirror modes. If the image was captued with flip or mirror on then you must re-orient the image before using it with lenscal.
The YCbCrParams structure:

lc_SetInputImage()

Definition:
short *lc_SetInputImage(void *lc, short *pOriginal, int nWidth, int nHeight, int nBpp, int nBayerPattern, int nBlack, int nCropLeft, int nCropTop)
Summary:
Set the current image from a memory buffer. If it's Bayer data, convert the data to 12 bits per pixel and subtract the black pedestal value. The data in the buffer may be altered.
Parameters:

Returns:

Do not free the returned pointer if it is different from pOriginal. It will be freed when the lenscal object is destroyed or a new image is loaded.
The Bayer data must be either 8, 10 or 12 bits per pixel. If greater than 8 bits then each pixel must occupy the low bits of a 16-bit word, with little endian byte order. The function will subtract the black pedestal and convert the data to 12 bits per pixel. If the input is 8 bpp then the function will allocate a new buffer to hold the 12 bpp data, otherwise the transform will be done in place in your buffer.
RGB data must be 32 bits per pixel, 8 bits per color channel, B-G-R-x byte order.
The Bayer pattern codes are: 0 – GR/BG; 1 – RG/GB; 2 – BG/GR; 3 – GB/RG. Unless you are using some unusual register settings, the Bayer pattern should be 0. The lenscal library requires that the image be captured without flip or mirror modes. If the image was captued with flip or mirror on then you must re-orient the image before using it with lenscal.
The raw Bayer pixel data from a sensor almost always has an offset (black pedestal) added to all pixels so there is a small blacker-than-black margin. The black pedestal must be subtracted off correctly in order for the calibration to be accurate. The black pedestal is programmed by a register on the sensor, but there is rarely any reason to change it from its default. For non-SOC sensors, assuming the sensor black pedestal register has not been changed from the default and you have not altered the data, pass -1 for nBlack. For SOCs, passing -1 will subtract a value appropriate for the sensor core of the SOC, however many SOCs have a second bypass mode called LC Bypass or PGA Bypass that subtracts the pedestal already. If the image data was captured in that mode then you must pass 0 for nBlack. If you have already subtracted the black pedestal pass 0. If you know that the black pedestal is some specific value, pass that value.

lc_SetInputImageYcbcr()

Definition:
short *lc_SetInputImageYcbcr(void *lc, unsigned char *pOriginal, int nWidth, int nHeight, YCbCrParams *ycbcrParams, int nCropLeft, int nCropTop)
Summary:
Set the current image from a memory buffer containing YCbCr data. The data will be converted to Bayer (or RGB for MT9D111), and a pointer to the converted data is returned.
There are several variations on YCbCr data, so the ycbcrParams structure contains the remaining parameters needed to convert the YCbCr data to RGB. Take care to fill in the parameters correctly or else the calibration will be incorrect.
Except for the MT9D111 (SOC2010), it is recommended to use raw Bayer data instead of YCbCr data for lens calibration. This function is provided only for those cases where it is impossible to get raw Bayer data from the camera system.
Parameters:

Returns:

Do not free the returned pointer. It will be freed when the lenscal object is destroyed or a new image is loaded.
The lenscal library requires that the image be captured without flip or mirror modes. If the image was captued with flip or mirror on then you must re-orient the image before using it with lenscal.

lc_LoadInputIniFile()

Definition:
int lc_LoadInputIniFile(void *lc, const char *szInFileNameIni, const char *szSection);
Summary:
Load a DevWare style ini file with lens correction register settings. If you load an image from a file or a memory buffer, you can simulate the lens correction on the image with lc_SimulateCorrectedImage(). The register settings have to be for the sensor type used to create the lc object, of course.
Parameters:

Returns:

lc_LoadBasisSetting()

Definition:
int lc_LoadBasisSetting(void *lc, const char *szBasisFileNameIni);
Summary:
Load a lens correction register setting to be used as the "basis" for the new register settings generated by lc_FindSolution(). The center coordinate, zone boundaries and scale factors will be carried from the basis setting to the new setting.
Parameters:

Returns:

There is no way to unload a basis setting. You would have to destroy the lenscal object and create a new one.

lc_LoadBandsFile()

Definition:
int lc_LoadBandsFile(void lc, const char *szBandsFileName);
Summary:
Load a file specifying the areas of the image to use in the calibration. (Corresponds to the Analysis Bands dialog page in DevWare.) This information is only used for the orthogonal type of lens correction, the polynomial calibration always uses the whole image.
Parameters:

Returns:

For complete control over the analysis band positions and weights, put the data in a text file and load it with this function. In the file, for each analysis band put 'H' for a horizontal band or 'V' for a vertical band, followed by the position of the band as a fraction of the image width or height and the weight in arbitrary units. Up to three horizontal bands and three vertical bands may be specified. Example:
H 0.333 1
H 0.667 1
V 0.25 1
V 0.50 2
V 0.75 1
Defines two horizontal bands a 1/3rd and 2/3rd of the image height, at equal weight, and three vertical bands at 1/4 1/2 and 3/4 of the image width, with the center band having greater weight. The default is:
H 0.25 1
H 0.50 1
H 0.75 1
V 0.25 1
V 0.50 1
V 0.75 1
There is no unloading of analysis band parameters. To go back to the defaults, you must destroy the lenscal object and create a new one.

lc_SetImageTransform()

Definition:
int lc_SetImageTransform(void *lc, float *pTransform, int nWidth, int nHeight)
Summary:
Set the current image transform surface from a memory buffer. A transform surface is an array of single-precision floating point values, one for each pixel in the input image. Each pixel in the input image will be multiplied by the corresponding value from the file prior to calibration. It only applies to Bayer images.
Parameters:

Returns:

The transform surface is applied to the input image in lc_FindSolution(), so it doesn't matter in which order you call lc_SetInputImage() and lc_SetImageTransform(). The transform doesn't change the input image buffer, so you can apply multiple transforms to the same input image.
As of this writing, the width and height of the transform surface must match exactly the input image dimensions or else lc_FindSolution() will fail (this function will not fail). Be informed that this function only keeps a copy of the pointer, not of the array, so you must not free the array memory until after you call lc_FindSolution().
The purpose of this feature is to simulate multiple illuminant responses from a single flat field image.

lc_FindSolution()

Definition:
int lc_FindSolution(void *lc, CalibParams *pCalibParams);
Summary:
Run a calibration algorithm on the input image to find good lens correction and PDAF spatial calibration register settings. You must provide an input image with lc_LoadInputImageFile() or lc_SetInputImage() prior to calling this function. To get the results use lc_DumpRegList() or lc_DumpRegFile().
Parameters:

Returns:

The CalibParams structure:

lc_FindApga()

Definition:
int lc_FindApga(void *lc, ApgaParams *pApgaParams);
Summary:
Calibrate APGA (Adaptive Positional Gain Adjustment) register settings. APGA is an additional refinement to the lens correction.
You can call this function following lc_FindSolution() to get an even better calibration.
Alternately you can load another uncorrected image and use an existing lens calibration setting with lc_FindApga() to get the APGA refinement to that setting that best corrects the input image.
This is useful when the lens calibration varies with illuminant type. To more easily correct under different illumination conditions create one full lens calibration setting with lc_FindSolution(), then generate APGA refinements to that setting for other illuminants using lc_FindApga().
Like lc_FindSolution(), you must provide an input image with lc_LoadInputImageFile() or lc_SetInputImage() prior to calling this function. You must also provide a lens correction setting, either implicitly with a previous call to lc_FindSolution() or by loading from a file with lc_LoadInputIniFile(). To get the results use lc_DumpRegList() or lc_DumpRegFile().
Parameters:

Returns:

The ApgaParams structure:

lc_ResetPga()

Definition:
int lc_ResetPga(void *lc);
Summary:
The non-APGA registers will not be included by lc_DumpRegList() or lc_DumpRegFile().

Parameters:

Returns:

lc_ResetApga()

Definition:
int lc_ResetApga(void *lc);
Summary:
Set the APGA coefficients in the lc object to 0.
Useful, for example, if you want to run a simulation without APGA.
Parameters:

Returns:

lc_DumpRegList()

Definition:
RegList * lc_DumpRegList(void *lc);
Summary:
Return the current register settings in a RegList structure. The register settings can come from lc_FindSolution() or lc_LoadInputIniFile().
Parameters:

Returns:

The RegList structure:

Do not free the returned pointer. It will be freed when the lenscal object is destroyed.
This function depends on the sensor data file for the sensor being present on the computer in order to generate numerical register addresses in the output.

lc_DumpRegFile()

Definition:
int lc_DumpRegFile(void *lc, const char *szOutFileName, enum RegFormat format, const char *szHeader, const char *szFooter);
Summary:
Write the current register settings to a file.
Parameters:

Returns:

This function depends on the sensor data file for the sensor being present on the computer in order to generate numerical register addresses in the output file. If the sensor data file is not present, using the DevWare ini format will still work, but the file will conatain FIELD_WR= commands instead of REG= commands. REGFMT_DEVWARE_INI_FIELDWR forces the output to use FIELD_WR= commands with register names instead of addresses. In that case the sensor data file is not needed.

lc_DumpRegFileAppend()

Definition:
int lc_DumpRegFileAppend(void *lc, const char *szOutFileName, enum RegFormat format, const char *szHeader, const char *szFooter);
Summary:
Same as lc_DumpRegFile() except appends to the file if it already exists.
Parameters:

Returns:

lc_SimulateCorrectedImage()

Definition:
short * lc_SimulateCorrectedImage(void *lc, const char *szOutFileName, enum RawFormat outFormat, int nBlack);
Summary:
Run a simulation of the current register settings on the current input image, add a black pedestal value, and write the image out to a file. You must provide an input image with lc_LoadInputImageFile() or lc_SetInputImage(), and a set of register values with lc_LoadInputIniFile() or lc_FindSolution() prior to calling this function.
Parameters:

Returns:

Do not free the returned pointer. It will be freed when the lenscal object is destroyed.

lc_CalculateCorrectedSbl()

Definition:
int lc_CalculateCorrectedSbl(void *lc, double *pResults, int nLength);
Summary:
Calculate the shading balance results for the corrected image. You must provide an input image with lc_LoadInputImageFile() or lc_SetInputImage(), and a set of register values with lc_LoadInputIniFile() or lc_FindSolution() prior to calling this function. It is not necessary to call lc_SimulateCorrectedImage() first.
Parameters:

Returns:

pResults[0] will be shading balance value. pResults[1] will be the non-radial shading balance value. If there are more than two elements in the pResults array, the remainder are undefined.

lc_CalculateCorrectedAvgColor()

Definition:
int lc_CalculateCorrectedAvgColor(void *lc, double *pResults, int nLength);
Summary:
Calculate the average color of the corrected image. You must call lc_SimulateCorrectedImage() first. The results are normalized to 0.0… 1.0 range.
Parameters:

Returns:

pResults[0] through pResults[3] will be the Red, Gr, Gb, and Blue average values respectively. If there are more than four elements in the pResults array, the remainder are undefined.