Resize Processor

Overview

The Resize Processor (AbProcResize) is responsible for transforming an input RGBA PNG image according to user-defined width, height, and method. This processor always produces a PNG in RGBA format, using a moderate compression level. It supports multiple resizing modes, allowing users to preserve or alter aspect ratios and optionally fill the outside area with a matte color. It also supports upscaling via the upscaling parameter. In addition, the processor enforces a maximum size for the output image and computes several metrics during resizing that can be assigned as variables for subsequent processing steps. When both explicit dimensions and scaling factors are provided, the explicit dimensions take precedence, and specific height and width scaling factors override a general scale factor.

Example Usage

- processor:
    processor: "resize"
    inputs:
      source: "input/photo.png" # Virtual filepath in storage
    params:
      width: 800 # Desired width in pixels, must be in the range [1..max_size]
      height: 600 # Desired height in pixels, must be in the range [1..max_size]
      method: "matte" # Resizing approach; one of: "contain", "cover", "stretch", "matte", "width", "height"
      matte_color: "rgba(255, 255, 255, 0.5)" # Used if method is "matte"; a color string in typical formats
      max_size: 1500 # Safety check for output dimensions; final width or height will not exceed 1500 pixels
      upscaling: False # If false, the processor will not enlarge the image beyond its original dimensions
      scale: "0.5" # Optional general scale factor applied when explicit dimensions are not provided
      height_scale: "0.75" # Optional specific scaling factor for height; takes precedence over a general scale
      width_scale: "0.8" # Optional specific scaling factor for width; takes precedence over a general scale
    outputs:
      target: "output/resized.png" # File path where the resized PNG image is saved
    assigns:
      width: "resize_width" # Final computed width of the image after resizing
      height: "resize_height" # Final computed height of the image after resizing
      width_scale: "resize_width_scale" # Effective scaling factor applied to the width
      height_scale: "resize_height_scale" # Effective scaling factor applied to the height

Inputs

Key	Required	Description
`source`	Yes	Virtual filepath to the input image in the storage system (for example, `"input/photo.png"`).

Params

Key	Type	Required	Default	Description
`width`	`int`	Yes	(no default)	The desired output width in pixels. This value must be within the range of 1 to `max_size`.
`height`	`int`	Yes	(no default)	The desired output height in pixels. This value must be within the range of 1 to `max_size`.
`method`	`str`		`"fit"`	The resizing approach. Valid options include: `"contain"` (alias: `"fit"`), `"cover"` (alias: `"expand"`), `"stretch"`, `"matte"`, `"width"`, and `"height"`.
`matte_color`	`str`		None	A color string used if `method` is `"matte"`. Accepted formats include `#RRGGBB`, `rgba(...)`, or named colors (e.g., `"white"`).
`max_size`	`int`		`1500`	A safety check for output dimensions. The final width or height of the image will not exceed this value.
`upscaling`	`boolean`		True	If set to false, the processor will not enlarge the image beyond its original dimensions.
`scale`	`float`		None	A general scaling factor to apply if explicit width and height are not provided.
`height_scale`	`float`		None	A specific scaling factor for height. This value takes precedence over the general `scale` if provided.
`width_scale`	`float`		None	A specific scaling factor for width. This value takes precedence over the general `scale` if provided.

Outputs

Key	Required	Description
`target`		The file path for the new PNG image. If omitted, the resized image may overwrite the `source` image.

Resizing Methods

The method parameter (case-insensitive) can be one of the following:

contain
- Preserves the image's aspect ratio while fitting it within the specified (width, height).
- Uses the .thumbnail(...) method by default, which does not upscale smaller images unless explicitly allowed.
- Alias: "fit".
cover
- Scales the image so that the entire specified (width, height) area is covered, then center-crops any overflow.
- Alias: "expand".
stretch
- Resizes the image to exactly match the specified (width, height) dimensions without preserving aspect ratio, which may cause distortion.
matte
- Similar to "contain", but places the scaled image onto a canvas filled with matte_color.
- The outside area is filled with the matte color while the original image remains centered and its internal transparency is preserved.
- Alias: "pad".
width
- Sets the final image width to the specified width and computes the height based on the original aspect ratio.
- If the computed height exceeds max_size, the image is clamped or cropped accordingly.
height
- Sets the final image height to the specified height and computes the width based on the original aspect ratio.
- If the computed width exceeds max_size, the image is clamped or cropped accordingly.

Notes

RGBA PNG
- The processor loads or converts images to RGBA internally and always saves them as PNG files using a moderate compression level (compress_level=6).
Matte Color Parsing
- The matte_color parameter is processed via PIL.ImageColor.getcolor(color_str, "RGBA"), which accepts typical formats such as #RRGGBB, rgba(...), and named colors.
- The matte color is applied only to the background area outside the resized image. Transparent regions in the original image remain unchanged.
Maximum Size Constraint
- The max_size parameter ensures that neither the final width nor the final height exceeds the specified maximum (1500 pixels). If the computed dimensions exceed this value, the image is scaled down proportionally.
Assignment of Cropping Metrics
- The processor can output computed values for the cropping region and scaling factors via an assigns: block. Suggested assignment variables include:
  - resize_width: The final computed width of the image.
  - resize_height: The final computed height of the image.
  - resize_width_scale: The effective scaling factor applied to the width.
  - resize_height_scale: The effective scaling factor applied to the height.
- If both overall dimensions and specific per-side assignments (such as left, top, right, bottom) are provided in the parameters, the per-side values take precedence.
Precedence of Scaling Parameters
- When both explicit dimensions (width and height) and scaling factors (scale, height_scale, and width_scale) are provided, the explicit dimensions take precedence.
- Specific scaling factors (height_scale and width_scale) override a general scale parameter if provided.

Workflow

Load the Input Image:
The processor retrieves the image from the specified source path in storage.
Parameter Evaluation:
The processor validates and parses the width, height, and max_size parameters, ensuring that the output dimensions are within the allowed range. It also evaluates any provided scaling factors, with specific factors taking precedence over a general scale factor.
Resizing Operation:
The image is resized using the selected method (contain, cover, stretch, matte, width, or height). If upscaling is disabled, the processor prevents enlarging the image beyond its original dimensions.
Enforce Maximum Size Constraint:
After resizing, the processor checks the final dimensions and scales the image down if either dimension exceeds max_size.
Apply Padding:
The processor applies a uniform padding (specified by padding) around the trimmed region, with per-side values (padding_left, padding_right, padding_top, padding_bottom) overriding the uniform value if provided.
Generate and Save Output:
The resized image is saved as a PNG to the specified target path. If target is not provided, the source image may be overwritten.
Assign Cropping and Scaling Metrics:
The processor outputs computed values such as the final width, height, and effective scaling factors via the assigns: block. These values are available for subsequent processing steps.