FFmpeg Floodfill Filter: Coordinates and Tolerance

This guide explains how to define the starting coordinates for FFmpeg's floodfill filter and how color matching functions during processing. While FFmpeg provides direct parameters for target coordinates, managing color tolerance requires specific handling due to the filter's exact-match design.

Configuring Start Coordinates

The floodfill filter identifies the region to fill by using a starting seed coordinate defined by the x and y parameters. The coordinate system begins at (0,0), which corresponds to the top-left corner of the video frame.

To specify the starting location, supply the x and y pixel positions:

ffmpeg -i input.mp4 -vf "floodfill=x=150:y=200:d0=255:d1=0:d2=0" output.mp4

In this command:

  • x=150: The horizontal offset from the left edge.
  • y=200: The vertical offset from the top edge.
  • d0, d1, d2: The destination color components (e.g., Red, Green, and Blue in an RGB space).

Setting the Target Color

The filter determines which pixels to overwrite based on source components s0, s1, s2, and s3:

  • Automatic Sampling: By default, source components are set to -1. This instructs FFmpeg to automatically sample the exact pixel value located at the specified (x, y) coordinate.
  • Manual Definition: You can explicitly define the color to replace by assigning values to s0, s1, and s2 (and s3 for alpha channels):
ffmpeg -i input.mp4 -vf "floodfill=x=150:y=200:s0=255:s1=255:s2=255:d0=0:d1=0:d2=0" output.mp4

Managing Color Tolerance

FFmpeg's floodfill filter does not include a native tolerance or threshold parameter. It operates exclusively on exact color matches across the specified pixel components. If adjacent pixels vary even slightly due to compression artifacts, gradients, or noise, the fill operation will halt at those boundaries.

To simulate tolerance, you must reduce the color depth or posterize the image before applying floodfill so that near-identical colors snap to uniform values:

  1. Pre-process with lutrgb or lutyuv: Use lookup tables to round pixel values into discrete bins.
  2. Apply floodfill: Fill the uniform region.
  3. Optional cleanup: Blend or adjust the frame back if necessary.

An example of rounding color values to simulate tolerance:

ffmpeg -i input.mp4 -vf "lutrgb=r='val-mod(val,16)':g='val-mod(val,16)':b='val-mod(val,16)',floodfill=x=150:y=200:d0=0:d1=255:d2=0" output.mp4

In this pipeline, lutrgb groups values within ranges of 16, allowing floodfill to traverse across subtle color variations that would otherwise stop an exact-match fill.