Hopenet

Hopenet 是一个准确且易于使用的头部姿态估计网络。该模型在 300W-LP 数据集上进行训练，并在真实数据上进行了测试，取得了良好的定性效果。

有关方法细节和定量结果，请参阅 CVPR 研讨会论文 paper。

新 权力的游戏预告片示例视频

新 柯南-巡洋舰-汽车示例视频

使用前请安装 PyTorch 和 OpenCV（用于视频处理）——我认为除了常见的 numpy 等库之外，这些就是所需的全部依赖项。目前运行 Hopenet 需要 GPU。

若要使用 dlib 人脸检测对视频进行测试（头部中心点可能会跳动）：

python code/test_on_video_dlib.py --snapshot 模型路径 --face_model dlib模型路径 --video 视频路径 --output_string 输出文件名后缀 --n_frames 处理帧数 --fps 原始视频帧率

若要使用您自己的人脸检测结果对视频进行测试（推荐使用 dockerface，头部中心点会更平滑）：

python code/test_on_video_dockerface.py --snapshot 模型路径 --video 视频路径 --bboxes 人脸框标注 --output_string 输出文件名后缀 --n_frames 处理帧数 --fps 原始视频帧率

人脸框标注应采用 Dockerface 格式：n_frame x_min y_min x_max y_max confidence。

预训练模型：

300W-LP, alpha 1

300W-LP, alpha 2

300W-LP, alpha 1, 对图像质量鲁棒

关于 alpha 的具体含义，请参阅论文。前两个模型主要用于验证论文结果；如果用于实际数据，我们建议使用最后一个模型，因为它对图像质量和模糊具有更强的鲁棒性，并且在视频处理中表现良好。

如果您遇到任何问题，请提交 issue。

一些优秀的人士在其他平台上对该工作的实现也非常精彩：

Gluon

MXNet

TensorFlow with Keras

还有一个非常酷的轻量级版本 HopeNet：

Deep Head Pose Light

如果您在研究中使用了 Hopenet，请引用以下文献：

@InProceedings{Ruiz_2018_CVPR_Workshops,
author = {Ruiz, Nataniel and Chong, Eunji and Rehg, James M.},
title = {无需关键点的细粒度头部姿态估计},
booktitle = {IEEE 计算机视觉与模式识别会议 (CVPR) 研讨会},
month = {六月},
year = {2018}
}

Nataniel Ruiz、Eunji Chong、James M. Rehg

佐治亚理工学院

deep-head-pose (Hopenet) 快速上手指南

Hopenet 是一个高精度且易于使用的头部姿态估计网络。该模型基于 300W-LP 数据集训练，在真实数据测试中表现优异，适用于视频流分析。

环境准备

在开始之前，请确保您的系统满足以下要求：

• 操作系统：Linux / macOS / Windows
• 硬件要求：必须拥有 NVIDIA GPU（目前版本仅支持 GPU 运行）
• 核心依赖：
  • PyTorch
  • OpenCV (用于视频处理)
  • NumPy 等基础科学计算库
• 可选依赖：
  • dlib：如果使用内置的人脸检测功能。
  • dockerface：推荐使用，能提供更平滑的头部中心定位。

提示：国内用户安装 PyTorch 时，建议访问 PyTorch 官网 选择对应的 CUDA 版本，并复制包含国内镜像源（如清华源）的安装命令。

安装步骤

1. 克隆项目代码

   git clone https://github.com/natanielruiz/deep-head-pose.git
   cd deep-head-pose
   

2. 安装 Python 依赖 确保已安装 PyTorch 和 OpenCV。如果尚未安装，可使用 pip 进行安装（以下为通用示例，请根据实际 CUDA 版本调整）：

   pip install torch torchvision opencv-python numpy
   # 若使用 dlib 方案，还需安装：
   pip install dlib
   

3. 下载预训练模型 根据需求下载模型文件。对于真实场景和视频应用，强烈推荐使用对图像质量和模糊更鲁棒的模型：

   • 推荐模型：300W-LP, alpha 1 (robust to image quality)

   下载后将模型路径记为 PATH_OF_SNAPSHOT。

基本使用

以下是两种最常用的视频测试方式。请将命令中的占位符替换为实际路径。

方式一：使用 dlib 进行人脸检测（简单快捷）

此方法无需额外标注文件，但检测到的头部中心可能会有轻微跳动。

python code/test_on_video_dlib.py --snapshot PATH_OF_SNAPSHOT --face_model PATH_OF_DLIB_MODEL --video PATH_OF_VIDEO --output_string _result --n_frames -1 --fps 25

• --face_model: dlib 的人脸检测模型路径（通常为 shape_predictor_68_face_landmarks.dat）。
• --n_frames: 设置为 -1 可处理整个视频。

方式二：使用自定义人脸检测（推荐，更平滑）

此方法需配合 dockerface 生成的边界框标注文件，头部中心定位更平滑稳定。

python code/test_on_video_dockerface.py --snapshot PATH_OF_SNAPSHOT --video PATH_OF_VIDEO --bboxes FACE_BOUNDING_BOX_ANNOTATIONS --output_string _result --n_frames -1 --fps 25

• --bboxes: 人脸边界框标注文件路径。
• 标注格式要求：Dockerface 格式 (n_frame x_min y_min x_max y_max confidence)。

运行完成后，输出视频将保存在当前目录，文件名包含您指定的 --output_string 后缀。