feat(skills): add Tier A references — external-data, panel-ui, replicator, dat-scripting, 3d-scene
Five additional reference docs covering common TD use cases that were not yet documented in any reference (operators.md lists the ops, but no usage patterns). - external-data.md: webDAT, webclientDAT, webserverDAT, websocketDAT, mqttClientDAT, serialDAT, tcpipDAT — auth, polling, push, JSON parsing - panel-ui.md: custom parameter pages, button/slider/field/list COMPs, containerCOMP layouts, panelExecuteDAT callbacks - replicator.md: replicatorCOMP for data-driven cloning, per-row overrides, recreatemissing pattern, replicator vs Python loop - dat-scripting.md: full Execute DAT family — chopExecuteDAT, datExecuteDAT, parameterExecuteDAT, panelExecuteDAT, opExecuteDAT, executeDAT lifecycle - 3d-scene.md: light types, three-point rigs, shadows, IBL/cubemaps, PBR materials with idiom table, multi-camera, DOF Same conventions as existing refs: code-first, verify param names with td_get_par_info, no token-budget impact (load on demand).
This commit is contained in:
SHL0MS
@@ -343,6 +343,11 @@ See `references/network-patterns.md` for complete build scripts + shader code.
|
||||
| `references/midi-osc.md` | MIDI/OSC controllers, TouchOSC, multi-machine sync |
|
||||
| `references/particles.md` | POPs and legacy particleSOP — emission, forces, collisions |
|
||||
| `references/projection-mapping.md` | Multi-window output, corner pin, mesh warp, edge blending |
|
||||
| `references/external-data.md` | HTTP, WebSocket, MQTT, Serial, TCP, webserverDAT |
|
||||
| `references/panel-ui.md` | Custom params, panel COMPs, button/slider/field, panelExecuteDAT |
|
||||
| `references/replicator.md` | replicatorCOMP — data-driven cloning, layouts, callbacks |
|
||||
| `references/dat-scripting.md` | Execute DAT family — chop/dat/parameter/panel/op/executeDAT |
|
||||
| `references/3d-scene.md` | Lighting rigs, shadows, IBL/cubemaps, multi-camera, PBR |
|
||||
| `scripts/setup.sh` | Automated setup script |
|
||||
|
||||
---
|
||||
|
||||
275
skills/creative/touchdesigner-mcp/references/3d-scene.md
Normal file
275
skills/creative/touchdesigner-mcp/references/3d-scene.md
Normal file
@@ -0,0 +1,275 @@
|
||||
# 3D Scene Reference
|
||||
|
||||
Lighting rigs, shadows, IBL/cubemaps, multi-camera, and PBR materials. For wireframe rendering and feedback TOPs see `operator-tips.md`. For instancing geometry see `geometry-comp.md`. For shader code see `glsl.md`.
|
||||
|
||||
---
|
||||
|
||||
## Anatomy of a 3D Scene
|
||||
|
||||
```
|
||||
[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 is the heart. It takes an explicit `geometry` path, an explicit `camera` path, and lights via the lights table or an envlight reference.
|
||||
|
||||
---
|
||||
|
||||
## Minimal Scene
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
For multiple lights, leave `par.lights` blank — Render TOP scans the network for all `lightCOMP` and `envlightCOMP` ops by default. To restrict to specific lights, set `par.lights = '/project1/key_light /project1/fill_light'` (space-separated paths).
|
||||
|
||||
---
|
||||
|
||||
## Light Types
|
||||
|
||||
| Type | What | Common params |
|
||||
|---|---|---|
|
||||
| `point` | Omnidirectional, falls off with distance | `dimmer`, `coneangle` (n/a), `attenuation` |
|
||||
| `directional` | Parallel rays, infinite distance (sun) | `dimmer`, light's rotation only matters |
|
||||
| `spot` | Cone, falls off with distance + angle | `coneangle`, `conedelta`, `dimmer` |
|
||||
| `cone` | Like spot but harder edge | same |
|
||||
| `area` | Rectangular soft light source | `sizex`, `sizey` |
|
||||
|
||||
For all: `colorr`, `colorg`, `colorb`, `tx/ty/tz`, `rx/ry/rz`, `dimmer`.
|
||||
|
||||
### Three-Point Lighting (Studio Setup)
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Shadows
|
||||
|
||||
Spot and directional lights cast shadows when `par.shadowtype != 'none'`.
|
||||
|
||||
```python
|
||||
key.par.shadowtype = 'softshadow' # 'none' | 'hardshadow' | 'softshadow'
|
||||
key.par.shadowsize = 1024 # shadow map resolution
|
||||
key.par.shadowsoftness = 0.02 # softshadow only
|
||||
```
|
||||
|
||||
**Tips:**
|
||||
- Soft shadows are GPU-expensive. Start with `shadowsize = 1024` and only go higher (2048/4096) if shadow edges look pixelated at your resolution.
|
||||
- Set the spot light's `near`/`far` to JUST contain the scene. Wider range = wasted shadow map precision.
|
||||
- Multiple shadow-casting lights compound cost. Limit to 1-2 in real-time work; pre-bake the rest into the materials.
|
||||
|
||||
---
|
||||
|
||||
## Image-Based Lighting (IBL) / Environment Light
|
||||
|
||||
For realistic PBR materials you need a cubemap for reflections.
|
||||
|
||||
```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)
|
||||
```
|
||||
|
||||
PBR materials sample the environment automatically when `envlightCOMP` is in the scene. Verify param names with `td_get_par_info(op_type='envlightCOMP')` — TD versions vary.
|
||||
|
||||
---
|
||||
|
||||
## PBR Material Setup
|
||||
|
||||
```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'
|
||||
```
|
||||
|
||||
**Material idioms:**
|
||||
|
||||
| Look | metallic | roughness | basecolor |
|
||||
|---|---|---|---|
|
||||
| Brushed steel | 1.0 | 0.4 | (0.7, 0.7, 0.7) |
|
||||
| Polished gold | 1.0 | 0.1 | (1.0, 0.85, 0.4) |
|
||||
| Plastic | 0.0 | 0.5 | mid-saturated |
|
||||
| Rubber | 0.0 | 0.9 | dark |
|
||||
| Glass | 0.0 | 0.05 | (1, 1, 1), low alpha + transmission |
|
||||
| Glowing emitter | 0.0 | 1.0 | dark, high `emitcolor` |
|
||||
|
||||
For glass/transmission, recent TD versions support `transmission` in PBR; older versions need glslMAT.
|
||||
|
||||
---
|
||||
|
||||
## Multi-Camera Setups
|
||||
|
||||
For comparison views, instant replay, multi-screen mapping, etc.
|
||||
|
||||
```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
|
||||
```
|
||||
|
||||
Composite both with a `multiplyTOP`/`compositeTOP` for picture-in-picture, or route to separate `windowCOMP`s for multi-display.
|
||||
|
||||
### Camera animation
|
||||
|
||||
Drive camera params via expressions (orbit), animationCOMP (waypoint), or LFO (oscillation):
|
||||
|
||||
```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` is the simplest "always look at target" mechanism.
|
||||
|
||||
### Depth of field
|
||||
|
||||
PBR + Render TOP supports DOF when `par.dof = 'on'`.
|
||||
|
||||
```python
|
||||
render.par.dof = 'on'
|
||||
render.par.focusdistance = 5.0
|
||||
render.par.aperture = 0.05 # blur strength
|
||||
render.par.bokehshape = 'hexagon'
|
||||
```
|
||||
|
||||
DOF is GPU-heavy. Render at lower res then upscale for performance.
|
||||
|
||||
---
|
||||
|
||||
## Common Pitfalls
|
||||
|
||||
1. **Render TOP shows black** — most common cause: no light. Even with PBR you need at least one `lightCOMP` or `envlightCOMP`. Add an `ambientlightCOMP` at low dimmer as a safety net.
|
||||
2. **Material doesn't appear** — `geo.par.material` must be a string PATH, not the material op itself. Use `mat.path`, not `mat`.
|
||||
3. **Lights ignored** — by default Render TOP picks up ALL `lightCOMP`s in the network. If you have leftover lights from another scene, they leak in. Set `par.lights` explicitly.
|
||||
4. **PBR looks flat** — without an `envlightCOMP` providing reflections, PBR materials look like Phong. Add one even if you don't have an HDR (use a `constantTOP` cubemap as fallback).
|
||||
5. **Shadow acne / striping** — increase `par.shadowbias` slightly. Tune per-light.
|
||||
6. **Camera inside geometry** — if `cam.par.tz` is INSIDE a sphere, you see the inside (or nothing if backface culled). Move the camera further out.
|
||||
7. **Light range too small** — point lights have implicit attenuation. Far-away geometry receives little light. Increase `par.dimmer` or move lights closer.
|
||||
8. **Multiple cameras conflict** — one render TOP = one camera. Don't try to share. Use multiple render TOPs.
|
||||
9. **Wrong handedness** — TD is right-handed Y-up. Imported assets from Z-up apps (Blender, Maya in Z-up) need a 90° X rotation on the geo COMP.
|
||||
10. **Cooking budget** — PBR + IBL + shadows + DOF at 1080p60 is fine on modern GPUs but 4K + 4 lights + soft shadows + DOF will tank. Profile via `td_get_perf` and downgrade settings before adding more.
|
||||
|
||||
---
|
||||
|
||||
## Quick Recipes
|
||||
|
||||
| Goal | Recipe |
|
||||
|---|---|
|
||||
| Studio portrait | 3-point rig (key + fill + rim) + ambient + PBR mat + DOF |
|
||||
| Outdoor daylight | One directional `lightCOMP` (sun) + envlight (sky HDR) + soft shadows |
|
||||
| Dramatic / film noir | Single spot light from upper side, hard shadows, deep ambient = 0.05 |
|
||||
| Abstract / dreamy | Multiple area lights at low dimmer, no shadows, `bloomTOP` post |
|
||||
| Product render | Three-point + IBL + neutral PBR + `bgcolorr=g=b=1` (white seamless) |
|
||||
| Game-style | Phong MAT + 1-2 lights + no IBL + flat ambient (cheap, stylized) |
|
||||
| Wireframe + solid | Two render TOPs (one with wireframeMAT, one with PBR), composite via `addTOP` |
|
||||
| Orbiting camera | `par.lookat` + expressions on tx/tz using sin/cos |
|
||||
352
skills/creative/touchdesigner-mcp/references/dat-scripting.md
Normal file
352
skills/creative/touchdesigner-mcp/references/dat-scripting.md
Normal file
@@ -0,0 +1,352 @@
|
||||
# DAT-Based Scripting Reference
|
||||
|
||||
TD's event/callback model — Python that runs in response to network events. The full set of "Execute DATs" plus their idiomatic patterns.
|
||||
|
||||
For arbitrary Python execution (not callback-based), see `python-api.md`. For the MCP's `td_execute_python` tool, see `mcp-tools.md`.
|
||||
|
||||
---
|
||||
|
||||
## The Execute DAT Family
|
||||
|
||||
Every type watches one kind of event source and fires Python on changes.
|
||||
|
||||
| DAT | Watches | Use for |
|
||||
|---|---|---|
|
||||
| `chopExecuteDAT` | A CHOP's channel values | Audio triggers, threshold callbacks, state machines on numeric input |
|
||||
| `datExecuteDAT` | A DAT's content (table cells, text) | Reacting to data updates from APIs, parsing webDAT responses |
|
||||
| `parameterExecuteDAT` | A parameter's value or pulse | Reacting to user-changed params, custom pulse buttons |
|
||||
| `panelExecuteDAT` | A panel COMP's interaction | Button clicks, slider drags, field commits |
|
||||
| `opExecuteDAT` | Operator lifecycle | New operator created, deleted, name changed |
|
||||
| `executeDAT` | Project lifecycle, frame events | Run-once setup, per-frame logic, save/load hooks |
|
||||
|
||||
All have a docked DAT with predefined callback functions. You only fill in the bodies of the ones you care about.
|
||||
|
||||
---
|
||||
|
||||
## chopExecuteDAT — Numeric Triggers
|
||||
|
||||
```python
|
||||
ce = root.create(chopExecuteDAT, 'kick_handler')
|
||||
ce.par.chop = '/project1/audio/out_kick' # source CHOP
|
||||
ce.par.offtoon = True # fire when channel rises above 0
|
||||
ce.par.ontooff = False
|
||||
ce.par.whileon = False
|
||||
ce.par.valuechange = False
|
||||
```
|
||||
|
||||
In the docked callback DAT:
|
||||
|
||||
```python
|
||||
def offToOn(channel, sampleIndex, val, prev):
|
||||
"""Channel went from 0 to non-zero. Classic beat trigger."""
|
||||
op('/project1/strobe').par.flash.pulse()
|
||||
op('/project1/scene').par.index = (op('/project1/scene').par.index + 1) % 8
|
||||
return
|
||||
|
||||
def onToOff(channel, sampleIndex, val, prev):
|
||||
"""Channel went from non-zero to 0."""
|
||||
return
|
||||
|
||||
def whileOn(channel, sampleIndex, val, prev):
|
||||
"""Fires every frame while channel is non-zero. Use sparingly."""
|
||||
return
|
||||
|
||||
def valueChange(channel, sampleIndex, val, prev):
|
||||
"""Fires every frame the value changes (continuous). Heavy."""
|
||||
return
|
||||
```
|
||||
|
||||
`channel` is a `Channel` object — `.name`, `.owner`, `.vals[]`. Use `channel.name == 'chan1'` to filter.
|
||||
|
||||
**Threshold-based custom triggers:** wire the source CHOP through a `triggerCHOP` first to get clean 0/1 pulses, then watch with `offtoon`.
|
||||
|
||||
---
|
||||
|
||||
## datExecuteDAT — Table/Text Changes
|
||||
|
||||
```python
|
||||
de = root.create(datExecuteDAT, 'api_response')
|
||||
de.par.dat = '/project1/api/web1' # source DAT
|
||||
de.par.tablechange = True # any cell change
|
||||
de.par.cellchange = False
|
||||
de.par.rowchange = False
|
||||
de.par.colchange = False
|
||||
```
|
||||
|
||||
```python
|
||||
def onTableChange(dat):
|
||||
"""Whole table changed (including text DAT content updates)."""
|
||||
if dat.numRows == 0:
|
||||
return
|
||||
# If it's a webDAT response, parse JSON
|
||||
import json
|
||||
try:
|
||||
data = json.loads(dat.text)
|
||||
except json.JSONDecodeError:
|
||||
debug(f'Bad JSON: {dat.text[:100]}')
|
||||
return
|
||||
# Write to a CHOP
|
||||
op('/project1/api_value').par.value0 = float(data.get('count', 0))
|
||||
return
|
||||
|
||||
def onCellChange(dat, cells, prev):
|
||||
"""Specific cells changed."""
|
||||
for cell in cells:
|
||||
# cell.row, cell.col, cell.val
|
||||
pass
|
||||
return
|
||||
```
|
||||
|
||||
`debug()` prints to the textport — readable via `td_read_textport`.
|
||||
|
||||
---
|
||||
|
||||
## parameterExecuteDAT — Param Changes & Pulse
|
||||
|
||||
```python
|
||||
pe = root.create(parameterExecuteDAT, 'comp_params')
|
||||
pe.par.op = '/project1/my_component' # COMP whose params to watch
|
||||
pe.par.parameters = '*' # or specific names like 'Intensity Reset'
|
||||
pe.par.valuechange = True
|
||||
pe.par.pulse = True
|
||||
```
|
||||
|
||||
```python
|
||||
def onValueChange(par, prev):
|
||||
"""par is a Par object. par.name, par.eval(), par.owner."""
|
||||
if par.name == 'Intensity':
|
||||
op('/project1/bloom').par.threshold = par.eval()
|
||||
return
|
||||
|
||||
def onPulse(par):
|
||||
"""Pulse param was triggered."""
|
||||
if par.name == 'Reset':
|
||||
op('/project1/scene').par.index = 0
|
||||
op('/project1/audio_player').par.cuepoint = 0
|
||||
op('/project1/audio_player').par.cuepulse.pulse()
|
||||
return
|
||||
|
||||
def onExpressionChange(par, val, prev):
|
||||
"""User changed the expression on a param."""
|
||||
return
|
||||
|
||||
def onExportChange(par, val, prev):
|
||||
"""Export source changed."""
|
||||
return
|
||||
|
||||
def onModeChange(par, val, prev):
|
||||
"""Param mode changed (CONSTANT / EXPRESSION / EXPORT / etc)."""
|
||||
return
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## panelExecuteDAT — UI Events
|
||||
|
||||
For interactive control surfaces. See `panel-ui.md` for the full panel COMP context.
|
||||
|
||||
```python
|
||||
pe = root.create(panelExecuteDAT, 'btn_handler')
|
||||
pe.par.panel = '/project1/play_btn'
|
||||
pe.par.click = True # mouse click events
|
||||
pe.par.value = True # state changes (toggle)
|
||||
pe.par.lockedchange = False
|
||||
```
|
||||
|
||||
```python
|
||||
def onOffToOn(panelValue):
|
||||
"""Panel value rose to 1 (button pressed, slider crossed threshold)."""
|
||||
op('/project1/scene_timer').par.start.pulse()
|
||||
return
|
||||
|
||||
def onOnToOff(panelValue):
|
||||
"""Panel value dropped to 0."""
|
||||
return
|
||||
|
||||
def onValueChange(panelValue):
|
||||
"""Continuous: every frame the value changes."""
|
||||
val = panelValue.eval()
|
||||
op('/project1/master').par.opacity = val
|
||||
return
|
||||
|
||||
def onClick(panelValue):
|
||||
"""Discrete click event, fires once per click."""
|
||||
return
|
||||
```
|
||||
|
||||
`panelValue` is a `Par` object on the panel COMP.
|
||||
|
||||
---
|
||||
|
||||
## opExecuteDAT — Operator Lifecycle
|
||||
|
||||
Watches creation/deletion/renaming of operators in a parent COMP.
|
||||
|
||||
```python
|
||||
oe = root.create(opExecuteDAT, 'lifecycle')
|
||||
oe.par.op = '/project1'
|
||||
oe.par.create = True
|
||||
oe.par.destroy = True
|
||||
oe.par.namechange = True
|
||||
oe.par.flagchange = False
|
||||
```
|
||||
|
||||
```python
|
||||
def onCreate(opCreated):
|
||||
"""A new operator was created. Useful for auto-applying conventions."""
|
||||
if opCreated.OPType == 'glslTOP':
|
||||
# Always wrap with a null
|
||||
n = opCreated.parent().create(nullTOP, opCreated.name + '_out')
|
||||
n.inputConnectors[0].connect(opCreated)
|
||||
return
|
||||
|
||||
def onDestroy(opDestroyed):
|
||||
"""Operator was deleted. opDestroyed.path is still valid for one frame."""
|
||||
return
|
||||
|
||||
def onNameChange(opChanged):
|
||||
"""Operator was renamed."""
|
||||
return
|
||||
```
|
||||
|
||||
Useful for dev-time scaffolding (auto-create downstream nullTOPs, auto-name conventions). Disable in production projects to avoid surprise side effects.
|
||||
|
||||
---
|
||||
|
||||
## executeDAT — Project Lifecycle & Per-Frame
|
||||
|
||||
The catch-all. Gets you hooks into project start, save, load, frame-start, frame-end.
|
||||
|
||||
```python
|
||||
exec_dat = root.create(executeDAT, 'lifecycle')
|
||||
exec_dat.par.start = True
|
||||
exec_dat.par.create = True
|
||||
exec_dat.par.framestart = True
|
||||
exec_dat.par.frameend = False
|
||||
```
|
||||
|
||||
```python
|
||||
def onStart():
|
||||
"""Project just started cooking. Run once."""
|
||||
op('/project1/scene').par.index = 0
|
||||
debug('Project started')
|
||||
return
|
||||
|
||||
def onCreate():
|
||||
"""Component was just created (only fires for component executeDATs, not project root)."""
|
||||
return
|
||||
|
||||
def onFrameStart(frame):
|
||||
"""Per-frame, BEFORE network cooks. Heavy logic here = bottleneck."""
|
||||
return
|
||||
|
||||
def onFrameEnd(frame):
|
||||
"""Per-frame, AFTER network cooks. Use for capture, recording, post-network logic."""
|
||||
return
|
||||
|
||||
def onPlayStateChange(playing):
|
||||
"""Project play/pause toggled."""
|
||||
return
|
||||
|
||||
def onProjectPreSave():
|
||||
"""Right before saving the .toe file."""
|
||||
return
|
||||
|
||||
def onProjectPostSave():
|
||||
return
|
||||
```
|
||||
|
||||
Heavy per-frame logic in `onFrameStart` is one of the top performance regressions in TD projects. Use CHOPs for per-frame computation, scripts for events.
|
||||
|
||||
---
|
||||
|
||||
## Pattern: Triggering an Animation Sequence on Beat
|
||||
|
||||
```python
|
||||
# Source: a kick trigger CHOP
|
||||
# Goal: on each kick, run a 1.5s scale pulse + color flash
|
||||
|
||||
# Setup (create once)
|
||||
animator = root.create(timerCHOP, 'pulse_anim')
|
||||
animator.par.length = 1.5
|
||||
animator.par.cycle = False
|
||||
|
||||
# Param expressions on visual targets:
|
||||
op('logo').par.sx.expr = "1.0 + (1 - op('pulse_anim')['timer_fraction']) * 0.3"
|
||||
op('logo').par.sx.mode = ParMode.EXPRESSION
|
||||
op('logo').par.sy.expr = "1.0 + (1 - op('pulse_anim')['timer_fraction']) * 0.3"
|
||||
op('logo').par.sy.mode = ParMode.EXPRESSION
|
||||
|
||||
# In a chopExecuteDAT watching the kick CHOP:
|
||||
def offToOn(channel, sampleIndex, val, prev):
|
||||
op('pulse_anim').par.start.pulse()
|
||||
return
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pattern: Live Editing a CHOP from API Data
|
||||
|
||||
```python
|
||||
# webDAT polls an API every 5 seconds
|
||||
# datExecuteDAT parses the response and writes to a constantCHOP
|
||||
|
||||
def onTableChange(dat):
|
||||
import json
|
||||
try:
|
||||
data = json.loads(dat.text)
|
||||
except:
|
||||
return
|
||||
target = op('/project1/external_state')
|
||||
target.par.name0 = 'temperature'
|
||||
target.par.value0 = float(data['temp_c'])
|
||||
target.par.name1 = 'humidity'
|
||||
target.par.value1 = float(data['humidity'])
|
||||
return
|
||||
```
|
||||
|
||||
Visuals just reference `op('external_state')['temperature']` — they update live.
|
||||
|
||||
---
|
||||
|
||||
## Pattern: Self-Cleaning Network
|
||||
|
||||
```python
|
||||
# An opExecuteDAT watching for orphaned helper ops, deleting them after their parent disappears
|
||||
|
||||
def onDestroy(opDestroyed):
|
||||
parent_name = opDestroyed.name
|
||||
helper = op(f'/project1/{parent_name}_helper')
|
||||
if helper:
|
||||
helper.destroy()
|
||||
return
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pitfalls
|
||||
|
||||
1. **Callbacks crash silently** — exceptions print to the textport but don't show up in the UI. Always `td_clear_textport` before debugging, then `td_read_textport` after.
|
||||
2. **`debug()` vs `print()`** — both write to textport, but `debug()` includes the file/line of the calling DAT. Prefer `debug()` for scripts.
|
||||
3. **`val` is the new value, `prev` is old** — easy to swap. Always: `def offToOn(channel, sampleIndex, val, prev)`. Check parameter order in TD docs if confused.
|
||||
4. **`whileOn` and `valueChange` are per-frame** — heavy. Avoid unless absolutely needed. Drive via expressions instead.
|
||||
5. **Callbacks don't run during cooking-paused state** — if the parent COMP has `allowCooking=False`, callbacks freeze. Useful for "disable me" toggles.
|
||||
6. **`par` vs `panelValue`** — parameterExecuteDAT gives `par` (a Par object), panelExecuteDAT gives `panelValue` (also a Par-like object). Both have `.name` and `.eval()` but their context differs.
|
||||
7. **`opExecuteDAT` fires for itself** — when you create an opExecuteDAT, it can fire `onCreate` for itself if `par.create=True` and parent matches. Filter by `if opCreated == me: return`.
|
||||
8. **Reload behavior** — when reloading an extension (`td_reinit_extension`), all callback DATs reset their internal state. Module-level vars are lost. Persist state in tableDATs or the docked DAT itself, not in module globals.
|
||||
9. **Cooking dependencies** — if a callback writes to an op that's upstream of the callback's source, you get a cooking loop. TD warns about it but doesn't always block. Keep dataflow one-directional.
|
||||
10. **Active flag** — every Execute DAT has `par.active`. False = silent. Easy to toggle for testing without deleting wiring.
|
||||
|
||||
---
|
||||
|
||||
## Quick Recipes
|
||||
|
||||
| Goal | Setup |
|
||||
|---|---|
|
||||
| Beat trigger | `chopExecuteDAT.par.offtoon=True` watching a `triggerCHOP` |
|
||||
| API response handler | `datExecuteDAT.par.tablechange=True` watching a `webDAT` |
|
||||
| Custom button → action | `parameterExecuteDAT.par.pulse=True` watching a custom pulse param |
|
||||
| Slider → continuous param | `panelExecuteDAT.par.value=True` watching a `sliderCOMP` |
|
||||
| Run-once setup | `executeDAT.par.start=True` with logic in `onStart()` |
|
||||
| Per-frame metrics | `executeDAT.par.frameend=True` recording values to a CHOP |
|
||||
| Auto-name new ops | `opExecuteDAT.par.create=True` enforcing naming conventions |
|
||||
322
skills/creative/touchdesigner-mcp/references/external-data.md
Normal file
322
skills/creative/touchdesigner-mcp/references/external-data.md
Normal file
@@ -0,0 +1,322 @@
|
||||
# External Data Reference
|
||||
|
||||
Network and device I/O — HTTP requests, WebSockets, MQTT, Serial, TCP, UDP. For MIDI/OSC specifically see `midi-osc.md`.
|
||||
|
||||
Common production needs:
|
||||
- API polling / webhook ingestion
|
||||
- Real-time data streams (sensors, market data, chat)
|
||||
- IoT device control (Arduino, ESP32, smart lights)
|
||||
- Inter-application messaging
|
||||
- Hosting a tiny TD-side HTTP server for remote control
|
||||
|
||||
---
|
||||
|
||||
## Web DAT — HTTP Requests
|
||||
|
||||
```python
|
||||
web = root.create(webDAT, 'api_call')
|
||||
web.par.url = 'https://api.example.com/v1/status'
|
||||
web.par.fetchmethod = 'get' # 'get' | 'post' | 'put' | 'delete'
|
||||
web.par.format = 'auto' # 'auto' | 'text' | 'json'
|
||||
web.par.timeout = 5.0
|
||||
```
|
||||
|
||||
**Triggering a request:**
|
||||
|
||||
`webDAT` does NOT auto-fetch on cook. Trigger explicitly:
|
||||
|
||||
```python
|
||||
web.par.fetch.pulse()
|
||||
```
|
||||
|
||||
Or via expression on a CHOP value-change (chopExecuteDAT — see `dat-scripting.md`).
|
||||
|
||||
**Authentication headers:**
|
||||
|
||||
Use `webclientDAT` (more flexible) or set `webDAT` headers via the headers DAT:
|
||||
|
||||
```python
|
||||
web_headers = root.create(tableDAT, 'headers')
|
||||
web_headers.appendRow(['Authorization', 'Bearer YOUR_TOKEN'])
|
||||
web_headers.appendRow(['Accept', 'application/json'])
|
||||
web.par.headers = web_headers.path
|
||||
```
|
||||
|
||||
**Parsing JSON response:**
|
||||
|
||||
```python
|
||||
import json
|
||||
|
||||
def onTableChange(dat):
|
||||
response = dat.text # raw response body
|
||||
data = json.loads(response)
|
||||
# Update a tableDAT or store in a constantCHOP for downstream use
|
||||
op('/project1/api_status').par.value0 = data['count']
|
||||
return
|
||||
```
|
||||
|
||||
Wire this in a `datExecuteDAT` watching the webDAT.
|
||||
|
||||
**Polling pattern:**
|
||||
|
||||
```python
|
||||
# timerCHOP fires every N seconds
|
||||
timer = root.create(timerCHOP, 'poll_timer')
|
||||
timer.par.length = 5.0
|
||||
timer.par.cycle = True
|
||||
|
||||
# chopExecuteDAT on the timer's 'cycles' channel pulses the webDAT
|
||||
def offToOn(channel, sampleIndex, val, prev):
|
||||
op('/project1/api_call').par.fetch.pulse()
|
||||
return
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Web Client DAT — More Robust HTTP
|
||||
|
||||
`webclientDAT` is the modern replacement for `webDAT` — supports streaming responses, chunked transfer, custom auth.
|
||||
|
||||
```python
|
||||
client = root.create(webclientDAT, 'api')
|
||||
client.par.method = 'POST'
|
||||
client.par.url = 'https://api.example.com/events'
|
||||
client.par.uploadtype = 'json'
|
||||
client.par.uploaddata = '{"event": "scene_change", "scene": 3}'
|
||||
client.par.request.pulse()
|
||||
```
|
||||
|
||||
Output goes to its child `webclient1_response` DAT. Use a `datExecuteDAT` to react.
|
||||
|
||||
---
|
||||
|
||||
## Web Server DAT — TD as HTTP Server
|
||||
|
||||
Hosts a tiny HTTP server inside TD. Useful for:
|
||||
- Status/health endpoints
|
||||
- Remote control from a phone or another machine
|
||||
- Webhook receivers from external services
|
||||
|
||||
```python
|
||||
server = root.create(webserverDAT, 'control_server')
|
||||
server.par.port = 8080
|
||||
server.par.active = True
|
||||
|
||||
# Define handler in the docked callback DAT
|
||||
```
|
||||
|
||||
In the auto-created `webserver1_callbacks` DAT:
|
||||
|
||||
```python
|
||||
def onHTTPRequest(webServerDAT, request, response):
|
||||
path = request['uri']
|
||||
if path == '/status':
|
||||
response['statusCode'] = 200
|
||||
response['data'] = '{"fps": 60, "scene": "active"}'
|
||||
elif path == '/scene':
|
||||
idx = int(request['args'].get('index', 0))
|
||||
op('/project1/scene_switch').par.index = idx
|
||||
response['statusCode'] = 200
|
||||
response['data'] = 'OK'
|
||||
else:
|
||||
response['statusCode'] = 404
|
||||
response['data'] = 'Not Found'
|
||||
return response
|
||||
```
|
||||
|
||||
Test from terminal: `curl http://localhost:8080/status`.
|
||||
|
||||
**Security:** No auth by default. Bind to localhost only or add a token check in the callback. Never expose to the public internet without auth.
|
||||
|
||||
---
|
||||
|
||||
## WebSocket DAT — Bidirectional Real-Time
|
||||
|
||||
For low-latency bidirectional streams (chat, live data feeds, controllers).
|
||||
|
||||
### Client
|
||||
|
||||
```python
|
||||
ws = root.create(websocketDAT, 'ws_client')
|
||||
ws.par.netaddress = 'wss://api.example.com/socket'
|
||||
ws.par.active = True
|
||||
```
|
||||
|
||||
In the docked callbacks DAT:
|
||||
|
||||
```python
|
||||
def onConnect(dat):
|
||||
dat.sendText('{"action": "subscribe", "channel": "ticks"}')
|
||||
return
|
||||
|
||||
def onReceiveText(dat, rowIndex, message):
|
||||
# message is a string; parse JSON, dispatch to ops
|
||||
import json
|
||||
data = json.loads(message)
|
||||
op('/project1/price_chop').par.value0 = data['price']
|
||||
return
|
||||
|
||||
def onDisconnect(dat):
|
||||
# Optionally schedule a reconnect
|
||||
return
|
||||
```
|
||||
|
||||
### Server
|
||||
|
||||
```python
|
||||
ws = root.create(websocketDAT, 'ws_server')
|
||||
ws.par.mode = 'server'
|
||||
ws.par.port = 9001
|
||||
ws.par.active = True
|
||||
```
|
||||
|
||||
Same callback structure with an additional `clientID` arg.
|
||||
|
||||
---
|
||||
|
||||
## MQTT — Pub/Sub for IoT
|
||||
|
||||
```python
|
||||
mqtt = root.create(mqttClientDAT, 'iot')
|
||||
mqtt.par.brokeraddress = 'broker.hivemq.com'
|
||||
mqtt.par.brokerport = 1883
|
||||
mqtt.par.clientid = 'td_install_01'
|
||||
mqtt.par.connect.pulse()
|
||||
|
||||
# Subscribe in callbacks DAT:
|
||||
def onConnect(dat):
|
||||
dat.subscribe('home/lights/+', qos=1)
|
||||
return
|
||||
|
||||
def onReceive(dat, topic, payload, qos, retained, dup):
|
||||
# payload is bytes — decode if JSON
|
||||
msg = payload.decode('utf-8')
|
||||
# Dispatch by topic
|
||||
return
|
||||
|
||||
# Publish from anywhere:
|
||||
op('iot').publish('show/scene', 'sunset', qos=0, retain=False)
|
||||
```
|
||||
|
||||
For Mosquitto / HiveMQ self-hosted brokers use the same setup with `tcp://192.168.x.x` and your local port.
|
||||
|
||||
---
|
||||
|
||||
## Serial DAT — Arduino, USB Devices
|
||||
|
||||
```python
|
||||
serial = root.create(serialDAT, 'arduino')
|
||||
serial.par.port = '/dev/cu.usbmodem14101' # macOS — check Arduino IDE
|
||||
# Windows: 'COM3', 'COM4', etc.
|
||||
serial.par.baudrate = 115200
|
||||
serial.par.active = True
|
||||
```
|
||||
|
||||
In callbacks:
|
||||
|
||||
```python
|
||||
def onReceive(dat, rowIndex, line):
|
||||
# Each newline-terminated line from Arduino arrives here
|
||||
parts = line.split(',')
|
||||
op('/project1/sensors').par.value0 = float(parts[0])
|
||||
op('/project1/sensors').par.value1 = float(parts[1])
|
||||
return
|
||||
```
|
||||
|
||||
Send to Arduino:
|
||||
```python
|
||||
op('arduino').send('LED_ON\n')
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## TCP/IP DAT — Custom Protocols
|
||||
|
||||
For talking to non-HTTP servers (game servers, custom protocols, legacy systems).
|
||||
|
||||
```python
|
||||
tcp = root.create(tcpipDAT, 'show_control')
|
||||
tcp.par.netaddress = '192.168.1.50'
|
||||
tcp.par.port = 7000
|
||||
tcp.par.protocol = 'tcp' # 'tcp' | 'udp'
|
||||
tcp.par.active = True
|
||||
```
|
||||
|
||||
Send / receive via callbacks similar to websocketDAT.
|
||||
|
||||
For UDP-only (fire-and-forget, no connection), use `udpoutDAT` + `udpinDAT` — simpler but unreliable across networks.
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### REST API → Visual
|
||||
|
||||
```
|
||||
timerCHOP (5s loop)
|
||||
→ chopExecuteDAT (pulse webDAT.par.fetch on cycle)
|
||||
→ webDAT (returns JSON)
|
||||
→ datExecuteDAT (parse, write to constantCHOP)
|
||||
→ CHOP drives glsl uniform → visuals
|
||||
```
|
||||
|
||||
### Webhook receiver
|
||||
|
||||
```
|
||||
webserverDAT (port 8080, /webhook endpoint)
|
||||
→ callback writes to a tableDAT log + triggers a scene change
|
||||
```
|
||||
|
||||
### Real-time stock/crypto ticker
|
||||
|
||||
```
|
||||
websocketDAT (subscribe to feed)
|
||||
→ onReceiveText callback parses JSON
|
||||
→ writes to constantCHOP
|
||||
→ drives bar chart / typography animation
|
||||
```
|
||||
|
||||
### IoT-controlled installation
|
||||
|
||||
```
|
||||
MQTT → callback dispatches by topic
|
||||
→ /lights/main → constantCHOP drives lighting render
|
||||
→ /audio/volume → mathCHOP for master fader
|
||||
```
|
||||
|
||||
### Two-way phone control
|
||||
|
||||
```
|
||||
WebSocket server in TD
|
||||
→ simple HTML page on phone connects, sends slider values
|
||||
→ callback writes to ops
|
||||
→ TD pushes status back via dat.sendText() to phone UI
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Pitfalls
|
||||
|
||||
1. **`webDAT` doesn't auto-fetch** — must explicitly pulse `par.fetch`. Easy to forget.
|
||||
2. **Blocking on slow APIs** — `webDAT` runs on the cook thread. A 30s API call freezes TD for 30s. Use `webclientDAT` (async) for anything potentially slow.
|
||||
3. **WebSocket reconnection** — TD does NOT auto-reconnect on disconnect. Implement backoff in `onDisconnect`.
|
||||
4. **Serial port permissions on macOS** — TD needs Full Disk Access OR the port needs to be unlocked via `sudo chmod 666 /dev/cu.usbmodem...` per session.
|
||||
5. **MQTT broker connection state** — `mqttClientDAT` may show `connected=true` but messages don't flow if QoS is wrong or topic ACL blocks. Check broker logs.
|
||||
6. **JSON parse errors crash callbacks silently** — wrap parses in try/except and log to textport. Otherwise the callback just stops firing.
|
||||
7. **Firewall on Windows** — first time `webserverDAT` binds, Windows pops a firewall dialog. Approve it or the server is unreachable.
|
||||
8. **CORS** — `webserverDAT` doesn't add CORS headers by default. If serving a webapp from a different origin, add `Access-Control-Allow-Origin: *` in the response.
|
||||
9. **Polling vs push** — polling burns API quota. Always prefer WebSocket / webhook / MQTT for high-frequency data.
|
||||
10. **Floating-point parsing** — sensor data over Serial often comes as strings. `float()` will crash on `'\n'` or `'NaN'`. Validate before converting.
|
||||
|
||||
---
|
||||
|
||||
## Quick Recipes
|
||||
|
||||
| Goal | Op chain |
|
||||
|---|---|
|
||||
| Periodic API fetch | `timerCHOP` → `chopExecuteDAT` pulses → `webDAT` → `datExecuteDAT` parses |
|
||||
| Webhook receiver | `webserverDAT` (port + path), callback writes to ops |
|
||||
| Real-time stream | `websocketDAT` client → onReceiveText → CHOP/DAT |
|
||||
| Arduino sensor → visual | `serialDAT` → callback → `constantCHOP` → expression on visual op |
|
||||
| TD ↔ phone control | `websocketDAT` server + simple HTML page on phone |
|
||||
| MQTT IoT integration | `mqttClientDAT` subscribe → callback dispatches by topic |
|
||||
281
skills/creative/touchdesigner-mcp/references/panel-ui.md
Normal file
281
skills/creative/touchdesigner-mcp/references/panel-ui.md
Normal file
@@ -0,0 +1,281 @@
|
||||
# Panel & UI Reference
|
||||
|
||||
Interactive control surfaces inside TouchDesigner — buttons, sliders, fields, custom parameter pages, panel callbacks. For HUD overlays (rendered text on visuals) see `layout-compositor.md`.
|
||||
|
||||
Use cases:
|
||||
- VJ control rack (master fader, scene buttons, FX toggles)
|
||||
- Installation operator console
|
||||
- Self-contained TOX components with their own parameter UIs
|
||||
- Phone-style touch interfaces displayed on a tablet
|
||||
|
||||
---
|
||||
|
||||
## Two Layers of UI
|
||||
|
||||
| Layer | What it is | Use for |
|
||||
|---|---|---|
|
||||
| **Custom Parameters** | Params on any COMP, edited like built-in TD params | Configurable components, presets, "settings" panels |
|
||||
| **Panel COMPs** | Visible widgets (button, slider, field) inside a containerCOMP | Interactive control surfaces, real-time UIs |
|
||||
|
||||
Combine both: build a containerCOMP with panel widgets that read/write custom parameters on a parent component.
|
||||
|
||||
---
|
||||
|
||||
## Custom Parameters
|
||||
|
||||
Add user-editable params to any COMP. Params persist with the COMP, drive expressions, and survive save/reload.
|
||||
|
||||
```python
|
||||
# Add a custom page to a baseCOMP
|
||||
comp = op('/project1/my_component')
|
||||
page = comp.appendCustomPage('Controls')
|
||||
|
||||
# Add typed params
|
||||
page.appendFloat('Intensity', label='Intensity')[0] # returns a Par
|
||||
page.appendInt('Count', label='Count')[0]
|
||||
page.appendToggle('Enabled', label='Enabled')[0]
|
||||
page.appendMenu('Mode', menuNames=['off', 'soft', 'hard'], menuLabels=['Off', 'Soft', 'Hard'])[0]
|
||||
page.appendStr('Title', label='Title')[0]
|
||||
page.appendRGB('Color', label='Color') # returns 3 pars
|
||||
page.appendXY('Offset', label='Offset') # returns 2 pars
|
||||
page.appendPulse('Reset', label='Reset')[0]
|
||||
page.appendFile('TextureFile', label='Texture')[0]
|
||||
```
|
||||
|
||||
**Read/write from anywhere:**
|
||||
|
||||
```python
|
||||
val = op('/project1/my_component').par.Intensity.eval()
|
||||
op('/project1/my_component').par.Intensity = 0.7
|
||||
```
|
||||
|
||||
**Drive other params via expression:**
|
||||
|
||||
```python
|
||||
op('bloom1').par.threshold.mode = ParMode.EXPRESSION
|
||||
op('bloom1').par.threshold.expr = "op('/project1/my_component').par.Intensity"
|
||||
```
|
||||
|
||||
**Pulse handler (Reset button):**
|
||||
|
||||
Use a `parameterExecuteDAT` watching the COMP's pulse params. See `dat-scripting.md`.
|
||||
|
||||
---
|
||||
|
||||
## Panel COMPs — The Widgets
|
||||
|
||||
Each is a COMP that renders as a clickable/draggable widget inside a `containerCOMP`.
|
||||
|
||||
| Type | Type Name | Use |
|
||||
|---|---|---|
|
||||
| Button | `buttonCOMP` | Click action — momentary or toggle |
|
||||
| Slider | `sliderCOMP` | Drag to set 0-1 value (1D or 2D) |
|
||||
| Field | `fieldCOMP` | Text input |
|
||||
| Container | `containerCOMP` | Layout + visual styling, holds children |
|
||||
| Select | `selectCOMP` | Reference and display content from another COMP |
|
||||
| List | `listCOMP` | Scrollable list with row callbacks |
|
||||
|
||||
### Button
|
||||
|
||||
```python
|
||||
btn = root.create(buttonCOMP, 'play_btn')
|
||||
btn.par.w = 120; btn.par.h = 40
|
||||
btn.par.buttontype = 'momentary' # 'momentary' | 'toggleup' | 'togglepress' | 'radio'
|
||||
btn.par.bgcolorr = 0.1; btn.par.bgcolorg = 0.1; btn.par.bgcolorb = 0.1
|
||||
btn.par.text = 'Play'
|
||||
|
||||
# Read state
|
||||
state = btn.panel.state # 1 when active
|
||||
```
|
||||
|
||||
### Slider
|
||||
|
||||
```python
|
||||
sld = root.create(sliderCOMP, 'master_fader')
|
||||
sld.par.w = 60; sld.par.h = 300
|
||||
sld.par.style = 'vertical' # 'vertical' | 'horizontal' | 'xy'
|
||||
sld.par.value0min = 0.0
|
||||
sld.par.value0max = 1.0
|
||||
|
||||
# Drive a parameter via expression (always-on, no callback needed)
|
||||
op('/project1/master_level').par.opacity.mode = ParMode.EXPRESSION
|
||||
op('/project1/master_level').par.opacity.expr = "op('master_fader').panel.u"
|
||||
```
|
||||
|
||||
`panel.u` and `panel.v` give the 0-1 normalized values. For 2D sliders both are populated.
|
||||
|
||||
### Field (Text Input)
|
||||
|
||||
```python
|
||||
fld = root.create(fieldCOMP, 'scene_name')
|
||||
fld.par.w = 200; fld.par.h = 30
|
||||
fld.par.fieldtype = 'string' # 'string' | 'integer' | 'float'
|
||||
|
||||
# Read current text
|
||||
text = fld.panel.field # the text content
|
||||
```
|
||||
|
||||
### List
|
||||
|
||||
For scrollable lists with selectable rows, use the docked `list1_callbacks` DAT to handle row interactions. Set up cells via the `list_definition` table DAT.
|
||||
|
||||
---
|
||||
|
||||
## Container COMP — Layout & Styling
|
||||
|
||||
`containerCOMP` is the primary parent for grouping widgets and arranging layouts.
|
||||
|
||||
```python
|
||||
panel = root.create(containerCOMP, 'control_panel')
|
||||
panel.par.w = 400; panel.par.h = 600
|
||||
panel.par.bgcolorr = 0.05
|
||||
panel.par.bgcolorg = 0.05
|
||||
panel.par.bgcolorb = 0.05
|
||||
panel.par.bgalpha = 1.0
|
||||
|
||||
# Layout child panels in vertical stack
|
||||
panel.par.align = 'lefttoright' # 'lefttoright' | 'toptobottom' | etc.
|
||||
```
|
||||
|
||||
Children are positioned automatically based on `par.align`. For absolute positioning use `par.align = 'fillresize'` and set each child's `par.x` / `par.y`.
|
||||
|
||||
### Layout Strategies
|
||||
|
||||
| `par.align` | Behavior |
|
||||
|---|---|
|
||||
| `lefttoright` | Children stacked horizontally |
|
||||
| `toptobottom` | Children stacked vertically |
|
||||
| `righttoleft` / `bottomtotop` | Reversed stacks |
|
||||
| `fillresize` | Children sized to fill, manual positioning |
|
||||
| `top` / `bottom` / `left` / `right` | Fixed positioning |
|
||||
|
||||
For complex grids: nest containers — vertical container holding horizontal containers.
|
||||
|
||||
---
|
||||
|
||||
## Panel Callbacks — Reacting to Events
|
||||
|
||||
`panelExecuteDAT` watches a panel and fires Python callbacks on user interaction.
|
||||
|
||||
```python
|
||||
pe = root.create(panelExecuteDAT, 'btn_handler')
|
||||
pe.par.panel = '/project1/play_btn'
|
||||
pe.par.click = True # respond to clicks
|
||||
pe.par.value = True # respond to value changes
|
||||
```
|
||||
|
||||
In its docked DAT:
|
||||
|
||||
```python
|
||||
def onOffToOn(panelValue):
|
||||
# Click pressed
|
||||
op('/project1/scene_timer').par.start.pulse()
|
||||
return
|
||||
|
||||
def onOnToOff(panelValue):
|
||||
# Click released
|
||||
return
|
||||
|
||||
def onValueChange(panelValue):
|
||||
# Slider drag, field change, etc.
|
||||
new_val = panelValue.eval()
|
||||
op('/project1/master').par.opacity = new_val
|
||||
return
|
||||
```
|
||||
|
||||
For pulse params on custom-parameter pages, use a `parameterExecuteDAT` instead.
|
||||
|
||||
---
|
||||
|
||||
## Building a Complete VJ Control Panel
|
||||
|
||||
End-to-end pattern:
|
||||
|
||||
```python
|
||||
# 1. Top-level container
|
||||
panel = root.create(containerCOMP, 'vj_control')
|
||||
panel.par.w = 800; panel.par.h = 200
|
||||
panel.par.align = 'lefttoright'
|
||||
|
||||
# 2. Master fader column
|
||||
master_col = panel.create(containerCOMP, 'master')
|
||||
master_col.par.w = 120; master_col.par.h = 200
|
||||
master_col.par.align = 'toptobottom'
|
||||
|
||||
master_label = master_col.create(textTOP, 'lbl')
|
||||
master_label.par.text = 'MASTER'
|
||||
|
||||
master_sld = master_col.create(sliderCOMP, 'fader')
|
||||
master_sld.par.w = 60; master_sld.par.h = 150
|
||||
master_sld.par.style = 'vertical'
|
||||
|
||||
# 3. Scene buttons row
|
||||
scene_col = panel.create(containerCOMP, 'scenes')
|
||||
scene_col.par.w = 400; scene_col.par.h = 200
|
||||
scene_col.par.align = 'lefttoright'
|
||||
for i in range(8):
|
||||
b = scene_col.create(buttonCOMP, f'scene_{i+1}')
|
||||
b.par.w = 50; b.par.h = 50
|
||||
b.par.text = str(i+1)
|
||||
b.par.buttontype = 'radio' # only one active at a time
|
||||
|
||||
# 4. FX toggle column
|
||||
fx_col = panel.create(containerCOMP, 'fx')
|
||||
fx_col.par.w = 280; fx_col.par.h = 200
|
||||
fx_col.par.align = 'toptobottom'
|
||||
for fx in ['Bloom', 'CRT', 'Glitch', 'Strobe']:
|
||||
t = fx_col.create(buttonCOMP, fx.lower())
|
||||
t.par.w = 220; t.par.h = 35
|
||||
t.par.text = fx
|
||||
t.par.buttontype = 'toggleup'
|
||||
|
||||
# 5. Display in a window
|
||||
win = root.create(windowCOMP, 'control_win')
|
||||
win.par.winop = panel.path
|
||||
win.par.winw = 800; win.par.winh = 200
|
||||
win.par.borders = True
|
||||
win.par.winopen.pulse()
|
||||
```
|
||||
|
||||
Then wire panel values to ops via expressions or panelExecuteDATs.
|
||||
|
||||
---
|
||||
|
||||
## Showing the Panel — Window or Embedded
|
||||
|
||||
| Approach | When |
|
||||
|---|---|
|
||||
| `windowCOMP` pointing at panel | Standalone control surface, separate display |
|
||||
| Render the containerCOMP via `renderTOP` | Composite UI over visuals (HUD-style) |
|
||||
| Use a `panelCOMP` directly inside a network editor pane | Designer/dev preview only — panel is fully interactive |
|
||||
|
||||
For a touch-screen tablet, use a `windowCOMP` on a second display routed to the tablet's HDMI input.
|
||||
|
||||
---
|
||||
|
||||
## Pitfalls
|
||||
|
||||
1. **Panel won't respond to clicks** — likely `par.disabled = True` or the parent container has `par.disableinputs = True`. Check the panel hierarchy.
|
||||
2. **Slider value not updating** — `panel.u/v` reads the visual position. If you set `par.value0` directly, the visual lags. Use `par.value0` AS the source of truth and let the slider follow.
|
||||
3. **Custom param won't appear** — must call `appendCustomPage` first, then append params. Pages with no params don't show.
|
||||
4. **Custom param disappears on reload** — params added via Python at runtime persist only if the COMP is saved AFTER. Use a `tox` save (`comp.save('mycomp.tox')`) or commit via `td_execute_python` then save the project.
|
||||
5. **Event callback fires twice** — both `onOffToOn` and `onValueChange` may fire on a single button press. Pick one to handle the action; don't double-trigger.
|
||||
6. **Pulse params need `.pulse()`** — setting `par.X = True` on a pulse param does nothing. Always use `.pulse()`.
|
||||
7. **Field text doesn't commit until Tab/Enter** — fields don't fire callbacks while typing. Use `par.committemode = 'all'` to fire on every keystroke (heavy).
|
||||
8. **`par.text` vs panel content** — `buttonCOMP.par.text` is the LABEL on the button. The button's STATE is `panel.state` (0/1). Don't confuse them.
|
||||
9. **Touch input on macOS** — multi-touch via direct touch panels works but TD's gesture handling is rudimentary. For complex multi-touch (pinch/rotate), use TouchOSC on a tablet instead.
|
||||
10. **Layout doesn't update** — changing `par.align` requires the container to re-cook. Touch a child or pulse the container to trigger.
|
||||
|
||||
---
|
||||
|
||||
## Quick Recipes
|
||||
|
||||
| Goal | Setup |
|
||||
|---|---|
|
||||
| Master fader | `sliderCOMP` (vertical) → expression on `level.par.opacity` |
|
||||
| Scene picker | 8 `buttonCOMP` (radio) → `selectCHOP` on their state → drive `switchTOP.par.index` |
|
||||
| FX toggle | `buttonCOMP` (toggleup) → expression on `bypass` of an FX op |
|
||||
| Numeric input | `fieldCOMP` (float) → expression on target par |
|
||||
| Component settings | Custom params on the component COMP, panel widgets inside drive them |
|
||||
| Touch tablet UI | `containerCOMP` with widgets → `windowCOMP` to second display |
|
||||
| Status display | `textTOP` rendered into the panel via `selectCOMP` |
|
||||
198
skills/creative/touchdesigner-mcp/references/replicator.md
Normal file
198
skills/creative/touchdesigner-mcp/references/replicator.md
Normal file
@@ -0,0 +1,198 @@
|
||||
# Replicator COMP Reference
|
||||
|
||||
The `replicatorCOMP` clones a template operator N times, driven by a table of data. The fundamental TD pattern for data-driven networks: button grids, scene rosters, dynamic UI, parameter panels per-channel.
|
||||
|
||||
For visual instancing (per-pixel/per-render copies), see `geometry-comp.md`. Replicator builds NETWORK NODES; instancing builds RENDER COPIES. Different layer.
|
||||
|
||||
---
|
||||
|
||||
## Concept
|
||||
|
||||
```
|
||||
[Template OP] [Data tableDAT]
|
||||
│ │
|
||||
└─────→ replicatorCOMP ←───────┘
|
||||
│
|
||||
▼
|
||||
[N clones], one per data row
|
||||
Each clone gets per-row params
|
||||
```
|
||||
|
||||
Edit the template once → all clones inherit. Edit the table → clones add/remove dynamically. Push parameter overrides per-row.
|
||||
|
||||
---
|
||||
|
||||
## Minimal Setup
|
||||
|
||||
```python
|
||||
# 1. Make a template (the thing to clone)
|
||||
template = root.create(buttonCOMP, 'btn_template')
|
||||
template.par.w = 80; template.par.h = 80
|
||||
template.par.text = 'X'
|
||||
template.par.bgcolorr = 0.2
|
||||
|
||||
# 2. Make a data table (one row per clone)
|
||||
data = root.create(tableDAT, 'scene_data')
|
||||
data.appendRow(['name', 'color_r', 'color_g', 'color_b'])
|
||||
data.appendRow(['Sunset', 1.0, 0.4, 0.0])
|
||||
data.appendRow(['Midnight', 0.0, 0.1, 0.4])
|
||||
data.appendRow(['Storm', 0.3, 0.3, 0.5])
|
||||
data.appendRow(['Forest', 0.0, 0.5, 0.2])
|
||||
|
||||
# 3. Replicator — points at template + data
|
||||
rep = root.create(replicatorCOMP, 'scene_buttons')
|
||||
rep.par.template = template.path
|
||||
rep.par.opfromdat = data.path
|
||||
rep.par.namefromdatname = 'name' # use 'name' column for clone names
|
||||
rep.par.incrementalnumbering = False
|
||||
```
|
||||
|
||||
After cooking, the replicator creates 4 child COMPs named `Sunset`, `Midnight`, `Storm`, `Forest` (one per non-header row), each cloned from `btn_template`.
|
||||
|
||||
---
|
||||
|
||||
## Per-Row Parameter Overrides
|
||||
|
||||
The replicator's docked `replicator1_callbacks` DAT lets you customize each clone:
|
||||
|
||||
```python
|
||||
def onReplicate(comp, allOps, newOps, template, master):
|
||||
"""Called once per replicate cycle. newOps is the list of just-created clones."""
|
||||
data = op('scene_data')
|
||||
for i, clone in enumerate(newOps):
|
||||
row = i + 1 # +1 to skip header
|
||||
clone.par.text = data[row, 'name'].val
|
||||
clone.par.bgcolorr = float(data[row, 'color_r'].val)
|
||||
clone.par.bgcolorg = float(data[row, 'color_g'].val)
|
||||
clone.par.bgcolorb = float(data[row, 'color_b'].val)
|
||||
return
|
||||
```
|
||||
|
||||
Or use parameter expressions referencing `digits` (the per-clone index, available as a built-in expression token inside the cloned subtree):
|
||||
|
||||
```python
|
||||
# Inside the template, set a param expression like:
|
||||
# par.value0.expr = "op('../scene_data')[me.digits + 1, 'value']"
|
||||
```
|
||||
|
||||
`me.digits` resolves to the row index of the current clone. This is the cleanest way for static reference patterns — no callback needed.
|
||||
|
||||
---
|
||||
|
||||
## Layout: Buttons in a Grid
|
||||
|
||||
Drop the replicator inside a `containerCOMP` with auto-layout:
|
||||
|
||||
```python
|
||||
panel = root.create(containerCOMP, 'scene_panel')
|
||||
panel.par.w = 400; panel.par.h = 100
|
||||
panel.par.align = 'lefttoright'
|
||||
|
||||
# Move the replicator inside
|
||||
rep.parent = panel.path # or create rep as a child of panel directly
|
||||
```
|
||||
|
||||
Each clone is a child of the replicator (which itself is a child of the panel). The panel auto-arranges everything.
|
||||
|
||||
For a 2D grid, set `par.align = 'fillresize'` on the container and override `par.x` / `par.y` per clone in the callback based on row/col index.
|
||||
|
||||
---
|
||||
|
||||
## Updating Without Rebuilding
|
||||
|
||||
When the data table changes, the replicator regenerates the clones. By default it destroys and recreates everything. To preserve state, set:
|
||||
|
||||
```python
|
||||
rep.par.recreatemissing = True # only add/remove changed rows
|
||||
rep.par.recreateallonchange = False
|
||||
```
|
||||
|
||||
This pattern is essential for live-edit scenarios (designer adjusts table, network keeps running).
|
||||
|
||||
For incremental data ingestion (e.g., from a `webDAT` polling an API), have a `datExecuteDAT` watch the response, parse, write to the data table, and the replicator self-updates.
|
||||
|
||||
---
|
||||
|
||||
## Common Patterns
|
||||
|
||||
### Scene Roster (Data → Buttons + Logic)
|
||||
|
||||
```python
|
||||
# Data per scene: name, file path, audio track, BPM
|
||||
scene_data.appendRow(['name', 'file', 'audio', 'bpm'])
|
||||
scene_data.appendRow(['Intro', '/scenes/intro.tox', '/audio/intro.wav', 110])
|
||||
scene_data.appendRow(['Main', '/scenes/main.tox', '/audio/main.wav', 128])
|
||||
|
||||
# Replicator clones a buttonCOMP per scene
|
||||
# Each button's onClick callback loads the corresponding tox + cues audio
|
||||
```
|
||||
|
||||
### Dynamic Parameter Panel
|
||||
|
||||
For a list of audio bands, generate a fader strip per band:
|
||||
|
||||
```python
|
||||
# Data: band names (sub, low, mid, hi-mid, high, air)
|
||||
# Template: containerCOMP with label + sliderCOMP
|
||||
# Replicator clones N strips
|
||||
# Each slider's value is read at /audio_eq/{band_name}/fader
|
||||
```
|
||||
|
||||
### Procedural Visual Network
|
||||
|
||||
Build a multi-channel visual network from a config file:
|
||||
|
||||
```python
|
||||
# Data: which TOPs to chain, per "scene"
|
||||
# Template: a baseCOMP with placeholder children
|
||||
# Replicator builds one baseCOMP per scene; each scene contains a custom chain
|
||||
# Switch between scenes via switchTOP.par.index driven by panel
|
||||
```
|
||||
|
||||
### Per-Channel CHOP Display
|
||||
|
||||
Visualize each channel of a multi-channel CHOP separately:
|
||||
|
||||
```python
|
||||
# Data table: one row per channel (auto-extracted via choptodatDAT)
|
||||
# Template: a small chopVis COMP showing one channel
|
||||
# Replicator generates N visualizers stacked vertically
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## Replicator vs. Pure Python Loop
|
||||
|
||||
| Approach | When to use |
|
||||
|---|---|
|
||||
| **replicatorCOMP** | The set of clones changes (add/remove rows live). Visual editor expectations. Pattern is reusable across projects. |
|
||||
| **Python loop** (in `td_execute_python`) | One-shot generation. Static set. Simpler logic, no template overhead. Faster to write. |
|
||||
|
||||
If you'll only ever build the network once, prefer a Python loop with `td_execute_python`. The replicator earns its weight when data is live.
|
||||
|
||||
---
|
||||
|
||||
## Pitfalls
|
||||
|
||||
1. **Header row** — `tableDAT` rows are 0-indexed. If you have a header, your first data row is index 1. Off-by-one bugs are common in callbacks.
|
||||
2. **`namefromdatname` column missing** — replicator silently uses `digits` (numeric suffix) names. Buttons end up named `1`, `2`, `3` instead of meaningful names. Set `par.namefromdatname` explicitly.
|
||||
3. **Template lives in network** — the template OP is itself a real network node. Don't connect things downstream of it directly; connect to the clones (or use a `nullCOMP` between).
|
||||
4. **Recreate-on-change wipes state** — toggles, slider positions, and uncached data inside clones are lost on each regeneration. Use `recreatemissing` to preserve.
|
||||
5. **`onReplicate` doesn't fire on edit** — only fires when the clone set changes. Editing a value WITHIN an existing row doesn't re-trigger. Use `parameterExecuteDAT` or expressions for per-cell live updates.
|
||||
6. **Custom params on clones** — pages added in the template propagate. Pages added in `onReplicate` don't survive the next regeneration. Always add custom pages on the template, not the clone.
|
||||
7. **Cooking storms** — adding many rows fast triggers many clone events. Bundle adds via Python and call `data.cook(force=True)` once at the end.
|
||||
8. **`me.digits` outside replicator children** — `me.digits` only resolves inside an op that's a descendant of the replicator. Don't reference it in unrelated networks.
|
||||
9. **Cross-clone references** — referencing a sibling clone via relative path works from inside a clone (`op('../OtherClone/x')`), but breaks if names change. Prefer absolute paths via the data table.
|
||||
|
||||
---
|
||||
|
||||
## Quick Recipes
|
||||
|
||||
| Goal | Setup |
|
||||
|---|---|
|
||||
| 8-button scene picker | `tableDAT` (8 rows) + `buttonCOMP` template + `replicatorCOMP` |
|
||||
| Per-band EQ strip panel | `tableDAT` (band names) + container template (label + slider) + replicator |
|
||||
| Data-driven visual scenes | `tableDAT` (scene config) + `baseCOMP` template (visual chain) + replicator |
|
||||
| Live-updating clone set | Same as above + `par.recreatemissing = True` |
|
||||
| Per-row colored UI | Data table with color cols, `onReplicate` callback sets per-clone colors |
|
||||
| List from API response | `webDAT` → `datExecuteDAT` parses JSON → writes to data table → replicator updates |
|
||||
Reference in New Issue
Block a user