## 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 ```yaml - processor: processor: "trim" inputs: source: "output/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: "output/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 - **Tolerances:** For images with partially transparent edges, a higher `tolerance` (e.g., `128`) may be needed to correctly trim near-transparent regions. - **Channels:** Use `channel="A"` for images with clear alpha transparency. Use `channel="RGBA"` if both color and transparency need to be considered. - **Edge Cases:** - If the entire image is considered background, a 10×10 fallback image is produced. - If the computed crop box equals the full image, no trimming occurs, though additional padding may still be applied.