Documentation

mask Mask Type

Values

  • corners: Creates rounded corners.
  • ellipse: Creates an ellipse bounded by the image dimensions.
  • <url>: Masks the image with another image, referenced by the URL.

Note: When the parameter value is a URL or multiple comma-separated values, it should be encoded. If you’re using Base64 encoding, then use the mask64 version of the parameter.


The mask parameter has pre-defined shapes for two common use cases: rounded corners and ellipses. Custom mask shapes can also be defined by supplying the URL to a transparent image file. When a masked image is output as a PNG file using fm=png, masked areas will be transparent—otherwise they will default to white.

mask=corners

The corners value will round the corners of the image to the value or values specified by the corner-radius parameter. If that parameter isn’t set, the radius defaults to 20% of the smaller dimension for all corners. The radius for each corner can be controlled individually.

mask=ellipse

When defining an ellipse, mask will attempt to fit the dimensions of the image. To generate a circle, the image must have the same width and height.

mask=<url>

You can also use an image to serve as a mask. When an image URL is the value for the mask parameter, its luminance values and any existing transparency data will define visible and hidden pixels. Similar to the ellipse, image masks will stretch to fill the space of the image to be masked.

When using images as masks, white areas denote what is visible, and black areas will be hidden. Full 24-bit transparency is supported, meaning that values of grey translated from the mask will be semi-transparent. When using a full-color image as a mask, the luminance value in each pixel will determine transparency instead.

The following examples display how using an images as a mask affect the sample image above. Note: The grey checkerboard areas are not part of the images below—they have been placed to better demonstrate the image’s transparency.

Docs mask1
Docs mask2
Docs mask3
Docs mask4
mask=mask1.png
Docs mask1
mask=mask2.png
Docs mask2
mask=mask3.png
Docs mask3
mask=mask4.png
Docs mask4