简介

SAM 3D Body 人体三维重建算子。对单张图像做人体检测 → （可选）分割 → FOV 估计 → SAM 3D Body 前向，输出每个人的三维网格、二维/三维关键点、MHR 姿态参数与相机平移。三方源码与权重需提前就位，算子内零网络零安装。

功能描述

• 四级流水线：vitdet 人体检测 → sam2 人体分割（可选）→ moge2 FOV 估计 → SAM 3D Body 重建，三个子模型通过 tools/build_detector.py / tools/build_sam.py / tools/build_fov_estimator.py 按文件路径加载（spec_from_file_location）
• sam-3d-body 源码目录由 sam_3d_body_repo_path 指定，sys.path 只在构建 estimator 与单张推理期间临时插入、用完即撤；源码目录不存在直接 FileNotFoundError，运行期不会 clone
• 主模型 ckpt 与 MHR 资源可显式给路径，为空时按 <model_path>/<model_name>/model.ckpt 和 <model_path>/<model_name>/assets/mhr_model.pt 推导，两者缺一即 FileNotFoundError
• 只有传了 segmentor_path 才会构建分割器，因此 use_mask=True 必须同时给 segmentor_path；detector_name 置空则跳过检测
• 上游 process_one_image 返回的是每个人一个 dict 的 list，逐人取 bbox / focal_length / pred_vertices / pred_keypoints_3d / pred_keypoints_2d / mhr_model_params / pred_cam_t；上游没有检测分数字段，输出里也不编造
• 张量统一存成 {shape, data}：形状 + 一维 float32 展平数据，不用多层嵌套 list
• 两个输出体积开关：max_instances 限制每张图保留的实例数，if_output_vertices=False 时不输出网格顶点（实测每人约 1.8 万顶点，人多时网格是输出体积主体）
• 未检出人体时 instances 为空列表、status 为 success: no person detected；单张图异常时该行 instances 为空、status 为 error: <异常信息>，不中断整列
• 输入支持 image_url（含 BOS 路径，先落到本地临时路径再推理）、image_base64、image_binary；后两者写成 /tmp 下的临时 jpg 文件后推理，用完即删
• 可视化（pyrender + EGL）本期不做

算子参数

输入

输出

输出为一个 struct 列，字段如下（tensor 均指 struct<shape: list<int32>, data: list<float32>>，data 是按行优先展平的 float32；缺失时为 {"shape": [], "data": []}）：

参数

注意事项

• 算子内零网络零安装：运行期不下载权重、不安装依赖、不拉源码；sam_3d_body_repo_path 指向的源码目录或权重缺失时，构造阶段直接抛 FileNotFoundError。
• detector_path传目录，fov_path必须传model.pt文件：vitdet 的 detector_path 指向包含 model_final_f05665.pkl 的目录；MoGe 的 from_pretrained 接受 .pt 文件或 HF repo id，fov_path 传目录会 IsADirectoryError。
• sm_120（Blackwell）上 detectron2 需要自编 CUDA 扩展：现成 wheel 不含 sm_120 kernel，需要按目标 GPU 架构自行编好 detectron2，算子内不做编译。
• 按concurrency=1起：这条链路的并发安全性未经验证；本算子测试与建议用法均为 num_cpus=1, num_gpus=1, concurrency=1, batch_size=1。
• 依赖面很大：detectron2 + pytorch-lightning + hydra + pyrender 等 30 余个包，建议给它单独的运行环境。
• 输出体积：单人网格 [18439,3] 就是 5.5 万个 float32，人多的图建议配 max_instances，只要姿态参数与关键点时把 if_output_vertices 关掉。

调用示例

1from __future__ import annotations
2
3import os
4
5import daft
6from daft import col
7
8from daft.aihc.common.udf import aihc_udf
9from daft.aihc.functions.embodied.perception.image_sam_3d_body import ImageSam3dBody
10
11MODEL_PATH = "/path/to/models"
12
13if __name__ == "__main__":
14    if os.getenv("DAFT_RUNNER", "native") == "ray":
15        import ray
16        ray.init(dashboard_host="0.0.0.0", ignore_reinit_error=True)
17        daft.set_runner_ray()
18    daft.set_execution_config(actor_udf_ready_timeout=6000, min_cpu_per_task=0)
19
20ds = daft.from_pydict({"image": ["bos://your-bucket/sample.jpg"]})
21    ds = ds.with_column(
22        "body",
23        aihc_udf(
24            ImageSam3dBody,
25            construct_args={
26                "image_src_type": "image_url",
27                "model_path": MODEL_PATH,
28                "model_name": "facebook/sam-3d-body-dinov3",
29                "sam_3d_body_repo_path": "/path/to/thirdparty/sam-3d-body",
30                # 检测器传目录（内含 model_final_f05665.pkl）
31                "detector_path": f"{MODEL_PATH}/sam3d_vitdet",
32                # FOV 传 MoGe 的权重文件，不能传目录
33                "fov_path": f"{MODEL_PATH}/Ruicheng/moge-2-vitl/model.pt",
34                "bbox_thresh": 0.5,
35                "max_instances": 4,
36            },
37            num_cpus=1,
38            num_gpus=1,
39            concurrency=1,
40            batch_size=1,
41        )(col("image")),
42    )
43    ds = ds.with_column("status", col("body")["status"])
44    ds.show()