Color Palette Extraction
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
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 Dark
- Vibrant Light
- 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.
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 colorPalette-swatch set easier.
prefix is also set, its value will replace "image" in the CSS class names in the output CSS file.
Here's how this works in practice:
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:
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
dominant_colors arrays contains a hash describing its
blue components (expressed as floating point numbers between 0.0 and 1.0), and a
palette is set to
prefix parameter is ignored.
Here is the JSON payload from the tree frog image used above:
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.
See the API specification for more information about this parameter's value ranges and format.