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

- 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

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.
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.
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.
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.