Watermarks and Overlays¶

Add watermark images and branded overlays to protect and brand your content. Peakhour's optimiser supports flexible positioning, scaling, tiling, and conditional logic so you can reuse a single asset across many layouts.

Parameters¶

Watermark layers inherit unset values from the base (wm_url/wm0_*) so you can define shared padding, opacity, or scaling once and override only the differences per layer.

`wm_url`¶

Absolute HTTPS URL or relative path to the watermark image. Relative paths are resolved with wm_base.

Type: string
Supported formats: PNG, JPG, WebP, GIF, SVG
Notes: Only HTTP(S) URLs or relative paths are accepted. Remote assets are cached by the optimiser for reuse.

`wm_base`¶

Base URL used to resolve relative wm_url values.

Type: string (absolute HTTPS URL)
Usage: Required when wm_url is a relative path.

`wm_pos`¶

Preferred anchor position for the watermark.

Type: string
Values: center, top, bottom, left, right, north, south, east, west, northeast, northwest, southeast, southwest, middle
Default: center
Notes: Synonyms with hyphens or underscores are accepted (for example top-right, south_west, centre).

`wm_x`, `wm_y`¶

Fine-grained x/y offsets applied after anchoring.

Type: integer (pixels)
Default: 0
Notes: Positive values move the watermark right/down; negative values move it left/up.

`wm_pad`¶

Inset padding applied between the watermark and the chosen edges.

Type: integer (pixels)
Default: 0
Range: >= 0

`wm_opacity`¶

Control overlay transparency.

Type: float or integer
Accepted values: 0.0-1.0 or 0-100 (percentage)
Default: 1.0 (fully opaque)

`wm_scale`¶

Scale the watermark proportionally relative to the base image width.

Type: float
Range: > 0 and <= 100
Usage: Sets the watermark width to a percentage of the base width while maintaining aspect ratio. Overrides wm_width/wm_height.

`wm_width`, `wm_height`¶

Explicit dimensions for the watermark in pixels.

Type: integer
Range: > 0
Notes: Combine with wm_fit to control how the watermark scales inside the target box.

`wm_fit`¶

Control how explicit dimensions are interpreted.

Type: string
Values: clip, crop, fill, scale, max
Usage:
- clip/max preserve aspect ratio.
- fill/crop use the full target box.
- scale allows independent width/height scaling.

`wm_tile`¶

Repeat the watermark to cover the entire base image.

Type: string
Values: grid, both, x, y
Usage: grid/both tile in both axes; x or y tile horizontally or vertically.

`wm_rot`¶

Rotate the watermark around its centre.

Type: float
Range: -360 to 360 degrees

`wm_if_min_width`, `wm_if_min_height`¶

Only apply the watermark when the base image is at least the specified size.

Type: integer (pixels)
Range: >= 0
Usage: Skip watermarking for small thumbnails.

Usage¶

Basic Watermark¶

image.jpg?wm_url=/logo.png&wm_opacity=0.7

Adds the logo at centre with 70% opacity.

Relative Asset with Base URL¶

image.jpg?wm_url=logos/mark.png&wm_base=https://cdn.example.com/&wm_pos=southeast&wm_pad=24

Resolves a relative watermark asset against wm_base and adds padding from the corner.

Responsive Scaling¶

image.jpg?wm_url=/brand.svg&wm_scale=18&wm_pos=northeast&wm_pad=16

Scales the watermark to 18% of the base width while maintaining aspect ratio.

Explicit Size and Fit¶

image.jpg?wm_url=/badge.png&wm_width=180&wm_height=60&wm_fit=fill&wm_pos=south

Forces the badge into a 180×60 box using centre cropping.

Tiled Background¶

image.jpg?wm_url=/pattern.png&wm_tile=grid&wm_opacity=0.25

Tiles a semi-transparent pattern across the entire image.

Conditional Large-Image Watermark¶

image.jpg?wm_url=/hero-logo.png&wm_if_min_width=1280&wm_scale=22&wm_pos=center

Applies the watermark only when the original image is wider than 1280px.

Rotated Diagonal Watermark¶

image.jpg?wm_url=/diagonal.png&wm_tile=y&wm_rot=45&wm_opacity=0.4

Rotates the watermark by 45° and repeats it vertically for high-coverage overlays.

Layered Watermarks¶

Stack multiple overlays in a single pass by adding indexed parameters (wm1_url, wm2_pos, …) or structured wm_layers JSON. Layers render in ascending index order: the base layer (wm_url/wm0_*) draws first, with higher-numbered layers composited on top. Any parameters you leave unspecified on a later layer inherit from the previous layer, so shared values like wm_pad, wm_opacity, or wm_pos only need to be declared once.

image.jpg?wm_url=/logo-light.svg&wm_pos=northwest&wm_pad=18
  &wm1_url=/logo-dark.svg&wm1_pos=southeast&wm1_pad=24&wm1_opacity=0.85
  &wm2_url=/ribbon.png&wm2_pos=south&wm2_width=640&wm2_fit=fill

Adds a light logo in the top-left corner, a darker variant bottom-right, and a ribbon graphic anchored to the bottom edge. Each layer reuses the base padding unless explicitly overridden.

For structured payloads, populate wm_layers with layer indexes as keys. Index 0 overrides the base layer if present.

{
  "wm_url": "/logo.svg",
  "wm_pad": 20,
  "wm_layers": {
    "1": {"wm_url": "/badge.svg", "wm_pos": "center", "wm_scale": 28},
    "2": {"wm_url": "/cta.svg", "wm_pos": "south", "wm_pad": 32}
  }
}

The total number of layers is capped by your deployment's MAX_WATERMARK_LAYERS environment variable (default 5). Requests that exceed the limit return an error before any rendering work begins.

Positioning Reference¶

Corners: northwest, northeast, southwest, southeast
Edges: north (top-centre), south (bottom-centre), east (right-centre), west (left-centre)
Middle: center, centre, or middle
Hyphenated or underscored forms (top-right, south_west) are normalised automatically.

Use wm_pad, wm_x, and wm_y to fine-tune placement without editing source artwork.

Watermark Design Best Practices¶

Aim for 15-25% of the base width using wm_scale for consistent sizing.
Use PNG or SVG with transparency for crisp results.
Keep opacity between 0.3-0.6 for subtle branding and up to 1.0 for strict protection.
Pair wm_pad with corner placement to avoid hugging edges.
Use wm_if_min_width / wm_if_min_height to skip smaller derivatives.

Technical Considerations¶

Remote watermark assets are fetched over HTTPS and cached on disk for repeat requests.
Only HTTP(S) URLs are accepted; other schemes (file, ftp, s3) are rejected for security.
Combining wm_tile with wm_rot adds processing cost, but cached results avoid repeat work.
Watermark operations preserve any alpha channel in the base image.

Troubleshooting¶

Watermark missing: check URL accessibility or ensure min width/height thresholds are met.
Unexpected size: review wm_scale, wm_width, and wm_fit values.
Wrong position: confirm wm_pos and adjust wm_pad/wm_x/wm_y.
Opacity too strong: wm_opacity=35 (or 0.35) produces a subtle 35% overlay.
Relative URL errors: include an absolute HTTPS wm_base when using relative paths.
Layer limit reached: reduce the number of indexed layers or raise MAX_WATERMARK_LAYERS (service restart required).

Watermarks and Overlays¶

Parameters¶

wm_url¶

wm_base¶

wm_pos¶

wm_x, wm_y¶

wm_pad¶

wm_opacity¶

wm_scale¶

wm_width, wm_height¶

wm_fit¶

wm_tile¶

wm_rot¶

wm_if_min_width, wm_if_min_height¶