TD Watercolor 2

TouchDesigner · GLSL · one component, watercolor2.tox · TouchDesigner 2023+ (built on 2025.33230) · NVIDIA GPU for moving shots · available on Gumroad

A watercolour that paints itself from footage or a still. It is not a blur-and-feedback look: the picture is the painter, and a small fluid simulation on paper does the rest. Pigment and water move only on wet paper, dry at their own pace, pool at the edges of a wash, settle into the valleys of the paper and stay where they dried. On a moving camera shot the painting travels with the footage and repaints itself where it no longer matches.

Version 2 puts everything into one component: the paint mask, a new colour stage, the simulation and the export, with a single parameter interface. This page explains the watercolour ideas the effect is built on, lists every control page by page, gives the settings that worked best in our tests, and the steps to render a video or save a still. It does not assume you know the first version; if you do, see What is new in version 2 first.

What is new in version 2

The painting itself has not changed: with the default settings the output of watercolor2.tox is pixel-identical to the first version (checked against the version 1 still rig: 0 of 4.2 million pixels differ at frames 60 and 240). What changed is everything around it.

• One component instead of two. TD Watercolor (version 1) came as prep.tox + wc_engine.tox plus a separate rig for saving stills. watercolor2.tox contains the paint mask (the old prep), the simulation and the export in one Base COMP, and every control is on its parameter pages. Inputs: 1 paint (footage or still), 2 motion (optional: clean, un-zoomed footage for the optical flow), 3 paper (optional: a paper scan; or set Paper → Paper file). Output: the painting, 16-bit float RGBA.
• Color page (new). Input black / Input white / Gamma / Brightness / Contrast / Saturation / Hue shift / Output black / Output white, applied to the masked picture before it is painted. The paint mask (the alpha) is never changed by it. While every control is neutral the stage is bypassed, which is why the default output stays identical to version 1.
• Export page (new). Save still writes OUT to Still file (.tif / .exr / .png, the frame number appended when Add frame number to the still is on). Record video writes Video file with the chosen Video codec (ProRes by default); Unique suffix avoids overwriting, Stop at the end of the timeline ends the recording by itself.
• System page. Reset (hold) and Reset at timeline start (frames 1-2), on by default, so every render starts from clean paper. No more Reset expression to type in. Width / Height / Sim FPS are gone from the interface: the simulation follows the resolution of input 1 and the project frame rate. The pressure solver runs a fixed 20 iterations.
• Presets page. Load / Save JSON presets, relative to the project folder (presets/…). Six presets ship with the component; version 1 presets load as well (they are converted on load).
• Mask noise. The noise controls of the paint mask have their own page, Mask noise (Noise amount, Noise scale, Noise drift, Seed), so they no longer clash with the water's turbulence and the system seed.

Watercolour in a nutshell

The controls are named after what a watercolourist does. These are the ideas behind them, and where each one lives in the effect.

Paint is transparent: why everything goes light to dark

Watercolour has no white paint. Light passes through the pigment, bounces off the paper and passes through the pigment again. Two layers on top of each other always make a darker colour, like two sheets of tinted glass, so you can darken a painting but you cannot really lighten it. The whites of a watercolour are bare paper that was never painted. This is why a painter works from light to dark and plans the whites from the start.

The effect works the same way. It thinks in optical density: how much light a layer of pigment swallows. Densities add up, light gets multiplied (the Beer–Lambert law), and the painting can only get darker where pigment lands. In the effect the whites come from the paint mask (the Mask page): what the mask leaves out stays bare paper.

Wash

A wash is a layer of diluted paint laid over an area in one go, while it is wet. Inside a wash the colour is smooth, and its look comes from what happens at the edges and while it dries.

Glaze

A glaze is a transparent wash laid over an earlier one after that has dried. The new layer does not mix with the old one; it sits on top and darkens it like a filter. Painters build a picture from a few glazes: a light first glaze for the overall colour, then darker ones only where the picture needs more depth. Where a glaze ends on dry paper it leaves a crisp edge, so a stack of glazes shows layered, hard-edged shapes.

In the effect, Progress runs from 0 to 1 and lays down Glazes (3) one after the other. Each glaze is a wet front that sweeps across the frame. The first one may only reach a light density (First glaze max density), later ones get darker, and a later glaze only wets the paper where the picture still has to get darker. That gives the layered, hard-edged shapes of real glazing.

Where the wet front goes first. By default a noise pattern decides which areas a glaze reaches first, so the first washes appear as random, cloud-like patches. With Glaze order from the picture the footage decides instead: either the shapes of the paint mask grow from their core outwards, or the light areas are reached first, as a painter lays down the light and works around it. The finished painting is the same; the way it comes into being is different.

Wet-in-wet and wet-on-dry

Paint dropped into wet paper spreads softly and blends: wet-in-wet. Paint laid on dry paper stays where it is and keeps a hard edge: wet-on-dry. Most of a watercolour's character is the mix of soft and hard edges.

In the effect, how far paint can move depends on how much water is on the paper (Mobility starts at water, Full mobility at water). Wet paper lets pigment bleed and flow; on dry paper it stops. A dry neighbour acts as a wall.

Blooms and backruns

When water runs back into a wash that is already drying, it pushes the pigment outwards and leaves a pale centre with a ragged, darker rim: a bloom (also called a backrun or cauliflower). Painters fear and love it.

In the effect: Wet to dry push (water flows from wet towards dry paper) and Uneven paper sizing (some spots dry later than others).

Edge darkening

While a wash dries, the water flows towards its edge and carries pigment with it, so the border of a dried wash is darker than its middle, like a coffee ring.

In the effect: Edge darkening and Edge radius on the Look page.

Granulation

Some pigments are made of heavier grains. They do not stay suspended; they sink into the valleys of the paper and give a speckled, sandy texture.

In the effect: Granulation (the look) and Settle in valleys (pigment settles faster in the paper's valleys).

Lifting

A wet brush or a damp tissue can pick pigment back up, even after it has dried, as long as it has not stained the paper. This is how painters soften an edge or pull a highlight back out.

In the effect: Lift wet pigment and Lift dried pigment. On moving shots this is also how the painting lightens areas where the footage got brighter.

Paper and sizing

Watercolour paper is textured. Cold-press paper has a bumpy surface; the bumps catch the brush (dry-brush strokes skip the peaks), and the valleys collect granulating pigment. Sizing is the glue in and on the paper that controls how fast it absorbs water; uneven sizing makes some spots dry later, which causes blooms.

In the effect: the Paper page (procedural cold-press paper, or your own scan on input 3 or from Paper file), Dry brush, Uneven paper sizing, Fibre feathering.

Optical flow (moving shots)

A painting on paper does not move, but a camera does. Optical flow measures, for every pixel, where it moved between two frames. The effect uses it to carry the wet and the dried paint along with the footage, and repaints the areas that no longer match.

How it works

One frame, in order:

1. Mask (the pages Mask, Mask noise and Edge) turns the picture into a paint mask: a luminance threshold (lights, darks or both), broken by noise, with a feathered, torn frame border. The colour passes through untouched; the mask travels in the alpha channel.
2. Color grades the masked picture: levels, gamma, brightness, contrast, saturation and hue. Only the colour channels change; the alpha, the mask, is taken from before the grade. While every control is neutral this stage is skipped.
3. source is the painter: it converts the graded picture into a target pigment density and decides where the wet brush is this frame.
4. velocity → divergence → pressure (×20) → project is a small 2D fluid at a quarter of the resolution. Water only moves where the paper is wet.
5. state is the wet layer (mobile pigment and water), fixed the dry layer (pigment that has settled into the paper).
6. display turns density into colour on paper (Beer–Lambert), with edge darkening, granulation, paper relief and a wet sheen. This is OUT, the output of the component, and what the Export page saves.

With a moving camera the painting is carried along by the footage's optical flow, and repaint dabs freshen up the areas where it no longer matches the video.

Using watercolor2.tox

watercolor2.tox is self-contained: the shaders are embedded, it does not need any file next to it except the optional presets/ folder and your paper scan. Drag it into a network, connect the footage to input 1, and play the timeline. A README DAT inside lists the inputs and a quick start.

Inputs

1. paint: the footage or still that becomes the painting. The simulation runs at its resolution and at the project frame rate, so set the project frame rate to the frame rate of the footage.
2. motion (optional): the footage the optical flow is computed from. Feed it the clean, un-zoomed footage. When nothing is connected, input 1 is used.
3. paper (optional): a paper scan or photo (16:9), used when Paper → Use paper input is on. When input 3 is empty, Paper → Paper file is used instead.

Output: the painting, 16-bit float RGBA.

Quick start

1. Connect the footage to input 1.
2. Mask page: Paint coverage decides how much of the picture gets paint; the rest stays bare paper. View mask shows it.
3. Color page: levels, gamma, contrast, saturation and hue of the masked picture before it is painted. The mask itself is never changed by it.
4. Paint → Progress runs 0 → 1 and lays the glazes down. By default it is an expression over the timeline (150 frames). System → Reset at timeline start restarts the painting on frames 1–2, so every render starts from clean paper.
5. Export page: Save still writes OUT to Still file; Record video writes Video file while the timeline plays.
6. Presets page: load one of the shipped presets, or save your own.

Two things to know: System → Always cook steps the simulation every frame even when nothing displays it; leave it on. The optical flow (Flow page) needs an NVIDIA GPU; without it the flow is black and the painting sticks to the frame. Stills work on any GPU.

The pages below follow the order the picture passes through: the mask, the colour grade, the painting, the export. On the component the tabs run Paint · Water · Pigment · Look · Paper · Flow · Mask · Mask noise · Edge · Color · Export · System · Presets.

Mask: the paint mask

The mask decides where the paper stays white. A painter leaves the lightest parts of a subject unpainted; the mask does the same with a threshold on the picture's brightness. Everything outside the mask stays bare paper, soft mask values give a thinner wash, and a torn, feathered border keeps the painting from running to the frame edge, like a sketch on a larger sheet.

Why a fixed threshold is not enough. A drone shot goes from a bright sunset sea to a dark jungle. One fixed cut would punch 90 % of one scene and 20 % of the other. Paint coverage asks for a share of the frame instead, and the cut is recomputed every frame.

Auto threshold works on the pixel ranking. "Paint 30 % of the frame" depends only on which pixels are darker than which. A gamma or contrast change keeps that ranking, so the cut simply moves with it and the mask stays the same. This is also why the Color page does not move the mask: it changes the colours that get painted, not where. To shape the mask by hand, turn Auto threshold off and set the thresholds.

Two keys. One threshold paints one end of the tones. On a waterfall shot, painting only the darks (coverage 0.45) melted the waterfall, the mist and most of the cliff into one bare-paper hole. With Key mix 0.5 and an opposite coverage of 0.15 the waterfall, the mist and the foam got a mask too, the mid-tone cliff opened up, and the waterfall read as a shape again (painted area 26 % → 37 %). Being white, these areas only receive a pale wash.

Mask noise

Noise that breaks the mask edge into brush-like shapes. In version 1 these lived on the Noise page of prep; they have their own page now so that they do not clash with the water's Turbulence and the system Seed.

Edge

The component zooms the paint input (Flow → Zoom) before the mask, so the border stays inside the final frame.

Color

New in version 2. A colour grade on the masked picture, applied before it is painted: the painter mixes different colours, but paints the same shapes. Inside, a Level TOP (black and white points, gamma, brightness, contrast) and an HSV Adjust TOP (saturation, hue) work on the colour channels only; the alpha, the paint mask, is taken from before the grade, so the mask never changes.

While every control is at its neutral value the stage is bypassed altogether, and the output is identical to version 1. (Even a neutral HSV round trip would add about 0.0005 of rounding; the bypass avoids it.)

Remember how the painter reads the picture. The painter converts brightness into pigment density: a pixel of Paper colour becomes bare paper, darker pixels become denser pigment. So Brightness and Output white change how much pigment goes down overall, much like Density gain and Max density on the Paint page do, but with the colours of a graded picture. Pushing Contrast darkens the shadows into heavy washes and lifts the lights towards bare paper.

With Auto threshold on, the Color page does not move the mask. The mask follows the ranking of the pixels, and the controls only change the colours that get painted. To change where the paper stays white, use Paint coverage and Key mix on the Mask page.

Paint

This page is the painter's plan: in how many glazes the picture goes down, how dark each may be, in what order the brush reaches the areas, and, on moving shots, how the painting is repainted where it no longer matches the footage.

Water

The water is the life of a watercolour. Here you set how much water the brush carries, how long the paper stays wet, how far and how wildly the paint flows while it is wet, and how the paper takes the water in.

Water on a still vs. a moving shot. The livelier water of the video preset (turbulence 0.15, vorticity 2, gravity −0.04, damping 0.8) works on video because repainting keeps pulling the picture back to the footage. On a still nothing pulls it back, and within ten seconds the water stirs everything into marbled swirls. Use the defaults above for stills.

Pigment

What the pigment does once it is on the paper: how fast it reaches its colour, how it settles into the paper as the water dries, and how it can be lifted again.

Look

How the pigment on the paper is shown: how dark and transparent the paint looks, how much the edges and the paper texture show.

Paper

Flow (moving shots)

Why the flow is cleaned (measured). Compared with phase correlation on the footage, the NVIDIA flow is right on average but full of per-pixel outliers, up to 250 px per frame where the real motion is 3–23 px. Clamping them shoved whole blocks of paint (staircase artefacts). Rejecting outliers and averaging over cells cut the per-pixel flow error from 6.2 px to 3.7 px and removed the blocks. Blurring the flow did not help: it smeared the outliers instead of dropping them.

Export

New in version 2: the still and the video export are on the component, so no Movie File Out has to be built outside it. Both save OUT, the finished painting.

System

Not on the page any more: the width, height and time step follow input 1 and the project frame rate, and the pressure solver runs a fixed 20 iterations.

Presets

A preset is a JSON file that stores every control except the Presets and Export pages and Reset: fixed values under values, expressions (such as the Progress animation) under expressions. Controls that a preset does not contain keep their current value when it is loaded. Presets of version 1 (with their wc_engine and prep sections) load as well; the renamed mask-noise controls are converted on the way.

Shipped presets (in presets/):

Recommended settings

The two starting points are video_export.json and still_x3.json; load them on the Presets page. The table lists what they set differently from the defaults.

How they were chosen. For video we measured how recognisable the picture stays (correlation of output and footage luminance, frames 100–700): a hand-tuned set 0.58, the still-image look on its own 0.55, the same with paint coverage 0.45 0.64. Calmer water also gave 0.64, so the bolder flow stayed. Very dark scenes (a cliff wall in shadow) wash into a dark blot with every setting.

For the still we compared variants by eye against the traits above: bare-paper whites, transparent layers, soft and hard edges, no black, no rainbow fringes.

Rendering a video

1. Realtime off: untick Realtime in the top bar. In realtime TouchDesigner skips frames when it falls behind, and the simulation steps with the wrong time.
2. The footage's Movie File In → Play Mode: Locked to Timeline. The timeline runs from 1 to the length of the clip; the project frame rate matches the footage.
3. Load presets/video_export.json, or your own preset.
4. Reset is automatic at timeline frames 1–2 (System → Reset at timeline start).
5. Export page: set Video file and Video codec (ProRes by default). Keep Unique suffix and Stop at the end of the timeline on, so nothing is overwritten and the recording ends with the clip. For an image sequence save stills instead (below), or record with the Animation codec.
6. Set the timeline to play once instead of looping, so it stops at the last frame.
7. Timeline to frame 1, Record video on, Play. The recording stops by itself at the end of the timeline; turn Record video off afterwards.

Repeatable renders: the shaders take their time from the timeline, and the automatic threshold does not carry smoothing over from a previous run. Two renders of frame 60 differed in 55 of two million pixels (0.003 %, scattered): GPU and optical-flow noise, invisible.

Tuning in realtime is fine: keep the footage on Locked to Timeline and let the timeline loop, so the automatic Reset always falls on the start of the clip. With a Sequential movie the clip runs independently of the timeline, and the Reset would restart the painting in the middle of the shot.

Saving a still

1. Connect the image (a Movie File In with the still) to input 1. The simulation runs at the image's own resolution.
2. Load presets/still_x3.json (no flow, no repaint, calm water). Presets never touch Always cook, Reset or the Export page.
3. Timeline to frame 1, Play. Progress lays down three glazes over 150 frames; by about frame 240 the paint has dried. Pause there.
4. Export → Save still. The file goes to Still file, with the frame number appended when Add frame number to the still is on, for example render/watercolor2_still_0240.tif. Status shows the path. Use .tif or .exr for a 16-bit master.

Troubleshooting

• The mask does not change when I adjust the key: check Bypass, then Auto threshold (with it on, the Color page and gamma have no effect on the mask), then Key mix (at 0 the opposite key is not used).
• The Color page changes the colours but not the shapes: that is by design. The mask is taken from before the grade. Change where the paper stays white on the Mask page.
• The painting sticks to the frame on a moving shot: Painting follows footage is off, or the optical flow is black because there is no NVIDIA GPU.
• Staircase blocks at the frame edges: the flow. Keep Flow limit and Flow cell on; raise Flow cell for looser motion.
• Ghosting, the painting lags and jumps: the component is not stepping every frame. Turn Always cook on.
• Everything turns to grey mud on a moving shot: Flow scale is wrong (it must be around 72 for the Optical Flow TOP), or Forget dried pigment is 0.
• The first seconds look dimmed and frozen: the reveal is too long for a moving shot. Let Progress run over about 24 frames.
• The painting restarts in the middle of the shot: the footage is on Sequential play mode, so the clip and the timeline are out of step. Use Locked to Timeline, or turn Reset at timeline start off.
• Rainbow fringes: lower Colour separation.
• Blobs that pop in and out: repaint dabs. Try Repaint dab structure between 0 and 1 and watch it play; a still frame does not tell.
• The paper scan is barely visible: Use paper input on, Scan colour 1, Scan contrast 1.5–3. With nothing on input 3, set Paper file.
• Save still does nothing: look at Status on the Export page. no still file set means Still file is empty.
• A preset loads with "unknown" values: the file came from version 1 or from another build and has controls this component does not have. The rest is applied.

How it was made

TD Watercolor 2 is a research project in painting animation: how a watercolour comes into being on paper, re-created as a process rather than as a filter. The simulation follows published computer-graphics research on fluids and on watercolour rendering (below), and the paint-handling rules come from the way a painter works: light before dark, whites kept as bare paper, glazes over dry layers. The implementation — the twelve GLSL shaders, the TouchDesigner network and the Python around them — was written from scratch for this component, with AI-assisted coding under the author's direction, and tuned in measured tests on real footage and stills.

The component is not locked: the shaders and the scripts are readable inside, so it can be studied and built upon. Its use is covered by the license in the package (personal and commercial use in your own work; no redistribution or resale of the component itself).

Research and references

• J. Stam, Stable Fluids, SIGGRAPH 1999 — the semi-Lagrangian fluid solver the water uses (advection, pressure projection with Jacobi iterations).
• C. Curtis, S. Anderson, J. Seims, K. Fleischer, D. Salesin, Computer-Generated Watercolor, SIGGRAPH 1997 — the three-layer model (shallow water, pigment deposition, capillary layer), edge darkening, granulation, backruns and the optical compositing of glazes.
• S. Montesdeoca et al., Art-directed watercolor stylization of 3D animations in real-time, Computers & Graphics 2017 — real-time watercolour effects (bleeding, edge darkening, paper distortion) and how to make them art-directable.
• J. Whitaker, inkwash (source) — a wetness-driven ink simulation; the idea that water is the permission for pigment to move.
• Beer–Lambert law — pigment layers multiply light, which is why glazes only darken.
• TouchDesigner references: touchFluid (a 2D fluid solver in TD) and the elekktronaut Watercolors tutorial (the blur-and-feedback look this component deliberately does not use).