# Canvas Processor
## Overview
The **Canvas Processor** creates or expands an image’s canvas in a way similar to Photoshop’s “Canvas Size” tool combined with the “New” command. It can accept an optional input image (under the key `source`), placing it on a blank canvas with specified dimensions and background color. If no input image is provided, it simply creates a new blank canvas. Parameters allow you to specify padding (which takes precedence over explicit dimensions) and control the alignment of the input image within the new canvas.
---
## Example Usage
```yaml
- processor:
processor: "canvas"
step: "make_blank"
inputs:
source: "input/input.png" # Optional. If omitted, a blank canvas is created.
params:
padding: 20 # Uniform padding on all sides (overrides width/height if specified)
padding_left: 100 # Left padding takes precedence over the general 'padding' value
width: 1024 # Canvas width (used if no padding is specified)
height: 768 # Canvas height (used if no padding is specified)
align: "center" # Horizontal alignment of the input image: "left", "center", "right"
vertical_align: "center" # Vertical alignment of the input image: "top", "center", "bottom"
background: "#000000" # Background color (in any supported color format)
assigns:
top: "canvas_top" # Y-coordinate of the top of the input image on the canvas
left: "canvas_left" # X-coordinate of the left of the input image on the canvas
bottom: "canvas_bottom" # Y-coordinate of the bottom of the input image on the canvas
right: "canvas_right" # X-coordinate of the right of the input image on the canvas
outputs:
target: "mem/blank.png" # Output PNG image (RGBA)
```
---
## Inputs
| **Key** | **Required** | **Description** |
| -------- | ------------ | ------------------------------------------------------------------------------------------------------------ |
| `source` | **Optional** | Filepath to the input image (RGBA) that will be placed on the canvas. If omitted, a blank canvas is created. |
---
## Params
| **Key** | **Type** | **Default** | **Description** |
| ---------------- | -------- | ----------- | ---------------------------------------------------------------------------------------------- |
| `width` | `int` | _Required_ | The overall width of the canvas in pixels (if no padding is specified). |
| `height` | `int` | _Required_ | The overall height of the canvas in pixels (if no padding is specified). |
| `padding` | `int` | _Optional_ | Uniform padding (in pixels) to add on all sides; takes precedence over explicit width/height. |
| `padding_left` | `int` | _Optional_ | Left padding in pixels; overrides the general `padding` value for the left side only. |
| `align` | `str` | `"center"` | Horizontal alignment of the input image within the canvas. Options: "left", "center", "right". |
| `vertical_align` | `str` | `"center"` | Vertical alignment of the input image within the canvas. Options: "top", "center", "bottom". |
| `background` | `str` | `#000000` | Background color of the canvas (in any supported color format). |
---
## Outputs
| **Key** | **Required** | **Description** |
| -------- | -----------: | ----------------------------------------------------------------------- |
| `target` | **Yes** | Filepath to the output PNG image (RGBA) of the created/expanded canvas. |
---
## Assigns
These assignments record the position metrics of the input image on the canvas.
| **Key** | **Description** |
| -------- | ----------------------------------------------------------------- |
| `top` | Y-coordinate of the top edge of the input image on the canvas. |
| `left` | X-coordinate of the left edge of the input image on the canvas. |
| `bottom` | Y-coordinate of the bottom edge of the input image on the canvas. |
| `right` | X-coordinate of the right edge of the input image on the canvas. |
---
## Processing Details
1. **Input Loading:**
- If an input image is provided under `inputs: source`, load it as an RGBA image and position it on the new canvas.
- If no input is provided, create a blank canvas with the specified background color.
2. **Canvas Creation & Sizing:**
- The overall canvas size is defined by the `width` and `height` parameters.
- If `padding` is specified, it is applied uniformly on all sides (with `padding_left` overriding the left side), and the canvas size is adjusted accordingly.
3. **Image Alignment:**
- When an input image is provided, it is aligned within the canvas based on the `align` (horizontal) and `vertical_align` (vertical) parameters.
- The resulting position metrics (top, left, bottom, right) are computed and assigned to the corresponding keys.
4. **Output Generation:**
- The final canvas (with the input image composed, if provided) is saved as a PNG in RGBA format at the specified output target.