企业官网建设流程全解析

• 人工智能
• 计算机视觉
• 深度学习

导读

本文是 ViTPose（基于 MMPose 的姿态估计框架）中3D 手部关键点（3D Hand Keypoint）任务的数据准备与使用指南，围绕官方文档 docs/en/tasks/3d_hand_keypoint.md 展开。你将学会：如何下载并组织 InterHand2.6M 数据集、如何将数据根目录软链接到$MMPOSE/data、InterHand2.6M 的 42 关键点定义与标注体系，以及仓库中配套的数据集类、模型结构、训练配置、评测指标与可视化 demo 的完整调用链路。

数据集总览：InterHand2.6M

MMPose 当前支持的 3D 手部关键点数据集为InterHand2.6M（ECCV 2020）。这是目前规模较大的交互手部 3D 姿态数据集，其核心特点是从单张 RGB 图像同时估计两只交互手的 3D 关键点，覆盖单只手（single）与双手交互（interacting）两种场景。

官方引用信息（可直接用于论文致谢）：

@InProceedings{Moon_2020_ECCV_InterHand2.6M, author = {Moon, Gyeongsik and Yu, Shoou-I and Wen, He and Shiratori, Takaaki and Lee, Kyoung Mu}, title = {InterHand2.6M: A Dataset and Baseline for 3D Interacting Hand Pose Estimation from a Single RGB Image}, booktitle = {European Conference on Computer Vision (ECCV)}, year = {2020} }

在仓库的配置中，该数据集的论文元信息记录于 configs/base/datasets/interhand3d.py 的paper_info字段，名称、作者与年份均与此引用一致。

目录规划与软链接准备

官方文档首先强调了一个全局约定：建议将数据集根目录软链接到$MMPOSE/data（$MMPOSE即仓库根目录，例如本仓库的 ViTPose 根目录）。如果你的目录结构与默认约定不同，则需要同步修改对应配置文件中的路径（主要是data_root与各ann_file/camera_file/joint_file/img_prefix）。

下载与解压

InterHand2.6M 需要从数据集官方主页下载图像数据，并单独下载标注文件（annotations）。下载完成后，将两者统一解压到{MMPOSE}/data下，使其目录结构如下：

mmpose # 即仓库根目录 ├── mmpose ├── docs ├── tests ├── tools ├── configs `── data │── interhand2.6m |── annotations | |── all | |── human_annot | |── machine_annot | |── skeleton.txt | |── subject.txt | `── images | |── train | | |-- Capture0 ~ Capture26 | |── val | | |-- Capture0 | |── test | | |-- Capture0 ~ Capture7

要点说明：

• annotations下包含三份标注子集：all（全部标注）、human_annot（人工标注）、machine_annot（机器标注），此外还有skeleton.txt（骨架连接定义）与subject.txt（受试者划分）。
• images按train/val/test划分，train包含 Capture0～Capture26，test包含 Capture0～Capture7，val仅 Capture0。
• 本任务对应的 3D 标注文件在all子目录下，命名形如InterHand2.6M_train_data.json、InterHand2.6M_train_camera.json、InterHand2.6M_train_joint_3d.json（详见下文配置）。

若以软链接方式挂载（例如数据集实际存放在其他磁盘路径），可使用：

ln -s /path/to/your/interhand2.6m data/interhand2.6m

创建软链接后，配置文件中默认的data_root = 'data/interhand2.6m'即可直接生效。

关键点定义与标注体系：42 关键点、左右手与交换对

InterHand2.6M 的 3D 标注包含42 个关键点：左右手各 21 个，每只手由 5 根手指（每指 4 个关节点）加 1 个手腕组成。该定义完整记录在两个文件中：

• 3D 数据集配置 configs/base/datasets/interhand3d.py：42 个关键点，命名形如right_thumb4、left_wrist，并带左右手swap互换关系（如right_thumb4 ↔ left_thumb4），joint_weights=[1.] * 42。
• 数据集类文档字符串 mmpose/datasets/datasets/hand/interhand3d_dataset.py 给出了索引对应关系：

0: 'r_thumb4', 1: 'r_thumb3', 2: 'r_thumb2', 3: 'r_thumb1', 4: 'r_index4', 5: 'r_index3', 6: 'r_index2', 7: 'r_index1', 8: 'r_middle4', 9: 'r_middle3', 10: 'r_middle2', 11: 'r_middle1', 12: 'r_ring4', 13: 'r_ring3', 14: 'r_ring2', 15: 'r_ring1', 16: 'r_pinky4', 17: 'r_pinky3', 18: 'r_pinky2', 19: 'r_pinky1', 20: 'r_wrist', 21: 'l_thumb4', ... 41: 'l_wrist'

其中索引 0～20 为右手，索引 21～41 为左手。右手根节点（root）为r_wrist（索引 20），左手根节点为l_wrist（索引 41），这两个根节点的深度信息（abs_depth）与相对深度（rel_root_depth）是 3D 恢复的关键。

此外，仓库还提供了 2D 版本的 InterHand2.6M 配置 configs/base/datasets/interhand2d.py，其关键点定义退化为单只手 21 个关键点（thumb4～wrist，无左右手区分），供 2D 手部热图任务（如 configs/hand/2d_kpt_sview_rgb_img/topdown_heatmap/interhand2d 下的 ViTPose 系列配置）使用。可以推断：2D 任务直接回归像素坐标，而 3D 任务需要额外处理深度维度与双手交互，因此两者关键点体系不同。

InterHand3DDataset：加载逻辑与关键参数

3D 手部任务的官方数据集类是InterHand3DDataset（继承自Kpt3dSviewRgbImgTopDownDataset），注册于 mmpose/datasets/datasets/hand/interhand3d_dataset.py。其构造函数除常规的ann_file、img_prefix、pipeline、dataset_info外，还接收 3D 任务特有参数：

数据加载流程（_get_db）

从源码看，_get_db()的加载逻辑（interhand3d_dataset.py）依次完成：

1. 读取camera_file与joint_file，按capture编号与相机名索引相机参数（campos/camrot/focal/princpt），并将世界坐标经_world2cam与_cam2pixel投影为像素坐标。
2. 通过_encode_handtype将hand_type编码为多标签向量：right → [1,0]、left → [0,1]、interacting → [1,1]。
3. 若use_gt_root_depth=True，直接取左右手腕的相机深度作为abs_depth，并将 bbox 扩展 1.25 倍以包含上下文；否则从rootnet_result_file读取 RootNet 预测的 bbox 与绝对深度。
4. 计算相对根深度rel_root_depth = joint_cam[41,2] - joint_cam[20,2]（左腕深度减右腕深度），并依据左右根节点的有效性对整只手关键点做有效性掩码（joint_valid）处理。
5. 生成 3D 目标：joints_3d的 x/y 为像素坐标，z 为相对各自根节点的深度（右手减去joint_cam[20,2]，左手减去joint_cam[41,2]）。

data_cfg 中的 3D 专属参数

在训练配置 configs/hand/3d_kpt_sview_rgb_img/internet/interhand3d/res50_interhand3d_all_256x256.py 中，data_cfg定义了 3D 任务的关键数值：

data_cfg = dict( image_size=[256, 256], heatmap_size=[64, 64, 64], heatmap3d_depth_bound=400.0, heatmap_size_root=64, root_depth_bound=400.0, num_output_channels=42, num_joints=42, dataset_channel=[list(range(42))], inference_channel=list(range(42)))

• heatmap_size=[64, 64, 64]：3D 热图的空间分辨率（宽、高、深度三轴各 64），对应Heatmap3DHead中depth_size=64的深度离散化。
• heatmap3d_depth_bound=400.0：关键点 3D 热图的深度范围上界（单位 mm），解码时用于将离散深度映射回相机空间。
• root_depth_bound=400.0：相对根深度 1D 热图的深度范围上界。
• heatmap_size_root=64：相对根深度 1D 热图的离散长度。

这三个 depth 相关参数在推理时会写入img_metas，被 interhand_3d_head.py 的decode方法读取并用于反算真实深度。

配套模型：Interhand3D 与三头结构

3D 手部任务使用的检测器是Interhand3D（mmpose/models/detectors/interhand_3d.py），它是TopDown的子类，注册名为Interhand3D。其头部Interhand3DHead（mmpose/models/heads/interhand_3d_head.py）由三个子模块组成，对应三个训练目标：

关键实现细节（可从源码确认）：

• 3D 热图生成：Heatmap3DHead先经 3 层反卷积（num_deconv_layers=3、每层 256 通道、核 4×4）与 1×1 卷积，输出通道数为21 * 64，再在 forward 中 reshape 为(N, 21, 64, 64, 64)的 3D 热图；左右手分支在Interhand3DHead.forward中被torch.cat拼接为 42 通道（interhand_3d_head.py）。
• 深度解码：decode中将 3D 热图经keypoints_from_heatmaps3d解码出像素坐标与深度索引，再通过(idx / depth_size - 0.5) * heatmap3d_depth_bound映射到 mm 单位；rel_root_depth同理按root_depth_bound换算；hand_type以 0.5 为阈值判定（interhand_3d_head.py）。
• 测试时翻转：flip_test开启时，3D 热图按flip_pairs翻回并与原图输出取平均，rel_root_depth取负，左右手标签互换（interhand_3d_head.py）。

训练配置速览

默认训练配置为 res50_interhand3d_all_256x256.py，其要点：

• 主干网络：ResNet-50（pretrained='torchvision://resnet50'）。
• 优化器：Adam，lr=2e-4；学习率策略step=[15, 17]，共total_epochs=20。
• 训练数据增强流水线：HandRandomFlip（翻转概率 0.5）、TopDownRandomTranslation（trans_factor=0.15）、TopDownGetRandomScaleRotation（rot_factor=45、scale_factor=0.25、rot_prob=0.6）、TopDownAffine、NormalizeTensor，最后经MultitaskGatherTarget同时生成三类目标：Generate3DHeatmapTarget（sigma=2.5）、HandGenerateRelDepthTarget、手型标签重命名。
• 数据划分：train用annotations/all下的InterHand2.6M_train_*文件；val用annotations/machine_annot下的InterHand2.6M_val_*文件；test用annotations/all下的InterHand2.6M_test_*文件，三者的img_prefix分别指向images/train/、images/val/、images/test/。
• 三个子集均设置use_gt_root_depth=True、rootnet_result_file=None。

训练与测试入口见仓库标准脚本 tools/train.py 与 tools/test.py（以及 tools/dist_train.sh / tools/dist_test.sh）。

评测指标：MRRPE、MPJPE 与 Handedness_acc

InterHand3DDataset.evaluate（interhand3d_dataset.py）支持三类指标（可通过evaluation.metric组合指定）：

• MRRPE（Mean Relative Root Position Error）：左右手腕相对根位置的误差，仅在双手均为有效标注（hand_type为 interacting 且两腕可见）的样本上计算。
• MPJPE（Mean Per-Joint Position Error）：在相机坐标系下逐关节计算位置误差，并细分为MPJPE_all、MPJPE_single（单手样本）、MPJPE_interacting（交互样本）三个子指标。计算时使用 GT 的abs_depth与相机参数（focal、princpt）把预测像素坐标反投影到相机空间，再减去各自根节点得到根相对误差。
• Handedness_acc（手型判定准确率）：多标签分类准确率，即预测的左右手标签与 GT 的一致性。

这些指标均由 mmpose/core/evaluation/top_down_eval.py 中的keypoint_epe与multilabel_classification_accuracy等工具函数支撑。训练配置中evaluation设置为metric=['MRRPE', 'MPJPE', 'Handedness_acc']且save_best='MPJPE_all'，即默认以 MPJPE_all 作为选优指标。

仓库在 configs/hand/3d_kpt_sview_rgb_img/internet/interhand3d/internet_interhand3d.md 中记录了 InterNet（InterHand2.6M 原论文基线）在 256×256 输入下的测试结果表格（含 MPJPE-single / MPJPE-interacting / MPJPE-all / MRRPE / APh 等列），可作为训练结果的对照参考；该表同样包含官方 ckpt 与 log 的下载入口信息。

推理与可视化：demo 脚本与 API 调用链

仓库提供专用推理脚本 demo/interhand3d_img_demo.py，用于对单张图像中的手部 bbox 执行 3D 姿态估计并可视化。其用法：

python demo/interhand3d_img_demo.py \ configs/hand/3d_kpt_sview_rgb_img/internet/interhand3d/res50_interhand3d_all_256x256.py \ /path/to/checkpoint.pth \ --img-root data/interhand2.6m/images \ --json-file data/interhand2.6m/annotations/all/InterHand2.6M_test_data.json \ --camera-param-file data/interhand2.6m/annotations/all/InterHand2.6M_test_camera.json \ --gt-joints-file data/interhand2.6m/annotations/all/InterHand2.6M_test_joint_3d.json \ --out-img-root ./vis_output \ --show

脚本关键参数与行为（对应 demo/interhand3d_img_demo.py）：

• pose_config/pose_checkpoint：模型配置与权重；--device指定推理设备（默认cuda:0）。
• --img-root/--json-file：图像根目录与包含 bbox、capture、camera、frame_idx等信息的 COCO 格式 JSON。
• --camera-param-file：相机参数文件，若提供则将预测从像素空间转换到相机空间（脚本内置_transform_interhand_camera_param将camrot/campos/focal/princpt转换为R/T/f/c格式，再交由SimpleCamera处理）。
• --gt-joints-file：GT 3D 关节文件，提供后可叠加显示 Ground Truth。
• --rebase-keypoint-height：将最低关键点高度归零，便于观察相对高度。
• --kpt-thr/--radius/--thickness：可视化阈值与线条参数。

其底层推理函数为inference_interhand_3d_model（mmpose/apis/inference_3d.py），流程为：按bbox_thr过滤手部 bbox →_box2cs计算 center/scale → 走Compose(cfg.test_pipeline)数据管线 → 模型 forward → 返回含keypoints_3d、boxes、rel_root_depth、hand_type的预测字典。

对应单元测试 tests/test_apis/test_inference_3d.py 使用tests/data/interhand2.6m/image2017.jpg与真实配置res50_interhand3d_all_256x256.py验证了该推理链路；模型与头部的前向/损失/解码正确性由 tests/test_models/test_interhand_3d_forward.py 与 tests/test_models/test_interhand_3d_head.py 覆盖（后者断言输出形状[N,42,64,64,64]、[N,1]、[N,2]及三类损失名称）。

相关文档与资源索引

• 任务文档：docs/en/tasks/3d_hand_keypoint.md（本文主体）、docs/en/tasks/2d_hand_keypoint.md（2D 手部任务）、docs/en/tasks/3d_body_keypoint.md（3D 人体任务对照）。
• 数据准备入口：docs/en/data_preparation.md 汇总了各任务的数据准备指南并链接到本文。
• 数据集配置：configs/base/datasets/interhand3d.py、configs/base/datasets/interhand2d.py。
• 数据集实现：mmpose/datasets/datasets/hand/interhand3d_dataset.py、mmpose/datasets/datasets/hand/interhand2d_dataset.py。
• 模型实现：mmpose/models/detectors/interhand_3d.py、mmpose/models/heads/interhand_3d_head.py。
• 训练配置与结果：configs/hand/3d_kpt_sview_rgb_img/internet/interhand3d、configs/hand/2d_kpt_sview_rgb_img/topdown_heatmap/interhand2d（ViTPose 在 2D 手部任务上的配置）。
• 推理 API 与测试：mmpose/apis/inference_3d.py、tests/test_apis/test_inference_3d.py、tests/test_models/test_interhand_3d_head.py。

常见问题与注意事项

1. 路径不匹配：若未使用软链接而是自行放置数据，务必把配置中的data_root（默认data/interhand2.6m）以及 train/val/test 的ann_file、camera_file、joint_file、img_prefix同步改为实际路径，否则会在加载阶段报文件缺失。
2. 3D 任务与 2D 任务配置不要混用：3D 任务使用InterHand3DDataset与Interhand3D模型（42 关键点），2D 任务使用InterHand2DDataset与常规 top-down 热图模型（21 关键点），两者的dataset_info、data_cfg与输出通道数均不同。
3. 深度范围一致性：heatmap3d_depth_bound、root_depth_bound、heatmap_size_root需要在data_cfg与data各子集间保持一致，它们直接影响 3D 热图生成与深度解码的毫米级数值。
4. RootNet 模式：当use_gt_root_depth=False时，必须提供rootnet_result_file（含 bbox 与abs_depth的 JSON），否则构造数据集会断言失败（interhand3d_dataset.py）。

• 人工智能
• 计算机视觉
• 深度学习