查看 Markdown

InstantHMR

InstantHMR 出自 Naturalpad 和 LAAS-CNRS,是一个实时人体网格重建模型。对每个人体框,它返回 MHR 身体姿态和体型参数、70 个 2D 和 3D 关键点、相机平移,以及一个 18,439 个顶点的网格。LibreYOLO 用 PyTorch 原生移植了它,并用 RF-DETR 找出画面里的人。

任务
body mesh
安装
pip install libreyolo
支持层级
已支持,自 v1.8.0 起。起支撑作用的可训练家族:在 CI 里保持绿色,功能视情况落地。
上游
InstantHMR,由 Naturalpad and LAAS-CNRS 发布,采用 CC-BY-NC-4.0 (n, t, s, m checkpoints); Apache-2.0 (m commercial checkpoint) 许可。论文、源码
许可
代码采用 Apache-2.0,权重采用 CC-BY-NC-4.0 (n, t, s, m); Apache-2.0 (m-commercial)。商用

安装

InstantHMR 不需要任何可选 extra。默认的人体检测器 LibreRFDETRm.pt 需要 RF-DETR 的 extra。

bash
pip install "libreyolo[rfdetr]"

预测

权重在首次使用时从 LibreYOLO 的 Hugging Face 镜像下载,下载前会显示一次许可证提示。

Python
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 里,可用于你自己持有的 数据集。

Python
from libreyolo import LibreYOLO # 在 YOLO-pose 格式的 COCO-17 数据集上微调一个预训练检查点model = LibreYOLO("LibreInstantHMRs-mesh.pt")model.train(data="my-pose-dataset.yaml", epochs=20)

导出

任务ONNXTorchScriptExecuTorchTensorRTOpenVINOPaddleMNNRKNNAxelerancnnTFLiteCoreMLCore AI
Body meshBody 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 输入的计算图,网格面片存在 它的元数据里。

Python
from libreyolo import LibreYOLO model = LibreYOLO("LibreInstantHMRm-mesh.pt")model.export(format="onnx")   # 输入为 image、cliff_cond;面片存在元数据里

检查点

上面的每个文件目前都在 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 上提供的引用块。

已针对 LibreYOLO v1.8.0 验证。本页的支持表、检查点和基准测试数据由已发布的库和权重生成,并非手工编写。