Package toxi.color

Class Histogram

java.lang.Object
toxi.color.Histogram
All Implemented Interfaces:
Iterable<HistEntry>
public class Histogram extends Object implements Iterable<HistEntry>
This class can be used to compute the distribution frequency of colors within a given ColorList. In other words, it will provide some statistics of how many times each color occurs within the list. In most cases the source for this ColorList will be the pixel buffer of an image. The calculation of the histogram works with tolerances, allowing similar colors to be grouped (and blended) and so can be used to produce results of varying precision.

  • Constructor Details

    • Histogram

      public Histogram(ColorList palette)
      Constructs a new instance for the given ColorList.
      Parameters:
      palette - list of source colors

  • Method Details

    • newFromARGBArray

      public static Histogram newFromARGBArray(int[] pixels, int numSamples, float tolerance, boolean blendCols)
      Creates a new histogram of random color samples taken from the given ARGB array in order to identify the most frequently used colors in the image. This is a convenience factory method which internally uses ColorList.createFromARGBArray(int[], int, boolean, int) to sample the image before computing the histogram. Supports blending of grouped result colors. If enabled, the colors returned in the histogram will be averaged for each group based on the given tolerance. If disabled, only the first color found for each tolerance group is used.
      Parameters:
      pixels - source pixel buffer (in ARGB format), alpha is ignored though
      numSamples - number of random samples. If the number of samples equals or exceeds the number of pixels, NO RANDOM samples are used.
      tolerance - normalized grouping tolerance, e.g. 0.2 = 20%
      blendCols - flag to enable automatic blending of result colors.
      Returns:
      histogram instance
      See Also:

    • compute

      public List<HistEntry> compute(float tolerance, boolean blendCols)
      Computes the histogram for the given ColorList. Supports blending of grouped result colors. If enabled, the colors returned in the histogram will be averaged for each group based on the given tolerance (using RGB distances). If disabled, only the first color found for each tolerance group is used.
      Parameters:
      tolerance - normalized grouping tolerance, 0.0 .. 1.0 interval, e.g. 0.2 = 20%
      blendCols - flag to enable automatic blending of result colors.
      Returns:
      sorted histogram as List of HistEntry
      See Also:

    • getEntries

      public List<HistEntry> getEntries()
      Returns the list of HistEntry elements produced by the compute(float, boolean) method.
      Returns:
      the histogram entries

    • getPalette

      public ColorList getPalette()
      Returns the list of source colors
      Returns:
      the palette

    • iterator

      public Iterator<HistEntry> iterator()
      Returns an iterator of the underlying list of HistEntry elements. That way, the Histogram instance itself can be directly used in for() loops processing the entries.
      Specified by:
      iterator in interface Iterable<HistEntry>

    • setPalette

      public void setPalette(ColorList palette)
      Configures the histogram instance to use a new list of source colors.
      Parameters:
      palette - the palette to set