Trim¶

Automatically detect and remove uniform borders from images, keeping the content centered and optionally adding consistent padding. This is useful for cleaning up product shots, removing white backgrounds, or standardizing hero banners.

Parameters¶

`trim`¶

Enable trimming and select the detection mode.

Type: string | boolean Values: auto, color, alpha, colorunlessalpha, true Default: None (no trimming applied)

Value	Description
`auto`	Automatic edge detection using mean difference and standard deviation thresholds
`color`	Trim based on a specific background color (sampled from top-left pixel or specified with `trim-color`)
`alpha`	Trim based on transparent pixels (requires image with alpha channel)
`colorunlessalpha`	Use alpha-based trimming if the image has transparency, otherwise fall back to color-based
`true`	Alias for `color` mode

`trim-color`¶

Specify the background color to trim. If not provided, the color is sampled from the top-left pixel.

Type: string Format: Hex color (e.g., ffffff, f5f5f5, FF0000) Default: Sampled from top-left pixel

`trim-tol`¶

Color tolerance threshold for color mode. Higher values trim more aggressively.

Type: float Range: 0 - 100 Default: 0

`trim-pad`¶

Add uniform padding around the trimmed content. This helps maintain consistent spacing after trimming.

Type: integer Range: 0 - any positive value (pixels) Default: 0

`trim-md`¶

Mean difference threshold for auto mode. Controls how different a pixel must be from the background to be considered content.

Type: float Range: 0 - 100 Default: 11

`trim-sd`¶

Standard deviation threshold for auto mode. Controls variance tolerance in edge detection.

Type: float Range: 0 - 100 Default: 10

`trim-alpha`¶

Alpha threshold for alpha and colorunlessalpha modes. Pixels with alpha values below this threshold are considered transparent and will be trimmed.

Type: integer Range: 0 - 255 Default: 0

Usage¶

Auto Mode (Hero Banners)¶

image.jpg?trim=auto&trim-md=18&trim-sd=12&trim-pad=36

Automatically detects and trims uniform edges from hero banners or marketing images, adding 36px padding to the result.

Color Mode (Product Shots)¶

image.jpg?trim=color&trim-color=f5f5f5&trim-tol=18&trim-pad=24

Trims a light gray (#f5f5f5) background from studio product shots with 18% tolerance, adding 24px padding.

Alpha Mode (Transparent UI Elements)¶

image.png?trim=alpha&trim-alpha=16&trim-pad=12

Trims transparent pixels from PNG images with alpha channels, keeping pixels with alpha > 16 and adding 12px padding.

ColorUnlessAlpha (Universal Preset)¶

image.jpg?trim=colorunlessalpha&trim-color=ffffff&trim-tol=12&trim-alpha=20&trim-pad=20

A single preset that handles both transparent PNGs and JPEGs with white backgrounds. Uses alpha trimming for PNGs with transparency, falls back to color trimming for JPEGs.

Use Cases¶

E-commerce Product Images: Remove inconsistent white/gray backgrounds from product photography
User-Uploaded Content: Automatically clean up scanned documents or screenshots with borders
Hero Banners: Standardize marketing images by removing letterboxing or pillarboxing
Logo Processing: Trim transparent areas around logos for consistent sizing
Batch Processing: Apply uniform trimming rules across large image collections

Combining with Other Parameters¶

Trim operations are applied early in the processing pipeline, before resizing. This allows you to:

Trim then Resize¶

image.jpg?trim=auto&trim-pad=20&w=400&h=300&fit=fill

First trim the borders, then resize the cleaned content to fit specific dimensions.

Trim with Format Conversion¶

image.jpg?trim=color&trim-color=ffffff&trim-tol=15&fm=webp&q=85

Clean up white borders and convert to optimized WebP format.

Trim with Effects¶

image.jpg?trim=auto&blur=1.5&brightness=10

Trim borders, then apply blur and brightness adjustments.

Performance Notes¶

Trim detection analyzes the entire image border, which adds minimal processing overhead
Results are cached at the edge for subsequent requests
For best results, use specific trim-color values when the background color is known
The auto mode works well for images with subtle gradients or compression artifacts in borders

Mode Selection Guide¶

Image Type	Recommended Mode	Key Parameters
Product photos on white	`color`	`trim-color=ffffff`, `trim-tol=10-20`
Product photos on gray	`color`	`trim-color=f5f5f5`, `trim-tol=15-25`
PNGs with transparency	`alpha`	`trim-alpha=0-32`
Mixed JPEG/PNG uploads	`colorunlessalpha`	Set both `trim-color` and `trim-alpha`
Hero banners with noise	`auto`	`trim-md=15-20`, `trim-sd=10-15`