Overlay

The overlay operation allows to layer images one over another.

-/overlay/:uuid/
-/overlay/:uuid/:relative_dimensions/:relative_coordinates/:opacity/

One of the most common use cases here are watermarks: semi-transparent images layered over opaque ones to complicate their unauthorized usage, etc.

  • :uuid — UUID of an image to be layered over input. To be recognized by :uuid, that image should be related to any project of your account.
  • :relative_dimensions — linear dimensions of the overlay image. The aspect ratio of an overlay is preserved. What you set is a maximum linear size along one of the axes: -/overlay/:uuid/50%x50%/ means any linear dimension of the overlay can not exceed 50% in size. Default size setting is 100%.
  • :relative_coordinates — position of the overlay over your input. By default, an overlay is positioned in the top-left corner of an input. Coordinates represent an offset along each of the axes in either pixel or percent format. In general, the coordinate system is similar to the CSS background-position. For example, -/overlay/:uuid/10%,90%/ places overlay in bottom left corner.
  • :opacity — controls the opacity of the overlay in percent format. Your overlay may either be initially semi-transparent or made to be so by tuning :opacity.

Since % is an escape char in URLs, it can’t be used as-is and should be replaced with either %25 escape sequence or the p char, which is a more readable and concise option.

Every overlay parameter is optional and can be omitted. However, the order of parameter URL directives should be preserved.

Watermark with transparency
/overlay/:uuid/50px50p/20p/
Specifying size and opacity, positioning is omitted.		Overlay, centered, good for logo
/overlay/:uuid/50%x50%/center/
Specifying size and position, opacity is omitted.		Overlays with various positions
Adding multiple overlays with varied positions.

Overlay the source image

-/overlay/self/
-/overlay/self/:relative_dimensions/:relative_coordinates/:opacity/

To fit an image into a specified placeholder, you can add a stylized background from the same image. It visually extends the image appearance vertically or horizontally.

Scale and crop landscape image to center with a square aspect ratio
/scale_crop/440x440/center/
Step 1. Scale and crop
background to size.		Blur cropped image and set gamma to dull colors
/blur/60/-/gamma/50/
Step 2. Blur and wash out colors.		Overlay the original landscape image over its square blurred version to extend the image appearance vertically
/overlay/self/100px100p/center/
Step 3. Place the original image.

With all steps combined, this operation will look like:

-/scale_crop/440x440/center/-/blur/60/-/gamma/50/-/overlay/self/100px100p/center/

Unlike the standard overlay, -/overlay/self/ doesn't require an image UUID. It helps when you don't have access to UUIDs when using Proxy, and when you do batch image processing.