Fill Processor

Overview

The Fill Processor creates an image filled entirely with a specified background color and supports additional overlays. A gradient overlay is applied when the parameters origin, gradient_end, and gradient_colors are defined.

Example Usage

- processor:
    processor: "fill"
    step: "fill_background"
    inputs:
      mask: "input/mask.png" # Optional. A grayscale mask defining the fill area.
      tile: "input/tile.png" # Optional. A tile image that will be repeated over the canvas.
    params:
      width: 1024 # Canvas width in pixels.
      height: 768 # Canvas height in pixels.
      background: "#000000" # Background color.
      foreground: "rgba(255,255,255,0.2)" # (Optional) Foreground overlay color.
      origin: "(10,20)" # (Optional) Origin offset for tiling and gradient start, in (x,y) format.
      gradient_end: "(100,100)" # (Optional) Defines the endpoint for the linear gradient.
      gradient_colors: "(0.0, #FF0000, 0.5, #0000FF, 1.0, #000000)" # (Optional) Gradient stops.
    assigns:
      origin_x: "fill_origin_x" # X-coordinate of the tiling origin.
      origin_y: "fill_origin_y" # Y-coordinate of the tiling origin.
      gradient_end_x: "fill_gradient_end_x" # X-coordinate parsed from gradient_end.
      gradient_end_y: "fill_gradient_end_y" # Y-coordinate parsed from gradient_end.
    outputs:
      target: "output/filled.png" # Output PNG image (RGBA)

Inputs

Key	Required	Description
`mask`	Optional	Filepath to a grayscale mask image that defines the region where the fill (and overlays) is applied.
`tile`	Optional	Filepath to an image (RGBA) used as the tile pattern.

Params

Key	Type	Default	Description
`width`	`int`	Required	Canvas width in pixels (clamped to a maximum of 1500).
`height`	`int`	Required	Canvas height in pixels (clamped to a maximum of 1500).
`background`	`str`	`#000000`	Background color for the canvas.
`foreground`	`str`	Optional	An optional foreground overlay color (with alpha) to blend over the tiled image.
`origin`	`str`	`(0,0)`	Origin offset for the tile pattern and the start point of the gradient, specified as an (x,y) coordinate.
`gradient_end`	`str`	Optional	A point in the format `"(x,y)"` that defines the endpoint of the linear gradient.
`gradient_colors`	`str`	Optional	A string defining two or more gradient stops. For example: `"(0.0, #FF0000, 0.5, #0000FF, 1.0, #000000)"`. Each stop is a position (0–1) and a color.

Outputs

Key	Required	Description
`target`	Yes	Filepath to the output PNG image (RGBA) generated by the processor.

Assigns

These assignments capture the parsed coordinate values for key parameters:

Key	Description
`origin_x`	The x-coordinate of the tiling origin (parsed from the `origin` parameter).
`origin_y`	The y-coordinate of the tiling origin (parsed from the `origin` parameter).
`gradient_end_x`	The x-coordinate from the `gradient_end` parameter.
`gradient_end_y`	The y-coordinate from the `gradient_end` parameter.

Processing Details

Input & Parameter Handling:
- A new blank canvas is created using the specified width and height, filled with the background color.
- If a tile image is provided via inputs: tile, it is loaded as an RGBA image and tiled over the canvas starting at the position specified by origin.
- The origin and gradient_end parameters are parsed to support relative syntax. Their parsed values are assigned to origin_x, origin_y, gradient_end_x, and gradient_end_y.
Tiling and Overlays:
- If a tile image is provided, it is repeated (tiled) to cover the entire canvas.
- If a foreground color is specified, it is blended over the tiled image.
- If all three gradient parameters (origin, gradient_end, and gradient_colors) are provided, a linear gradient is generated by interpolating between the defined gradient stops and blended over the canvas.
Mask Application (Optional):
- If a mask is provided, the fill and overlays are restricted to the regions where the mask has non-zero values.
Output Generation:
- The final image, combining the background, tiled image, optional foreground overlay, and optional gradient overlay, is saved as a PNG (RGBA) to the specified output target.