Metadata-Version: 2.4
Name: sam3d
Version: 0.1.0
Summary: Unified Python interface for Meta SAM 3D Body and SAM 3D Objects
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: numpy>=1.24
Requires-Dist: Pillow>=10.0
Provides-Extra: inference

# sam3d

`sam3d` 提供 SAM 3D Body 和 SAM 3D Objects 的统一 Python 接口，目标是下载好模型后可直接调用。

## 1. 准备模型文件

### SAM 3D Body

示例路径约定：

- `sam-3d-body/checkpoints/sam-3d-body-dinov3/model.ckpt`
- `sam-3d-body/checkpoints/sam-3d-body-dinov3/assets/mhr_model.pt`

### SAM 3D Objects

示例路径约定：

- `sam-3d-objects/checkpoints/hf/pipeline.yaml`

你也可以传入自定义绝对路径（`SAM3DConfig`）。

## 2. 安装

```bash
cd /Users/sun/Projects/embody/sam3d
pip install -e .
```

## 3. 使用

```python
import numpy as np
from sam3d import SAM3D

sam3d = SAM3D.from_defaults(
    workspace_dir="/Users/sun/Projects/embody/sam3d",
    device="cuda",
)

# 4.1 人体重建
body_result = sam3d.predict(
    task="body",
    image="/path/to/person.jpg",
)
print(len(body_result["instances"]))

# 4.2 物体重建
mask = np.zeros((1024, 1024), dtype=bool)  # 你的物体 mask
obj_result = sam3d.predict(
    task="objects",
    image="/path/to/object.png",
    mask=mask,
    seed=42,
)
obj_result["gaussian_splat"].save_ply("object.ply")
```

## 4. 接口设计说明

- 统一入口：`SAM3D.predict(task=...)`
- 任务拆分：`predict_body(...)` 和 `predict_objects(...)`
- 懒加载：首次调用对应任务时才初始化模型，减少启动负担
- 与官方实现兼容：底层直接复用 Meta 仓库里的推理入口

## 5. 第三方源码

当前包已 vendoring 下列源码（仅包含统一接口所需部分）：

- `sam_3d_body`（来自 `facebookresearch/sam-3d-body`）
- `sam3d_objects`（来自 `facebookresearch/sam-3d-objects`）
