@baimingtao/lbs-agent 1.0.0

package/extensions/skills/builtin/creative/touchdesigner-mcp/SKILL.md

@@ -0,0 +1,356 @@
+---
+name: touchdesigner-mcp
+description: "通过 twozero MCP 控制正在运行的 TouchDesigner 实例 —— 创建 operator、设置参数、建立连接、执行 Python、构建实时视觉效果。包含 36 个原生工具。"
+version: 1.1.0
+author: kshitijk4poor
+license: MIT
+platforms: [linux, macos, windows]
+metadata:
+  hermes:
+    tags: [TouchDesigner, MCP, twozero, creative-coding, real-time-visuals, generative-art, audio-reactive, VJ, installation, GLSL]
+    related_skills: [native-mcp, ascii-video, manim-video, hermes-video]
+
+---
+
+# TouchDesigner 集成 (twozero MCP)
+
+## 关键规则
+
+1. **绝不猜测参数名称。** 首先针对 op 类型调用 `td_get_par_info`。你的训练数据对 TD 2025.32 来说是错误的。
+2. **如果触发了 `tdAttributeError`，立即停止。** 在继续之前，对失败的节点调用 `td_get_operator_info`。
+3. **绝不在脚本回调中硬编码绝对路径。** 请使用 `me.parent()` / `scriptOp.parent()`。
+4. **优先使用原生 MCP 工具，而不是 `td_execute_python`。** 使用 `td_create_operator`、`td_set_operator_pars`、`td_get_errors` 等。仅在需要复杂的多步逻辑时才回退到 `td_execute_python`。
+5. **在构建之前调用 `td_get_hints`。** 它会返回特定于你正在使用的 op 类型的模式。
+
+## 架构
+
+```
+Hermes Agent -> MCP (Streamable HTTP) -> twozero.tox (port 40404) -> TD Python
+```
+
+36 个原生工具。免费插件（无需付款/授权 —— 已于 2026 年 4 月确认）。
+具备上下文感知能力（了解选中的 OP、当前网络）。
+Hub 健康检查：`GET http://localhost:40404/mcp` 返回包含实例 PID、项目名称、TD 版本的 JSON。
+
+## 配置 (自动化)
+
+运行安装脚本来处理一切：
+
+```bash
+bash "${HERMES_HOME:-$HOME/.hermes}/skills/creative/touchdesigner-mcp/scripts/setup.sh"
+```
+
+该脚本将：
+1. 检查 TD 是否正在运行
+2. 如果尚未缓存，则下载 twozero.tox
+3. 将 `twozero_td` MCP 服务器添加到 Hermes 配置中（如果缺失）
+4. 测试端口 40404 上的 MCP 连接
+5. 报告剩余的手动步骤（将 .tox 拖入 TD，启用 MCP 开关）
+
+### 手动步骤（一次性，无法自动化）
+
+1. **将 `~/Downloads/twozero.tox` 拖入 TD 网络编辑器** → 点击 安装
+2. **启用 MCP：** 点击 twozero 图标 → Settings → mcp → "auto start MCP" → Yes
+3. **重启 Hermes 会话** 以加载新的 MCP 服务器
+
+安装完成后，验证：
+```bash
+nc -z 127.0.0.1 40404 && echo "twozero MCP: READY"
+```
+
+## 环境说明
+
+- **非商业版 TD** 的分辨率上限为 1280×1280。请使用 `outputresolution = 'custom'` 并显式设置宽/高。
+- **编解码器：** `prores`（macOS 首选）或 `mjpa` 作为备选。H.264/H.265/AV1 需要商业许可证。
+- 在设置参数之前务必调用 `td_get_par_info` —— 名称会因 TD 版本而异（参见关键规则 #1）。
+
+## 工作流
+
+### 步骤 0：发现（在构建任何内容之前）
+
+```
+针对你计划使用的每种类型，使用 op_type 调用 td_get_par_info。
+使用你正在构建的主题（例如 "glsl"、"audio reactive"、"feedback"）调用 td_get_hints。
+调用 td_get_focus 以查看用户所在位置以及选中了什么。
+调用 td_get_network 以查看已存在的内容。
+```
+
+不需要临时节点，不需要清理。这完全取代了以前的发现过程。
+
+### 步骤 1：清理 + 构建
+
+**重要提示：将清理和创建拆分为独立的 MCP 调用。** 在一个 `td_execute_python` 脚本中销毁并重新创建同名节点会导致 "Invalid OP object" 错误。参见陷阱 #11b。
+
+为每个节点使用 `td_create_operator`（自动处理视口定位）：
+
+```
+td_create_operator(type="noiseTOP", parent="/project1", name="bg", parameters={"resolutionw": 1280, "resolutionh": 720})
+td_create_operator(type="levelTOP", parent="/project1", name="brightness")
+td_create_operator(type="nullTOP", parent="/project1", name="out")
+```
+
+对于批量创建或连线，请使用 `td_execute_python`：
+
+```python
+# td_execute_python script:
+root = op('/project1')
+nodes = []
+for name, optype in [('bg', noiseTOP), ('fx', levelTOP), ('out', nullTOP)]:
+    n = root.create(optype, name)
+    nodes.append(n.path)
+# Wire chain
+for i in range(len(nodes)-1):
+    op(nodes[i]).outputConnectors[0].connect(op(nodes[i+1]).inputConnectors[0])
+result = {'created': nodes}
+```
+
+### 步骤 2：设置参数
+
+优先使用原生工具（会验证参数，不会导致崩溃）：
+
+```
+td_set_operator_pars(path="/project1/bg", parameters={"roughness": 0.6, "monochrome": true})
+```
+
+对于表达式或模式，请使用 `td_execute_python`：
+
+```python
+op('/project1/time_driver').par.colorr.expr = "absTime.seconds % 1000.0"
+```
+
+### 步骤 3：连线
+
+使用 `td_execute_python` —— 不存在原生连线工具：
+
+```python
+op('/project1/bg').outputConnectors[0].connect(op('/project1/fx').inputConnectors[0])
+```
+
+### 步骤 4：验证
+
+```
+td_get_errors(path="/project1", recursive=true)
+td_get_perf()
+td_get_operator_info(path="/project1/out", detail="full")
+```
+
+### 步骤 5：显示 / 捕获
+
+```
+td_get_screenshot(path="/project1/out")
+```
+
+或通过脚本打开一个窗口：
+
+```python
+win = op('/project1').create(windowCOMP, 'display')
+win.par.winop = op('/project1/out').path
+win.par.winw = 1280; win.par.winh = 720
+win.par.winopen.pulse()
+```
+
+## MCP 工具快速参考
+
+**核心（最常使用）：**
+| 工具 | 说明 |
+|------|------|
+| `td_execute_python` | 在 TD 中运行任意 Python。完整的 API 访问权限。 |
+| `td_create_operator` | 创建带有参数并自动定位的节点 |
+| `td_set_operator_pars` | 安全地设置参数（进行验证，不会崩溃） |
+| `td_get_operator_info` | 检查单个节点：连接、参数、错误 |
+| `td_get_operators_info` | 在一次调用中检查多个节点 |
+| `td_get_network` | 查看指定路径的网络结构 |
+| `td_get_errors` | 递归查找错误/警告 |
+| `td_get_par_info` | 获取 OP 类型的参数名称（取代发现过程） |
+| `td_get_hints` | 在构建之前获取模式/提示 |
+| `td_get_focus` | 查看当前打开的网络及选中的内容 |
+
+**读/写：**
+| 工具 | 说明 |
+|------|------|
+| `td_read_dat` | 读取 DAT 文本内容 |
+| `td_write_dat` | 写入/修补 DAT 内容 |
+| `td_read_chop` | 读取 CHOP 通道值 |
+| `td_read_textport` | 读取 TD 控制台输出 |
+
+**视觉：**
+| 工具 | 说明 |
+|------|------|
+| `td_get_screenshot` | 将单个 OP 查看器捕获为文件 |
+| `td_get_screenshots` | 一次捕获多个 OP |
+| `td_get_screen_screenshot` | 通过 TD 捕获实际屏幕 |
+| `td_navigate_to` | 将网络编辑器跳转到某个 OP |
+
+**搜索：**
+| 工具 | 说明 |
+|------|------|
+| `td_find_op` | 跨项目按名称/类型查找 ops |
+| `td_search` | 搜索代码、表达式、字符串参数 |
+
+**系统：**
+| 工具 | 说明 |
+|------|------|
+| `td_get_perf` | 性能分析（FPS、慢速 ops） |
+| `td_list_instances` | 列出所有正在运行的 TD 实例 |
+| `td_get_docs` | 关于 TD 主题的深度文档 |
+| `td_agents_md` | 读取/写入每个 COMP 的 markdown 文档 |
+| `td_reinit_extension` | 编辑代码后重新加载扩展 |
+| `td_clear_textport` | 在调试会话前清空控制台 |
+
+**输入自动化：**
+| 工具 | 说明 |
+|------|------|
+| `td_input_execute` | 向 TD 发送鼠标/键盘指令 |
+| `td_input_status` | 轮询输入队列状态 |
+| `td_input_clear` | 停止输入自动化 |
+| `td_op_screen_rect` | 获取节点的屏幕坐标 |
+| `td_click_screen_point` | 点击屏幕截图中的某个点 |
+| `td_screen_point_to_global` | 将屏幕截图像素转换为绝对屏幕坐标 |
+
+上表涵盖了典型创意工作流中使用的 32 个工具。其余 4 个工具（`td_project_quit`、`td_test_session`、`td_dev_log`、`td_clear_dev_log`）是管理/开发模式实用程序 —— 有关包含完整参数架构的全部 36 个工具参考，请参见 `references/mcp-tools.md`。
+
+## 关键实现规则
+
+**GLSL 时间：** GLSL TOP 中没有 `uTDCurrentTime`。使用 Values 页面：
+```python
+# 先调用 td_get_par_info(op_type="glslTOP") 确认参数名
+td_set_operator_pars(path="/project1/shader", parameters={"value0name": "uTime"})
+# 然后通过脚本设置表达式：
+# op('/project1/shader').par.value0.expr = "absTime.seconds"
+# 在 GLSL 中：uniform float uTime;
+```
+
+备选方案：使用 `rgba32float` 格式的 Constant TOP（8 位会限制在 0-1，导致着色器冻结）。
+
+**Feedback TOP：** 使用 `top` 参数引用，而不是直接输入连线。"Not enough sources" 会在首次 cook 后解决。出现 "Cook dependency loop" 警告是正常现象。
+
+**分辨率：** 非商业版上限为 1280×1280。请使用 `outputresolution = 'custom'`。
+
+**大型着色器：** 将 GLSL 写入 `/tmp/file.glsl`，然后使用 `td_write_dat` 或 `td_execute_python` 加载。
+
+**顶点/点访问 (TD 2025.32)：** `point.P[0]`, `point.P[1]`, `point.P[2]` —— 而不是 `.x`, `.y`, `.z`。
+
+**扩展：** 在 CONSTANT 模式下，`ext0object` 的格式为 `"op('./datName').module.ClassName(me)"`。使用 `td_write_dat` 编辑扩展代码后，调用 `td_reinit_extension`。
+
+**脚本回调：** 务必通过 `me.parent()` / `scriptOp.parent()` 使用相对路径。
+
+**清理节点：** 在迭代之前始终使用 `list(root.children)` + `child.valid` 检查。
+
+## 录制 / 导出视频
+
+```python
+# via td_execute_python:
+root = op('/project1')
+rec = root.create(moviefileoutTOP, 'recorder')
+op('/project1/out').outputConnectors[0].connect(rec.inputConnectors[0])
+rec.par.type = 'movie'
+rec.par.file = '/tmp/output.mov'
+rec.par.videocodec = 'prores'  # Apple ProRes — 在 macOS 上不受许可证限制
+rec.par.record = True   # start
+# rec.par.record = False  # stop (call separately later)
+```
+
+H.264/H.265/AV1 需要商业许可证。在 macOS 上使用 `prores` 或使用 `mjpa` 作为备选。
+提取帧：`ffmpeg -i /tmp/output.mov -vframes 120 /tmp/frames/frame_%06d.png`
+
+**TOP.save() 不适用于动画** —— 每次捕获的都是相同的 GPU 纹理。务必使用 MovieFileOut。
+
+### 录制前：检查清单
+
+1. **通过 `td_get_perf` 验证 FPS > 0。** 如果 FPS=0，录制内容将为空。参见陷阱 #38-39。
+2. **通过 `td_get_screenshot` 验证着色器输出不是黑色的。** 输出为黑色意味着着色器错误或缺少输入。参见陷阱 #8、#40。
+3. **如果带音频录制：** 提示音频先开始，然后将录制延迟 3 帧。参见陷阱 #19。
+4. **在开始录制之前设置输出路径** —— 在同一个脚本中同时设置两者可能会发生竞态条件。
+
+## 音频反应式 GLSL（经过验证的方法）
+
+### 正确的信号链（2026 年 4 月测试）
+
+```
+AudioFileIn CHOP (playmode=sequential)
+  → AudioSpectrum CHOP (FFT=512, outputmenu=setmanually, outlength=256, timeslice=ON)
+  → Math CHOP (gain=10)
+  → CHOP to TOP (dataformat=r, layout=rowscropped)
+  → GLSL TOP input 1 (spectrum texture, 256x2)
+
+Constant TOP (rgba32float, time) → GLSL TOP input 0
+GLSL TOP → Null TOP → MovieFileOut
+```
+
+### 关键的音频反应规则（经验证）
+
+1. **AudioSpectrum 必须保持开启 TimeSlice。** 关闭 = 处理整个音频文件 → 24000+ 个采样 → CHOP to TOP 溢出。
+2. **通过 `outputmenu='setmanually'` 和 `outlength=256` 手动将 Output Length 设置为 256。** 默认输出 22050 个采样。
+3. **不要使用 Lag CHOP 进行频谱平滑。** Lag CHOP 在 timeslice 模式下运行，会将 256 个采样扩展到 2400+ 个，将所有值平均为接近零（~1e-06）。着色器接收不到任何可用数据。这是测试中导致音频同步失败的头号原因。
+4. **也不要使用 Filter CHOP** —— 频谱数据存在同样的 timeslice 扩展问题。
+5. **如果需要，平滑应在 GLSL 着色器中完成**，通过带有反馈纹理的时间插值来实现：`mix(prevValue, newValue, 0.3)`。这能提供帧完美的同步，且流水线延迟为零。
+6. **CHOP to TOP 的 dataformat = 'r'**，layout = 'rowscropped'。频谱输出为 256x2（立体声）。在 y=0.25 处采样以获取第一个通道。
+7. **Math 的 gain = 10**（不是 5）。原始频谱值在低音范围约为 0.19。10 的增益可为着色器提供可用的 ~5.0 的值。
+8. **不需要 Resample CHOP。** 直接通过 AudioSpectrum 的 `outlength` 参数控制输出大小。
+
+### GLSL 频谱采样
+
+```glsl
+// Input 0 = time (1x1 rgba32float), Input 1 = spectrum (256x2)
+float iTime = texture(sTD2DInputs[0], vec2(0.5)).r;
+
+// Sample multiple points per band and average for stability:
+// NOTE: y=0.25 for first channel (stereo texture is 256x2, first row center is 0.25)
+float bass = (texture(sTD2DInputs[1], vec2(0.02, 0.25)).r +
+              texture(sTD2DInputs[1], vec2(0.05, 0.25)).r) / 2.0;
+float mid  = (texture(sTD2DInputs[1], vec2(0.2, 0.25)).r +
+              texture(sTD2DInputs[1], vec2(0.35, 0.25)).r) / 2.0;
+float hi   = (texture(sTD2DInputs[1], vec2(0.6, 0.25)).r +
+              texture(sTD2DInputs[1], vec2(0.8, 0.25)).r) / 2.0;
+```
+
+完整的构建脚本和着色器代码请参见 `references/network-patterns.md`。
+
+## Operator 快速参考
+
+| 家族 | 颜色 | Python 类 / MCP 类型 | 后缀 |
+|--------|-------|-------------|--------|
+| TOP | 紫色 | noiseTOP, glslTOP, compositeTOP, levelTop, blurTOP, textTOP, nullTOP | TOP |
+| CHOP | 绿色 | audiofileinCHOP, audiospectrumCHOP, mathCHOP, lfoCHOP, constantCHOP | CHOP |
+| SOP | 蓝色 | gridSOP, sphereSOP, transformSOP, noiseSOP | SOP |
+| DAT | 白色 | textDAT, tableDAT, scriptDAT, webserverDAT | DAT |
+| MAT | 黄色 | phongMAT, pbrMAT, glslMAT, constMAT | MAT |
+| COMP | 灰色 | geometryCOMP, containerCOMP, cameraCOMP, lightCOMP, windowCOMP | COMP |
+
+## 安全说明
+
+- MCP 仅在 localhost（端口 40404）上运行。无身份验证 —— 任何本地进程都可以发送命令。
+- `td_execute_python` 以 TD 进程用户的身份，对 TD Python 环境和文件系统拥有不受限制的访问权限。
+- `setup.sh` 会从官方 404zero.com URL 下载 twozero.tox。如有顾虑，请验证下载内容。
+- 该技能绝不会将数据发送到 localhost 之外。所有 MCP 通信都是本地的。
+
+## 参考
+
+| 文件 | 内容 |
+|------|------|
+| `references/pitfalls.md` | 来自真实会话的来之不易的经验教训 |
+| `references/operators.md` | 所有 operator 家族及其参数和用例 |
+| `references/network-patterns.md` | 方法方案：音频反应、生成式、GLSL、实例化 |
+| `references/mcp-tools.md` | 完整的 twozero MCP 工具参数架构 |
+| `references/python-api.md` | TD Python：op()、脚本编写、扩展 |
+| `references/troubleshooting.md` | 连接诊断、调试 |
+| `references/glsl.md` | GLSL uniforms、内置函数、着色器模板 |
+| `references/postfx.md` | 后期特效：泛光、CRT、色差、反馈发光 |
+| `references/layout-compositor.md` | HUD 布局模式、面板网格、BSP 风格布局 |
+| `references/operator-tips.md` | 线框渲染、Feedback TOP 设置 |
+| `references/geometry-comp.md` | Geometry COMP：实例化、POP 与 SOP、变形 |
+| `references/audio-reactive.md` | 音频频段提取、节拍检测、包络跟踪 |
+| `references/animation.md` | LFO、计时器、关键帧、缓动、表达式驱动的运动 |
+| `references/midi-osc.md` | MIDI/OSC 控制器、TouchOSC、多机同步 |
+| `references/particles.md` | POP 和旧版 particleSOP —— 发射、力、碰撞 |
+| `references/projection-mapping.md` | 多窗口输出、边角锁定、网格变形、边缘融合 |
+| `references/external-data.md` | HTTP、WebSocket、MQTT、Serial、TCP、webserverDAT |
+| `references/panel-ui.md` | 自定义参数、面板 COMP、按钮/滑块/字段、panelExecuteDAT |
+| `references/replicator.md` | replicatorCOMP —— 数据驱动的克隆、布局、回调 |
+| `references/dat-scripting.md` | Execute DAT 家族 —— chop/dat/parameter/panel/op/executeDAT |
+| `references/3d-scene.md` | 灯光装置、阴影、IBL/立方体贴图、多相机、PBR |
+| `scripts/setup.sh` | 自动化安装脚本 |
+
+---
+
+> 你不是在编写代码。你是在指挥光。

package/extensions/skills/builtin/creative/touchdesigner-mcp/references/3d-scene.md

@@ -0,0 +1,275 @@
+# 3D 场景参考
+
+灯光阵列、阴影、IBL/cubemaps、多相机以及 PBR 材质。关于线框渲染和 feedback TOP，请参阅 `operator-tips.md`。关于实例化几何体，请参阅 `geometry-comp.md`。关于 shader 代码，请参阅 `glsl.md`。
+
+---
+
+## 3D 场景结构剖析
+
+```
+[Geometry COMP]    ← contains SOPs (the shapes)
+[Material]         ← Phong/PBR/GLSL/Constant MAT
+[Light COMPs]      ← point/directional/spot/area/environment
+[Camera COMP]      ← view position, FOV
+        │
+        ▼
+   [Render TOP]    ← combines geo + lights + camera into a 2D image
+        │
+        ▼
+   [post-FX chain] ← bloomTOP, glsl shaders, etc.
+        │
+        ▼
+   [windowCOMP]    ← actual display
+```
+
+Render TOP 是核心。它接收一个明确的 `geometry` 路径、一个明确的 `camera` 路径，并通过 lights 表格或 envlight 引用来获取灯光。
+
+---
+
+## 最小场景
+
+```python
+# Geometry
+geo = root.create(geometryCOMP, 'scene_geo')
+sphere = geo.create(sphereSOP, 'shape')
+sphere.par.rad = 1.0; sphere.par.rows = 64; sphere.par.cols = 64
+
+# Material — start with PBR
+mat = root.create(pbrMAT, 'mat')
+mat.par.basecolorr = 0.7; mat.par.basecolorg = 0.7; mat.par.basecolorb = 0.7
+mat.par.metallic = 0.0
+mat.par.roughness = 0.4
+
+geo.par.material = mat.path
+
+# Camera
+cam = root.create(cameraCOMP, 'cam1')
+cam.par.tx = 0; cam.par.ty = 0; cam.par.tz = 4
+cam.par.fov = 45
+cam.par.near = 0.1; cam.par.far = 100
+
+# Key light
+key = root.create(lightCOMP, 'key_light')
+key.par.lighttype = 'point'
+key.par.tx = 3; key.par.ty = 3; key.par.tz = 3
+key.par.dimmer = 1.5
+
+# Render
+render = root.create(renderTOP, 'render1')
+render.par.outputresolution = 'custom'
+render.par.resolutionw = 1920; render.par.resolutionh = 1080
+render.par.camera = cam.path
+render.par.geometry = geo.path
+render.par.lights = key.path                 # single light path; for multi, see below
+render.par.bgcolorr = 0; render.par.bgcolorg = 0; render.par.bgcolorb = 0
+```
+
+对于多个灯光，请将 `par.lights` 留空 —— Render TOP 默认会扫描网络以获取所有的 `lightCOMP` 和 `envlightCOMP` ops。若要限制为特定灯光，请设置 `par.lights = '/project1/key_light /project1/fill_light'`（路径以空格分隔）。
+
+---
+
+## 灯光类型
+
+| 类型 | 说明 | 常用参数 |
+|---|---|---|
+| `point` | 全向发光，随距离衰减 | `dimmer`, `coneangle` (不适用), `attenuation` |
+| `directional` | 平行射线，无限距离（如太阳） | `dimmer`，仅旋转角度有效 |
+| `spot` | 锥形，随距离和角度衰减 | `coneangle`, `conedelta`, `dimmer` |
+| `cone` | 类似 spot，但边缘更锐利 | 同上 |
+| `area` | 矩形柔光光源 | `sizex`, `sizey` |
+
+所有类型通用参数：`colorr`, `colorg`, `colorb`, `tx/ty/tz`, `rx/ry/rz`, `dimmer`。
+
+### 三点照明（Studio 配置）
+
+```python
+# Key — main light, ~45° front
+key = root.create(lightCOMP, 'key')
+key.par.lighttype = 'point'
+key.par.tx = 4; key.par.ty = 3; key.par.tz = 4
+key.par.dimmer = 1.5
+key.par.colorr = 1.0; key.par.colorg = 0.95; key.par.colorb = 0.85
+
+# Fill — softer, opposite side
+fill = root.create(lightCOMP, 'fill')
+fill.par.lighttype = 'area'
+fill.par.tx = -4; fill.par.ty = 2; fill.par.tz = 3
+fill.par.dimmer = 0.5
+fill.par.colorr = 0.7; fill.par.colorg = 0.8; fill.par.colorb = 1.0
+fill.par.sizex = 4; fill.par.sizey = 4
+
+# Rim/back — outline from behind
+rim = root.create(lightCOMP, 'rim')
+rim.par.lighttype = 'spot'
+rim.par.tx = 0; rim.par.ty = 4; rim.par.tz = -4
+rim.par.coneangle = 30
+rim.par.dimmer = 1.0
+
+# Optional: ambient lift to prevent pure-black shadows
+amb = root.create(ambientlightCOMP, 'ambient')
+amb.par.dimmer = 0.15
+```
+
+---
+
+## 阴影
+
+当 `par.shadowtype != 'none'` 时，Spot 和 directional 灯光会投射阴影。
+
+```python
+key.par.shadowtype = 'softshadow'        # 'none' | 'hardshadow' | 'softshadow'
+key.par.shadowsize = 1024                # shadow map resolution
+key.par.shadowsoftness = 0.02            # softshadow only
+```
+
+**提示：**
+- 软阴影对 GPU 开销极大。初始可设置 `shadowsize = 1024`，仅当在当前分辨率下阴影边缘出现像素化时，再提升至 (2048/4096)。
+- 将 spot light 的 `near`/`far` 设置为刚好包含场景即可。范围过大会浪费阴影贴图精度。
+- 多个投射阴影的灯光会使开销成倍增加。在实时项目中应限制在 1-2 个；其余的可预先烘焙到材质中。
+
+---
+
+## 基于图像的照明 (IBL) / 环境光
+
+为了获得逼真的 PBR 材质，你需要一个 cubemap 用于反射。
+
+```python
+# Environment light from an HDR
+env = root.create(envlightCOMP, 'env')
+env.par.envmap = '/project1/cube_in'         # path to a TOP that produces a cubemap
+env.par.envlightmap = ...                    # diffuse irradiance map (often same as envmap)
+env.par.dimmer = 1.0
+
+# Cubemap source — option A: built-in cubeTOP from 6 faces
+cube = root.create(cubeTOP, 'cube_in')
+# (assign 6 face TOPs)
+
+# Option B: HDR equirectangular → cubemap conversion
+# Use a moviefileinTOP loading .hdr or .exr, then projectTOP type='cubemapfromequirect'
+hdr = root.create(moviefileinTOP, 'hdr_src')
+hdr.par.file = '/path/to/environment.hdr'
+
+proj = root.create(projectTOP, 'cube_proj')
+proj.par.projecttype = 'cubemapfromequirect'
+proj.inputConnectors[0].connect(hdr)
+```
+
+当场景中存在 `envlightCOMP` 时，PBR 材质会自动对环境进行采样。请使用 `td_get_par_info(op_type='envlightCOMP')` 验证参数名称 —— 不同的 TD 版本可能会有所差异。
+
+---
+
+## PBR Material 配置
+
+```python
+mat = root.create(pbrMAT, 'pbr_metal')
+mat.par.basecolorr = 0.95; mat.par.basecolorg = 0.65; mat.par.basecolorb = 0.4
+mat.par.metallic = 1.0
+mat.par.roughness = 0.25
+mat.par.specularlevel = 0.5
+mat.par.emitcolorr = 0; mat.par.emitcolorg = 0; mat.par.emitcolorb = 0
+
+# Texture maps
+mat.par.basecolormap = '/project1/textures/albedo'         # TOP path
+mat.par.metallicroughnessmap = '/project1/textures/mr'      # G=roughness, B=metallic (glTF convention)
+mat.par.normalmap = '/project1/textures/normal'
+mat.par.emitmap = '/project1/textures/emit'
+mat.par.occlusionmap = '/project1/textures/ao'
+```
+
+**常见材质设定：**
+
+| 外观 | metallic | roughness | basecolor |
+|---|---|---|---|
+| 拉丝钢 | 1.0 | 0.4 | (0.7, 0.7, 0.7) |
+| 抛光金 | 1.0 | 0.1 | (1.0, 0.85, 0.4) |
+| 塑料 | 0.0 | 0.5 | 中等饱和度 |
+| 橡胶 | 0.0 | 0.9 | 深色 |
+| 玻璃 | 0.0 | 0.05 | (1, 1, 1)，低 alpha + transmission |
+| 发光体 | 0.0 | 1.0 | 深色，高 `emitcolor` |
+
+对于玻璃/透射效果，近期的 TD 版本在 PBR 中支持 `transmission`；较旧版本需要使用 glslMAT。
+
+---
+
+## 多相机设置
+
+用于对比视图、即时回放、多屏映射等。
+
+```python
+# Camera A — main scene
+cam_a = root.create(cameraCOMP, 'cam_main')
+cam_a.par.tz = 5
+
+# Camera B — orbiting top-down
+cam_b = root.create(cameraCOMP, 'cam_top')
+cam_b.par.ty = 6; cam_b.par.rx = -90
+
+# Render each via separate Render TOPs
+render_a = root.create(renderTOP, 'render_main')
+render_a.par.camera = cam_a.path
+render_a.par.geometry = geo.path
+
+render_b = root.create(renderTOP, 'render_top')
+render_b.par.camera = cam_b.path
+render_b.par.geometry = geo.path
+```
+
+通过 `multiplyTOP`/`compositeTOP` 将两者合成以实现画中画效果，或者分别路由到独立的 `windowCOMP` 以实现多屏显示。
+
+### 相机动画
+
+通过表达式（环绕轨道）、animationCOMP（路径点）或 LFO（震荡）来驱动相机参数：
+
+```python
+# Orbiting camera
+cam_a.par.tx.mode = ParMode.EXPRESSION
+cam_a.par.tx.expr = "cos(absTime.seconds * 0.3) * 6"
+cam_a.par.tz.mode = ParMode.EXPRESSION
+cam_a.par.tz.expr = "sin(absTime.seconds * 0.3) * 6"
+cam_a.par.lookat = '/project1/scene_geo'        # auto-aim at target
+```
+
+`par.lookat` 是最简单的“始终看向目标”机制。
+
+### 景深
+
+当 `par.dof = 'on'` 时，PBR + Render TOP 支持 DOF。
+
+```python
+render.par.dof = 'on'
+render.par.focusdistance = 5.0
+render.par.aperture = 0.05         # blur strength
+render.par.bokehshape = 'hexagon'
+```
+
+DOF 对 GPU 消耗很大。建议以较低分辨率渲染然后再放大，以提高性能。
+
+---
+
+## 常见陷阱
+
+1. **Render TOP 显示为纯黑** —— 最常见原因：没有灯光。即使使用 PBR，你也需要至少一个 `lightCOMP` 或 `envlightCOMP`。建议添加一个低 `dimmer` 的 `ambientlightCOMP` 作为保障。
+2. **材质不显示** —— `geo.par.material` 必须是代表路径的字符串，而不是材质 op 本身。请使用 `mat.path`，而不是 `mat`。
+3. **灯光被忽略** —— Render TOP 默认会拾取网络中的所有 `lightCOMP`。如果有其他场景遗留的灯光，它们也会混入其中。需显式设置 `par.lights`。
+4. **PBR 看起来很扁平** —— 如果没有提供反射的 `envlightCOMP`，PBR 材质看起来会像 Phong。即使没有 HDR，也应添加一个（可使用 `constantTOP` cubemap 作为替代方案）。
+5. **阴影条纹/阴影痤疮** —— 适当增加 `par.shadowbias`。需针对每个灯光进行微调。
+6. **相机位于几何体内部** —— 如果 `cam.par.tz` 位于球体内部，你看到的是内部（如果背面被剔除则什么也看不到）。请将相机向外移动。
+7. **灯光范围太小** —— point light 具有隐式衰减。距离较远的几何体接收到的光照很弱。请增加 `par.dimmer` 或将灯光移近。
+8. **多个相机冲突** —— 一个 render TOP 只能对应一个相机。不要尝试共享。请使用多个 render TOP。
+9. **坐标系错误** —— TD 采用右手坐标系，Y 轴朝上。从 Z 轴朝上软件导入的资源需要在 geo COMP 上进行 90° 的 X 轴旋转。
+10. **性能开销预算** —— 在现代 GPU 上，1080p60 分辨率下运行 PBR + IBL + 阴影 + DOF 是没问题的，但 4K + 4 灯光 + 软阴影 + DOF 会导致性能暴跌。请通过 `td_get_perf` 分析性能，并在添加更多效果前降低设置。
+
+---
+
+## 快速参考配方
+
+| 目标 | 配方 |
+|---|---|
+| 影棚肖像 | 三点照明 (key + fill + rim) + ambient + PBR mat + DOF |
+| 户外日光 | 一个 directional `lightCOMP`（太阳）+ envlight（天空 HDR）+ 软阴影 |
+| 戏剧性 / 黑色电影风 | 从上方侧边照射的单个 spot light，硬阴影，深 ambient = 0.05 |
+| 抽象 / 梦幻风 | 多个 area light 处于低 `dimmer`，无阴影，`bloomTOP` 后期处理 |
+| 产品渲染 | 三点照明 + IBL + 中性 PBR + `bgcolorr=g=b=1`（纯白无缝背景）|
+| 游戏风格 | Phong MAT + 1-2 个灯光 + 无 IBL + 平滑 ambient（开销低，风格化）|
+| 线框 + 实体 | 两个 render TOP（一个配 wireframeMAT，一个配 PBR），通过 `addTOP` 合成 |
+| 环绕相机 | `par.lookat` + 在 tx/tz 上使用 sin/cos 表达式 |