InstantHMR
InstantHMR 出自 Naturalpad 和 LAAS-CNRS,是一个实时人体网格重建模型。对每个人体框,它返回 MHR 身体姿态和体型参数、70 个 2D 和 3D 关键点、相机平移,以及一个 18,439 个顶点的网格。LibreYOLO 用 PyTorch 原生移植了它,并用 RF-DETR 找出画面里的人。
安装
InstantHMR 不需要任何可选 extra。默认的人体检测器 LibreRFDETRm.pt 需要 RF-DETR
的 extra。
pip install "libreyolo[rfdetr]"预测
权重在首次使用时从 LibreYOLO 的 Hugging Face 镜像下载,下载前会显示一次许可证提示。
from libreyolo import LibreYOLO model = LibreYOLO("LibreInstantHMRm-mesh.pt") # 用 LibreRFDETRm.pt 找人result = model("people.jpg") meshes = result.meshes # result.boxes 里的每个框对应一行print(meshes.body_model) # "mhr"print(meshes.vertices.shape) # (people, 18439, 3),单位为米,相机坐标系print(meshes.joints2d.shape) # (people, 70, 2),像素from libreyolo import LibreYOLO model = LibreYOLO("LibreInstantHMRm-mesh-commercial.pt")boxes = [[40, 20, 260, 600]] # 每个人一组 x1, y1, x2, y2result = model("people.jpg", person_boxes=boxes)人由 RF-DETR 检测器找出(默认是 LibreRFDETRm.pt)。传入 person_boxes= 可以用你
自己的框,传入 person_detector= 可以换掉检测器。result.meshes 的各行与
result.boxes 一一对应。所有内容都在原图的相机坐标系里:transl 以米为单位,
vertices 和 joints3d 是度量值并已包含 transl,joints2d 是原图上的像素坐标。
global_orient、body_pose 和 betas 存放 MHR 参数;MHR 的旋转是以弧度表示的欧拉
角。完整载荷见人体网格任务页。
变体
四种尺寸 n、t、s 和 m,人体裁剪都是 288 px,外加
LibreInstantHMRm-mesh-commercial.pt,这是一个只用可商用图像训练的 m。上游只发布
ONNX;LibreYOLO 重建了 PyTorch 检查点,全部五个发布版都与上游 ONNX 计算图的误差在
8e-5 以内。
训练
train() 在带 COCO-17 人体关键点的 YOLO-pose 数据集上微调预训练检查点,使用 2D
关键点损失、重投影损失和冻结先验损失。不支持从零训练和 resume。val() 会抛出异常:
常用的人体网格基准(3DPW、EMDB)只有研究用途许可,所以没有内置任何一个;MPJPE、
PA-MPJPE 和 PVE 指标在 libreyolo.validation.mesh_metrics 里,可用于你自己持有的
数据集。
from libreyolo import LibreYOLO # 在 YOLO-pose 格式的 COCO-17 数据集上微调一个预训练检查点model = LibreYOLO("LibreInstantHMRs-mesh.pt")model.train(data="my-pose-dataset.yaml", epochs=20)导出
| 任务 | ONNX | TorchScript | ExecuTorch | TensorRT | OpenVINO | Paddle | MNN | RKNN | Axelera | ncnn | TFLite | CoreML | Core AI |
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Body mesh | Body mesh to ONNX:支持 | Body mesh to TorchScript:不支持 | Body mesh to ExecuTorch:不支持 | Body mesh to TensorRT:不支持 | Body mesh to OpenVINO:不支持 | Body mesh to Paddle:不支持 | Body mesh to MNN:不支持 | Body mesh to RKNN:不支持 | Body mesh to Axelera:不支持 | Body mesh to ncnn:不支持 | Body mesh to TFLite:不支持 | Body mesh to CoreML:不支持 | Body mesh to Core AI:不支持 |
export(format="onnx") 写出一个带 image 和 cliff_cond 输入的计算图,网格面片存在
它的元数据里。
from libreyolo import LibreYOLO model = LibreYOLO("LibreInstantHMRm-mesh.pt")model.export(format="onnx") # 输入为 image、cliff_cond;面片存在元数据里检查点
| 文件 | 权重许可 |
|---|---|
| Body mesh | |
| LibreInstantHMRn-mesh.pt | cc-by-nc-4.0 |
| LibreInstantHMRt-mesh.pt | cc-by-nc-4.0 |
| LibreInstantHMRs-mesh.pt | cc-by-nc-4.0 |
| LibreInstantHMRm-mesh.pt | cc-by-nc-4.0 |
| LibreInstantHMRm-mesh-commercial.pt | apache-2.0 |
上面的每个文件目前都在 LibreYOLO 组织中,并会在首次使用时下载。
许可证
请检查你所下载的具体权重在 Hugging Face 仓库中的许可。LibreYOLO 组织里的每个检查点都附有许可,同一家族内也不一定相同。该仓库是权威来源;以下摘要说明本页上次验证时适用的情况。
这里只说明涉及的许可证,不构成法律意见。如果答案对商用很重要,请自行阅读许可证并咨询法律顾问。
- 原始工作
- InstantHMR, Naturalpad and LAAS-CNRS
- 上游许可
- CC-BY-NC-4.0 (n, t, s, m checkpoints); Apache-2.0 (m commercial checkpoint)
- LibreYOLO 代码
- MIT
- 权重
- 采用 CC-BY-NC-4.0 (n, t, s, m); Apache-2.0 (m-commercial) 许可,重新发布在 huggingface.co/LibreYOLO
- 解读
- The licence depends on the checkpoint. The n, t, s and m weights are CC BY-NC 4.0: attribution is required and commercial use is not allowed, because part of their training images (SA-1B, AI Challenger) are non-commercial. LibreInstantHMRm-mesh-commercial was trained on Harmony4D and commercially licensed COCO images only and is Apache-2.0, which allows commercial and closed-source use if you keep the license text and notices. Every checkpoint was also trained on the SAM 3D Body dataset annotations, released by Meta under the SAM License, whose terms pass through with the weights, and they embed the MHR body constants (Apache-2.0). The upstream code is Apache-2.0 (Naturalpad-studio/InstantHMR at commit 5437400d4b25c1972821e51916fac34bd96acce6; LICENSE and NOTICE in libreyolo/models/instanthmr); the mesh decode was written clean-room so that no SAM-licensed sam-3d-body code is used, and the fine-tuning trainer is original LibreYOLO MIT code. Upstream publishes ONNX only (momolesang/InstantHMR, revision 07988f51c8c8908cfc7bb44fc18f645c9551b0bf); LibreYOLO converts them to PyTorch and mirrors them as LibreYOLO/LibreInstantHMR{n,t,s,m}-mesh and -m-mesh-commercial, not gated, and prints a notice before auto-download.
InstantHMR 出自 Naturalpad 和 LAAS-CNRS (Naturalpad-studio/InstantHMR)。 代码采用 Apache-2.0 许可。权重的许可证取决于检查点:
n、t、s和m:CC BY-NC 4.0,仅限非商用,因为它们的部分训练图像 (SA-1B、AI Challenger)仅限非商用。m-commercial:Apache-2.0,只用 Harmony4D 和获得商用许可的 COCO 图像训练。
每个检查点(checkpoint)还都用 SAM 3D Body 数据集的标注训练过,这些标注由 Meta 以
SAM License 发布,其条款随权重一并传递。网格解码是以净室方式编写的,所以没有使用任何
采用 SAM 许可的 sam-3d-body 代码。检查点镜像为
LibreYOLO/LibreInstantHMR{n,t,s,m}-mesh 和
LibreYOLO/LibreInstantHMRm-mesh-commercial,不需要申请访问。
引用
@misc{adjel2026instanthmr,
title = {InstantHMR: Real-Time Human Mesh Recovery on Your Phone},
author = {Adjel, Mohamed and Chalabi, Kahina and Bonnet, Vincent},
year = {2026},
howpublished = {HAL preprint hal-05854387},
url = {https://hal.science/hal-05854387},
note = {LAAS report no. 26486}
}复制自作者在 github.com/Naturalpad-studio/InstantHMR#citation 上提供的引用块。