5. AWB¶

5.1. Overview¶

The color temperature changes with the spectral composition of visible light. In low color temperature light source, white objects tend to be red. In high color temperature light source, white objects tend to be blue. The human eye can judge the real color of objects according to the memory of the brain. The function of AWB is to reduce the influence of external light sources on the real color of objects, so that the color information we collect can be transformed into unbiased color information under the ideal sunlight source.

5.2. Important Concepts¶

Color temperature: the color temperature is defined by the absolute blackbody. When the radiation of the light source in the visible area is exactly the same as that of the absolute blackbody, the temperature of the blackbody is called the color temperature of the light source.
White balance: under the light source of different color temperature, the response of white in the sensor will be blue or red. White balance algorithm adjusts the intensity of R, G, B three color channels to make white real.

5.3. Function Overview¶

AWB module consists of WB information statistics module and AWB strategy control algorithm firewall. The WB information statistics module of ISP determines whether each pixel output by sensor meets the white dot condition set by the user, and calculates the average value of R, G and B color channels of all pixels meeting the condition.

The image can be divided into m * n (M rows and N columns) regions, and the R, G and B mean values of each region and the number of white points participating in the statistics can be counted.

Support the output of R, G, B means of the whole image and the number of white points participating in the statistics.

The working principle of AWB is shown in Figure 4-1.

Fig. 5.1 Figure 4-1 AWB working principle¶

5.4. API Reference¶

5.4.1. AWB library interface¶

All AWB library interfaces are only for CVI AWB library. If customers implement AWB library by themselves, they don’t need to care for these interfaces and can’t use them.

CVI_AWB_Register : Register AWB library with ISP.
CVI_AWB_UnRegister : Inject AWB library to ISP.
CVI_AWB_SensorRegCallBack : The callback interface of sensor registration provided by AWB library.
CVI_AWB_SensorUnRegCallBack : The callback interface of sensor annotation provided by AWB library.

5.4.1.1. CVI_AWB_Register¶

【Description】

Register AWB library with ISP.

【Syntax】

CVI_S32 CVI_AWB_Register(VI_PIPE ViPipe, ALG_LIB_S *pstAwbLib);

【Parameter】

Parameter	Description	Input/Output
ViPipe	ViPipe number	Input
pstAwbLib	AWB algorithm library structure pointer	Input

【Return Value】

Return Value	Description
0	Success
Non 0	Failure. An error code is returned. For details, see chapter Error Codes.

【Requirement】

Header files：cvi_awb.h
Library files：libawb.a

【Note】

This interface calls CVI_ISP_AWBLibRegCallBack , which is the callback interface of AWB registration provided by
ISP library, to realize the function of AWB registering with ISP library.
This interface does not support multi process operation.
This interface is not supported on the linux side of the dual-os SDK.

【Example】

None

【Related Topic】

None

5.4.1.2. CVI_AWB_UnRegister¶

【Description】

Inject AWB library to ISP.

【Syntax】

CVI_S32 CVI_AWB_UnRegister(VI_PIPE ViPipe, ALG_LIB_S *pstAwbLib);

【Parameter】

Parameter	Description	Input/Output
ViPipe	ViPipe number	Input
pstAwbLib	AWB algorithm library structure pointer	Input

【Return Value】

Return Value	Description
0	Success
Non 0	Failure. An error code is returned. For details, see chapter Error Codes.

【Requirement】

Header files：cvi_awb.h
Library files：libawb.a

【Note】

The interface calls the callback interface CVI_ISP_AWBLibUnRegCallBack of AWB anti registration provided by
ISP library to realize the function of AWB anti registration with ISP library.
This interface does not support multi-process operations.
This interface is not supported on the linux side of the dual-os SDK.

【Example】

None

【Related Topic】

None

5.4.1.3. CVI_AWB_SensorRegCallBack¶

【Description】

The callback interface of sensor registration provided by AWB library.

【Syntax】

CVI_S32 CVI_AWB_SensorRegCallBack(VI_PIPE ViPipe, ALG_LIB_S *pstAwbLib, ISP_SNS_ATTR_INFO_S *pstSnsAttrInfo, AWB_SENSOR_REGISTER_S *pstRegister);

【Parameter】

Parameter	Description	Input/Output
ViPipe	ViPipe number	Input
pstAeLib	AWB algorithm library structure pointer	Input
pstSnsAttrInfo	Properties of sensors registered with AWB	Input
pstRegister	Sensor register structure pointer	Input

【Return Value】

Return Value	Description
0	Success
Non 0	Failure. An error code is returned. For details, see chapter Error Codes.

【Requirement】

Header files：cvi_awb.h
Library files：libawb.a

【Note】

SensorId is a custom value in the sensor library. It is mainly used to check whether the sensor registered with ISP and 3A are the same sensor.
Through a series of callback interfaces registered by sensor, AWB obtains differentiated initialization parameters and controls sensor.
This interface does not support multi process operation.
This interface is not supported on the linux side of the dual-os SDK.

_images/AWB004.png — Fig. 5.2 Figure 4-2 interface between AWB library and sensor Library¶

【Example】

None

【Related Topic】

None

5.4.1.4. CVI_AWB_SensorUnRegCallBack¶

【Description】

The callback interface for sensor de-registration provided by the AWB library.

【Syntax】

CVI_S32 CVI_AWB_SensorUnRegCallBack(VI_PIPE ViPipe, ALG_LIB_S *pstAwbLib, SENSOR_ID SensorId);

【Parameter】

Parameter	Description	Input/Output
ViPipe	ViPipe number	Input
pstAwbLib	AWB algorithm library structure pointer	Input
SensorId	Id of sensor de-registered with AWB	Input

【Return Value】

Return Value	Description
0	Success
Non 0	Failure. An error code is returned. For details, see chapter Error Codes.

【Requirement】

Header files：cvi_awb.h
Library files：libawb.a

【Note】

SensorId is a custom value in the sensor library. It is mainly
used to check whether the sensor registered with ISP and 3A are the same sensor.
This interface does not support multi process operation.
This interface is not supported on the linux side of the dual-os SDK.

【Example】

None

【Related Topic】

None

5.4.2. AWB Control Module¶

CVI_ISP_SetWBAttr : Set white balance attributes.
CVI_ISP_GetWBAttr : Get the white balance attribute.
CVI_ISP_SetWBAttrEx :set the white balance extension property.
CVI_ISP_GetWBAttrEx :get the white balance extension property.
CVI_ISP_QueryWBINfo : Get the current white balance gain coefficient, detect the color temperature, saturation value,color correction matrix coefficient.
CVI_ISP_SetAWBLogPath :When using CVI Awb lib, save the path of AWB debug log.
CVI_ISP_SetAWBLogName :When using CVI Awb lib, store the name of AWB debug log.
CVI_ISP_GetGrayWorldAwbInfo :Get gray world WB information.

5.4.2.1. CVI_ISP_SetWBAttr¶

【Description】

Set white balance attributes.

【Syntax】

CVI_S32 CVI_ISP_SetWBAttr(VI_PIPE ViPipe, const ISP_WB_ATTR_S *pstWBAttr);

【Parameter】

Parameter	Description	Input/Output
ViPipe	ViPipe number	Input
pstWBAttr	White balance attribute struct pointer	Input

【Return Value】

Return Value	Description
0	Success
Non 0	Failure. An error code is returned. For details, see chapter Error Codes.

【Requirement】

Header files：cvi_awb.h
Library files：libawb.a

【Note】

When the white balance control type is automatic, AWB algorithm automatically adjusts the white balance coefficient.

When the white balance control type is manual, the AWB algorithm is invalid, and user needs to set Rgain, Ggain, Bgain on one’s own.

The environment color temperature and illumination will affect the distribution of white spots. During the operation of CVI AWB algorithm, the white spot parameters of AWB Byaer statistical information will be automatically refreshed according to the environment parameters. If users want to modify AWB statistical parameters when CVI AWB algorithm is running, they need to call CVI_ISP_SetWBAttr interface to turn off the automatic refresh function of statistical parameters. When the user turns off the automatic refresh function of statistical parameters, there is a delay of 2 frames when the ISP receives the configuration and response. Therefore, the user needs to wait 2 frames before modifying the AWB statistical parameters.

【Example】

None

【Related Topic】

CVI_ISP_GetWBAttr

5.4.2.2. CVI_ISP_GetWBAttr¶

【Description】

Get the white balance attributes.

【Syntax】

CVI_S32 CVI_ISP_GetWBAttr(VI_PIPE ViPipe, ISP_WB_ATTR_S *pstWBAttr);

【Parameter】

Parameter	Description	Input/Output
ViPipe	ViPipe number	Input
pstWBAttr	White balance attribute struct pointer	Output

【Return Value】

Return Value	Description
0	Success
Non 0	Failure. An error code is returned. For details, see chapter Error Codes.

【Requirement】

Header files：cvi_awb.h
Library files：libawb.a

【Note】

None

【Example】

None

【Related Topic】

CVI_ISP_SetWBAttr

5.4.2.3. CVI_ISP_SetAWBAttrEx¶

【Description】

Set the white balance extension attributes.

【Syntax】

CVI_S32 CVI_ISP_SetAWBAttrEx(VI_PIPE ViPipe, const ISP_AWB_ATTR_EX_S *pstAWBAttrEx);

【Parameter】

Parameter	Description	Input/Output
ViPipe	ViPipe number	Input
PstAWBAttrEx	Extended white balance attribute struct pointer	Input

【Return Value】

Return Value	Description
0	Success
Non 0	Failure. An error code is returned. For details, see chapter Error Codes.

【Requirement】

Header files：cvi_awb.h
Library files：libawb.a

【Note】

This interface is valid only when the CVI_ISP_SetWBAttr interface member pstWBAttr->enAlgType is AWB_ALG_ADVANCE.

【Example】

None

【Related Topic】

CVI_ISP_GetAWBAttrEx

5.4.2.4. CVI_ISP_GetAWBAttrEx¶

【Description】

Get the white balance extension attributes.

【Syntax】

CVI_S32 CVI_ISP_GetAWBAttrEx(VI_PIPE ViPipe, ISP_AWB_ATTR_EX_S *pstAWBAttrEx);

【Parameter】

Parameter	Description	Input/Output
ViPipe	ViPipe number	Input
pstAWBAttrEx	Extended white balance attribute struct pointer	Output

【Return Value】

Return Value	Description
0	Success
Non 0	Failure. An error code is returned. For details, see chapter Error Codes.

【Requirement】

Header files：cvi_awb.h
Library files：libawb.a

【Note】

None

【Example】

None

【Related Topic】

CVI_ISP_SetAWBAttrEx

5.4.2.5. CVI_ISP_QueryWBInfo¶

【Description】

Get the current white balance gain coefficient, detect the color temperature, saturation value, color correction matrix coefficient.

【Syntax】

CVI_S32 CVI_ISP_QueryWBInfo(VI_PIPE ViPipe, ISP_WB_INFO_S *pstWBInfo);

【Parameter】

Parameter	Description	Input/Output
ViPipe	ViPipe number	Input
PstWBInfo	Color related state parameters	Output

【Return Value】

Return Value	Description
0	Success
Non 0	Failure. An error code is returned. For details, see chapter Error Codes.

【Requirement】

Header files：cvi_awb.h
Library files：libawb.a

【Note】

None

【Example】

None

【Related Topic】

None

5.4.2.6. CVI_ISP_SetAWBLogPath¶

【Description】

When using CVI Awb lib, save the path of AWB debug log.

【Syntax】

CVI_S32 CVI_ISP_SetAWBLogPath(const char *szPath);

【Parameter】

Parameter	Description	Input/Output
szPath	debug file path	Input

【Return Value】

Return Value	Description
0	Success
Non 0	Failure. An error code is returned. For details, see chapter Error Codes.

【Requirement】

Header files：cvi_awb.h
Library files：libawb.a

【Note】

The default path is /var/log
This interface is not supported on the linux side of the dual-os SDK.

【Example】

None

【Related Topic】

None

5.4.2.7. CVI_ISP_SetAWBLogName¶

【Description】

When using CVI Awb lib, store the name of AWB debug log.

【Syntax】

CVI_S32 CVI_ISP_SetAWBLogName(const char *szName);

【Parameter】

Parameter	Description	Input/Output
szName	File name	Input

【Return Value】

Return Value	Description
0	Success
Non 0	Failure. An error code is returned. For details, see chapter Error Codes.

【Requirement】

Header files：cvi_awb.h
Library files：libawb.a

【Note】

The preset file name is AwbLog0.txt
This interface is not supported on the linux side of the dual-os SDK.

【Example】

None

【Related Topic】

None

5.4.2.8. CVI_ISP_GetGrayWorldAwbInfo¶

【Description】

Get gray world WB information.

【Syntax】

CVI_S32 CVI_ISP_GetGrayWorldAwbInfo(VI_PIPE ViPipe, CVI_U16 *pRgain, CVI_U16 *pBgain);

【Parameter】

Parameter	Description	Input/Output
ViPipe	ViPipe id	Input
pRgain	R channel gain	Output
pBgain	B channel gain	Output

【Return Value】

Return Value	Description
0	Success
Non 0	Failure. An error code is returned. For details, see chapter Error Codes.

【Requirement】

Header files：cvi_awb.h
Library files：libawb.a

【Note】

None

【Example】

None

【Related Topic】

None

5.5. Date Types¶

5.5.1. Register¶

AWB_SENSOR_REGISTER_S :Define the sensor registration structure.
AWB_SENSOR_EXP_FUNC_S :Define the sensor callback function structure.
AWB_SENSOR_DEFAULT_S :Define the initialization parameter structure of AWB algorithm library.
AWB_SPEC_SENSOR_DEFAULT_S :Define the initialization parameter structure of SPECAWB algorithm.
AWB_AGC_TABLE_S : Define the saturation initialization parameter structure.
AWB_CCM_TAB_S : The automatic color correction matrix coefficients at different color temperatures are defined.
AWB_CCM_S : Define CCM color correction matrix attributes.

5.5.2. WB¶

ISP_AWB_CBCR_TRACK_ATTR_S :Define the linkage parameters of Bayer domain statistics
ISP_AWB_LUM_HISTGRAM_ATTR_S :The brightness histogram statistical parameters of white balance are defined
ISP_AWB_ALG_E :Define the calculation method property of white balance.
ISP_AWB_CT_LIMIT_ATTR_S :Define the gain range limit attribute of white balance.
ISP_MWB_ATTR_S :Define ISP manual white balance properties.
ISP_WB_ATTR_S :Define the white balance attribute.
ISP_AWB_ATTR_S：Define ISP automatic white balance properties.
ISP_AWB_ALG_TYPE_E：Define AWB algorithm properties.
ISP_AWB_ATTR_EX_S : Define the auto white balance extension attribute
ISP_AWB_EXTRA_LIGHTSOURCE_INFO_S :Define information about individual light points
ISP_AWB_IN_OUT_ATTR_S :Define information about individual light points
ISP_AWB_MULTI_LS_TYPE_E :Define AWB strategy under mixed light source
ISP_AWB_INDOOR_OUTDOOR_STATUS_E : Define AWB indoor and outdoor state.
ISP_WB_INFO_S :Define white balance, saturation, color correction information.

5.5.2.1. ISP_MWB_ATTR_S¶

【Description】

Define ISP manual white balance properties.

【Syntax】

typedef struct _ISP_MWB_ATTR_S {
  CVI_U16 u16Rgain;
  CVI_U16 u16Grgain;
  CVI_U16 u16Gbgain;
  CVI_U16 u16Bgain;
} ISP_MWB_ATTR_S;

【Member】

Member	Description
u16Rgain	R channel gain at MWB
u16Grgain	Gr channel gain at MWB
u16Grgain	Gb channel gain at MWB
u16Bgain	B channel gain at MWB

【Note】

A doubled gain of RGB channel is 0x400

【Related Data Type and Interface】

None

5.5.2.2. ISP_AWB_CT_LIMIT_ATTR_S¶

【Description】

Define the gain range limit attribute of white balance.

【Syntax】

typedef struct _ISP_AWB_CT_LIMIT_ATTR_S {
  CVI_BOOL bEnable;
  ISP_OP_TYPE_E enOpType;
  CVI_U16 u16HighRgLimit;
  CVI_U16 u16HighBgLimit;
  CVI_U16 u16LowRgLimit;
  CVI_U16 u16LowBgLimit;
} ISP_AWB_CT_LIMIT_ATTR_S;

【Member】

Member	Description
bEnable	awb gain range limiting switch
enOpType	Automatically or manually set the gain range of self balancing
u16HighRgLimit	Maximum R gain at high color temperature in manual mode
u16HighBgLimit	Minimum B gain at high color temperature in manual mode
u16LowRgLimit	Minimum R gain at low color temperature in manual mode
u16LowBgLimit	Maximum B gain at low color temperature in manual mode

【Note】

In automatic mode, AWB algorithm will calculate the upper and lower limits of gain by itself. When switching to manual mode, the above four R.B. gain limits will be used.

One time gain is 0x400

【Related Data Type and Interface】

None

5.5.3. ISP_AWB_ALG_E¶

【Description】

Define the calculation method property of white balance.

【Syntax】

typedef enum _ISP_AWB_ALG_E {
  ALG_AWB,
  ALG_AWB_SPEC,
  ALG_BUTT
} ISP_AWB_ALG_E;

【Member】

Member	Description
AWB	General AWB algorithm
ALG_AWB_SPEC	AWB algorithm based on machine learning is not supported at present.

【Note】

None

【Related Data Type and Interface】

None

5.5.3.1. ISP_AWB_ATTR_S¶

【Description】

Define automatic white balance properties.

【Syntax】

typedef struct _ISP_AWB_ATTR_S {
  CVI_BOOL bEnable;
  CVI_U16 u16RefColorTemp;
  CVI_U16 au16StaticWB[ISP_BAYER_CHN_NUM];
  CVI_S32 as32CurvePara[AWB_CURVE_PARA_NUM];
  ISP_AWB_ALG_TYPE_E enAlgType;
  CVI_U8 u8RGStrength;
  CVI_U8 u8BGStrength;
  CVI_U16 u16Speed;
  CVI_U16 u16ZoneSel;
  CVI_U16 u16HighColorTemp;
  CVI_U16 u16LowColorTemp;
  ISP_AWB_CT_LIMIT_ATTR_S stCTLimit;
  CVI_BOOL bShiftLimitEn;
  CVI_U16 u16ShiftLimit[AWB_CURVE_BOUND_NUM];
  CVI_BOOL bGainNormEn;
  CVI_BOOL bNaturalCastEn;
  ISP_AWB_CBCR_TRACK_ATTR_S stCbCrTrack;
  ISP_AWB_LUM_HISTGRAM_ATTR_S stLumaHist;
  CVI_BOOL bAWBZoneWtEn;
  CVI_U8 au8ZoneWt[AWB_ZONE_ORIG_ROW * AWB_ZONE_ORIG_COLUMN];
} ISP_AWB_ATTR_S;

【Member】

Member	Description
bEnable	Automatic white balance algorithm switch
u16RefColorTemp	The color temperature value of static white balance light source is recommended as 5000K light source
au16StaticWB	Static white balance coefficient is given by AWB calibration tool. Value range: [0-0x3FFF]。
as32CurvePara	CurvePara[0-2] Planck curve coefficient is given by AWB calibration tool. Planck curve describes the color performance of white block under standard light source with different color temperature. CurvePara[3-5] color temperature curve coefficient, given by AWB calibration tool. The color temperature curve describes the corresponding relationship between the color performance of white block and color temperature.
enAlgType	AWB algorithm categories selection includes AWB_ALG_LOWCOST and AWB_ALG_ADVANCE. ISP_AWB_ATTR_EX_S extended attributes only work in AWB_ALG_ADVANCE.
u8RGStrength	Automatic white balance R channel calibration intensity. Value range: [0, 255]
u8BGStrength	Automatic white balance B channel calibration intensity. Value range: [0, 255]
u16Speed	The convergence speed of the automatic white balance algorithm is improved. Value range: [0, 4095]
u16ZoneSel	When the parameter is 0 or 255, the white balance algorithm similar to gray world is adopted, and other values are classified and screened to improve the accuracy
u16HighColorTemp	The upper limit of color temperature of automatic white balance algorithm. Value range: [8000, 10000]
u16LowColorTemp	The lower limit of color temperature for automatic white balance algorithm. Value range: [0x0, u8HighColorTemp)
stCTLimit	Manually or automatically limit the white balance gain value
bShiftLimitEn	AWB gain beyond white point range maps back to white point range switch
u16ShiftLimit	AWB calculation of white point range parameters
bGainNormEn	By limiting the gain of RGB channel, the signal-to-noise ratio of low color temperature and low illumination scenes can be improved
bNaturalCastEn	AWB style switch at low color temperature. Default to off.
stCbCrTrack	AWB statistical range and ISO linked parameters
stLumaHist	AWB brightness and weight parameters
bAWBZoneWtEn	Screen partition weight switch, preset as off.
au8ZoneWt	32x32 image weight, value range [0,0xff] (not implemented yet)

【Note】

None

【Related Data Type and Interface】

None

5.5.3.2. ISP_AWB_ALG_TYPE_E¶

【Description】

Define AWB algorithm properties.

【Syntax】

typedef enum _ISP_AWB_ALG_TYPE_E {
  AWB_ALG_LOWCOST,
  AWB_ALG_ADVANCE,
  AWB_ALG_BUTT
} ISP_AWB_ALG_TYPE_E;

【Member】

Member	Description
AWB_ALG_LOWCOST	A simple and low computation AWB algorithm
AWB_ALG_ADVANCE	Advanced extended AWB algorithm, related to ISP_AWB_ATTR_EX_S
AWB_ALG_BUTT	Invalid setting

【Note】

None

【Related Data Type and Interface】

ISP_AWB_ATTR_EX_S_`

5.5.3.3. ISP_AWB_CBCR_TRACK_ATTR_S¶

【Description】

Define AWB statistical range and ISO linked parameters

【Syntax】

typedef struct _ISP_AWB_CBCR_TRACK_ATTR_S {
  CVI_BOOL bEnable;
  CVI_U16 au16CrMax[ISP_AUTO_ISO_STRENGTH_NUM];
  CVI_U16 au16CrMin[ISP_AUTO_ISO_STRENGTH_NUM];
  CVI_U16 au16CbMax[ISP_AUTO_ISO_STRENGTH_NUM];
  CVI_U16 au16CbMin[ISP_AUTO_ISO_STRENGTH_NUM];
} ISP_AWB_CBCR_TRACK_ATTR_S;

【Member】

Member	Description
bEnable	AWB statistical range and ISO linked switch
au16CrMax	The maximum value of R/G under different ISO
au16CrMin	The minimum value of R/G under different ISO
au16CbMax	The maximum value of B/G under different ISO
au16CbMin	The minimum value of B/G under different ISO

【Note】

It is recommended to calibrate CrMax(R/G) ,CbMin(B/G) at low color temperature.

【Related Data Type and Interface】

None

5.5.3.4. ISP_AWB_LUM_HISTGRAM_ATTR_S¶

【Description】

Define AWB brightness and weight parameters

【Syntax】

typedef struct _ISP_AWB_LUM_HISTGRAM_ATTR_S {
    CVI_BOOL bEnable;
    ISP_OP_TYPE_E enOpType;
    CVI_U8 au8HistThresh[AWB_LUM_HIST_NUM];
    CVI_U16 au16HistWt[AWB_LUM_HIST_NUM];
} ISP_AWB_LUM_HISTGRAM_ATTR_S;

Macro definition is as follow

#define AWB_LUM_HIST_NUM (6)

【Member】

Member	Description
bEnable	Whether or not to turn on the weight for different brightness, preset as open
enOpType	Automatic mode: AWB assigns weight automatically. Manual mode: users can set brightness classification and weight by themselves
au8HistThresh	Threshold of brightness classification (valid in manual mode)
au16HistWt	Weight of brightness classification (effective in manual mode)

【Note】

au8HistThresh[0] is fixed to 0, au8HistThresh[5] is fixed to 255.

au8HistThresh[i+1] must be greater than au8HistThresh[i]

au16HistWt weight value range is 32~512

【Related Data Type and Interface】

None

5.5.4. ISP_WB_ATTR_S¶

【Description】

Define white balance attributes

【Syntax】

typedef struct _ISP_WB_ATTR_S {
  CVI_BOOL bByPass;
  CVI_U8 u8AWBRunInterval;
  ISP_OP_TYPE_E enOpType;
  ISP_MWB_ATTR_S stManual;
  ISP_AWB_ATTR_S stAuto;
  ISP_AWB_ALG_E enAlgType;
  CVI_U8 u8DebugMode;
} ISP_WB_ATTR_S;

【Member】

Member	Description
bByPass	White balance module Bypass enable, default to CVI_FALSE.
u8AWBRunInterval	Working frequency of white balance module. Value range: [0x1, 0xFF]
enOpType	Automatic white balance and manual white balance switch.
stManual	Manual parameters
stAuto	Automatic parameters
enAlgType	AWB algorithm type
u8DebugMode	It is used in debugging, and generally does not need to be set

【Note】

When bByPass is TRUE, other WB parameters will not take effect, and the RGB channel gain is fixed to double 0x400

The default value of u8AWBRunInterval is 6, which means AWB is executed every 6 frames. This value can be increased according to the demand to reduce the frequency of AWB.

【Related Data Type and Interface】

None

5.5.4.1. ISP_AWB_ATTR_EX_S¶

【Description】

Define auto white balance extended attributes

【Syntax】

typedef struct _ISP_AWB_ATTR_EX_S {
  CVI_U8 u8Tolerance;
  CVI_U8 u8ZoneRadius;
  CVI_U16 u16CurveLLimit;
  CVI_U16 u16CurveRLimit;
  CVI_BOOL bExtraLightEn;
  ISP_AWB_EXTRA_LIGHTSOURCE_INFO_S stLightInfo[AWB_LS_NUM];
  ISP_AWB_IN_OUT_ATTR_S stInOrOut;
  CVI_BOOL bMultiLightSourceEn;
  ISP_AWB_MULTI_LS_TYPE_E enMultiLSType;
  CVI_U16 u16MultiLSScaler;
  CVI_U16 au16MultiCTBin[AWB_CT_BIN_NUM];
  CVI_U16 au16MultiCTWt[AWB_CT_BIN_NUM];
  CVI_BOOL bFineTunEn;
  CVI_U8 u8FineTunStrength;
  //AWB Algo 6
  struct ST_ISP_AWB_INTERFERNCE_S stInterfernce;
  struct ST_ISP_AWB_SKIN_S stSkin;
  struct ST_ISP_AWB_SKY_S stSky;
  struct ST_ISP_AWB_GRASS_S stGrass;
  struct ST_ISP_AWB_CT_WGT_S stCtLv;
  struct ST_ISP_AWB_SHIFT_LV_S stShiftLv;
  struct ST_ISP_AWB_REGION_S stRegion;
  CVI_U8 adjBgainMode;
  CVI_U8 reserve[239];
} ISP_AWB_ATTR_EX_S;

The macro is defined as follows:
#define AWB_CT_BIN_NUM    (8)
#define AWB_LS_NUM   (4)

【Member】

Member	Description
u8Tolerance	AWB adjust the deviation range. When the error is within this range, AWB will not adjust.
u8ZoneRadius	The size of AWB statistical partition. The smaller the value, the higher the accuracy of AWB, but it will reduce the stability of AWB algorithm
u16CurveLLimit	Left limit of AWB color temperature curve (R/G, B/G), value range: [0x0, 0x200]
u16CurveRLimit	Right limit of AWB color temperature curve (R/G, B/G), value range: [0x200, 0x3FF]
bExtraLightEn	Whether to turn on the independent light source
stLightInfo	Whether to consider the independent light source points outside the color temperature curve in AWB calculation, up to four independent points
stInOrOut	Parameters for AWB to judge indoor and outdoor scenes
bMultiLightSourceEn	AWB detects whether the current scene is a mixed light source to adjust the saturation or CCM
enMultiLSType	Adjust saturation or CCM
u16MultiLSScaler	Adjust the saturation or CCM intensity under mixed light source
au16MultiCTBin	The segmentation parameter of color temperature. Must be an increasing sequence
au16MultiCTWt	Color temperature segmentation weight, range: [0x0, 0x400]
bFineTunEn	AWB special color detection switch, such as skin color
u8FineTunStrength	The intensity of skin color, blue and other special color detection

【Note】

ISP_AWB_ATTR_EX_S extended attribute only works when pstWBAttr->enAlgType is AWB_ALG_ADVANCE

u8Tolerance is the sensitivity parameter of AWB.

When the value is 0, the AWB parameter will be updated imAWB/mediately.

When the value is relatively large, the AWB parameter will not be updated when the ambient color temperature slightly changes, and the screen will be slightly biased. It is recommended that the outdoor setting be 0 and the indoor setting be 2.

When u16CurveLLimit value < 512, it is mainly to exclude green objects, whereas when u16CurveRLimit value > 512, it is to exclude purplish areas

After bMultiLightSourceEn is turned on, AWB will judge whether the scene is a mixed light source. In such a scene, the saturation or CCM will be reduced to reduce the color deviation

In WDR mode, the mixed light detection function will be automatically turned off

【Related Data Type and Interface】

None

5.5.4.2. ISP_AWB_EXTRA_LIGHTSOURCE_INFO_S¶

【Description】

Define the parameters of the independent light point

【Syntax】

typedef struct _ISP_AWB_EXTRA_LIGHTSOURCE_INFO_S {
  CVI_U16 u16WhiteRgain;
  CVI_U16 u16WhiteBgain;
  CVI_U16 u16ExpQuant;
  CVI_U8 u8LightStatus;
  CVI_U8 u8Radius;
} ISP_AWB_EXTRA_LIGHTSOURCE_INFO_S;

【Member】

Member	Description
u16WhiteRgain	R-channel gain of special light source
u16WhiteBgain	B-channel gain of special light source
u16ExpQuant	Judging by the external brightness. ExpQuant is the limit value of the brightness that is turned on. For example ExpQuant = 6, which means that the WB light source point is turned on below LV6 (the general night scene is below LV6) ExpQuant =106 means LV6 and above open ExpQuant =112 means it is enabled above LV12 (LV12 is generally outdoor)
u8LightStatus	Types of special light sources,0: no action 1: Add light point 2: Delete calculations near light points
u8Radius	Area size of special light source point, value range: [0x0, 0xFF]

【Note】

None

【Related Data Type and Interface】

None

5.5.4.3. ISP_AWB_IN_OUT_ATTR_S¶

【Description】

Define the parameters of AWB for outdoor and indoor judgment of the scene

【Syntax】

typedef struct _ISP_AWB_IN_OUT_ATTR_S {
  CVI_BOOL bEnable;
  ISP_OP_TYPE_E enOpType;
  ISP_AWB_INDOOR_OUTDOOR_STATUS_E enOutdoorStatus;
  CVI_U32 u32OutThresh;
  CVI_U16 u16LowStart;
  CVI_U16 u16LowStop;
  CVI_U16 u16HighStart;
  CVI_U16 u16HighStop;
  CVI_BOOL bGreenEnhanceEn;
  CVI_U u8OutShiftLimit;
} ISP_AWB_IN_OUT_ATTR_S;

【Member】

Member	Description
bEnable	Judge whether the scene is indoor or outdoor switch
enOpType	Judge indoor and outdoor (automatic or manual)
enOutdoorStatus	Indoor or outdoor mode (in manual mode)
u32OutThresh	Threshold to determine indoor and outdoor. When the brightness is less than the threshold, it is judged that the LV of indoor and outdoor is more than 15.
u16LowStart	Lower the weight of low color temperature, and the starting point of low color temperature region is suggested to be 5000K.
u16LowStop	Lower the weight of low color temperature, and the end point of low color temperature area is recommended to be 4500k. Value range: (0,u16LowStart)
u16HighStart	Lower the weight of high color temperature, the starting point of high color temperature region is suggested to be 6500k. Value range: (u16LowStart, 0xFFFF]
u16HighStop	Lower the weight of high color temperature, and the end point of high color temperature area is recommended to be 8000K. Value range: (u16HighStart, 0xFFFF]
bGreenEnhanceEn	Switch for adding green channel in green plant scene
u8OutShiftLimit	When the scene is judged as outdoor scene, the AWB algorithm is limited by the range of white points

【Note】

Most outdoor brightness LV is greater than 15, so u32OutThresh is recommended to be greater than 15.

The range of the four parameters is as follows: u16LowStop<u16LowStart<u16HighStart<u16HighStop

【Related Data Type and Interface】

As shown in the figure below, u16LowStop is 3800K, and u16LowStart is 5000K

u16HighStart is 6200K, and u16HighStop is 7200K

The general weight is 32, and the maximum weight of outdoor color temperature is 256.

5.5.4.4. ISP_AWB_MULTI_LS_TYPE_E¶

【Description】

Define AWB strategy under mixed light source

【Syntax】

typedef enum _ISP_AWB_MULTI_LS_TYPE_E {
  AWB_MULTI_LS_SAT,
  AWB_MULTI_LS_CCM,
  AWB_MULTI_LS_BUTT
} ISP_AWB_MULTI_LS_TYPE_E;

【Member】

Member	Description
AWB_MULTI_LS_SAT	Adjusting saturation under mixed light source
AWB_MULTI_LS_CCM	Adjusting CCM under mixed light source
AWB_MULTI_LS_BUTT	Invalid

【Note】

None

【Related Data Type and Interface】

None

5.5.4.5. ISP_AWB_INDOOR_OUTDOOR_STATUS_E¶

【Description】

Define AWB indoor and outdoor state

【Syntax】

typedef enum _ISP_AWB_INDOOR_OUTDOOR_STATUS_E {
  AWB_INDOOR_MODE,
  AWB_OUTDOOR_MODE,
  AWB_INDOOR_OUTDOOR_BUTT
} ISP_AWB_INDOOR_OUTDOOR_STATUS_E;

【Member】

Member	Description
AWB_INDOOR_MODE	indoor mode
AWB_OUTDOOR_MODE	Outdoor mode
AWB_INDOOR_OUTDOOR_BUTT	invalid

【Note】

None

【Related Data Type and Interface】

None

5.5.5. ISP_WB_INFO_S¶

【Description】

Define white balance, saturation, color correction information

【Syntax】

typedef struct _ISP_WB_INFO_S {
  CVI_U16 u16Rgain;
  CVI_U16 u16Grgain;
  CVI_U16 u16Gbgain;
  CVI_U16 u16Bgain;
  CVI_U16 u16Saturation;
  CVI_U16 u16ColorTemp;
  CVI_U16 au16CCM[CCM_MATRIX_SIZE];
  CVI_U16 u16LS0CT;
  CVI_U16 u16LS1CT;
  CVI_U16 u16LS0Area;
  CVI_U16 u16LS1Area;
  CVI_U8  u8MultiDegree;
  CVI_U16 u16ActiveShift;
  CVI_U32 u32FirstStableTime;
  ISP_AWB_INDOOR_OUTDOOR_STATUS_E enInOutStatus;
  CVI_S16 s16Bv;
} ISP_WB_INFO_S;

【Member】

Member	Description
u16Rgain	Current R-channel gain value
u16Grgain	Current Gr channel gain value
u16Gbgain	Current Gb channel gain value
u16Bgain	Current B channel gain value
u16Saturation	Current Saturation
u16ColorTemp	The current calculated color temperature value
au16CCM	The current color correction matrix, 10bit decimal precision. bit 15 is the sign bit, 0 means a positive number, 1 means a negative number, for example 0x8010 means -16
u16LS0CT	Color temperature of main light source in mixed light scene
u16LS1CT	Color temperature of secondary light source in mixed light scene
u16LS0Area	Main light area of mixed light scene
u16LS1Area	Secondary light area of mixed light scene
u8MultiDegree	The probability that the current scene is a mixed light source
u16ActiveShift	Limit value of current white balance range
u32FirstStableTime	The first AWB convergence time in frames
ISP_AWB_INDOOR_OUTDOOR_STATUS_E	Indoor and outdoor detection results
s16Bv	bv value of current environment

【Note】

None

【Related Data Type and Interface】

None