---
title: hi_isp_awb_attr_ex
description: "定义自动白平衡扩展属性。"
url: https://www.hiascend.com/document/detail/zh/CANNCommunityEdition/latest/others/ispdevug/ispdevapi_0236.html
sourcePath: /source/zh/CANNCommunityEdition/920beta1/others/ispdevug/ispdevapi_0236.html
indexId: 84b34c261ca96bdbde31e6cae4fcd4a7667b040370c8277006f51e4a9868048276
---
# hi_isp_awb_attr_ex

#### 说明

定义自动白平衡扩展属性。


#### 定义

```
typedef struct {
hi_u8
tolerance;
hi_u8
zone_radius;
hi_u16
curve_l_limit;
hi_u16
curve_r_limit;
hi_bool
extra_light_en;
hi_isp_awb_extra_light_source_info
light_info[HI_ISP_AWB_LS_NUM];
hi_isp_awb_in_out_attr
in_or_out;
hi_bool
multi_light_source_en;
hi_isp_awb_multi_ls_type
multi_ls_type;
hi_u16
multi_ls_scaler;
hi_u16
multi_ct_bin[HI_ISP_AWB_MULTI_CT_NUM];
hi_u16
multi_ct_wt[HI_ISP_AWB_MULTI_CT_NUM];
hi_bool
fine_tun_en;
hi_u8
fine_tun_strength;
} hi_isp_awb_attr_ex;
```


#### 成员

| 成员名称 | 描述 |
| --- | --- |
| tolerance | 自动白平衡调整的偏差范围，检测误差在门限范围内时，AWB不动作。 取值范围：[0x0,0xFF] |
| zone\_radius | 自动白平衡统计中对像素分类时用的距离范围。该值越小，AWB精度越高，但会降低AWB算法稳定性。 取值范围：[0x0,0xFF] |
| curve\_l\_limit | 自动白平衡色温曲线的左边界限。取值范围：[0x0,0x100] |
| curve\_r\_limit | 自动白平衡色温曲线的右边界限。取值范围：[0x100,0xFFF] |
| extra\_light\_en | 自动白平衡计算时是否考虑色温曲线外的独立光源点。 取值范围： HI\_FALSE: 关闭 HI\_TRUE: 开启 |
| light\_info[HI\_ISP\_AWB\_LS\_NUM] | 色温曲线外的独立光源点的信息，最多可以添加 4 个。 \#define HI\_ISP\_AWB\_LS\_NUM 4 |
| in\_or\_out | 自动白平衡对场景做室内外判断的参数。 |
| multi\_light\_source\_en | 自动白平衡检测当前场景是否为混合光源，根据混合光源程度调整饱和度或CCM。 取值范围： HI\_FALSE: 关闭 HI\_TRUE: 开启 |
| multi\_ls\_type | 混合光源调整策略选择，支持调整饱和度或CCM。 取值范围： AWB\_MULTI\_LS\_SAT：调整饱和度 AWB\_MULTI\_LS\_CCM：调整CCM |
| multi\_ls\_scaler | 混合光源下，饱和度或CCM最大调整幅度。实际调整幅度还和场景混合光源程度有关。 取值范围：[0x0, 0x100] |
| multi\_ct\_bin[HI\_ISP\_AWB\_MULTI\_CT\_NUM] | 混合光源下的色温分段参数。 取值范围：[0x0, 0xFFFF]，要求为单调递增序列。 \#define HI\_ISP\_AWB\_MULTI\_CT\_NUM 8 |
| multi\_ct\_wt[HI\_ISP\_AWB\_MULTI\_CT\_NUM] | 混合光源下的色温权重参数。 取值范围：[0x0, 0x400] \#define HI\_ISP\_AWB\_MULTI\_CT\_NUM 8 |
| fine\_tun\_en | 自动白平衡特殊色检测开关，包括肤色检测等。 取值范围： HI\_FALSE: 关闭 HI\_TRUE: 开启 |
| fine\_tun\_strength | 肤色、蓝色等单色检测的强度。仅在fine\_tun\_en启用时有效。取值范围：[0x0, 0xFF] |


图1 色温曲线的参数示意图

图2 混合光源场景色温权重设置示例说明（n为色温分段点个数）

注意事项

- tolerance是AWB的灵敏度参数。该值为0时，AWB系数实时更新，CPU占用较高；该值较大时，AWB在检测到环境色温变化时再更新AWB系数，CPU占用较低，但在环境色温微调时，AWB可能出现轻微的偏色。推荐室外应用时tolerance置为 0，室内应用时置为 2。
- zone_radius是选择光源环境白色块的色差半径。zone_radius越大，白色块的限制条件越宽，找到的白色块较多，稳定性稍好，精度稍低；zone_radius越小，白色块的限制条件越严格，找到的白色块较少，AWB精度更高。在混合光源的应用场景，推荐zone_radius比普通场景稍大。
- curve_l_limit取值<=0x100，curve_r_limit取值>=0x100。curve_l_limit和curve_r_limit两个参数用来排除颜色块。如图4-3 所示，curve_l_limit排除了左侧的阴影区域，curve_l_limit排除了右侧的阴影区域。
- AWB算法支持在色温曲线外，再增加独立光源点信息，提升特殊光源下的AWB表现。
- multi_light_source_en启用后，AWB算法判断场景是否混合光源，在混合光源场景，自动降低饱和度或调整CCM，以减弱偏色程度。最大调整幅度由multi_ls_scaler决定。调整CCM方式会改变色调。
- multi_ls_type= HI_ISP_AWB_MULTI_LS_SAT时，调整饱和度来改善混合光源场景的偏色。multi_ls_scaler/0x100表示饱和度增益系数的下限。multi_ls_scaler=0xC0，表示饱和度的增益系数下限是0xC0/0x100 = 0.75，图像饱和度的波动范围是[0.75, 1.0]( 1.0 表示关闭multi_light_source_en功能的图像饱和度)； multi_ls_scaler=0x0，表示饱和度的增益系数下限是 0x0/0x100 =0，图像饱和度的波动范围是[0, 1]，在混合光源下图像可能变黑白。multi_ls_scaler取值越小，图像饱和度的波动范围越大，颜色稳定性下降。
- multi_ls_type= HI_ISP_AWB_MULTI_LS_CCM时，调整CCM来改善混合光源场景的偏色。multi_ls_scaler/0x100表示CCM的调整幅度，取值越大，图像饱和度越低。multi_ls_scaler=0xC0，表示CCM的最大调整幅度为0xC0; multi_ls_scaler=0x0，表示CCM的最大调整幅度为0，等效于multi_light_source_en=0。
- AWB算法在WDR模式自动关闭混合光源判断功能。
- multi_ct_bin、multi_ct_wt两组参数的合理配置，可以改善混合光源高色温或低色温区域颜色表现。在非混合光源场景，参数配置不生效。图4-3说明色温和权重配置的映射关系。
- 如果混合光源场景希望启用色温权重来改善AWB表现，但不做饱和度或CCM调节，可配置如下：multi_light_source_en=HI_TRUE， multi_ls_type=HI_ISP_AWB_MULTI_LS_SAT，multi_ls_scaler=0x100。
- fine_tun_en打开，AWB会自动检测肤色等特殊色，改善肤色场景AWB表现，提高AWB精度。但可能在蓝色背景+3500K光源时发生误判，导致图像轻微偏黄。
- fine_tun_strength调整肤色检测的强度，取值越大，肤色场景AWB表现越好，但肤色误判时的副作用越明显。推荐采用默认值0x80。