imagor

imagor is a high-performance image processing server that leverages libvips and vipsgen (Go bindings) to achieve high throughput. It is designed to be competitive with other major image servers like imgproxy and generally faster than thumbor due to its efficient streamed request path and reduced buffering.

Performance Characteristics

• Strengths: High throughput for PNG and AVIF workloads; highly efficient for resize and thumbnail tasks.
• Comparison: In recent benchmarks on AWS c7i.large, imagor outperformed thumbor across JPEG, PNG, WebP, and AVIF. It is competitive with imgproxy, leading in PNG and AVIF, while imgproxy led in JPEG and WebP.
• Architecture: The speed comes from preparing streamed inputs for efficient libvips consumption, reusing blobs to reduce reader churn, and using a seekable libvips source path.

The imagor endpoint is constructed as a series of URL parts defining operations, followed by the image URI. The general structure is:

/HASH|unsafe/trim/AxB:CxD/(adaptive-)(full-)fit-in/stretch/-Ex-F/GxH:IxJ/HALIGN/VALIGN/smart/filters:NAME(ARGS):NAME(ARGS):.../IMAGE

Key components include:

• HASH: The URL signature hash (use unsafe for unsigned URLs).
• trim: Removes surrounding whitespace.
• AxB:CxD: Manual crop coordinates.
• fit-in, full-fit-in, adaptive-fit-in: Resizing modes that do not auto-crop.
• stretch: Resizes without preserving aspect ratio.
• -Ex-F: Resizing with optional flipping (using - signs).
• GxH:IxJ: Padding dimensions.
• HALIGN/VALIGN: Alignment for crops (left, right, center / top, bottom, middle).
• smart: Uses focal point detection for cropping.
• filters: A pipeline of operations applied after resizing.
• IMAGE: The source image path or URI.

You can control the number of threads libvips uses for image operations by setting the VIPS_CONCURRENCY environment variable.

Note: This is a global setting that controls threading within each individual image operation, not the number of concurrent requests handled by imagor.

• VIPS_CONCURRENCY=1 (Default): Single-threaded processing. Recommended for most deployments where concurrency is managed at the application level (e.g., via multiple imagor processes or containers).
• VIPS_CONCURRENCY=-1: Uses all available CPU cores. This can speed up processing for single large images but may cause resource contention under high request concurrency.
• VIPS_CONCURRENCY=[number]: Sets a specific number of threads for fine-tuned control.

VIPS_CONCURRENCY=1    # Single-threaded (default)
VIPS_CONCURRENCY=-1   # Use all available CPU cores
VIPS_CONCURRENCY=4    # Use 4 threads

The imagorpath package allows you to programmatically generate and parse signed imagor endpoint paths using Go structs. You can define image transformation parameters in an imagorpath.Params struct and use a signer to generate a secure path, or parse an existing signed path back into a Params struct.

import "github.com/cshum/imagor/imagorpath"

// 1. Define your transformation parameters
params := imagorpath.Params{
	Image:      "path/to/image.png",
	FitIn:      true,
	Width:      500,
	Height:     400,
	PaddingTop: 20,
	PaddingBottom: 20,
	Filters: imagorpath.Filters{
		{
			Name: "fill",
			Args: "white",
		},
	},
}

// 2. Generate a signed endpoint path using a signer
// NewDefaultSigner requires your secret key
path := imagorpath.Generate(params, imagorpath.NewDefaultSigner("mysecret"))

// 3. Parse a signed path back into a Params struct
parsedParams := imagorpath.Parse(path)