这是论文

DAD-3DHeads：一个大规模、密集、准确且多样化的单张图像3D头部对齐数据集
Tetiana Martyniuk, Orest Kupyn, Yana Kurlyak, Igor Krashenyi, Jiři Matas, Viktoriia Sharmanska
CVPR 2022

的官方代码仓库。

📰 新闻

• 2026-01-23 - DAD-3DHeads数据集现已在Hugging Face上发布。
• 2024-08-27 - 添加了UV纹理预测器和PNCC估计器。
• 2022-11-08 - DAD-3DHeads基准测试的评估代码已发布。
• 2022-05-11 - 初始代码发布。

📚 目录

• 安装
• 训练
• 演示
• DAD-3DHeads基准测试
• 许可证
• 引用

安装

代码使用 Python 3.8。

创建Conda虚拟环境：

conda create --name DAD-3DHeads python=3.8
conda activate DAD-3DHeads

克隆项目并安装依赖：

git clone https://github.com/PinataFarms/DAD-3DHeads.git
cd DAD-3DHeads

pip install -r requirements.txt

训练

准备DAD-3DHeads数据集：

首先，你需要下载该数据集，并将其解压到dataset/DAD-3DHeadsDataset目录下。

数据集的目录结构应如下所示：

./dataset
--DAD-3DHeadsDataset
----train
------images
--------<ID>.png
------annotations
--------<ID>.json
------train.json
----val
------images/<ID>.png
------annotations/<ID>.json
------val.json
----test
------images/<ID>.png
------test.json

注释文件 <ID>.json 的结构：

--vertices
--model_view_matrix
--projection_matrix

元数据文件 [train|val|test].json 的结构：

--item_id
--annotation_path
--img_path
--bbox #[x, y, w, h] 格式
----0
----1
----2
----3
--attributes
----quality #[hq, lq]
----gender #[female, male, undefined]
----expression #[true, false]
----age #[child, young, middle_aged, senior]
----occlusions #[true, false]
----pose #[front, sided, atypical]
----standard light #[true, false]

训练代码使用 hydra。要更改训练设置，可以在 model_training/config 文件夹中添加新的或编辑现有的 .yaml 文件。

可视化真实标签：

python visualize.py <subset> <id>

从 train, val, test 中选择 subset，并指定对应的 item_id（不带文件扩展名）。

运行训练代码：

python train.py

演示

第一行（从左到右）：输入图像、68个2D人脸关键点可视化、191个2D人脸关键点可视化、445个2D人脸关键点可视化。
第二行（从左到右）：面部网格可视化、头部网格可视化、头部姿态可视化、3D头部网格。

运行演示：

python demo.py <path/to/input/image.png> <path/to/output/folder> <type_of_output>

# 可视化68个2D人脸关键点
python demo.py images/demo_heads/1.jpeg outputs 68_landmarks

# 可视化191个2D人脸关键点
python demo.py images/demo_heads/1.jpeg outputs 191_landmarks

# 可视化445个2D人脸关键点
python demo.py images/demo_heads/1.jpeg outputs 445_landmarks

# 可视化面部网格
python demo.py images/demo_heads/1.jpeg outputs face_mesh

# 可视化头部网格
python demo.py images/demo_heads/1.jpeg outputs head_mesh

# 可视化头部姿态
python demo.py images/demo_heads/1.jpeg outputs pose

# 获取3D网格.obj文件
python demo.py images/demo_heads/1.jpeg outputs 3d_mesh

# 获取flame参数.json文件
python demo.py images/demo_heads/1.jpeg outputs flame_params

DAD-3DHeads基准测试

请参阅 dad_3dheads_benchmark 目录以获取评估协议。

许可证

本作品采用 知识共享署名-非商业性使用-相同方式共享4.0国际许可协议 许可。

通过使用此代码，您即表示已阅读并理解许可条款，并同意受其约束。如果您不同意这些条款和条件，请勿使用该代码。

引用

如果您在研究项目中使用了DAD-3DHeads数据集或此代码，请引用以下论文：

@inproceedings{dad3dheads,
    title={DAD-3DHeads: A Large-scale Dense, Accurate and Diverse Dataset for 3D Head Alignment from a Single Image},
    author={Martyniuk, Tetiana and Kupyn, Orest and Kurlyak, Yana and Krashenyi, Igor and Matas, Ji\v{r}i and Sharmanska, Viktoriia},
    booktitle = {Proc. IEEE Conf. on Computer Vision and Pattern Recognition (CVPR)},
    year={2022}
}

DAD-3DHeads 快速上手指南

DAD-3DHeads 是一个用于单图 3D 头部对齐的大规模、高密度、高精度且多样化的数据集及工具库。本指南将帮助你快速搭建环境并运行演示。

环境准备

• 操作系统: Linux / macOS (Windows 需使用 WSL)
• Python 版本: 3.8 (必须)
• 依赖管理: Conda (推荐)
• 硬件要求: 建议配备 NVIDIA GPU 以进行训练或加速推理

安装步骤

1. 创建虚拟环境

使用 Conda 创建并激活名为 DAD-3DHeads 的 Python 3.8 环境：

conda create --name DAD-3DHeads python=3.8
conda activate DAD-3DHeads

2. 克隆项目与安装依赖

拉取代码仓库并安装所需依赖包。国内用户若遇到下载慢的问题，可配置 pip 使用清华或阿里镜像源。

git clone https://github.com/PinataFarms/DAD-3DHeads.git
cd DAD-3DHeads

# 可选：使用国内镜像源加速安装
# pip install -r requirements.txt -i https://pypi.tuna.tsinghua.edu.cn/simple

pip install -r requirements.txt

3. 准备数据集（仅训练需要）

若仅需运行演示（Demo），可跳过此步。若需训练模型，请从 Hugging Face 下载数据集，并解压至 dataset/DAD-3DHeadsDataset 目录，确保目录结构如下：

./dataset
--DAD-3DHeadsDataset
----train
------images/<ID>.png
------annotations/<ID>.json
------train.json
----val
------images/<ID>.png
------annotations/<ID>.json
------val.json
----test
------images/<ID>.png
------test.json

基本使用

运行演示 (Demo)

无需训练即可直接对单张图片进行 3D 头部重建和关键点检测。

命令格式：

python demo.py <输入图片路径> <输出文件夹路径> <输出类型>

常用示例：

1. 可视化 68 个 2D 人脸关键点：

   python demo.py images/demo_heads/1.jpeg outputs 68_landmarks
   

2. 可视化人脸网格 (Face Mesh)：

   python demo.py images/demo_heads/1.jpeg outputs face_mesh
   

3. 可视化头部姿态 (Head Pose)：

   python demo.py images/demo_heads/1.jpeg outputs pose
   

4. 导出 3D 网格文件 (.obj)：

   python demo.py images/demo_heads/1.jpeg outputs 3d_mesh
   

5. 导出 FLAME 模型参数 (.json)：

   python demo.py images/demo_heads/1.jpeg outputs flame_params
   

运行完成后，结果将保存在指定的 outputs 文件夹中。

开始训练

若已准备好数据集并需要微调模型，可直接运行训练脚本（默认读取 model_training/config 下的配置）：

python train.py

注意：本项目采用 CC BY-NC-SA 4.0 许可协议，仅限非商业性使用。如在研究中使用该数据集或代码，请务必引用 CVPR 2022 的相关论文。