我們認真閱讀每一份回饋，並嚴肅看待您的意見。
如需查看所有可用的限定詞，請參閱我們的說明文件。
在 Mac 上原生運行 TRELLIS.2 影像轉 3D 生成。
這是 Microsoft 的 TRELLIS.2 — 一個最先進的影像轉 3D 模型 — 從僅支援 CUDA 的環境移植到 Apple Silicon，透過 PyTorch MPS 實現。無需 NVIDIA GPU。
在 M4 Pro (24GB, 冷啟動, 權重已快取, 機器冷卻, 管道類型 512) 上，從單張影像生成超過 400K 頂點網格，並烘焙 PBR 材質，耗時約 5 分 13 秒。其中約 3 分 20 秒為實際生成和烘焙時間；其餘約 1 分 45 秒為每次 Python 進程載入管道的時間。
輸出為 GLB 格式，包含基礎顏色、金屬度和粗糙度材質 — 可直接用於 3D 應用程式。
輸入影像 → 生成的 3D 網格 (~400K 頂點, ~800K 三角形) 及 Metal 烘焙的 PBR 材質：
若要跳過 Metal 建置 (例如在較舊的硬體上或加快設置速度)：
setup.sh 現在會預先將 Git 依賴項克隆到 deps/ 目錄，以便所有網路 I/O 都在前端完成。如果設置看起來不一致或您不確定本地克隆狀態，請刪除 deps/ 並重新執行 setup：
輸出檔案會儲存到目前目錄 (或使用 --output 指定路徑)。
TRELLIS.2 依賴於多個僅支援 CUDA 的函式庫。此移植版本將每個函式庫替換為可在 Apple Silicon 上運行的後端：
此外，程式碼庫中所有硬編碼的 .cuda() 呼叫都已修補，改為使用作用中的裝置。
稀疏 3D 卷積 (backends/conv_none.py)：透過建立作用體素的空間雜湊表、收集每個核心位置的鄰近特徵、透過矩陣乘法應用權重，然後將結果加總散射回來，來實現子網格稀疏卷積。鄰近圖會針對每個張量進行快取，以避免重複計算。
網格提取 (backends/mesh_extract.py)：使用 Python 字典而非 CUDA 雜湊表操作，重新實現 flexible_dual_grid_to_mesh。建立座標到索引的查找表，找出每個邊的連接體素，並使用法線對齊啟發式方法對四邊形進行三角化。
注意力機制 (patched full_attn.py)：為稀疏注意力模組添加了 SDPA 後端。將變長序列填充到批次中，運行 torch.nn.functional.scaled_dot_product_attention，然後取消填充結果。
材質烘焙：預設情況下，我們使用 @pedronaugusto 發布的 Metal 堆疊 — mtldiffrast, mtlbvh, mtlmesh，以及他 CPU 分支的 o_voxel — 它暴露了 o_voxel.postprocess.to_glb。我們在將解碼器網格傳遞給 Metal BVH 之前，會先將其快速簡化到約 20 萬個面 (BVH 建置器在輸入超過 80 萬個面時不穩定)。如果 Metal 工具鏈不可用，我們將回退到 backends/texture_baker.py：使用 xatlas 進行 UV 解展開，然後在原生 512 解析度的稀疏體素網格上進行 scipy cKDTree + 反距離加權。
在 M4 Pro (24GB), 管道類型 512, 已安裝完整的 Metal 堆疊, 權重已快取, SPARSE_CONV_BACKEND=flex_gemm (自 Pedro Naugusto 的零拷貝 MPS 修復以來為預設值) 上的基準測試。以下數字來自全新安裝的端到端運行 ( /usr/bin/time -h python generate.py shoe_input.png )。這些假設機器處於冷卻狀態。M4 Pro 在持續負載下會積極節流，我測量過在 CPU 已被佔用一小時後，相同運行時間會增加 6-10 倍。
在 Pedro Naugusto 修復了 mtlgemm 中的四個錯誤 (零拷貝 MPS, 真實 fp16/bf16 核心, 真實遮罩隱式 GEMM, 無每次呼叫 waitUntilCompleted) 後，形狀和材質解碼器 VAEs 的速度加快了 2.5-2.9 倍。在他修復之前，解碼器路徑約為 38 秒；現在約為 27 秒。觸及稀疏卷積的取樣步驟也有小幅提升 — 這些路徑主要由注意力機制主導，而注意力機制在 MPS 上仍是 SDPA 填充的。
生成期間記憶體使用量峰值約為 18GB 的統一記憶體。
首次運行會增加約 15GB 的 HuggingFace 權重下載 (TRELLIS.2, DINOv3, RMBG-2.0) — 這是網路瓶頸，不包含在上述時間內。管道載入時間主要由從磁碟反序列化這些權重所主導；如果您在單個 Python 進程中批次處理多個影像，則只需支付一次載入費用。
使用 SKIP_METAL=1 (純 Python KDTree 烘焙器) 時，材質烘焙耗時約 15 秒，而非約 11 秒，且 UV 圖邊界附近的覆蓋範圍略微柔和。如果沒有 mtlgemm Python 套件，Metal 烘焙器將回退到使用 torch.nn.functional.grid_sample 呼叫，這可能會在曲面上留下輕微的環狀偽影；安裝 mtlgemm (由 setup.sh 自動完成) 可以消除這些問題。
setup.sh 將 mtlgemm 作為 Metal 堆疊的一部分進行安裝。它同時用於稀疏卷積擴散路徑 (自 Pedro Naugusto 的零拷貝修復以來) 和材質烘焙器的 grid_sample_3d。如果沒有它，generate.py 將回退到 conv_none.py 進行擴散，並透過 torch.nn.functional.grid_sample 呼叫 monkey-patch o_voxel.postprocess._grid_sample_3d 進行烘焙。回退路徑可以工作，但速度較慢，並且會在曲面上留下輕微的環狀偽影。
測試期間遇到的問題：在 M4 Pro 進行了幾個小時的重度計算後，相同的管道從約 3.5 分鐘的生成時間變慢到約 36 分鐘，這完全是由於熱節流造成的 — 程式碼路徑中沒有任何改變。如果您遇到異常緩慢的運行，請讓機器冷卻幾分鐘後重試，再歸咎於程式碼。
此儲存庫中的移植程式碼 (backends, patches, scripts) 根據 MIT 授權條款發布。
上游模型權重受其自身授權條款約束：