Image

The Image.dominant_color/2 function supports two different methods for extracting dominant colors, each with different performance and quality characteristics:

1. :histogram (Default)

   • How it works: Uses a coarse 3D RGB histogram via vips_hist_find_ndim to return the centers of the most populated bins.
   • Performance: Extremely fast (two to three orders of magnitude faster than :imagequant). It scales well with image size and its cost barely increases with the number of colors requested (top_n).
   • Best for: Hot paths, bulk processing, or simple questions like "what is the overall dominant color?"
   • Output: Colors are quantized to the centers of a fixed 3D grid.

2. :imagequant

   • How it works: Routes through vips_gifsave_buffer to run libimagequant, creating a quantized Global Color Table (GCT). The GCT is then parsed into RGB tuples ordered by perceptual importance.
   • Performance: Significantly slower. The cost scales with both pixel count and the number of colors requested (top_n).
   • Best for: High-quality color extraction where palette quality matters more than latency (e.g., building UI swatches or accents from photographs).
   • Output: Perceptually representative colors.

Optimizing :imagequant with :effort

You can control the quantization quality/speed using the :effort option. On larger images, dropping from the default effort: 7 to effort: 3 can cut runtime by approximately 5× with minimal perceived quality loss.

# Example usage (conceptual)
Image.dominant_color(image, :histogram, top_n: 5)
Image.dominant_color(image, :imagequant, top_n: 5, effort: 3)

To render the placeholders, include the following CSS in your stylesheet. This CSS is a verbatim copy of the reference implementation and uses relative color syntax to unpack the 32-bit hex value into three distinct colors and apply them as radial gradients.

[data-lqip] {
  --lqip-c: attr(data-lqip type(<color>), white);
}

[style*="--lqip:"] {
  --lqip-c: var(--lqip);
}

[style*="--lqip"],
[data-lqip] {
  --lqip-c0: color(
    from var(--lqip-c) srgb calc(round(down, r * 255 / pow(2, 4)) / 15)
      calc(mod(round(down, r * 255), pow(2, 4)) / 15)
      calc(round(down, g * 255 / pow(2, 5)) / 7) / 1
  );

  --lqip-c1: color(
    from var(--lqip-c) srgb calc(mod(round(down, g * 255 / 2), pow(2, 4)) / 15)
      calc(
        (
            (mod(round(down, g * 255), 2) * pow(2, 3)) +
              (round(down, b * 255 / pow(2, 5)))
          ) /
          15
      )
      calc(mod(round(down, b * 255 / pow(2, 2)), pow(2, 3)) / 7) / 1
  );

  --lqip-c2: color(
    from var(--lqip-c) srgb
      calc(
        (
            ((mod(round(down, b * 255), pow(2, 2)) * 2)) +
              round(down, alpha * 255 / pow(2, 7))
          ) /
          7
      )
      calc(mod(round(down, alpha * 255 / pow(2, 3)), pow(2, 4)) / 15)
      calc(mod(round(down, alpha * 255), pow(2, 3)) / 7) / 1
  );

  background:
    radial-gradient(
      150% 75% at 80% 100%,
      var(--lqip-c2),
      rgb(from var(--lqip-c2) r g b / 98%) 10%,
      rgb(from var(--lqip-c2) r g b / 92%) 20%,
      rgb(from var(--lqip-c2) r g b / 82%) 30%,
      rgb(from var(--lqip-c2) r g b / 68%) 40%,
      rgb(from var(--lqip-c2) r g b / 32%) 60%,
      rgb(from var(--lqip-c2) r g b / 18%) 70%,
      rgb(from var(--lqip-c2) r g b / 8%) 80%,
      rgb(from var(--lqip-c2) r g b / 2%) 90%,
      transparent
    ),
    radial-gradient(
      100% 75% at 40% 50%,
      var(--lqip-c1),
      rgb(from var(--lqip-c1) r g b / 98%) 10%,
      rgb(from var(--lqip-c1) r g b / 92%) 20%,
      rgb(from var(--lqip-c1) r g b / 82%) 30%,
      rgb(from var(--lqip-c1) r g b / 68%) 40%,
      rgb(from var(--lqip-c1) r g b / 32%) 60%,
      rgb(from var(--lqip-c1) r g b / 18%) 70%,
      rgb(from var(--lqip-c1) r g b / 8%) 80%,
      rgb(from var(--lqip-c1) r g b / 2%) 90%,
      transparent
    ),
    var(--lqip-c0);
}```

When using Image.compose/3, you can specify a blend mode to determine how two images are combined. The Image.BlendMode module provides a set of Elixir-friendly atoms that map to underlying libvips modes.

Available Modes

• :over: (Default) Shows the top image over the bottom image (like two semi-transparent slides).
• :clear: Removes the first image where the second is drawn.
• :source: Draws the second image as if nothing were below it.
• :in: The first image is removed; the second is only drawn where the first was.
• :out: The second is drawn only where the first isn't.
• :atop: Leaves the first image mostly intact, but mixes both in the overlapping area.
• :dest: Leaves the first image untouched; the second is discarded.
• :dest_over: Swaps the arguments of :over.
• :dest_in: Swaps the arguments of :in.
• :dest_out: Swaps the arguments of :out.
• :dest_atop: Swaps the arguments of :atop.
• :xor: A difference-style operator.
• :add: Adds the two images together.
• :saturate: Uses the darker of the two.
• :multiply: At least as dark as the darker of the two inputs.
• :screen: At least as light as the lighter of the inputs.
• :overlay: Multiplies or screens colors depending on lightness.
• :darken: The darker of each component.
• :lighten: The lighter of each component.
• :colour_dodge: Brightens the first by a factor of the second.
• :colour_burn: Darkens the first by a factor of the second.
• :hard_light: Multiplies or screens depending on lightness.
• :soft_light: Darkens or lightens depending on lightness.
• :difference: The difference between the two.
• :exclusion: Similar to :difference, but with lower contrast.