# 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
```yaml
- 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
1. **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`.
2. **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.
3. **Mask Application (Optional):**
- If a mask is provided, the fill and overlays are restricted to the regions where the mask has non-zero values.
4. **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.