TouchDesigner (TD) 全局系统架构与逻辑控制文档

系统版本: v2.5 Live Master 核心控制器: Ableton Push2 & MIDI Foot Controller 通信协议: DMX512 / Art-Net / JSON WebSocket 状态机对齐: SoloEffects.ts

一、系统总体信号链路拓扑 (System Topology)

本工程采用“MIDI 触发门控锁存”、“Push2 8轴物理手感包络算法”与“DMX 8位数值标定输出”三大核心模块并行协同架构：

[MIDI / Ableton 硬件输入 (midiin1)]
       │
       ├─> [门控选择器 (select_long / select_short / select_beam / select_reset / select2)]
       │         │
       │         ▼
       │   [CHOP Execute 事件回调脚本 (chopexec_*)]
       │         │
       │         ▼
       │   [状态锁存与模式切换 (target_* / switch_* / gate_* / override_mode)]
       │         │
       │         ├─> [实时写入通信文件 (send_gates -> Gates.json)]
       │         └─> [音频门控切分 (audio_long / audio_short -> audiodevout*)]
       │
       └─> [Push2 8轴力感打击垫 (final_punch ~ final_float)] (0.0 - 1.0)
                 │
                 ▼
           [Physical Envelope 状态机算法 (beam_pad_effects / Script CHOP)]
                 │
                 ▼ (生成 chan1 ~ chan5 0.0 - 1.0 物理包络)
           [Override 信号融合 (override1 / Override CHOP)]
                 │
                 ▼ (替换 chan1~chan5，透传 chan6~chan13，组合成 13 通道 0.0 - 1.0 信号)
           [DMX 8位数值标定器 (math2: Multiply 255)]
                 │
                 ▼ (转换为 0 - 255 DMX 标准整型)
           [Art-Net / DMX 硬件输出 (dmx_out)] ──> 【现场物理摇摆光束灯 (Beam Light)】

二、核心 Python 脚本与控制逻辑

1. 长/短门控与系统重置控制 (`chopexec_*`)

系统通过 CHOP Execute DAT 监听 MIDI 通道，实现触发锁存、模式 Toggle 及全局复位：

chopexec_long：监听 select_long。检测到上升沿时执行 op('target_long').par.value0 = 1，激活并锁存长门控状态。
chopexec_short：监听 select_short。检测到上升沿时执行 op('target_short').par.value0 = 1，激活并锁存短门控状态。

chopexec_beam：监听 select_beam。实现 Toggle 开关机制：

c = op('target_beam')
c.par.value0 = 1 if c.par.value0 == 0 else 0

chopexec_reset：监听 select_reset。一键复位归零：

op('target_long').par.value0 = 0
op('target_short').par.value0 = 0

chopexec_override：监听 select2。翻转手动覆盖模式状态：
```
c = op('override_mode')
c.par.value0 = 0 if c.par.value0 == 1 else 1
```

2. Push2 8轴手感物理包络算法 (`beam_pad_effects`)

位于 script2_callbacks2 中，负责将 Ableton Push2 的 8 种手感（punch, press, dab, glide, slash, wring, impulse/flick, float）转化为摇摆光束灯的 5 维动态控制信号。

核心算法机制：

去抖与指数级衰减 (`step_pad`)：引入 RELEASE_DEBOUNCE_MS = 70 去抖窗口；基于帧率归一化计算衰减系数 decay = ENV_DECAY ** frames (默认为 0.82)，确保掉帧时包络衰减速度恒定。
5 维光效包络计算 (FX Functions)：
- punch：频闪冲击力包络，产生高频 displacement。
- slash / flick：侧抛与快速甩击，带有高频 Jitter 电机抖动。
- press / glide：缓升 Hold Ramp 压感控制。
- wring：6Hz 摇摆 (Wobble) 与灯珠正反向切换（CH5 正反转）。
- float：正弦波连续漂浮摆动（Sinusoidal Swing）。
多力效融合逻辑：CH3 (调光) / CH4 (频闪) 采用 Max Pooling 机制；CH1 (摇摆) / CH2 (微调) 采用 Vector Sum 矢量叠加机制。

3. 数据同步与发送 (`send_gates`)

实时轮询并把当前的 Gate 状态（gate_long / gate_short）打包为 JSON 格式，写入外部通信文件 Gates.json，与前端墙面视觉系统（如 SoloEffects.ts）保持毫秒级同步。

三、 DMX 输出链与数值标定 (DMX Output Chain & Channel Map)

来自上游处理完毕的 13 通道归一化灯光控制信号（0.0 ~ 1.0）在输出前的处理逻辑与标定映射如下：

override1 (Override CHOP)：将 Script CHOP 计算好的 chan1 ~ chan5 覆盖替换回主线，同时透传 chan6 ~ chan13。
math2 (Math CHOP)：Multiply = 255，将 0.0 ~ 1.0 浮点数精准映射标定为 DMX512 标准协议要求的 8位整型区间 (0 ~ 255)。

DMX 通道	信号来源	原始数值范围	Math2 标定	最终 DMX 值	物理灯具控制功能描述
chan1	beam_pad_effects	0.0 ~ 1.0	× 255	0 ~ 255 (中点 127.5)	Pan 水平摇摆行程（0.5 对应物理居中）
chan2	beam_pad_effects	0.0 ~ 1.0	× 255	0 ~ 255 (中点 127.5)	Pan Fine 微调/高频 Jitter
chan3	beam_pad_effects	0.0 ~ 1.0	× 255	0 ~ 255	Dimmer 总调光亮度（0 为关，255 为最亮）
chan4	beam_pad_effects	0.0 ~ 1.0	× 255	0 ~ 255	Strobe 频闪速率（灯具硬件频闪发生器）
chan5	beam_pad_effects	0.25 / 0.75	× 255	64 / 191	Motor Dir 电机转向（<128 正转，>128 反转）
chan6	beam_channels (透传)	0.0 ~ 1.0	× 255	0 ~ 255	Color Macro 色彩宏/前景色选色表
chan7	beam_channels (透传)	0.0 ~ 1.0	× 255	0 ~ 255	Gobo 图案片选择/旋转
chan8	beam_channels (透传)	0.0 ~ 1.0	× 255	0 ~ 255	Prism 棱镜展开/旋转
chan9	beam_channels (透传)	1.0 (基准)	× 255	255	Red 红色通道（满功率输出）
chan10	beam_channels (透传)	1.0 (基准)	× 255	255	Green 绿色通道（满功率输出）
chan11	beam_channels (透传)	1.0 (基准)	× 255	255	Blue 蓝色通道（满功率输出）
chan12	beam_channels (透传)	1.0 (基准)	× 255	255	White 白色通道（满功率输出）
chan13	beam_channels (透传)	0.0 (基准)	× 255	0 ~ 255	Lamp Control / Reset 复位与控制宏

四、控制节点功能对照表 (Control Reference)

节点名称	节点类型	监听/上游输入	核心动作 / 参数设置	功能描述
`midiin1`	MIDI In CHOP	外部 MIDI 硬件 / Ableton	Note / CC 信号分发	全局 MIDI 信号总入口
`chopexec_long`	CHOP Exec DAT	`select_long`	`target_long.par.value0 = 1`	单次长门控激活与锁存
`chopexec_short`	CHOP Exec DAT	`select_short`	`target_short.par.value0 = 1`	单次短门控激活与锁存
`chopexec_beam`	CHOP Exec DAT	`select_beam`	`target_beam.par.value0` Toggle	Beam 光束开启/关闭切换
`chopexec_reset`	CHOP Exec DAT	`select_reset`	`target_long` / `target_short` 归 0	全局门控紧急复位重置
`chopexec_override`	CHOP Exec DAT	`select2`	`override_mode.par.value0` Toggle	手动覆盖模式开关切换
`beam_pad_effects`	Script CHOP	`final_*` 8轴 CHOP	Python 8力感物理包络算法	生成 `chan1`~`chan5` 归一化动作包络
`math2`	Math CHOP	`override1`	`Multiply = 255`	归一化信号转 8 位 DMX 标准值 (0-255)
`dmx_out`	DMX Out CHOP	`math2`	DMX / Art-Net 协议打包发送	物理网络发送至摇摆光束灯具

一、 系统总体信号链路拓扑 (System Topology)

二、 核心 Python 脚本与控制逻辑