# **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 ```yaml - 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: 1. **`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"`. 2. **`cover`** - Scales the image so that the entire specified `(width, height)` area is covered, then center-crops any overflow. - Alias: `"expand"`. 3. **`stretch`** - Resizes the image to exactly match the specified `(width, height)` dimensions without preserving aspect ratio, which may cause distortion. 4. **`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"`. 5. **`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. 6. **`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 1. **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`). 2. **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. 3. **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. 4. **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. 5. **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 1. **Load the Input Image:** The processor retrieves the image from the specified `source` path in storage. 2. **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. 3. **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. 4. **Enforce Maximum Size Constraint:** After resizing, the processor checks the final dimensions and scales the image down if either dimension exceeds `max_size`. 5. **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. 6. **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. 7. **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.