ProgressiveDepth: Series-Joint Depth Completion for Transparent Objects

一个新的透明物体深度补全工作。核心思路：把 TransDiff 的 Data Preprocessing 抠出来得到 Refined Depth1，把它和 RGB 一起喂给 LIDF (Local Implicit Function) 继续补全；两个步骤端到端式串行联合并一起优化。

详细设计动机见 ProgressiveDepth的idea.md。

---

1. Pipeline 总览

RGB + Noisy Depth
        │
        ▼  Module A: TransDiff Data Preprocessing
                     （ip_basic 多尺度形态学填充 + bilateral，与 TransDiff
                      论文/仓库 transdiff_model.py:_extract_depth_ipbasic 一致）
   Refined Depth1
        │
        ▼  Module B: LIDF Local Implicit Function
                     （RGB + Refined1 → ray-voxel 隐式补全 → RefineNet 迭代）
   Final Depth

• 方案 b（分阶段训练，文档 L20-22）：因 ip_basic 数学上不可微，无法做方案 a 的端到端联合训练。我们固定 Module A，按 idea.md「再固定它，训练 LIDF」重训 LIDF：
  • Stage 1（LIDF base，60 epoch）— 复用论文协议下的 ckpt（暂未在 Refined1 分布上重训，记为 stage1 frozen baseline）
  • Stage 2（RefineNet 30 epoch，lr=0.001）— 在 Refined1 输入上重训 ✅ 已搭好
  • Stage 3（RefineNet 30 epoch，lr=0.0001 + hard-neg mining）— 在 Refined1 输入上接续 ✅ 已搭好

---

2. 仓库结构

ProgressiveDepth/
├── README.md                          # 本文档
├── ProgressiveDepth的idea.md          # 设计文档（保留原始）
│
├── pipeline_config.yaml               # 推理 / 评估配置入口
├── progressive_depth.py               # 端到端推理 + ClearGrasp 论文协议评估
│
├── train_progressive.sh               # 启动 Stage 2 训练（Refined1 输入）
├── auto_launch_stage3.sh              # Stage 2 → Stage 3 自动接续
│
├── transdiff_preprocess/              # ── Module A ──
│   ├── ip_basic.py                      # TransDiff 仓库原版多尺度形态学填充
│   ├── preprocess.py                    # 封装 + 工厂函数
│   ├── __init__.py
│   └── README.md
│
├── implicit_depth/                    # ── Module B（NVlabs/implicit_depth fork）──
│   ├── README.md                        # NVlabs 原 README
│   ├── LICENSE                          # NVIDIA Source Code License
│   ├── Dockerfile
│   ├── requirements.txt
│   └── src/
│       ├── datasets/
│       │   ├── transdiff_wrapped_dataset.py     # ⭐ NEW：on-the-fly 把 depth_corrupt 替换为 Refined1
│       │   ├── cleargrasp_dataset.py
│       │   ├── cleargrasp_synthetic_dataset.py
│       │   ├── omniverse_dataset.py
│       │   └── mixed_dataset.py
│       ├── trainers/
│       │   ├── train_progressive.py             # ⭐ NEW：Stage 2/3 重训入口（继承 train_refine）
│       │   ├── train_lidf.py
│       │   └── train_refine.py
│       └── experiments/implicit_depth/
│           ├── train_progressive_stage2.yaml    # ⭐ NEW
│           ├── train_progressive_stage3.yaml    # ⭐ NEW
│           ├── train_lidf.yaml / train_refine.yaml / ...    # 原 NVlabs
│           └── ...
│
├── results/                           # 评估输出（论文协议 RMSE/REL/MAE/δ1.05/1.10/1.25）
│   ├── evaluation_results_stage3_modeA_refined1.json
│   └── evaluation_results_stage3_modeB_noisy.json
│
└── docs/
    ├── PIPELINE.md                    # 详细 pipeline 文档（含决策分支、对照表）
    ├── IMPLICIT_DEPTH_SETUP.md        # 环境配置笔记（rftrans conda env / cuda / 数据路径）
    └── PLAN_STAGE3_AUDIT.md           # 论文 Stage-3 严格审计 + 执行计划记录

---

3. 与 idea.md 的实现映射

idea.md 描述	仓库内实现位置
L3 / L9：「TransDiff Data Preprocessing → Refined1 → LIDF 串联」	transdiff_preprocess/preprocess.py 产 Refined1 → progressive_depth.py:process_single 把它当 LIDF depth_corrupt 输入
L17-19：「Refined Depth1 作为 LIDF 的第一轮输入」	progressive_depth.py 推理路径 mode A（pipeline_config.yaml: transdiff.feed_to_lidf=refined1）
L20-22 方案 b：「先训好 TransDiff，固定它，训练 LIDF」	implicit_depth/src/datasets/transdiff_wrapped_dataset.py + trainers/train_progressive.py + 两个 yaml
L28：「在验证 A+B 的可行数值后」做创新点 1	docs/PIPELINE.md 决策树详细列出验证完进入哪一步
L28：创新点 1（Mask-driven，Segment + Boundary Loss）	待实现，接入位见 docs/PIPELINE.md 末尾
L32-51：创新点 2（SPVNAS 动态体素 + 多源几何特征融合）	待实现，接入位见 docs/PIPELINE.md 末尾

---

4. 当前实验状态（2026-05-18）

4.1 LIDF baseline 复现（论文 Table 1，paper protocol：256×144 + per-image avg + corrupt mask）

子集（论文术语）	指标	论文	我们复现	Δ
Syn-known	RMSE	0.0120	0.0126	✅ +5%
Syn-known	δ1.05	94.79	96.24	✅ +1.45
Syn-novel	RMSE	0.0280	0.0294	✅ +5%
Syn-novel	δ1.05	68.62	67.47	✅ -1.15
Real-known	RMSE	0.0280	0.0366	⚠️ +31%
Real-novel	RMSE	0.0250	0.0455	❌ +82%
Real-novel	δ1.05	76.21	36.93	❌ -39

合成集严格对齐；Real-novel 的差距来自 Omniverse 数据集失效（NVlabs/implicit_depth#3，官方 GDrive 链接 2025-03 起失效），我们 stage1 只用 ClearGrasp 训。

4.2 idea.md 串联推理（读法 1：不重训，仅替换输入）

mode A: feed_to_lidf=refined1 vs mode B: feed_to_lidf=noisy，结果 A ≈ B（差 ≤ 3%），单看推理时把 Refined1 替换 noisy 不带来增益。初步结论：idea 的弱版本（只串联不重训）失效。

4.3 idea.md 串联重训（读法 2：方案 b，正在跑）

C run 在 Refined1 分布上重训 RefineNet（CG-only，stage2 + stage3）。早期 Real-novel 已出现正面信号（epoch 10 RMSE 0.035 / δ1.05 53.95，显著优于 baseline 0.044 / 40.18）。完整结果待跑完后比对。

---

5. 快速使用

5.1 推理 / 评估（已有 ckpt）

cd ProgressiveDepth
export PATH=/path/to/conda/envs/rftrans/bin:$PATH
python progressive_depth.py --config pipeline_config.yaml --mode evaluate

输出 results/evaluation_results.json，同时打印 STRICT COMPARISON vs LIDF paper 对照表。

5.2 重训（idea.md 主线，方案 b）

# Stage 2
bash train_progressive.sh
# 监控
tail -f logs/train_progressive_stage2.log

# Stage 2 跑完后自动接 Stage 3 hard-neg
nohup bash auto_launch_stage3.sh > logs/auto_launch_stage3.log 2>&1 &

详细见 docs/PIPELINE.md。

---

6. 致谢与许可

• Module B：NVlabs/implicit_depth (CVPR 2021) — LICENSE 中保留 NVIDIA Source Code License (Non-commercial)
• Module A：来自 TransDiff 仓库 (ICRA 2025) src/model/ops/ip_basic.py