Trim Processor Specification

Overview

The Trim processor (trim) crops or expands an image’s edges to remove excess background or provide extra padding. It is typically used to remove transparent or uniformly colored borders around a subject or to add margins for a more uniform layout. This processor supports per-side padding, auto-detection of background color, adjustable tolerance for near-matches, and configurable channels (e.g. alpha-only or color+alpha) for background detection.

In addition to processing the image, the Trim processor can optionally assign key cropping metrics (i.e. left, top, right, bottom, width, and height) as output variables. These assignment values are available both as parameters and in an assigns: block. When both sets of parameters are provided, the per-side values (top/left/right/bottom) take precedence over the overall width/height.

Example Usage

- processor:
    processor: "trim"
    inputs:
      source: "mem/subject.png" # Required input image
    params:
      padding: "10" # Uniform margin (default = 0)
      padding_left: "2" # Per-side overrides
      padding_right: "15"
      padding_top: "1"
      padding_bottom: "20"
      trim_color: "transparent" # Background to trim: "transparent", "auto", or a specific color (e.g. "#FFFFFF")
      tolerance: "128" # Color difference threshold (0-255)
      channel: "A" # Channels to compare: "A" for alpha-only, "RGB" for color only, "RGBA" for both
      max_size: "1500" # Maximum allowed dimension; default and maximum is 1500 pixels.
      # Optional assign parameters (overriding or supplementing computed values)
      left: "" # Calculated left coordinate
      top: "" # Calculated top coordinate
      right: "" # Calculated right coordinate
      bottom: "" # Calculated bottom coordinate
      width: "" # Calculated width (if per-side not provided)
      height: "" # Calculated height (if per-side not provided)
    outputs:
      target: "mem/trimmed.png" # Optional: output image path; if omitted, may overwrite source.
    assigns: # Optional: processor may assign these values to variables.
      left: "trim_left"
      top: "trim_top"
      right: "trim_right"
      bottom: "trim_bottom"
      width: "trim_width"
      height: "trim_height"

Key Points

  1. Input

    • source:
      The file path referencing the input image to be trimmed or padded. This image must exist in your storage system.

  2. Padding Parameters

    • padding:
      A uniform margin (in pixels) applied around the final cropped region.
    • padding_left, padding_right, padding_top, padding_bottom:
      These per-side padding values override the uniform padding value if specified.

  3. Background Detection

    • trim_color:
      • "transparent": Focus on alpha-based trimming; pixels with near-zero alpha (within tolerance) are considered background.
      • "auto": Automatically detect the dominant background color from the image’s edges.
      • Or a specific color (e.g. #FFFFFF or rgba(255,255,255,128)).
    • tolerance:
      An integer (0-255) that specifies how similar a pixel must be to the background color to be considered background. A higher value allows for near-matches.
    • channel:
      Specifies which channels are compared in the background detection:
      • "A": Only the alpha channel is considered.
      • "RGB": Only the color channels are considered (ignoring alpha).
      • "RGBA": Both color and alpha channels are considered.
      • Defaults to "A" if trim_color is "transparent", otherwise defaults to "RGB".

  4. Maximum Size Constraint

    • max_size:
      Ensures that no final image dimension (width or height) exceeds 1500 pixels. This parameter defaults to 1500 and also represents the maximum allowed value.

  5. Output

    • target:
      The file path where the final trimmed (or padded) image is saved. If omitted, the processor may overwrite the input image.

  6. Assignment of Cropping Metrics

    • Assign Parameters (in params):
      You can optionally include parameters such as left, top, right, bottom, width, and height to capture the computed cropping metrics. When both per-side values and overall dimensions are provided, the per-side values take precedence.
    • assigns: Block:
      This block maps the computed cropping metrics to variable names for use in subsequent processing steps. For example:
      • left → assigned to variable trim_left
      • top → assigned to variable trim_top
      • right → assigned to variable trim_right
      • bottom → assigned to variable trim_bottom
      • width → assigned to variable trim_width
      • height → assigned to variable trim_height

  7. Empty Crop Fallback

    • If the entire image is detected as background (within the specified tolerance), the processor returns a fallback image of 10×10 pixels filled with trim_color.

Workflow

  1. Load the input image from source.
  2. Determine Background Color:
    • If trim_color is "auto", sample the image’s perimeter to detect the dominant background color.
    • Otherwise, use the provided trim_color.
  3. Build a Mask:
    • Create a mask separating “subject” from “background” using the specified tolerance and channel settings.
  4. Compute the Crop Box:
    • Determine the bounding box of non-background pixels.
    • If no subject is found, generate a fallback 10×10 image.
  5. Apply Padding:
    • Expand the computed crop box based on the padding parameters. Per-side padding (padding_left, etc.) overrides the uniform padding value.
  6. Enforce Maximum Size:
    • Ensure that the final width and height do not exceed max_size (1500 pixels).
  7. Generate and Save Output:
    • Crop (or expand) the image using the padded and size-constrained box.
    • Save the resulting image to the path specified by target.
  8. Assign Cropping Metrics:
    • Output computed values (left, top, right, bottom, width, height) via:
      • Optional assign parameters in params (where per-side values take precedence over width/height).
      • The assigns: block, mapping these values to variable names for later use.

Notes & Tips