Image transformation query parameters

Many of the same filter parameters as Site Accelerator (previously Photon) can be applied to images loaded from a VIP Platform site’s wp-content/uploads/. Filter parameters can be applied on demand for resizing, cropping, and processing successive transformation functions for an image. This eliminates the need to process those effects on all source images in advance.

For example, the width (w=) or height (h=) parameters can be appended to an image’s source URL to dynamically resize the image at the time it is requested.

This image transformation method also allows a theme or plugin to load a modified image from the site’s wp-content/uploads/ directory.

Examples

To observe the effect of a query parameter by applying it to an example image, select one of the buttons labeled with a query argument (e.g. w=300) provided below.

Also included below the row of buttons is an example of the query parameter format when it is appended to an image URL.

Multiple parameters can be applied to a single image URL. Each parameter is applied to the image in the order in which it is appended to the URL. If the same argument is appended more than once, only the value of the last appended version of the argument will be applied to the image.

Reference

This reference includes all available image transformation query arguments and a description for their usage. To toggle the application of a query parameter to the example image, select a button labeled with the query argument (e.g. w=300). An example of the query parameter format when appended to an image URL is displayed below the toggle buttons.

These query parameters are also compatible for images hosted on WordPress.com.

w=x,h=x

Set the width and/or height of an image in pixels.

If both w and h are present, the smaller axis will be used. These can also be combined into a central crop by adding crop=1.

crop=x,y,w,h

Crop an image by percentages x-offset, y-offset, width, height (x, y, w, h). Percentages are used so that cropping does not need to be recalculated when transforming the image with other methods such as resizing.

For example, crop=12,25,50,50 takes a 50% by 50% rectangle from the source image starting at 12% offset from the left and 25% offset from the top.

Pixel (px) values are also available, as is mixing percent and pixel types in one crop.

resize=x,y

Resize and crop an image to the exact width,height pixel dimensions. Set the first number as close to the target size as possible and then crop the rest. The direction in which it is resized and cropped depends on the aspect ratios of the original image and the target size. This works similarly to combining w, h and crop.

This is useful for taking an image of any size and making it fit into a certain location while losing as little of the image as possible.

fit=x,y

Fit an image to a containing box of width, height dimensions. Image aspect ratio is maintained.

For example, fit=100,100 on a landscape image with dimensions 400×300 will result in an image that is 100×75, while fit=100,100 on a portrait image with dimensions 300×400 will result in an image that is 75×100.

lb=x,y

Add black letterboxing effect to images, by scaling the canvas to width, height while maintaining the image aspect ratio and filling the rest with black.

ulb=true

Remove black letterboxing effect from images with ulb. This function takes only one argument, true.

filter=type

The filter parameter is used to apply one of multiple filters. Valid values are: negate, grayscale, sepia, edgedetect, emboss, blurgaussian, blurselective, meanremoval.

brightness=range

Adjust the brightness of an image. Valid values are -255 through 255 where -255 is black and 255 is white. Higher is brighter. The default is0.

contrast=range

Adjust the contrast contrast of an image. Valid values are -100 through 100. The default is 0.

colorize=r,g,b

Add color hues to an image with colorize by passing a comma separated list of red, green, and blue (RGB). For example, values such as 255,0,0 (red), 0,255,0 (green), 0,0,255 (blue).

smooth=1

The smooth parameter can be used to smooth out the image.

According to the PHP manual, the function applies a 9-cell convolution matrix where the center pixel is weighted by the value of the first argument, and all surrounding pixels have a weight of 1. The result is normalized by dividing by the total weight. In simpler terms, a value of 0 results in maximum smoothing, while higher values reduce the smoothing effect. Values around 2048 or more have little to no visible impact.

zoom=1|1.5|2

Use zoom to size images for high pixel ratio devices and browsers when zoomed. Not available to use with crop. Zoom is intended for use by scripts such as devicepx.js which automatically set the zoom level. Valid zoom levels are 1, 1.5, 2–10.

quality=10-100

Use this parameter to manage the quality output of the images. Valid settings are between the values 10 and 100. The degree of compression depends on the image, its lossy or lossless nature, and the requesting web browser’s capabilities.

For lossless images, providing the quality input less than 100 will result in a lossy image provided the requested browser supports this image type. Below is an example that shows conversion of a non-transparent PNG (lossless) image to a JPEG (or lossy WebP if browser supports it) when quality is specified.

strip=all|info|color

Use the strip functionality to modify how metadata is preserved. If the strip parameter is not applied to an image served by the VIP File System, all EXIF, IPTC and XMP metadata is preserved.

Valid settings for this parameter:

• all: (default) All data is stripped, with any existing orientation data being first applied to the image.
• info: All non-essential EXIF metadata is stripped; color metadata is preserved..
• color: Only EXIF color data is stripped.

If the strip query parameter is applied to an image served by Site Accelerator (loaded from the i0.wp.com domain instead of a site’s domain) only the setting values all and none are valid.

---