Color Palette Extraction

palette

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 does.

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 image 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 colorPaletteSwatch set easier.

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

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

Here’s how this works in practice:

<link
  rel="stylesheet"
  href="https://static.imgix.net/treefrog.jpg?w=640&h=320&fit=crop&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, and with the palettes limited to six colors:

<link
  rel="stylesheet"
  href="https://static.imgix.net/treefrog.jpg?w=640&h=320&fit=crop&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
    }
  }
}

Please note:

Using colorquant will not affect the results of the palette parameter. The colorquant parameter limits the number of colors that display based off the base image; however, these colors still exist within the image data itself.

Color Palette CSS Prefix