Skip to content

ly-xxx/RAM-Grounded-SAM3D

BranchesTags

Repository files navigation

SAM3D Pipeline

基于视觉基础模型的机器人场景三维重建与手眼标定系统

SAM3D Pipeline 是一个模块化的端到端系统，从单目视频输入出发，自动完成机器人场景的三维重建、语义分割、URDF 配准（手眼标定）以及新视角相机定位。系统集成了多个前沿视觉基础模型（GroundingDINO、SAM2、MASt3R、COLMAP、VGGT），并与机器人运动学约束相结合。

系统架构

输入: 单目视频 + URDF 模型 + 关节角度
                    │
    ┌───────────────┴───────────────┐
    │      Step 1: 视频预处理        │
    │  GroundingDINO 检测 + SAM2 追踪│
    │  MASt3R / COLMAP / VGGT 重建   │
    └───────────────┬───────────────┘
                    │  masks + 点云 + 位姿
    ┌───────────────┴───────────────┐
    │      Step 2: 点云分割          │
    │   多视角投票: 2D mask → 3D 语义│
    └───────────────┬───────────────┘
                    │  机器人点云 + 背景点云
    ┌───────────────┴───────────────┐
    │      Step 3: URDF 配准         │
    │  PCA + ICP → 尺度 + 位姿恢复  │
    └───────────────┬───────────────┘
                    │  标定后的相机参数
    ┌───────────────┴───────────────┐
    │      Step 4: 相机定位          │
    │  新视角 RGB(-D) → 内外参估计   │
    └───────────────────────────────┘

目录结构

sam3d_pipeline/
├── run_pipeline.py              # 统一入口 (编排 Step 1-4)
├── pyproject.toml               # 项目依赖与构建配置
├── src/                         # 源码包
│   ├── config.py                # 全局共享配置 (默认值 + argparse 工具)
│   └── modules/                 # 模块化视觉能力库
│       ├── base.py              # 抽象基类 + 注册工厂
│       ├── grounding_dino/      # 开放词汇目标检测
│       ├── sam/                 # 单帧实例分割 (SAM 1.0)
│       ├── sam2/                # 视频分割与追踪 (SAM 2.1)
│       ├── sam3/                # 文本驱动分割 (SAM 3)
│       ├── ram/                 # 图像标签识别 (RAM+)
│       ├── mast3r/              # 多帧稠密重建 (MASt3R)
│       ├── colmap/              # 经典 SfM 重建 (COLMAP)
│       ├── vggt/                # Transformer 重建 (VGGT)
│       ├── kinematics/          # URDF 运动学 + 点云配准
│       └── sam3d_objects/       # 单图 3D 物体生成
├── tools/                       # Pipeline 各步骤的独立脚本
│   ├── step1_reconstruct.py     # Step 1: 视频→点云重建
│   ├── step2_segment_cloud.py   # Step 2: 点云语义分割
│   ├── step3_calibrate.py       # Step 3: URDF 配准 (手眼标定)
│   └── step4_localize.py        # Step 4: 新视角相机定位
├── data/                        # 示例数据
│   ├── example_00/              # 示例场景 0 (xArm6)
│   └── example_01/              # 示例场景 1 (RM75)
├── experiments/                 # 实验脚本与配置
│   ├── scripts/                 # baseline 方法 + 评测 + 扰动实验
│   ├── configs/                 # 实验配置 JSON
│   └── references/              # Ground Truth 参考外参
├── docs/                        # 文档
├── paper/                       # 论文相关
├── related_works/               # 相关文献
└── 3party/                      # 第三方依赖 (mast3r, vggt)

快速开始

环境要求

  • OS: Linux x86_64 (仅支持)
  • Python: 3.11.x
  • GPU: NVIDIA GPU, 建议 16GB+ 显存 (CUDA 12.1)
  • 包管理: uv (推荐)

安装

# 1. 克隆仓库
git clone --recursive https://github.com/your-org/sam3d_pipeline.git
cd sam3d_pipeline

# 2. 安装依赖 (使用 uv)
uv sync

# 3. 安装第三方依赖
# MASt3R
cd 3party/mast3r && pip install -e . && cd ../..

# 4. 下载模型权重
# GroundingDINO -> src/modules/grounding_dino/checkpoints/
# SAM2          -> src/modules/sam2/checkpoints/
# MASt3R        -> src/modules/mast3r/checkpoints/

详细安装说明请参考 INSTALL.md。

运行完整流程

# Step 1-3: 视频预处理 + 点云分割 + URDF 配准
python run_pipeline.py \
    --video data/example_01/video.mp4 \
    --urdf data/example_01/robot_2/rm75_ag2f90c.urdf \
    --joints data/example_01/robot_2/joints_config.json

# Step 4: 新视角相机定位 (RGB-D)
python run_pipeline.py --steps 4 \
    --prev-step3 outputs/.../step3_xxx \
    --rgbd data/example_01/cam_1/image.npz

分步执行

# 只运行 Step 1 (视频预处理)
python run_pipeline.py --video data/example_01/video.mp4 --steps 1

# 使用 COLMAP 替代 MASt3R 进行重建
python run_pipeline.py --video data/example_01/video.mp4 --steps 1 --recon-method colmap

# 使用 VGGT 重建
python run_pipeline.py --video data/example_01/video.mp4 --steps 1 --recon-method vggt

# 从 Step 2 继续 (指定 Step 1 输出)
python run_pipeline.py --steps 2,3 \
    --prev-step1 outputs/step1_xxx \
    --urdf data/example_01/robot_2/rm75_ag2f90c.urdf

# 直接调用工具脚本
python tools/step1_reconstruct.py --video data/example_01/video.mp4 --output outputs/test
python tools/step2_segment_cloud.py --step1-dir outputs/step1_xxx --output outputs/step2_xxx

输出结构

Pipeline 采用递归嵌套的输出目录结构：

outputs/
└── step1_20250208_143000/           # Step 1 输出
    ├── masks/                       # SAM2 分割 mask (per-object 子目录)
    │   ├── robot_1_01/              #   机器人1 逐帧 mask
    │   └── robot_2_02/              #   机器人2 逐帧 mask
    ├── sparse_cloud.ply             # 重建点云
    ├── camera_poses.npy             # 相机位姿 (N, 4, 4) C2W
    ├── intrinsics.npy               # 相机内参 (N, 3, 3)
    ├── frames/                      # 关键帧图像
    ├── config.json                  # 运行配置快照
    ├── meta.json                    # 元信息
    └── step2_20250208_143500/       # Step 2 输出 (嵌套在 Step 1 内)
        ├── robot_cloud.npy          # 机器人点云
        ├── background_cloud.npy     # 背景点云
        └── step3_20250208_144000/   # Step 3 输出 (嵌套在 Step 2 内)
            ├── calibration.json     # 标定结果
            ├── calibrated_poses.npy # 标定后相机位姿
            └── step4_20250208_145000/  # Step 4 输出
                ├── camera_pose.npy     # 新视角位姿
                └── localization_result.json

Pipeline 详细说明

Step 1: 视频预处理 (检测 + 追踪 + 重建)

  1. GroundingDINO 在第一帧检测机器人 (文本提示: "robot arm")
  2. SAM2 从检测框初始化, 追踪整个视频, 输出逐帧 mask
  3. 3D 重建 (可选后端):
    • mast3r (默认): 端到端稠密匹配, 速度适中, 精度好
    • colmap: 经典 SfM, 精度最高, 速度较慢
    • vggt: 前馈 Transformer, 速度最快, 弱纹理鲁棒

Step 2: 点云语义分割

利用多视角投票机制将 2D mask 反投影到 3D 点云:

  • 每个 3D 点投影到所有视角, 统计被 mask 覆盖的比例
  • 投票比例 > 阈值 (默认 0.6) 的点标记为机器人

Step 3: URDF 配准 (手眼标定)

将分割出的机器人扫描点云配准到 URDF 模型:

  1. URDF 前向运动学生成标准点云
  2. PCA 主轴对齐 + 多尺度/多旋转候选搜索
  3. Point-to-Plane ICP 精细配准
  4. 方向检测与自动修正

恢复: 绝对尺度 + 基座位姿 + 标定后的相机内外参

Step 4: 相机定位

给定新视角 RGB(-D) 图像, 估计其内外参:

  • visual: 特征匹配 + PnP (支持 RGB 和 RGB-D)
  • pointcloud: 深度图→点云, ICP 配准 (需 RGB-D)
  • robot: 机器人姿态约束配准 (需 RGB-D)
  • silhouette: 轮廓对齐

模块能力

模块 功能 核心类 依赖
grounding_dino 开放词汇检测 GroundingDINO groundingdino
sam 单帧分割 SAMSegmentor segment-anything
sam2 视频追踪 SAM2VideoTracker, AutoVideoSegmentor sam2, hydra
sam3 文本分割 SAM3TextSegmentor sam3
ram 图像标签 RAMTagger recognize-anything
mast3r 稠密重建 MASt3RReconstructor mast3r, dust3r
colmap SfM 重建 COLMAPReconstructor pycolmap
vggt Transformer 重建 VGGTReconstructor vggt
kinematics URDF 配准 ChainGrowthSolver pytorch-kinematics, open3d
sam3d_objects 3D 生成 SAM3DGenerator 编译安装

可插拔架构

所有重建器和定位器通过装饰器注册到全局工厂:

from src.modules.base import register_reconstructor, get_reconstructor

@register_reconstructor("my_method")
class MyReconstructor(BaseReconstructor):
    def _load_model(self): ...
    def _unload_model(self): ...
    def reconstruct(self, frames, **kw): ...

# 按名称动态实例化
recon = get_reconstructor("my_method", device="cuda")

主要依赖

依赖 版本 用途
PyTorch 2.5.1 (CUDA 12.1) 深度学习框架
OpenCV >= 4.9.0 图像处理
Open3D >= 0.18.0 3D 点云处理与 ICP
trimesh >= 4.0.0 Mesh 加载与采样
pytorch-kinematics >= 0.7.0 URDF 解析与 FK
pycolmap >= 3.10.0 COLMAP Python API
hydra-core >= 1.3.2 配置管理 (SAM2)

实验与评测

# 运行 baseline 对比实验
python experiments/scripts/baseline_pca_icp.py \
    --step2-dir outputs/.../step2_xxx --urdf robot.urdf --joints joints.json

# 评测标定精度
python experiments/scripts/eval_calibration.py \
    --result outputs/.../step3_xxx/calibration.json \
    --reference experiments/references/example_01_ref.json

# 鲁棒性实验 (内参/关节角噪声)
python experiments/scripts/perturb_intrinsics.py --intrinsics intrinsics.npy --sigma 5.0
python experiments/scripts/perturb_joints.py --joints joints.json --sigma 0.05

开发

详细开发指南请参考 DEVELOPMENT.md。

许可证

本项目仅供学术研究使用。

About

An automated pipeline for generating 3D objects (Gaussian Splats/Mesh) from single images using RAM, GroundingDINO, SAM, and SAM3D. | 基于 RAM、GroundingDINO、SAM 和 SAM3D 的全自动单图生成 3D 模型（Gaussian Splats/Mesh）流水线。

Topics

computer-vision ram pytorch 3d-reconstruction 3d-generation segment-anything grounding-dino gaussian-splats

Resources

Readme
Activity

Stars

3 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages
⚡