InsightFace gaze 模块视线估计完整指南：一次 160×160 推理输出 3D 视线向量

InsightFace gaze 模块视线估计完整指南：一次 160×160 推理输出 3D 视线向量

【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface

InsightFace 是一个 2D/3D 人脸分析开源项目，其reconstruction/gaze目录下的 gaze 模块对普通人脸图像做视线估计：一次 160×160 裁剪推理即可输出 3D 视线向量，适合驾驶员注意力监测等需要回答"人在看哪里"的场景。

📷 效果速览：一张 160×160 裁剪如何变成 3D 视线向量

输入 → 输出只有一句话：输入是一张原图（无需手动裁剪眼部），输出是左右眼各一个、带两个角度（theta_x、theta_y）的 3D 视线向量。脚本test_gaze.py会把结果画出来——从眼睛位置沿视线方向画一条线，线的指向就是估计结果。

下面这张仓库测试集里的单人脸样例图，放进assets/images/后就可以直接作为 gaze 推理输入。

🚀 快速上手：gaze 从 clone 到推理的完整步骤

第一步，克隆仓库：

git clone https://gitcode.com/GitHub_Trending/in/insightface

第二步，装依赖。版本按 README 的要求钉住：

pip install timm pytorch-lightning==1.8.1 albumentations==1.3.0

第三步，权重与非代码资源放置（README 的 Preparation 清单，这步最容易漏）：

• eyes3d.pkl（481 点眼部模板）放入assets/
• 预训练 ckpt（README 示例名latest_a.ckpt）放入assets/
• 若干单人脸样例图放入assets/images/，test_gaze.py的主流程就是遍历这个目录

第四步，单条命令跑通，输出会写到outputs/，每张图生成"原图 + 结果图"左右并排文件：

cd reconstruction/gaze python test_gaze.py assets/latest_a.ckpt

🔍 原理链路：962 个眼部关键点如何回归出视线向量

先跑通再讲原理。整条链路只有三步：对齐 → 一次推理 → 后处理，没有任何分割或跟踪环节。

第一步：眼睛如何被对齐到固定的 160×160 裁剪

这像自动证件照亭：不管你转头转得多离谱，机器会先把摄像头位置调正，让照片里的人始终待在同一个位置。GazeHandler先用FaceAnalysis检测器（det_size=(320, 320)）拿到人脸框和 5 个关键点，再以双眼中点为中心做仿射变换，裁出 160×160：

self.input_size = 160 # 网络输入分辨率 aimg, M = face_align.transform(img, center, self.input_size, _scale, rotate)

矩阵 M 不是用完就扔，预测出的关键点之后要用它的逆矩阵映射回原图坐标，保证画线不偏移。见 test_gaze.py。

中间步：timm 骨干直接输出 962 个 3D 坐标

它像牙模打印机，不先把牙齿、牙龈一个个拼起来，而是把整副模型一次性打印出来。网络不区分虹膜、瞳孔、眼睑，而是把 timm 骨干的分类头直接换成 962×3 的回归头——左右眼各 481 个点：

self.backbone = timm.create_model(backbone, num_classes=481*2*3) # 默认 resnet101d loss = torch.mean(loss) * 20.0 # L1 损失，z 轴权重减半

默认骨干resnet101d在 trainer_gaze.py 里指定。训练侧还挂了一串模拟车载环境的增强：ColorJitter(brightness=0.3)、ISONoise(p=0.1)、MotionBlur(5-13)、ImageCompression(10-90)，出处见 models.py 和 dataset_gaze.py。

最后一步：虹膜质心偏移换算成视线向量

这像读表盘指针：看针离表盘中心偏多远、朝哪个方向偏，就能读出角度。这里的"针"是虹膜关键点组，"表盘中心"是前 32 个眼部轮廓点的质心。预测点先解码（x、y 加 1 再乘input_size // 2，z 乘 10.0），然后每只眼做一次质心偏移并归一化：

vec = (eye[iris_lms_idx] - eye[:32].mean(axis=0)).mean(axis=0) vec /= np.linalg.norm(vec, axis=0) # 归一化为单位视线向量

向量再经arctan2转成 theta_x、theta_y 两个角度，cv2.line从虹膜中心沿该方向画出线段。同样在 test_gaze.py 的angles_from_vec中实现。

📊 已公布与未公布：检测基准 vs 视线指标

gaze 模块本身没有公布任何基准数字，仓库里唯一的性能数据来自 cpp-package 的人脸检测基准，可作为链路前半段（检测 + 对齐）的时延参考：

数据取自 Benchmark-Remark(Updating).md.md>)。另外，160 是代码里的默认输入分辨率，调大输入可提升远距离人脸的视线精度，但推理成本随分辨率上升，建议先用默认值验证端到端时延。

⚠️ gaze 的依赖、资源文件与数据格式：三个部署问题

问题一：timm 版本漂移（依赖版本）。现象：加载assets/latest_a.ckpt时出现形状不匹配，或找不到resnet101d。原因：README 只钉住了pytorch-lightning==1.8.1和albumentations==1.3.0，timm 未固定版本，而 timm 跨版本会调整模型命名与参数形状。建议：先用能成功加载官方权重的版本组合验证，再把 timm 版本锁死，之后才动其他依赖。

问题二：assets/ 资源文件缺失（资源文件）。现象：启动即报FileNotFoundError，或脚本空扫assets/images/直接结束。原因：eyes3d.pkl与预训练 ckpt 都是仓库之外的非代码文件，需单独下载；样例图也必须自备到assets/images/。建议：对照 README 的 Preparation 清单逐项打勾。

问题三：训练数据不是普通图片目录（数据格式）。现象：GazeDataset初始化直接报错。原因：训练集是 MXNet recordio 格式（train.rec/train.idx），每个样本的 label 是 962 个 3D 眼部关键点，直接喂图片目录会失败。建议：想自行重训时，先按同格式构建 recordio 数据包。

收束

gaze 模块未公布精度与推理基准，默认骨干 resnet101d 较重，适合能接受单次前向时延的场景。后续更新建议持续关注reconstruction/gaze目录。

【免费下载链接】insightfaceState-of-the-art 2D and 3D Face Analysis Project项目地址: https://gitcode.com/GitHub_Trending/in/insightface