目標：在 TD 的 Script TOP/CHOP 裡 import torch 能成功；影像資料可在 TD ↔ NumPy ↔ Torch 張量間轉換。

Step 0｜先確認你用的 TD 內建 Python 版本

在 TouchDesigner 上方選單：Help → About（或 Dialogues → Textport 輸入 python 查版本）
你建立的虛擬環境（venv）一定要用相同的 Python 次版本（例如 TD 是 3.10，你就建 3.10 的 venv）

Step 1｜建立對應版本的虛擬環境

Windows / macOS / Linux（擇一）

建一個與 TD 相同版號的 venv

python -m venv td-venv

啟用

Windows

td-venv\Scripts\activate

macOS / Linux

source td-venv/bin/activate

之後只要你要開 TD 做 AI，先把這個 venv 啟用起來再開 TD（或把 site-packages 路徑加進 TD 設定，見 Step 3）。

Step 2｜安裝 PyTorch（選 CPU 或 GPU）

CPU-only（最穩，跨平台）

pip install --upgrade pip
pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cpu

NVIDIA GPU（依你驅動支援的 CUDA 版本）

例：CUDA 12.1

pip install torch torchvision torchaudio --index-url https://download.pytorch.org/whl/cu121
Apple Silicon（MPS）
pip install torch torchvision torchaudio

程式中 device='mps' 使用蘋果 GPU

若裝 GPU 版碰到 DLL/依賴錯誤，先改 CPU 版確認流程打通，再回頭解 GPU 依賴

Step 3｜讓 TD 找到 venv 的套件

做法 A（推薦｜永久設定）
在 TD：Edit → Preferences → Python 64-bit Module Path

加入你的 venv site-packages 路徑

Windows：…\td-venv\Lib\site-packages

macOS：…/td-venv/lib/python3.x/site-packages

做法 B（專案內設定）
在專案的 Text DAT（例如 init_paths）寫：

import sys
sys.path.append(r"C:\…\td-venv\Lib\site-packages") # 你的路徑

在 /local 的 /local/project1/Start 參考這個 DAT，讓專案開啟時自動執行。

Step 4｜在 TD 內測試

新增 Text DAT，按「Run」：

import torch
print("torch", torch.version)
print("cuda?", torch.cuda.is_available())

能印出版本且不報錯就成功了。

二、在 TD 中跑 PyTorch（影像 & 數據管線）

作法 1：Script TOP（即時影像推論→輸出影像）
新增 Video Device In TOP（或 Movie File In TOP）。
新增 Script TOP，DAT 指向一個 Text DAT（例如 pytorch_top）。
在 pytorch_top 寫：

pytorch_top DAT

import numpy as np
import torch

例：裝一個示意模型（這裡用 identity 佔位）

device = 'cuda' if torch.cuda.is_available() else ('mps' if torch.backends.mps.is_available() else 'cpu')
model = torch.nn.Identity().to(device).eval()

def onSetupParameters(scriptOp):
return

def onCook(scriptOp):
inTOP = scriptOp.inputs[0] if scriptOp.inputs else None
if inTOP is None:
scriptOp.copyNumpyArray(np.zeros((256,256,4), dtype=np.uint8))
return

# 取得 BGRA 影像為 numpy (H,W,4) uint8
img = inTOP.numpyArray(delayed=False)  # TD 2022+ 有此 API；若無可用 toImage 再轉

h, w, _ = img.shape
# 轉成 RGB 並去掉 alpha
rgb = img[:, :, :3][:, :, ::-1].copy()        # BGRA -> RGB
t = torch.from_numpy(rgb).permute(2,0,1).unsqueeze(0).float().to(device) / 255.0

with torch.no_grad():
    out = model(t)                             # (1,3,H,W)
    out = (out.clamp(0,1) * 255).byte().cpu()

out_np = out.squeeze(0).permute(1,2,0).numpy() # (H,W,3) RGB
# 回到 BGRA，補滿 alpha
bgra = np.concatenate([out_np[:, :, ::-1], np.full((h,w,1),255,np.uint8)], axis=2)

# 輸回 Script TOP
scriptOp.copyNumpyArray(bgra)
return

重點：inTOP.numpyArray() → torch.from_numpy() → 模型 → numpy → scriptOp.copyNumpyArray()。
作法 2：Script CHOP（把 AI 結果變成數值，給 Instancing/音像互動）
在 Text DAT（例 pose_chop）：

import numpy as np

def onCook(scriptOp):
# 假設你在別處已經把 PyTorch 模型跑出 17 個關鍵點 (x,y,confidence)
# 這裡用亂數當示範
kpts = np.random.rand(17, 3).astype(np.float32)

scriptOp.clear()
scriptOp.numChans = kpts.shape[1]
scriptOp.numSamples = kpts.shape[0]

for c in range(kpts.shape[1]):
    scriptOp[c].vals = kpts[:, c]
return

把這 CHOP 的輸出餵給 Geometry COMP Instancing / TOP 合成 / 音效觸發 等。

作法 3：分離進程（高負載/大模型）
以 外部 Python 伺服器（同個 venv）跑 PyTorch 推論 → 透過 OSC / WebSocket / TCP / Shared Memory / Spout/Syphon / NDI 與 TD 溝通。

優點：不阻塞 TD 主執行緒；缺點：管線與延遲較複雜。
適合：Stable Diffusion、SAM、DepthAnything 之類大模型或多路相機。

三、5 個可以直接動手做的互動作品
AI 風格畫框（Fast Neural Style）
TOP 流程：Video Device In → Script TOP（PyTorch style transfer）→ Composite → Output。
互動：手勢（Script CHOP）換風格、音量控制筆觸強度。
模型：任一輕量 style transfer（PyTorch Hub 有預訓練）。

人體姿態 → 粒子幕牆
TOP/CHOP 流程：相機 → Script TOP（Pose 模型）→ Script CHOP（輸出 2D 關鍵點）→ Instancing 粒子群。

互動：揮手開合、肢體控制粒子方向與速度。
模型：輕量 Pose（如 Ultralytics YOLOv8-pose）。

即時語意分割 → AR 影像合成

TOP 流程：相機 → Script TOP（Segmentation）→ Matte → 將人像疊到 3D 場景/影片。

互動：手勢觸發場景轉場、走進不同虛擬空間。

模型：DeepLabV3 / BiSeNet / U2Net（取人像）。

物件偵測控制介面

TOP/CHOP 流程：相機 → Script TOP（Object Detection）→ 將 bounding boxes 當 UI 元件（碰撞即觸發）→ 控制燈光/音效。

互動：把「拿起的物品」變成舞台控制器。

模型：YOLOv5/8（輕量、快）。

聲畫共鳴：音訊分類驅動視覺

CHOP/TOP 流程：Audio Device In → Script CHOP（Torch audio classifier）→ 觸發不同視覺模板（TOP 合成）。

互動：不同音色/節奏 → 不同 shader 效果或攝影機路徑。

模型：VGGish/自訓簡單 CNN（鼓掌/口哨/人聲/環境）。

四、效能建議（避免卡頓）
畫面尺寸：試跑 640×360 或 960×540，再逐步拉高解析度。
半精度：model.half() + t = t.half()（GPU 推論可試，注意相容）。
批次化：每 N 幀推一次（absTime.frame % N == 0），其餘沿用上一幀結果。
Threading/Queue：在 Script TOP 之外用 Background COMP 或外部進程，把推論與渲染解耦。
非同步輸入：inTOP.numpyArray(delayed=False)，避免跨幀阻塞。
記憶體拷貝：盡量少做 copy()；但 BGRA↔RGB 的通道翻轉要注意連續記憶體。
GPU 版 Torch：確認 CUDA 與顯卡驅動匹配；跑不動改 CPU 版先打通流程。

五、常見錯誤快查
ModuleNotFoundError: No module named 'torch'
→ site-packages 路徑沒加到 TD；或 venv 版本不對。

DLL load failed / libc10 / cudart 錯
→ CUDA 版不匹配；先改裝 CPU 版測通，再回頭處理。

numpyArray 取不到影像
→ 老版 TD 沒此 API，改用 TOP.toImage() 然後 np.frombuffer()；或升級 TD