Create optical flow
create_optical_flowCreate a CPU-based motion-energy field from a video source using frame differencing. Outputs a single-channel grayscale TOP where brightness denotes motion against a mid-grey still background; optional edge mode enhances motion near edges.
Instructions
Build a CPU motion-energy field from a video source (cheap drop-in for displacement / particle chains; NOT a real dense optical-flow solver). Output is a single-channel TOP: bright = motion, mid-grey = still, computed as gain × (current − previous luminance) + 0.5. In direction_from='edges' mode the result is multiplied by a Sobel edge map for a coarse where-is-motion-relative-to-edges estimate — still not a true dx/dy gradient flow. No CUDA, no external models — built entirely from stock TD TOPs: blurTOP (pre-blur), monochromeTOP, cacheTOP (previous-frame delay), compositeTOP subtract (frame diff), optional edgeTOP cross-multiply, mathTOP (sensitivity gain + 0.5 recenter), feedbackTOP+levelTOP (temporal smoothing). Defaults to TD's bundled Mosaic.mp4 test clip so the chain builds and previews standalone without a live camera (avoids macOS permission modal). Output is a nullTOP. Reads 0 when TD timeline is paused and the source is static — that is correct behavior. Returns a summary plus JSON with node paths, controls, warnings, and an inline preview image.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| name | No | Name of the container COMP created under parent_path. | optical_flow |
| parent_path | No | Parent COMP path the optical flow container is created inside. | /project1 |
| source | No | Absolute path of a TOP to analyze for motion (pulled in via selectTOP so it can live anywhere). Omit to use TD's bundled Mosaic.mp4 test clip so the chain previews standalone without a live camera (avoids macOS permission hang). | |
| resolution | No | Output resolution [width, height] in pixels. Default is half-HD — CPU optical flow is bandwidth-bound; larger resolutions are slower. | |
| sensitivity | No | Multiplier on the raw frame difference (before the 0.5 recenter). Higher values pick up subtler motion (and more noise). Maps to mathTOP gain. | |
| smoothing | No | Temporal smoothing on the flow output (feedbackTOP cross-fade). 0 = raw per-frame flow (jittery); 1 = ghosted/laggy. | |
| blur | No | Spatial pre-blur (pixels) on source before differencing — suppresses high-frequency camera noise. Maps to blurTOP size. | |
| direction_from | No | 'diff' (default, cheapest): scalar frame-difference luminance (temporal motion energy). 'edges': cross frame-diff with Sobel edgeTOP for a coarse where-is-motion-relative-to-edges estimate — more flow-like but still a scalar, not a dx/dy vector, and ~2× cost. | diff |