Image Processing

smoxy allows you to process images on the fly using rewrite rules. Instead of pre-generating thumbnails or editing images manually, you can resize, crop, blur, sharpen, rotate, and adjust the output quality of any image — all by simply defining the right URL pattern.

This is especially useful when your design changes and you need new thumbnail sizes. Instead of regenerating all thumbnails, you just update the image URL in your templates.

How It Works

Image processing is powered by smoxy's rewrite rules. You define a regex pattern that matches incoming image URLs and a target path that tells smoxy what operations to perform.

The target path has three parts:

1. /_sx/img/_/ — This prefix tells smoxy that the request should be processed as an image process operation.

2. Processing operations — One or more operations separated by / that define what to do with the image (resize, blur, set quality, etc.).

3. /plain/ — This separator tells smoxy that everything after it is the original path to the source image on your server.

/_sx/img/_/{operations}/plain/{original_path}

Each operation follows the format operation:param1:param2:... — the operation name (or its abbreviation), followed by colon-separated parameters.

Setting Up a Rewrite Rule

To use image processing, create a rewrite rule with a regex and a target path.

Regex:

^/thumbnail/(\d+)x(\d+)/(.*)

Target Path:

/_sx/img/_/rs:fit:$1:$2/q:100/plain/$3

In this example:

• $1 captures the desired width (e.g., 100)

• $2 captures the desired height (e.g., 100)

• $3 captures the original image path

When a user requests /thumbnail/100x100/media/images/product.jpg, smoxy will:

1. Fetch the original image from /media/images/product.jpg on your origin server.

2. Resize it to fit within 100×100 pixels while keeping the aspect ratio.

3. Set the output quality to 100%.

4. Deliver the processed image.

Chaining Multiple Operations

You can chain as many operations as you need, separated by /:

/_sx/img/_/rs:fill:800:600/q:85/bl:5/bg:ffffff/f:webp/plain/$1

This will resize the image to fill 800×600, set quality to 85%, apply a Gaussian blur with sigma 5, set the background color to white, and convert the output to WebP format.

Use Cases

Dynamic Thumbnails

The most common use case. Define different thumbnail sizes directly in your image URLs without generating them upfront. When your design changes and you need different sizes, just update the URL pattern — no backend changes required.

Regex:

^/img/(\d+)x(\d+)/(.*)

Target Path:

/_sx/img/_/rs:fit:$1:$2/q:80/plain/$3

Now you can use URLs like /img/300x200/photos/hero.jpg or /img/150x150/photos/hero.jpg and smoxy will generate the right size on the fly.

Blurred Hero Backgrounds

Use the original image as a hero element with a blur effect, then overlay text on top. No need to edit and re-upload a separate blurred version of the image.

Regex:

^/hero-bg/(.*)

Target Path:

/_sx/img/_/rs:fill:1920:600/bl:15/q:70/plain/$1

This takes any image, resizes it to fill 1920×600, applies a strong Gaussian blur, and reduces quality to keep the file size small — perfect as a background behind text.

Available Operations

smoxy supports a wide range of image processing operations, organized into the following categories:

Category	Operations	Description
Resizing & Cropping	resize, width, height, crop, trim, gravity, and more	Control image dimensions, aspect ratio, and framing
Effects & Adjustments	blur, sharpen, pixelate, rotate, background, padding	Apply visual effects and transformations
Output, Metadata & Delivery	quality, format, watermark, strip metadata, and more	Control output format, quality, metadata, and delivery behavior

Note: Operations are processed in a fixed internal pipeline order regardless of the order you specify them in the URL. However, for readability, it's good practice to write them in a logical order: sizing → effects → quality → format.