ComfyUI-LiTo 詳細教學

一張圖 → 524K 個 3D Gaussian Splats，4.7 秒（H100）。把 Apple ICLR 2026 的研究模型包成 ComfyUI 可拖拉的 5 個 node。

1. 專案定位（Project Positioning）

1.1 解決什麼問題

傳統 image-to-3D 流程多步驟、容易斷鏈：

1. 用 SAM / rembg 去背
2. 跑 Diffusion 生成多視角
3. 用 NeRF / Gaussian Splatting 重建 3D
4. 後處理（rigging / 紋理）

每一步都要不同的工具、不同的環境。LiTo 把 (2)+(3) 合成一個 flow-matching DiT 模型，直接從單張圖出 3D Gaussian Splats — 一次就把幾何 + 外觀（含 view-dependent 鏡面高光、Fresnel）做完。

ComfyUI-LiTo 把這條鏈封裝成 5 個 ComfyUI 自訂 node，讓非研究人員也能 drag-and-drop 跑 image-to-3D。

1.2 上游關係

1Apple/ml-lito (ICLR 2026 paper code, 研究用)
2        ↓ wrap
3PozzettiAndrea/ComfyUI-LiTo (本 repo, ComfyUI integration)
4        ↓ depend
5ComfyUI (host) + comfy-env (process isolation) + comfy-3d-viewers

1.3 三個關鍵設計選擇

1.4 為什麼這個 repo 重要

• 是 ICLR 2026 paper 變成可用 ComfyUI 工具 的最新範例
• 對 3D / 數位內容創作管線：單張圖直接出可編輯的 Gaussian Splat 可直接接到 Blender / Three.js / WebGL 的 3D 場景
• 對 AI 整合架構：示範了「研究 model + 隔離環境 + 平台 wrapper」的 production pattern

2. 安裝指南（Installation）

2.1 環境需求

• GPU：強烈建議 NVIDIA（H100 ~4.7s，較弱的卡時間會線性增長）；CPU 模式僅能載入不能 inference
• VRAM：~6–8 GB 推論用；compile 階段會再多用一些
• ComfyUI：較新版本（支援 comfy_api.latest 與 comfy.model_management）
• 磁碟：至少 4 GB（checkpoint 3GB + 依賴 wheels）

2.2 安裝流程

flowchart TD
    A[clone repo 到
ComfyUI/custom_nodes/] --> B[ComfyUI 啟動]
    B --> C[prestartup_script.py 跑]
    C --> D[comfy-env 建獨立子行程環境]
    D --> E[安裝 CUDA wheels
from cuda-wheels.pages.dev]
    E --> F[第一次跑 node]
    F --> G[從 Apple CDN 下載
lito_dit_rgba.ckpt ~3GB]
    G --> H[Ready]

 1# 1. 進到 ComfyUI 的 custom nodes 目錄
 2cd ComfyUI/custom_nodes
 3
 4# 2. clone
 5git clone https://github.com/PozzettiAndrea/ComfyUI-LiTo.git
 6
 7# 3. 重啟 ComfyUI（prestartup_script.py 會自動跑）
 8# 預期看到日誌：
 9#   [LiTo] loading...
10#   [LiTo] calling register_nodes

2.3 ComfyUI Manager（更省事）

如果你有裝 ComfyUI Manager，直接在 Manager 介面搜尋 “LiTo” 然後 install。

2.4 ⚠️ Experimental warning（README 開頭警告）

comfy-env 是實驗性的 process-isolation 套件，會：

1. 自動下載並使用 pixi package manager
2. 在子行程內建立獨立 Python 環境
3. 解析 CUDA wheels（從 cuda-wheels.pages.dev）

如果你對「自動下載 package manager + 從非 PyPI 來源裝 wheel」這件事敏感，請先看完第 6 節資安掃描。

3. 核心架構解析（Core Architecture）

3.1 5 個 ComfyUI nodes 的關係

flowchart LR
    A[LoadImage
ComfyUI built-in] --> B[LiToPreprocess
nodes/preprocess.py]
    M[LiToLoadModel
nodes/load_model.py] -->|MODEL| C[LiToImageTo3D
nodes/inference.py]
    B -->|IMAGE+MASK| C
    C -->|GAUSSIANS| D[LiToExportPLY
nodes/export_ply.py]
    C -->|GAUSSIANS| E[LiToPreviewPointCloud
nodes/preview_nodes.py]
    D --> F[.ply 檔]
    E --> G[瀏覽器 3D 預覽
web/pointcloud_vtk/]

3.2 目錄結構

 1ComfyUI-LiTo/
 2├── __init__.py              # 12 行；註冊 nodes
 3├── prestartup_script.py     # 16 行；setup comfy-env + copy 3D viewer
 4├── install.py               # 3 行；空殼
 5├── pyproject.toml           # ComfyUI registry metadata
 6├── requirements.txt         # 2 個 dep: comfy-env, comfy-3d-viewers
 7├── comfy-env-root.toml      # comfy-env 設定
 8├── comfy-test.toml          # ComfyUI registry 自動測試設定
 9├── assets/                  # 範例圖
10├── workflows/               # 範例 .json workflows
11├── web/                     # 前端：3D point cloud viewer (VTK)
12└── nodes/                   # 5 個 node 實作
13    ├── __init__.py          # 30 行；NODE_CLASS_MAPPINGS
14    ├── load_model.py        # 166 行；checkpoint download + load
15    ├── preprocess.py        # 187 行；rembg + crop/pad to 518x518
16    ├── inference.py         # 366 行；DiT sampling + Gaussian decoding
17    ├── export_ply.py        # 80 行；存 PLY
18    ├── preview_nodes.py     # 47 行；前端預覽橋接
19    ├── comfy_utils.py       # 17 行；helper
20    └── lito_src/            # Apple LiTo 完整 source code 嵌入
21        ├── lito/models/     # DiT, DINO, ResNet, point encoder/decoder
22        ├── lito/trainers/   # 訓練（推論不會用到）
23        ├── lito/flow/       # flow-matching path
24        ├── plibs/           # point lib utils (gs_utils, sh_utils 等)
25        └── third_party/TRELLIS/  # 部份 TRELLIS 模組（mesh / sparse attn）

3.3 Inference 主要流程（nodes/inference.py）

sequenceDiagram
    participant U as ComfyUI Workflow
    participant LI as LiToImageTo3D
    participant MM as comfy.model_management
    participant Worker as comfy-env Subprocess
    participant Model as DiT (~3GB)

    U->>LI: RGBA image (518x518) + model handle
    LI->>MM: free_memory()
    LI->>Worker: 把 image tensor + cfg 送進子行程
    Worker->>Model: lazy load checkpoint (cache after 1st)
    Worker->>Model: compile (1st run only, slower)
    Model->>Model: DiT flow-matching sampling
    Model->>Model: Gaussian decoding → 524K splats
    Worker-->>LI: GAUSSIANS dict
    LI->>MM: free_memory() + reset_peak_vram()
    LI-->>U: GAUSSIANS for downstream nodes

3.4 為什麼用 comfy-env subprocess？

LiTo 的依賴包含：

• pytorch3d — 編譯複雜，與 ComfyUI 主環境的 torch 版本常衝突
• gsplat — CUDA kernel，CUDA toolkit 版本綁死
• nvdiffrast — 編譯需要 OpenGL headers
• flash_attn — 與 CUDA / pytorch 版本三方綁死
• spconv — sparse conv，CUDA 版本嚴格
• xformers — 與 torch 版本綁死

如果直接裝到 ComfyUI 主環境，多半其中一兩個會編譯/載入失敗，且會污染其他 custom node。comfy-env 把這些依賴關進子行程，主環境保持乾淨。

3.5 模型權重來源

1# nodes/load_model.py
2CHECKPOINT_URLS = {
3    "lito_dit_rgba (recommended)": "https://ml-site.cdn-apple.com/models/lito/lito_dit_rgba.ckpt",
4    "lito_dit (paper)":            "https://ml-site.cdn-apple.com/models/lito/lito_dit.ckpt",
5}

下載到 ComfyUI/models/lito/。Apple CDN 是 HTTPS 官方來源，可信。

4. Helper Scripts / Node 詳細用法

4.1 LiToLoadModel

4.2 LiToPreprocess

4.3 LiToImageTo3D

4.4 LiToExportPLY

4.5 LiToPreviewPointCloud

4.6 prestartup_script.py 在做什麼

1setup_env()                                                  # 建 comfy-env subprocess
2copy_viewer("pointcloud_vtk", SCRIPT_DIR / "web")            # 複製 3D viewer 前端
3copy_files(SCRIPT_DIR / "assets", COMFYUI_DIR / "input")     # 把範例圖放到 ComfyUI input/

5. 應用場景（Use Cases）

5.1 場景 A：產品設計快速原型

設計師畫一張產品 sketch（或 ChatGPT/Imagen 生圖）→ ComfyUI-LiTo → PLY → Blender 開檔調整。從 idea 到可調 3D 不到 30 秒。

5.2 場景 B：電商 3D 預覽

把產品照片（去背的 RGBA） → 3D Gaussian Splat → 嵌到網站做可旋轉預覽（用 splat viewer / Three.js）。

5.3 場景 C：研究比較 baseline

LiTo 是 ICLR 2026 的新方法，直接跟 TRELLIS / Wonder3D / Zero123 比較單張圖→3D 品質與速度的 baseline。

5.4 場景 D：教學素材

把 ComfyUI 工作流當「圖到 3D 的 5 步驟教材」— preprocess / model load / sampling / export / preview 一條龍。

5.5 場景 E：與 Stable Diffusion 串接

1text prompt
2  → ComfyUI SDXL/Flux → RGBA image
3    → ComfyUI-LiTo → 3D Gaussian
4      → export to game asset

純文字到 3D 資產一氣呵成。

6. 資安掃描報告（Security Scan）

掃描日期：2026-05-22，範圍：__init__.py, prestartup_script.py, nodes/*.py

6.1 風險摘要

6.2 進 production 必做 checklist

• 確認你的場景是 非商業研究 / 學術 / 個人非商用，否則需聯繫 Apple 取得商用授權
• 把 ComfyUI / ComfyUI-LiTo 跑在「無 production secret 的環境」（custom node 走 host Python，理論上能讀環境變數）
• 不要把 ComfyUI Manager + LiTo 開放到公網（任意人可上傳圖 = 任意人可耗你的 GPU）
• 監控 GPU VRAM；compile 失敗時手動清子行程
• 若不接受 comfy-env 的 pixi 自動下載 → fork repo 改成手動 pip install + 自承依賴衝突風險

6.3 結論

🟢 低風險（從 repo 程式碼角度）。整體程式碼乾淨、無典型 RCE pattern、checkpoint 走官方 CDN、無 secret 處理。

🟡 中風險（從外部依賴與授權）。comfy-env 的 pixi 自動下載 + 模型授權非商業，是部署前要評估的兩個點。

7. FAQ

Q1: 需要多少 VRAM？ A1: 推論時 ~6–8 GB；compile 階段會再多。消費級 RTX 4090（24GB）綽綽有餘；3090（24GB）也可；3060（12GB）勉強；8GB 卡可能 OOM。

Q2: H100 4.7s 是包含 compile 嗎？ A2: 不是。是 compile 後 的純 sampling 時間。第一次跑 compile 約 30–60s（torch.compile 編譯 DiT），之後同 session 內都 ~5s。

Q3: 沒有 NVIDIA 卡能跑嗎？ A3: 載入可以，推論不行。模型需要 CUDA kernels（gsplat / flash_attn / spconv）。Apple Silicon 也不行（雖然 LiTo 是 Apple 出的）。

Q4: 跟 TRELLIS 差在哪？ A4: TRELLIS 是 SLAT (Structured LATent) → Gaussian/Mesh/NeRF 三種表示都做；LiTo 只做 Gaussian Splat 但更直接（flow-matching 一次到位）。本 repo 內也嵌了部份 TRELLIS 模組（mesh / sparse attention）作為 utility。

Q5: 輸出的 .ply 怎麼開？ A5:

• 快速看：用 LiToPreviewPointCloud（瀏覽器內）
• 編輯：Blender 4.2+ 內建 Gaussian Splat 支援 / SuperSplat（網頁版編輯器）
• WebGL：mkkellogg/GaussianSplats3D / Three.js + 自製 shader
• Unity / UE：UnityGaussianSplatting (aras-p) / Niagara plugins

Q6: 模型權重可以商用嗎？ A6: 預設不可。讀 LICENSE_MODEL — Apple ML Research model license 限非商業研究使用。商用要另外向 Apple 取授權。

Q7: 為什麼要去除 PyTorch Lightning？ A7: ComfyUI 的 comfy.model_management 與 PyTorch Lightning 的 ModelPatcher 不相容（commit b0ac634）。作者改用 mm.free_memory() 直接管 VRAM，讓 LiTo 能跟其他 custom node 共存而不爆 VRAM。

Q8: comfy-env 子行程跑掛了怎麼辦？ A8: 通常是 CUDA wheel 對不上 driver。查 comfy-env 的 log，常見解法：升級 NVIDIA driver / 確認 nvidia-smi 出來的 CUDA runtime 版本與 wheels 對得上。

8. 進階技巧

8.1 同 session 內批次處理

把 LiToLoadModel 放外面，後面接多個 LiToImageTo3D（不同輸入圖共用同一 model handle）。model 只 compile 一次，之後每張圖 ~5s。

8.2 控制隨機性

LiToImageTo3D 的 seed 參數 — 同 seed + 同輸入 = 確定性輸出（除非開 compile=True 之後有 cudnn nondeterminism）。

8.3 後處理 Gaussian 數量

預設 ~524K splats 可能對 web viewer 太多。可以：

• 寫一個 ComfyUI custom node 在 LiTo 後接 PLY-decimate
• 或在 Blender 開檔後用 splat editor 手動 prune low-opacity splats

8.4 用不同 checkpoint

lito_dit_rgba 是推薦版（帶 alpha channel 訓練）；lito_dit 是 paper 原版。如果你的輸入沒去背直接給原圖，可以試 lito_dit，但品質可能下降。

8.5 fork 並改 inference path

如果不想用 comfy-env，可以 fork 本 repo + 改 __init__.py 移除 from comfy_env import register_nodes + 手動寫 NODE_CLASS_MAPPINGS。但要自己處理依賴衝突。

9. 整合進其他工作流

9.1 與本知識專案的整合點

flowchart LR
    A[AI-knowledge 專案] --> B[ComfyUI-LiTo
image-to-3D]
    A1[ai-save
抓網路上的產品圖] --> B
    A2[paper-tutorial
讀 LiTo paper] -.參考.-> B
    B --> C[kami
把 3D 預覽嵌進報告]
    B --> D[meeting-intel
客戶產品 mockup]

9.2 對應到 AI-knowledge 的 layer

9.3 對應到外部工具

10. 重點摘要 Checklist

• 是 Apple ICLR 2026 paper LiTo 的 ComfyUI 包裝，單張圖直接出 3D Gaussian Splat
• 5 個 nodes：Load Model / Preprocess / Image-to-3D / Export PLY / Preview
• H100 ~4.7s（compile 後）；消費級 4090 也可；需 NVIDIA CUDA
• 用 comfy-env 做 process isolation，避免依賴衝突
• Checkpoint 從 Apple CDN 下載（~3GB）
• 程式碼安全性 🟢；外部依賴 🟡（pixi 自動下載 + 模型授權非商業）
• 不可商用（除非取得 Apple 授權）— 適用研究、學術、個人非商業
• 後續處理：Blender / Three.js / Unity / UE 都能讀 PLY

11. 進一步閱讀

Generated by: AI-knowledge_template gh-tutorial-qd workflow · 2026-05-22