内容纲要

人脸提亮接口说明

1. 文档目的

这份文档用于说明一套基于君正 ISP tuning 接口的人脸 / 人形区域提亮方案。

目标不是单独把某一个参数拉到最大，而是把下面几部分连成一条完整链路：

检测框输入
场景识别
ROI 权重配置
曝光补偿
暗部拉升

适用场景：

逆光人脸偏暗
室内暗光人脸偏暗
背景亮、人脸暗的门口 / 窗边 / 走廊场景
已经有 AI 人脸框或人形框，想直接在应用层接 ISP 提亮

2. 先看结论

不要只调用：

IMP_ISP_Tuning_SetBacklightComp(10);

单独调背光补偿，不一定能把人脸明显拉亮。

做人脸提亮，通常要同时处理三件事：

让 AE 统计重点看目标区域。
提高整体曝光目标。
用 DRC 拉起暗部层次。

因此建议把本文的封装接口放到应用层，由应用根据检测框和场景识别结果决定是否启用提亮。

3. 整体框架

3.1 功能分层

整套方案建议分成四层：

检测层
获取人脸框或人形框，坐标必须和视频帧同源。
场景识别层
判断当前是否属于需要提亮的场景，比如逆光、暗光、局部高对比。
策略层
根据场景决定 ROI 大小、AE 权重、曝光补偿、DRC 强度。
ISP 执行层
通过 IMP_ISP_Tuning_SetAeWeight()、IMP_ISP_Tuning_AE_SetROI()、IMP_ISP_Tuning_SetAeComp() 等接口把策略写进 ISP。

3.2 总体流程图

+------------------+
| 应用拿到视频帧   |
+---------+--------+
          |
          v
+------------------+
| AI输出人脸框/人形框 |
+---------+--------+
          |
          v
+------------------+
| 检测框是否有效?   |
+----+--------+----+
     |        |
    否        是
     |        |
     v        v
+---------+  +------------------+
| 默认AE  |  | 做场景识别       |
+---------+  +---------+--------+
                      |
                      v
             +------------------+
             | 是否属于提亮场景? |
             +----+--------+----+
                  |        |
                 否        是
                  |        |
                  v        v
          +---------------+  +------------------+
          | 默认AE/轻量ROI |  | 生成提亮策略     |
          +---------------+  +---------+--------+
                                       |
                                       v
                             +------------------+
                             | 换算15x15 ROI    |
                             +---------+--------+
                                       |
                                       v
                             +------------------+
                             | 设置AE/DRC/BLC   |
                             +---------+--------+
                                       |
                                       v
                             +------------------+
                             | ISP输出提亮结果  |
                             +------------------+

3.3 数据关系

检测框 -----------+
                  |
                  v
          +---------------+
          | 坐标合法性检查 |
          +-------+-------+
                  |
                  v
          +---------------+
          | 提亮策略生成   |
          +---+---+---+---+
              |   |   |
              |   |   +------> DRC / BLC 参数
              |   +----------> AE Comp 参数
              +--------------> ROI 权重矩阵
                              |
                              v
                     +----------------+
                     | ISP Tuning接口 |
                     +----------------+

4. 场景识别建议

4.1 为什么要做场景识别

人脸提亮不是所有画面都应该开到最大。

如果不区分场景，常见问题有：

正常画面被拉得过曝
背景一起被拉亮，层次发灰
白墙、窗户、灯具高光被冲掉
人形框过大时，AE 被背景带偏

所以建议先判断“当前是否真的需要提亮”，再调用接口。

4.2 推荐场景分类

场景类型	典型现象	建议策略
正常场景	人脸亮度正常，背景不过强	不提亮或轻量提亮
暗光场景	整体偏暗，人脸细节不足	提高 `AE_COMP`，适中 `DRC`
逆光场景	背景明显亮于人脸	高 ROI 权重 + 高 `BLC` + 高 `AE_COMP`
高风险高光场景	人脸暗，但窗户/灯具很亮	提亮但限制高光风险

4.3 最简场景识别逻辑

如果暂时没有完整亮度统计，可以先按下面方式简化：

有稳定人脸框。
用户主观反馈“脸黑、背景亮”。
当前产品目标是看人优先。

满足这些条件时，可以直接启用提亮接口。

4.4 推荐的规则化识别

如果应用层可以拿到亮度统计，建议至少做三项判断：

人脸区域均值亮度 face_y
全局均值亮度 global_y
人脸外背景亮度 bg_y

判断逻辑可以写成：

if face_y 很低 且 bg_y 明显高于 face_y:
    判定为逆光场景

if face_y 很低 且 global_y 也低:
    判定为暗光场景

if face_y 正常:
    判定为正常场景

if face_y 低，但画面存在大面积高亮区域:
    判定为高风险高光场景

4.5 场景识别流程图

输入检测框和亮度统计
        |
        v
检测框是否稳定?
   |             |
  否             是
   |             |
   v             v
不启用提亮     face_y是否偏低?
                 |           |
                否           是
                 |           |
                 v           v
          正常场景      bg_y是否明显高于face_y?
                            |             |
                           是             否
                            |             |
                            v             v
                       逆光场景      global_y是否整体偏低?
                                          |             |
                                         是             否
                                          |             |
                                          v             v
                                     暗光场景      高风险高光场景

5. 接口设计说明

5.1 核心思路

本接口把检测框映射到 15 x 15 AE 权重网格中，让 ISP 把曝光统计重点放到目标区域，然后再结合：

BacklightComp
HiLightDepress
DRC
AE Comp

共同完成提亮。

5.2 参数定义

#define FACE_LIGHT_ZONE_NUM     15
#define FACE_LIGHT_MIN_WEIGHT   0
#define FACE_LIGHT_MAX_WEIGHT   8
#define FACE_LIGHT_BLC          10
#define FACE_LIGHT_HILIGHT      0
#define FACE_LIGHT_DRC          255
#define FACE_LIGHT_AE_COMP      255

建议理解为：

FACE_LIGHT_MAX_WEIGHT：目标区域 AE 权重
FACE_LIGHT_BLC：逆光补偿强度
FACE_LIGHT_HILIGHT：高光抑制强度
FACE_LIGHT_DRC：暗部拉升强度
FACE_LIGHT_AE_COMP：整体曝光补偿强度

5.3 封装接口代码

#define FACE_LIGHT_ZONE_NUM     15
#define FACE_LIGHT_MIN_WEIGHT   0
#define FACE_LIGHT_MAX_WEIGHT   8
#define FACE_LIGHT_BLC          10
#define FACE_LIGHT_HILIGHT      0
#define FACE_LIGHT_DRC          255
#define FACE_LIGHT_AE_COMP      255

static int face_light_clamp(int value, int min, int max)
{
    if (value < min)
        return min;
    if (value > max)
        return max;
    return value;
}

/*
 * frame_width/frame_height：检测框坐标对应的画面宽高。
 * left/top/width/height：人脸或人形检测框，坐标必须和 frame_width/frame_height 同源。
 *
 * 返回值：
 *   0：成功
 *  -1：参数非法
 *  其他负值：某个 ISP tuning 接口失败
 */
int sample_set_face_light_rect(int frame_width, int frame_height,
                   int left, int top, int width, int height)
{
    IMPISPWeight weight;
    int right;
    int bottom;
    int zone_left;
    int zone_top;
    int zone_right;
    int zone_bottom;
    int x;
    int y;
    int ret;

    if (frame_width <= 0 || frame_height <= 0 || width <= 0 || height <= 0)
        return -1;

    right = face_light_clamp(left + width - 1, 0, frame_width - 1);
    bottom = face_light_clamp(top + height - 1, 0, frame_height - 1);
    left = face_light_clamp(left, 0, frame_width - 1);
    top = face_light_clamp(top, 0, frame_height - 1);

    if (right < left || bottom < top)
        return -1;

    zone_left = left * FACE_LIGHT_ZONE_NUM / frame_width;
    zone_right = right * FACE_LIGHT_ZONE_NUM / frame_width;
    zone_top = top * FACE_LIGHT_ZONE_NUM / frame_height;
    zone_bottom = bottom * FACE_LIGHT_ZONE_NUM / frame_height;

    zone_left = face_light_clamp(zone_left, 0, FACE_LIGHT_ZONE_NUM - 1);
    zone_right = face_light_clamp(zone_right, zone_left, FACE_LIGHT_ZONE_NUM - 1);
    zone_top = face_light_clamp(zone_top, 0, FACE_LIGHT_ZONE_NUM - 1);
    zone_bottom = face_light_clamp(zone_bottom, zone_top, FACE_LIGHT_ZONE_NUM - 1);

    memset(&weight, 0, sizeof(weight));
    for (y = 0; y < FACE_LIGHT_ZONE_NUM; y++) {
        for (x = 0; x < FACE_LIGHT_ZONE_NUM; x++) {
            if (x >= zone_left && x <= zone_right &&
                y >= zone_top && y <= zone_bottom)
                weight.weight[y][x] = FACE_LIGHT_MAX_WEIGHT;
            else
                weight.weight[y][x] = FACE_LIGHT_MIN_WEIGHT;
        }
    }

    ret = IMP_ISP_Tuning_SetAeWeight(&weight);
    if (ret < 0)
        return ret;

    ret = IMP_ISP_Tuning_AE_SetROI(&weight);
    if (ret < 0)
        return ret;

    ret = IMP_ISP_Tuning_SetBacklightComp(FACE_LIGHT_BLC);
    if (ret < 0)
        return ret;

    ret = IMP_ISP_Tuning_SetHiLightDepress(FACE_LIGHT_HILIGHT);
    if (ret < 0)
        return ret;

    ret = IMP_ISP_Tuning_EnableDRC(IMPISP_TUNING_OPS_MODE_ENABLE);
    if (ret < 0)
        return ret;

    ret = IMP_ISP_Tuning_SetDRC_Strength(FACE_LIGHT_DRC);
    if (ret < 0)
        return ret;

    ret = IMP_ISP_Tuning_SetAeComp(FACE_LIGHT_AE_COMP);
    if (ret < 0)
        return ret;

    return 0;
}

/*
 * 没有接检测框时，用 720x1280 中心区域验证最大提亮效果。
 */
int sample_set_face_light_center_720x1280(void)
{
    return sample_set_face_light_rect(720, 1280, 240, 426, 240, 426);
}

6. 调用流程

6.1 调用前提

必须在 IMP_ISP_EnableTuning() 成功之后调用。

6.2 典型调用方式

有检测框时：

int ret;

ret = sample_set_face_light_rect(720, 1280, face_x, face_y, face_w, face_h);
if (ret < 0) {
    printf("sample_set_face_light_rect failed: %d\n", ret);
}

没有检测框、只想验证最大提亮效果时：

int ret;

ret = sample_set_face_light_center_720x1280();
if (ret < 0) {
    printf("sample_set_face_light_center_720x1280 failed: %d\n", ret);
}

6.3 接口执行流程图

输入 frame 和检测框
        |
        v
参数合法性检查
        |
        v
检测框裁剪到画面边界
        |
        v
换算到 15x15 区域
        |
        v
生成 AE 权重矩阵
        |
        v
SetAeWeight
        |
        v
AE_SetROI
        |
        v
SetBacklightComp
        |
        v
SetHiLightDepress
        |
        v
EnableDRC
        |
        v
SetDRC_Strength
        |
        v
SetAeComp
        |
        v
返回结果

7. 参数调节建议

7.1 亮度控制入口

下面这些宏就是主要调节点：

#define FACE_LIGHT_MAX_WEIGHT   8
#define FACE_LIGHT_BLC          10
#define FACE_LIGHT_HILIGHT      0
#define FACE_LIGHT_DRC          255
#define FACE_LIGHT_AE_COMP      255

7.2 各参数作用

`FACE_LIGHT_AE_COMP`

范围：0 ~ 255

这是最直接的整体曝光补偿。数值越大，画面越亮。

推荐：

极限验证：255
逆光场景：180 ~ 255
暗光场景：160 ~ 220
正常场景轻提亮：96 ~ 160

`FACE_LIGHT_MAX_WEIGHT`

范围：0 ~ 8

这是 ROI 区域 AE 权重。数值越大，AE 越优先照顾人脸。

推荐：

人脸框：8
上半身框：6
整个人形框：4 ~ 6

`FACE_LIGHT_BLC`

范围：0 ~ 10

用于增强逆光场景下的人脸提亮效果。

推荐：

逆光强场景：8 ~ 10
普通暗光：4 ~ 8
正常场景：0 ~ 4

`FACE_LIGHT_DRC`

范围：0 ~ 255

用于拉起暗部层次。

推荐：

强提亮验证：255
日常建议：160 ~ 220

`FACE_LIGHT_HILIGHT`

范围：0 ~ 10

默认设为 0，避免高光抑制直接抵消提亮效果。

如果高亮区域明显过曝，可以尝试：

2 ~ 4

但数值越高，人脸提亮效果通常越弱。

8. 提亮范围怎么选

提亮范围主要由传入检测框决定：

sample_set_face_light_rect(frame_w, frame_h, face_x, face_y, face_w, face_h);

建议：

优先传人脸框。
没有人脸框时，再传上半身框。
不建议直接传整个人形大框，否则背景也容易被一并拉亮。

8.1 检测框使用建议

输入框类型	建议程度	说明
人脸框	最推荐	提亮集中，背景带动最小
头肩框	推荐	没有人脸框时可用
上半身框	可用	适合门口近景
整个人形框	谨慎	ROI 过大，容易把背景一起带亮

8.2 中心测试接口

中心测试当前使用：

sample_set_face_light_rect(720, 1280, 240, 426, 240, 426);

测试更大区域：

sample_set_face_light_rect(720, 1280, 180, 320, 360, 640);

测试更小区域：

sample_set_face_light_rect(720, 1280, 300, 540, 120, 180);

9. 场景到参数的推荐映射

场景	ROI 权重	BLC	DRC	AE_COMP	说明
正常场景	4	0~2	96~128	96~128	轻量或不提亮
暗光场景	6~8	4~6	160~220	160~220	重点提整体亮度
逆光场景	8	8~10	180~255	180~255	人脸优先级最高
高风险高光场景	6~8	4~8	128~180	128~180	防止窗户/灯具过曝

如果暂时不做动态调参，也建议至少分成两档：

强提亮档：逆光 / 严重暗脸
保守提亮档：普通暗光 / 日常人脸优化

10. 建议的应用层接法

推荐伪代码：

if (!isp_tuning_ready)
    return;

if (!face_box_valid)
    return;

scene = detect_face_light_scene(face_y, bg_y, global_y, highlight_ratio);

switch (scene) {
case FACE_LIGHT_SCENE_NORMAL:
    /* 可以不调，或只做轻量ROI */
    break;
case FACE_LIGHT_SCENE_LOWLIGHT:
case FACE_LIGHT_SCENE_BACKLIGHT:
case FACE_LIGHT_SCENE_HIGHLIGHT_RISK:
    sample_set_face_light_rect(frame_w, frame_h, face_x, face_y, face_w, face_h);
    break;
default:
    break;
}

建议后续把逻辑拆成三层：

scene detect
policy generate
isp apply

这样后面切 sensor 或分不同参数档位时，主流程不需要重写。

11. 仍然不亮时先检查

是否在 IMP_ISP_EnableTuning() 成功之后调用。
frame_width/frame_height 是否和检测框坐标同源。
检测框是否过大，导致背景权重也被放大。
当前场景是否已经接近过曝。
SetAeWeight、AE_SetROI、SetAeComp 是否都成功返回。
SDK 是否允许当前平台同时开启这些 tuning 能力。

12. 一句话总结

这套人脸提亮接口的本质不是“单调一个 ISP 参数”，而是：

先识别当前是否属于人脸偏暗场景，再把检测框转换成 AE 关注区域，并联动 ROI、曝光补偿、逆光补偿和 DRC，把人脸亮度稳定抬起来。
当遇到无法出流异常可以抓raw，抓取的raw数据，存放为/tmp/snap.raw:

echo saveraw >/proc/jz/isp/isp-w02
echo snapraw >/proc/jz/isp/isp-w02

内容来源及使用限制

欢迎访问 TomgZHE研习社（网址：https://blog.tomgzhe.com）。本网站部分文章内容源自网络，仅作学习交流与参考分享;若您发现有内容涉嫌侵权，请立即联系 tomgzhe@qq.com，我们将在接到通知后的 48 小时内核实并删除相关侵权内容。

软件资源相关规定

本网站为个人非盈利性质的站点，所有软件资源均来自网络。这些资源仅用于个人学习、研究和参考，严禁用于任何商业用途。您下载和使用本网站软件资源即表示您同意仅将其用于学习目的，若因违反此规定导致任何法律纠纷或损失，责任由您自行承担。

原创版权

本网站上的原创内容，包括但不限于文字作品、自行设计的图片、独家制作的音频视频等，其版权均归本网站所有。未经本网站书面授权，任何组织或个人不得擅自复制、转载、摘编、传播或以其他任何方式使用这些原创内容。如需使用，请提前与我们联系并获得书面许可，同时需在显著位置注明出处及作者信息。

转载与引用规范

若您需转载本网站文章，务必注明文章来源为 “[TomgZHE研习社]，原文链接：[ https://blog.tomgzhe.com/index.php/2026/07/17/君正t23-人脸提亮整体框架/ ‎]”；对于有明确作者署名的文章，还需完整保留作者姓名。在引用本网站内容时，请确保内容准确无误，并遵循学术及行业的引用规范。

君正T23 人脸提亮整体框架