Documentation

palette Color Palette Extraction

The palette parameter extracts a palette of color values from an image and returns them in the specified format. Palette extraction occurs after image processing, so applying any adjustments and cropping effects will change the color palette response. Valid values are css and json.

This parameter generally outputs two palette sets—both choose colors based on their dominance in the image. The default set is strictly algorithmic based on frequency of the color in the image, and is always available. The dominance set also weights frequency, but selects the colors to provide a more coordinated palette across the image’s colorspace and names the colors by their relative values, like Vibrant.js.

The default palette set defaults to six colors, but can be overridden with the colors parameter. The dominance palette set provides up to six named colors:

  • Vibrant
  • Vibrant Dark
  • Vibrant Light
  • Muted
  • Muted Dark
  • Muted Light

The dominance palette will vary (and may not be generated) depending on whether the image’s colors meet the criteria for each name. It may return all six colors, a portion, or none, although most images will return a complete set.


palette=css

The response to the request will be a CSS file with the text/css MIME type. Class pairs have a “foreground” and a “background” defintion. The foreground class has a color property defined, while the background class has a background-color property defined. The CSS output also includes white and black, to make displaying a swatch set easier.

If prefix is also set, its value will replace “image” in the CSS class names in the output CSS file.

.frog-fg-1 { color:#ffd807 !important; }
.frog-bg-1 { background-color:#ffd807 !important; }
.frog-fg-2 { color:#6dca9a !important; }
.frog-bg-2 { background-color:#6dca9a !important; }
.frog-fg-3 { color:#04a450 !important; }
.frog-bg-3 { background-color:#04a450 !important; }
.frog-fg-4 { color:#971d01 !important; }
.frog-bg-4 { background-color:#971d01 !important; }
.frog-fg-5 { color:#566363 !important; }
.frog-bg-5 { background-color:#566363 !important; }
.frog-fg-6 { color:#463a49 !important; }
.frog-bg-6 { background-color:#463a49 !important; }
.frog-fg-ex-1 { color:#ffffff !important; }
.frog-bg-ex-1 { background-color:#ffffff !important; }
.frog-fg-ex-2 { color:#000000 !important; }
.frog-bg-ex-2 { background-color:#000000 !important; }
.frog-fg-vibrant { color:#ffd807 !important; }
.frog-bg-vibrant { background-color:#ffd807 !important; }
.frog-fg-muted-dark { color:#2b5557 !important; }
.frog-bg-muted-dark { background-color:#2b5557 !important; }
.frog-fg-muted { color:#589964 !important; }
.frog-bg-muted { background-color:#589964 !important; }
.frog-fg-vibrant-light { color:#a3e0da !important; }
.frog-bg-vibrant-light { background-color:#a3e0da !important; }
.frog-fg-muted-light { color:#d2cfb7 !important; }
.frog-bg-muted-light { background-color:#d2cfb7 !important; }
.frog-fg-vibrant-dark { color:#018f53 !important; }
.frog-bg-vibrant-dark { background-color:#018f53 !important; }

Here’s how this works in practice:

<link rel="stylesheet" href="https://static.imgix.net/treefrog.jpg?palette=css&class=frog">

A very colorful little frog

Original Palette
Dominance Palette

As mentioned above, the palette calculations are done after all other resizing and enhancement operations. Here ’s the same image with a sepia filter applied:

<link rel="stylesheet" href="https://static.imgix.net/treefrog.jpg?palette=css&colors=8&sepia=80&class=frog2">

A more subdued, sepia-tone frog

Original Palette
Dominance Palette

palette=json

The response will be a JSON object with the application/json MIME type. The JSON object has three top-level properties: a floating-point average_luminance value, a colors array of colors for the original palette, and a dominant_colors array that represents the Vibrant.js-style values.

Each color in the colors and dominant_colors arrays contains a hash describing its red, green, and blue components (expressed as floating point numbers between 0.0 and 1.0), and a hex value.

If palette is set to json, the prefix parameter is ignored.

Here is the JSON payload from the tree frog image used above:

{
  "average_luminance":0.293949,
  "colors":[
    {
      "red":1,
      "hex":"#ffd807",
      "blue":0.027451,
      "green":0.847059
    },
    {
      "red":0.427451,
      "hex":"#6dca9a",
      "blue":0.603922,
      "green":0.792157
    },
    {
      "red":0.0509804,
      "hex":"#0da46e",
      "blue":0.431373,
      "green":0.643137
    },
    {
      "red":0.592157,
      "hex":"#971d01",
      "blue":0.00392157,
      "green":0.113725
    },
    {
      "red":0.337255,
      "hex":"#566363",
      "blue":0.388235,
      "green":0.388235
    },
    {
      "red":0.27451,
      "hex":"#463a49",
      "blue":0.286275,
      "green":0.227451
    }
  ],
  "dominant_colors":{
    "vibrant":{
      "red":1,
      "hex":"#ffd807",
      "blue":0.027451,
      "green":0.847059
    },
    "muted_light":{
      "red":0.823529,
      "hex":"#d2cfb7",
      "blue":0.717647,
      "green":0.811765
    },
    "muted":{
      "red":0.345098,
      "hex":"#589964",
      "blue":0.392157,
      "green":0.6
    },
    "vibrant_dark":{
      "red":0.00392157,
      "hex":"#018f53",
      "blue":0.32549,
      "green":0.560784
    },
    "vibrant_light":{
      "red":0.639216,
      "hex":"#a3e0da",
      "blue":0.854902,
      "green":0.878431
    },
    "muted_dark":{
      "red":0.168627,
      "hex":"#2b5557",
      "blue":0.341176,
      "green":0.333333
    }
  }
}