Colors
Color adjustment
-/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 range | Zero point |
---|---|---|
/brightness/ | from -100 to 100 | 0 |
/exposure/ | from -500 to 500 | 0 |
/gamma/ | from 0 to 1000 | 100 |
/contrast/ | from -100 to 500 | 0 |
/saturation/ | from -100 to 500 | 0 |
/vibrance/ | from -100 to 500 | 0 |
/warmth/ | from -100 to 100 | 0 |
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.
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.
Last but not least, the warmth
operation adjusts color temperature in images.
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.
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.
Grayscale
Desaturates images. The operation has no additional parameters and simply produces a grayscale image output when applied.
Inverting
Inverts images rendering a 'negative' of the input.
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.
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:
Color Profile Management
This section covers Image Transformations (or CDN API methods) that provide color profile management and configure Uploadcare’s CDN behavior depending on the size of ICC profiles embedded in images.
- Color Models and ICC Profiles
- Configure Conversion to sRGB,
srgb
- Setting the ICC Profile Size Threshold,
max_icc_size
Color Models and ICC Profiles
Digital images can be stored in different color models depending on how we use them: whether it is displaying, printing, or something else. The most common model for images intended for viewing is RGB, while CMYK is widely used for printing.
While CMYK images are common, some browsers support them poorly. But more importantly, CMYK support is inconsistent across different browsers. This means that if you happen to serve CMYK images on your site, the colors will vary.
To eliminate the inconsistency, by default, we convert all CMYK images to sRGB. Another drawback of rendering CMYK images on a page is the large size of CMYK ICC profiles (those weight more than a regular 1920x1080 JPEG image). This negatively affects your page performance metrics such as First Meaningful Paint (FMP) and Time to Interactive (TTI).
In turn, an ICC profile defines how we interpret colors for the given color model. ICC profiles are binary files, which can be either embedded in an image or distributed as is.
With RGB images, embedding a profile is optional. If there is no embed, sRGB is assumed as default color space. Since most of the images on the internet are in sRGB, they commonly don’t include any profile embeds. For CMYK images, an embedded ICC profile is mandatory, while still can be absent. In the last case, we assume that the image is in the “Web Coated (SWOP) v2” color space.
Conversion to sRGB
-/srgb/fast/
-/srgb/icc/
-/srgb/keep_profile/
The operation sets how Uploadcare behaves depending on different color profiles of uploaded images. See the table below to learn more about the possible outcomes. We also provide an option to omit the conversion for the cases where you explicitly want CMYK outputs.
The operation defaults to the fast
value. However, we plan to optimize our
image processing infrastructure to make icc
faster and make it default. Both
operations ensure consistently displaying images across different browsers.
Depending on the input color model, the parameter you include in the operation,
and threshold you set with max_icc_size
, one of the
four possible outcomes will occur: profile embedding, profile discarding, color
conversion, and fast color conversion.
Input Image | fast | icc | keep_profile |
---|---|---|---|
RGB, small profile | embedding | embedding | embedding |
RGB, large profile | discarding | conversion | embedding |
CMYK image | fast conversion | conversion | embedding* |
“small profile” and “large profile” stand for profile sizes below and above the
max_icc_size
setting respectively.
Here is the definition for every possible outcome:
- Profile embedding: no changes in image model or colors. ICC profile, if present in the source image, stays embedded.
- Profile discarding: no changes in image model or colors. ICC profile, if present, gets stripped off an image.
- Color conversion: an image will be converted to sRGB using a full-featured color management system.
- Fast color conversion is performed using a simple formula which doesn’t consider any color profile and thus provides a result different from a color-managed version.
* While we try to preserve the color model and profile for CMYK images with the
-/srgb/keep_profile/
setting, this is not always possible. Certain Image
Transformations require RGB color model, and thus we automatically convert the
subjected images to sRGB using the icc
mode. The list of operations
incompatible with CMYK includes:
setfill
, overlay
,
enhance
, filter
, and
Color Adjustments.
ICC Profile Size Threshold
-/max_icc_size/0/
-/max_icc_size/:number/
The operation defines which RGB color profile sizes will be considered “small”
and “large” when using srgb
in fast
or icc
modes. The
:number
stands for the ICC profile size in kilobytes.
The default value is 10 (10240 bytes). Most of the common RGB profile sizes (sRGB, Display P3, ProPhoto, Adobe RGB, Apple RGB) are below the threshold.