SAM3D Pipeline

基于 RAM-Grounded-SAM + SAM3D 的自动化 3D 模型生成流水线。

功能特性

• RAM (Recognize Anything Model): 自动识别图像中的物体标签
• GroundingDINO: 基于文本的目标检测，生成边界框
• SAM (Segment Anything): 实例分割，从边界框生成精确掩码
• SAM3D: 从单张图像 + 掩码生成 3D 模型 (Gaussian Splats / Mesh)

项目结构

sam3d_pipeline/
├── src/sam3d_pipeline/     # 核心代码
│   ├── config.py           # 配置管理
│   ├── pipeline.py         # 主流水线逻辑
│   ├── main.py             # 入口点
│   └── data_ingestion.py   # 数据加载
├── ckpt/                   # 模型权重 (需下载)
│   ├── groundingdino/      # GroundingDINO 权重
│   ├── sam/                # SAM 权重
│   ├── ram/                # RAM 权重
│   ├── sam3/               # SAM3 权重
│   └── sam3d-objects/      # SAM3D 权重
├── data/
│   ├── input/              # 输入数据 (.npz, .jpg, .png)
│   └── output/             # 输出结果 (按时间戳分组)
├── 3party/                 # 第三方代码库 (需克隆)
│   ├── GroundingDINO/
│   ├── sam3/
│   └── sam3d-objects/
├── scripts/                # 辅助脚本
├── run_pipeline.py         # 统一启动器
├── setup_uv_env.sh         # 环境配置脚本
└── requirements.txt        # Python 依赖

快速开始

1. 环境配置

# 运行自动配置脚本
./setup_uv_env.sh

# 激活虚拟环境
source .venv/bin/activate

2. 下载模型权重

模型权重需要手动下载到 ckpt/ 目录：

# GroundingDINO
mkdir -p ckpt/groundingdino
wget -P ckpt/groundingdino https://github.com/IDEA-Research/GroundingDINO/releases/download/v0.1.0-alpha/groundingdino_swinb_cogcoor.pth

# SAM ViT-H
mkdir -p ckpt/sam
wget -P ckpt/sam https://dl.fbaipublicfiles.com/segment_anything/sam_vit_h_4b8939.pth

# RAM (可选，使用预设标签时不需要)
# 从 HuggingFace 下载: xinyu1205/recognize-anything-plus-model

3. 准备输入数据

将输入数据放入 data/input/ 目录。支持格式：

• .npz: 包含 RGB + Depth + Camera 内参
• .jpg / .png: 普通图像

4. 运行流水线

# 完整模式 (包含3D生成)
python run_pipeline.py --mode full

# 快速模式 (跳过3D生成，用于测试检测和分割)
python run_pipeline.py --mode quick

# 仅检测和分割
python run_pipeline.py --skip-sam3d

输出结构

每次运行会在 data/output/run_YYYYMMDD_HHMMSS/ 创建输出目录：

run_20260126_150000/
├── images/
│   ├── input_image.jpg         # 输入图像
│   └── detection_boxes.jpg     # 检测结果可视化
├── masks/
│   ├── mask_000_xxx.png        # 各物体掩码
│   └── ...
├── models/
│   ├── object_000_xxx.ply      # 3D Gaussian Splats
│   ├── object_000_xxx.glb      # 3D Mesh
│   └── ...
└── logs/
    ├── pipeline.log            # 运行日志
    ├── ram_tags.json           # RAM 识别的标签
    └── groundingdino_detections.json  # 检测结果

配置选项

通过环境变量调整参数：

# 使用预设标签 (跳过 RAM 推理)
export SAM3D_TAGS_OVERRIDE="bottle. cup. keyboard"

# 调整检测阈值
export SAM3D_DINO_BOX_THRESHOLD=0.25
export SAM3D_DINO_TEXT_THRESHOLD=0.25

# 掩码后处理参数
export SAM3D_MASK_NMS_IOU_THRESHOLD=0.7
export SAM3D_MIN_MASK_PIXELS=100

依赖安装

核心依赖

# PyTorch (CUDA 12.1)
uv pip install torch torchvision --index-url https://download.pytorch.org/whl/cu121

# 基础依赖
uv pip install -r requirements.txt

# GroundingDINO
uv pip install git+https://github.com/IDEA-Research/GroundingDINO.git

# RAM
uv pip install git+https://github.com/xinyu1205/recognize-anything.git

3D 生成依赖 (可选)

# PyTorch3D
uv pip install pytorch3d -f https://dl.fbaipublicfiles.com/pytorch3d/packaging/wheels/py311_cu121_pyt251/download.html

# spconv
uv pip install spconv-cu120

常见问题

1. PyTorch3D 安装失败

如果预编译包不可用，尝试从源码编译：

uv pip install --no-build-isolation "git+https://github.com/facebookresearch/pytorch3d.git"

2. CUDA 版本不匹配

确保 PyTorch CUDA 版本与系统 CUDA 版本兼容。检查：

python -c "import torch; print(torch.cuda.is_available(), torch.version.cuda)"
nvcc --version

3. 内存不足

SAM3D 需要较大显存。建议：

• 使用 --mode quick 跳过 3D 生成
• 减少同时处理的物体数量
• 使用更小的图像分辨率

License

本项目仅供研究使用。各组件 License：

• GroundingDINO: Apache 2.0
• SAM: Apache 2.0
• RAM: Apache 2.0
• SAM3D: Meta License