picturium

Type at least two characters to search every documentation page.

Full-text searchEsc to close

 v0.2.0 GitHub Get started

Docs / Filters & effects

Filters & effects v0.2.0

filter= applies one or more effects. Separate them with |. They run left to right, so the order can change the result.

/photo.jpg?filter=brightness:1.1|contrast:1.2|blur:2

The filter parameter

Each part is a filter name, a colon, and a value. Names aren’t case-sensitive. An unknown name, a missing colon, or a value that doesn’t parse or is out of range makes the whole request invalid.

brightness
float ≥ 0 No-op 1

Scales brightness. 0 is black; above 1 brightens.

contrast
float ≥ 0 No-op 1

Scales contrast around the midpoint.

saturate
float ≥ 0 No-op 1

0 removes colour; above 1 boosts it.

hue
degrees, 0–360 No-op 0 or 360

Rotates hue the same way the CSS hue-rotate filter does.

grayscale
float, 0–1 No-op 0

Blends towards full grayscale.

sepia
float, 0–1 No-op 0

Blends towards full sepia.

invert
float, 0–1 No-op 0

Blends towards fully inverted colours.

blur
whole number ≥ 0 No-op 0

Gaussian blur, with the value as sigma.

sharpen
float, 0–10 No-op 0

Sharpening, with the value as sigma.

pixelate
whole number ≥ 1 No-op 1

Blocks roughly this many output pixels wide and tall.

palette
1–2 colours[, intensity] No-op intensity 0

Monochrome or duotone tint.

Brightness, contrast and saturation have no upper limit, but anything between 0 and 5 covers what most images need.

Tone & colour

brightness, contrast and saturate leave the image alone at 1. hue is in degrees. Mix them when one adjustment isn’t enough:

/photo.jpg?filter=brightness:1.08|contrast:1.15|saturate:0.85
/photo.jpg?filter=hue:90|saturate:1.25

These don’t touch the alpha channel. On grayscale images, saturate and hue have no colour to work with and do nothing.

Grayscale, sepia & invert

These take an amount between 0 and 1, not an on/off switch. 0 does nothing, 1 applies the full effect, and anything in between blends the two.

/photo.jpg?filter=grayscale:1
/photo.jpg?filter=sepia:0.65|contrast:1.1
/photo.jpg?filter=invert:0.5

Blur, sharpen & pixelate

blur and pixelate want whole numbers. sharpen takes a decimal up to 10.

/photo.jpg?w=900&filter=blur:3
/photo.jpg?filter=sharpen:1.5
/photo.jpg?w=800&h=600&filter=pixelate:12

Pixelate renders the image smaller by its factor, then scales it back up to the requested size with nearest-neighbour. That means the block size depends on the final dimensions from Sizing & layout.

Palette

One colour gives you a monochrome tint, two give a duotone. In a duotone, the first colour is used for the highlights and the second for the shadows. An optional number at the end sets the intensity: 1 by default, 0 for no effect.

# Monochrome
/photo.jpg?filter=palette:ff8a1f

# Duotone: light, dark
/photo.jpg?filter=palette:ffd633,16181f

# Duotone at 70% intensity
/photo.jpg?filter=palette:ffd633,16181f,0.7

Colours use the same syntax as bg, but since commas separate the palette values, stick to hex, colour names, or colour functions written with spaces (rgb(255%20138%2031) once URL-encoded). rgb(255,138,31) would be split apart.

Order & processing

Filters run after rotation, cropping, resizing, fitting and padding, and before the watermark is drawn. Each filter works on the output of the one before it:

Raster transform order
  1. Autorotate
    / rotate
  2. Crop
  3. Size × DPR
    × scale
  4. Fit
    / gravity
  5. Pad
  6. Filters
  7. Watermark

Filters apply to every frame of an animated image or video clip. Blur, sharpen and pixelate run frame by frame so neighbouring frames don’t bleed into each other. Filters are skipped when picturium returns the original file or a document with f=pdf or f=svg.

The short version is in the filter quick reference. Next up: Watermarking.