canvas

Change the size of the image canvas.

Sets the size of the image canvas, without changing the size of the image itself, which has the effect of adding space around the image.

This parameter takes multiple values. The first two represent the desired width and height, either as measurements of pixels, separated with a comma, or as a ratio, separated with a colon. The remaining parameters allow the placement of the image within the canvas to be adjusted. On each dimension, placement can be made either with a position coordinate (x or y, which are relative to the top left of the newly-enlarged canvas) or as a percentage offset from the center of the image using offset-x and offset-y. These can be mixed and matched, but only one method can be used for each dimension (i.e., x can be combined with offset-y but x cannot be combined with offset-x).

The remaining parameters determine the position of the cropped region.

Offset positioning acts to distribute the remaining space according to the specified offset proportions. For example, offset-y10 would place the image so that 10% of the leftover space is above the image and 90% below it.

Syntax

canvas={SIZE}
canvas={SIZE},{POSITION}

SIZE can be:

{width},{height}
{width-ratio}:{height-ratio}

POSITION can be:

x{x},y{y}
offset-x{offset-x},offset-y{offset-y}
x{x},offset-y{offset-y}
offset-x{offset-x},y{y}

Sub-parameters

ParamUnits
widthPixels or Percentage
heightPixels or Percentage
width-ratioNumber
height-ratioNumber
xPixels or Percentage
yPixels or Percentage
offset-xPercentage
offset-yPercentage

Notes

  1. x and y can be set as a value in pixels (e.g., 40 is 40 pixels) or as a percentage suffixed with p (e.g., 50p is 50%).
  2. When x and y are percentages, they are calculated as percentages of the image size, not the canvas size.
  3. offset-x and offset-y are always interpreted as percentages of the canvas size (e.g., 25 is 25%).
  4. If no x, y, offset-x, or offset-y parameters are supplied, the image is positioned in the center of the canvas.
  5. The background color of the canvas will default to transparency for image output formats that support transparency and white for formats that don't. This behavior can be changed by adding the bg-color parameter.
  6. When using canvas and pad at the same time, pad will be ignored.
  7. Any fractional pixel measurements will be rounded to the nearest whole pixel.

Examples

Click the links to view the transformed image using a demo Fastly IO service.

Example usageDescription
?width=300&canvas=320,240Set a canvas of 320px by 240px and place the image in the center.
?width=300&canvas=320,240,offset-x0.25,offset-y0.50Set a canvas of 320px by 240px and place the image such that a quarter of the leftover horizontal space is to the left and 75% to the right, and it is centered vertically.
?width=300&canvas=320,240&bg-color=000000Center image in canvas and set background color.

User contributed notes

BETA

Do you see an error in this page? Do you have an interesting use case, example or edge case people should know about? Share your knowledge and help people who are reading this page! (Comments are moderated; for support, please contact Fastly support)