uploadcaredocs

Image Filters

Uploadcare Image Transformations features automatic image enhancement along with other filters like sharpening, blurring, desaturating, and more. Filters follow the general CDN API workflow and should be included in CDN URLs as directives.

Automatic Image Enhancement, enhance

-/enhance/
-/enhance/:strength/

Auto-enhances an image by performing the following operations: auto levels, auto contrast, and saturation sharpening. :strength values should be in the range from 0 to 100. The default value is 50.


Original image. 24Kb

/enhance/50/ 28Kb

/enhance/100/ 32Kb

Adjusting Image Sharpness, sharp

-/sharp/
-/sharp/:strength/

Sharpens an image, might be especially useful with images that were subjected to downscaling. :strength can be in the range from 0 to 20 and defaults to the value of 5.


Downscaled image. 15Kb

/sharp/10/ 17Kb

/sharp/20/ 19Kb

Blurring Images, blur

-/blur/
-/blur/:strength/

Blurs images by the :strength factor. The filtering mode is Gaussian Blur, where :strength parameter sets the blur radius — effect intensity. Technically, :strength controls the Gaussian Blur standard deviation multiplied by ten. The value of :strength might come up to 5000, while the default value is 10. Note, different :strength values do not affect the operation performance.


Original image. 17Kb

/blur/20/ 10Kb

/blur/100/ 6Kb

Unsharp Masking

-/blur/:strength/:amount/

There is no specific operation for unsharp masking. Instead, you can adjust the :amount of the blur applied. :amount can be set in the range from –200 to 100 and defaults to 100.

Where the :amount of:

  • 100 stands for the opaque blur image.
  • 0 stands for no changes in the image, the output is equal to the original.
  • Any negative number would mean subtracting the difference between the blurred and original images from the original. That is the unsharp masking behavior.

You can implement unsharp masking with a large blur :strength (100;300) and a small negative :amount (–50;–10) to increase local contrast. Fine-tuned local contrast gives a “pop” to an image and mimics the look created by camera lenses. Local contrast enhancements let you minimize the effects of haze, lens flare, and “dull look.”

When implemented with a small :strength, unsharp masking increases image sharpness. For instance, the /blur/10/-200/ transformation is the full equivalent of /sharp/20/ with the exception that sharp operates much faster.

You can combine unsharp masking with the sharp operation to increase both local contrast and sharpness.


Original image. 16Kb

/blur/100/-50/ 19Kb

/blur/100/-120/ 22Kb

/sharp/20/ 20Kb

/blur/10/-200/ 20Kb

/sharp/10/-/blur/90/-50/ 21Kb

Adjust Image Colors

-/brightness/:value/
-/exposure/:value/
-/gamma/:value/
-/contrast/:value/
-/saturation/:value/
-/vibrance/:value/
-/warmth/:value/

Uploadcare features a set of operations for adjusting color properties of an image.

The :value parameter controls the strength of any applied adjustment. Ranges of the :value parameter differ between operations. There also is a zero point for each operation — the value producing outputs equal to original images.

Operation:value rangeZero point
/brightness/from -100 to 1000
/exposure/from -500 to 5000
/gamma/from 0 to 1000100
/contrast/from -100 to 5000
/saturation/from -100 to 5000
/vibrance/from -100 to 5000
/warmth/from -100 to 1000

The first three operations: brightness, exposure, and gamma are very similar. Unlike exposure and gamma, brightness works in a straightforward manner: the :value gets added to each color channel; out-of-range values are cut. Thus, when increasing brightness, brighter image features can be lost. Same works for darker features on brightness decrease. Conversely, exposure and gamma compress color values distribution in either lighter or darker areas depending on the provided :value, thus preserving details.


/brightness/-20/

Original image.

/brightness/20/

/exposure/-100/

Original image.

/exposure/80/

/gamma/150/

Original image.

/gamma/70/

The next three operations adjust color diversity and dynamic range in images:

  • contrast affects both colors and dynamic range; on increase, images lose both bright and dark details.
  • saturation uniformly bumps up color intensity leaving the dynamic range unchanged.
  • vibrance cleverly increases the intensity of muted colors and leaves the well-saturated ones alone. The operation produces more realistic results when applied to typical photos.

/contrast/-25/

Original image.

/contrast/25/

/saturation/-25/

Original image.

/saturation/25/

/vibrance/-50/

Original image.

/vibrance/50/

Last but not least, the warmth operation adjusts color temperature in images.


/warmth/-50/

Original image.

/warmth/50/

You can combine any adjustments to achieve the needed outputs. Piping the operations won't get you any performance or precision losses since all adjustments are applied in one pass.


Original image.

Old photo effect.
-/saturation/-80/
-/contrast/80/
-/warmth/50/

Fresh view.
-/exposure/50/
-/saturation/50/
-/warmth/-30/

Photo Filters, filter

-/filter/:name/
-/filter/:name/:amount/

Applies one of predefined photo filters by its :name. The way your images look affects their engagement rates. You apply filters thus providing beautiful images consistent across content pieces you publish.

The :name should be one of the following: adaris, briaril, calarel, carris, cynarel, cyren, elmet, elonni, enzana, erydark, fenralan, ferand, galen, gavin, gethriel, iorill, iothari, iselva, jadis, lavra, misiara, namala, nerion, nethari, pamaya, sarnar, sedis, sewen, sorahel, sorlen, tarian, thellassan, varriel, varven, vevera, virkas, yedis, yllara, zatvel, zevcen.

:amount can be set in the range from -100 to 200 and defaults to 100. The :amount of:

  • 0 stands for no changes in the image, the output is equal to the original.
  • Values in the range from 0 to 100 gradually increase filter strength; 100 makes filters work as designed.
  • Values over 100 emphasizes filter effect: the strength of applied changes.
  • Any negative number would mean subtracting the difference between the filtered and original images from the original. That will produce a "negative filter" effect.

/filter/vevera/-100/

Original image.

/filter/vevera/100/

/filter/vevera/200/

All filters provide predictable outputs with the :value ranging from 0 to 100. For some filter presets, setting the :amount value outside those bounds may produce weird results. For example, all filters producing grayscale outputs will result in a negative image when set to the :amount greater than 100. Set to negative values, those will saturate an image.

Here's how all of our filters look like:


/filter/adaris/

/filter/briaril/

/filter/calarel/

/filter/carris/

/filter/cynarel/

/filter/cyren/

/filter/elmet/

/filter/elonni/

/filter/enzana/

/filter/erydark/

/filter/fenralan/

/filter/ferand/

/filter/galen/

/filter/gavin/

/filter/gethriel/

/filter/iorill/

/filter/iothari/

/filter/iselva/

/filter/jadis/

/filter/lavra/

/filter/misiara/

/filter/namala/

/filter/nerion/

/filter/nethari/

/filter/pamaya/

/filter/sarnar/

/filter/sedis/

/filter/sewen/

/filter/sorahel/

/filter/sorlen/

/filter/tarian/

/filter/thellassan/

/filter/varriel/

/filter/varven/

/filter/vevera/

/filter/virkas/

/filter/yedis/

/filter/yllara/

/filter/zatvel/

/filter/zevcen/

Desaturating Images, grayscale

Desaturates images. The operation has no additional parameters and simply produces a grayscale image output when applied.


Original image.

/grayscale/

Inverting Images, invert

Inverts images rendering a 'negative' of the input.


Original image.

/invert/

We’re always happy to help with code, integration, and other stuff. Search our site for more info or post your question in our Community Area.