Monocle3D

视频 → 3D 模型 的自动重建开源管线，感知核心对接 Gemini 视觉模型（分割 + 度量深度 + 表面法线）。

命名说明：本项目原名 banana-vision-3d。为避免与 Google 的产品命名产生混淆，已更名为 Monocle3D（monocle = 单目镜，对应"单目视频 → 3D"）。本项目为社区开源实现，与 Google 无隶属关系，也未经其认可；Google、Gemini、Vision Banana、Nano Banana 等名称权利归其所有者。

---

这是什么

Google DeepMind 的统一视觉模型（Image Generators are Generalist Vision Learners, arXiv:2604.20329）把 语义分割、度量深度、表面法线 统一表述为"生成一张可解码的 RGB 图像"，zero-shot 达到或超过专用模型。

Monocle3D 把这种感知能力工程化成一条 视频自动建模管线，并完整实现了论文公开的解码方案：

视频/图片序列
   │  智能抽帧（清晰度 + 镜头切换）
   ▼
[Gemini 视觉 | 本地兜底] ── 分割掩码 / 度量深度 / 表面法线
   │  （输出为可解码 RGB，本项目逆解回物理量）
   ▼
深度反投影（针孔模型，无内参依赖）→ 帧间 ICP 配准 → 点云融合
   │  体素降采样 + 半径离群点滤波
   ▼
Poisson 网格（open3d，可选）→ 顶点着色
   ▼
model.glb / model.obj / model_mesh.ply / model_pointcloud.ply + report.json

核心特性

• 论文级解码器：RGB 立方体 Hamilton 路径（3D Hilbert 一阶迭代）+ power transform 的深度可逆双射；法线 RGB 编码；分割纯色聚类（monocle3d/perception/encoding.py）
• 双后端：gemini（Gemini API，输出严格可解码）与 local（离线兜底，可选接入 Depth-Anything-V2-Small）
• 零重依赖：核心链路仅 numpy + pillow；open3d/torch 全部可选、自动降级
• 可复现：感知结果 npz 缓存、report.json 全程留痕、56 个单元/端到端测试
• 自带查看器：viewer/index.html 拖拽查看 GLB/PLY/OBJ

安装

git clone https://github.com/hwc66626/monocle3d.git
cd monocle3d
pip install -e .            # 核心：numpy + pillow
pip install -e ".[mesh]"    # 可选：Poisson 网格化
sudo apt install ffmpeg     # 视频输入需要（图片目录/单图不需要）

快速开始

# 1. 配置 Gemini API key（Google AI Studio 申请）
export GEMINI_API_KEY="你的key"

# 2. 一行命令：视频 → 3D 模型
monocle3d run input.mp4 -o output --classes person,car

# 3. 查看结果
#    浏览器打开 monocle3d/viewer/index.html，拖入 output/model.glb

无 API key 也能跑（本地兜底后端，几何精度有限）：

monocle3d run examples/scene/ -o output --backend local

Python API：

from monocle3d import PipelineConfig, VideoTo3DPipeline

cfg = PipelineConfig().apply_env_overrides()   # 读 GEMINI_API_KEY
result = VideoTo3DPipeline(cfg).run("input.mp4", output_dir="output")
print(result.summary())      # 完成(gemini): 182304 点, 96543 顶点/190221 面

感知解码原理（简版）

任务	Prompt 约定	解码
语义分割	"类别 X 用纯色 <255, 255, 0> 渲染"	目标色最近邻聚类（带容差）→ 掩码
度量深度	沿 RGB 立方体边路径的严格单调色带（黑=近，白=远）	投影到折线求 t → power transform 逆 → 米
表面法线	标准 RGB 法线编码（R=x, G=y, B=z）	n = 2·rgb − 1，归一化

深度双射：t = d^α/(d^α + k)，再沿 8 顶点 Hamilton 路径分段线性映射到 [0,1]³；解码即逆过程。详见 encoding.py（带完整推导注释）。

配置速查

参数	默认	说明
backend	auto	有 key → gemini，否则 local
gemini_model	gemini-3-pro-image-preview	可用 GEMINI_MODEL 覆盖
max_frames / min_frames	40 / 4	参与重建的帧数预算
depth_colormap	hilbert	hilbert / grayscale / viridis / inferno / plasma
depth_k	4.0	power transform 尺度（t=0.5 处深度，米）
voxel_size	0.01	点云体素降采样（米）
segmentation_classes	自动	主体+背景；也可 --classes person,car
build_mesh	true	需要 open3d，缺失自动跳过

完整参数与校验规则见 monocle3d/config.py。

已知限制（诚实说明）

• 感知权重未公开：本项目按论文公开的 prompt 范式 + 解码规则实现 API 客户端，模型名可能随 Google 更新（用 GEMINI_MODEL 覆盖）
• 深度解码参数（depth_alpha/depth_k）：论文未公开精确常数，本项目使用同族可逆映射并参数化，可按实际模型输出标定
• local 后端的启发式深度仅供链路联调，不保证几何精度
• 大幅视角变化的视频：ICP 为 best-effort；大幅运动场景建议减少 max_frames 或分镜头处理
• 静态相机 + 主体运动的素材效果最稳；纯旋转台素材次之

项目结构

monocle3d/
├── config.py               # 全量配置与校验
├── pipeline.py             # 管线编排（阶段状态/缓存/报告）
├── cli.py                  # monocle3d 命令行
├── perception/             # ★ 感知核心
│   ├── encoding.py         #   RGB↔物理量 可逆编解码（论文方案）
│   ├── prompts.py          #   任务指令模板
│   ├── gemini_client.py    #   Gemini REST 客户端（重试/退避）
│   └── backends.py         #   Gemini / Local 双后端
├── video/frames.py         # 抽帧 + 关键帧选择
├── recon/                  # 点云融合 + ICP + Poisson 网格
├── exporting/formats.py    # PLY / OBJ / GLB 写入器
└── viewer/index.html       # three.js 查看器
tests/                      # 56 个测试（单元 + 端到端）
docs/DEBUG_LOG.md           # 10 轮排障记录（现象→根因→修复→验证）
docs/THIRD_PARTY_NOTICES.md # 第三方依赖协议审计

开发

pip install -e ".[dev]"
pytest tests/ -v                 # 全量测试（离线可跑，open3d 缺失自动跳过网格化）
python examples/make_synthetic_scene.py   # 生成合成测试场景

引用（感知方案原始论文）

@article{generalistvision2026,
  title  = {Image Generators are Generalist Vision Learners},
  author = {Google DeepMind et al.},
  journal= {arXiv preprint arXiv:2604.20329},
  year   = {2026},
}

License

MIT © Monocle3D contributors —— 第三方依赖协议见 docs/THIRD_PARTY_NOTICES.md。