Authoring guide Script FX

Purpose

Script FX runs a Python function per frame, using GPU tensors in a shared Python process. Use it for an image effect you can write in Python or to run a Python model. Face Track, Optical Flow, Track Anything, Video Depth, Portrait Rig and Stream Diffusion use Script FX sources with their model providers.

Use

Place Script FX from the Image view of the Voro menu, under Voro. The docked DAT script_fx_source is the source. Wire an image into image, edit process(ctx), press Reload. ctx.inputs and ctx.outputs are the node’s ports by name. Declare PARAMS at the top of the source and each row becomes a parameter.

This source halves RGB while preserving alpha. Paste it into the DAT and Reload:

def process(ctx):
    image = ctx.inputs['image']
    out = ctx.outputs['out']
    out.copy_(image)
    out[..., :3].mul_(0.5)

Change 0.5 to 1.0 and Reload to return to the input brightness. Write the result into ctx.outputs['out']; returning a tensor from the function does not fill the output.

Inputs and outputs

• image, required. The frame to process.
• field, optional. A two-channel field for scripts that read it.
• out. The processed frame.

Controls

• Reload compiles the candidate. The node switches to it only after it has produced a frame; until then the previous good script keeps running.
• Declared PARAMS appear as parameters and apply on the next frame.

Notes

• The example edits the output tensor after copying the input. Keep input tensors unchanged when writing your own effect.

Ports

Inputs

• image image required
  RGBA
• field image
  2 channels

Outputs

• out image
  RGBA

Parameters

Script

Script (Scriptdat) Str op('script_fx').par.Scriptdat

Default:

"" (Empty String)

Reload (Reload) Pulse op('script_fx').par.Reload

Default:

None

Script Revision (Scriptrevision) Int op('script_fx').par.Scriptrevision

Default:

0

Range:

0 to 2147483600