toxiclibs 0.2-java → 0.5.0-java

data/src/toxi/color/Histogram.java

@@ -0,0 +1,185 @@
+/*
+ *   __               .__       .__  ._____.           
+ * _/  |_  _______  __|__| ____ |  | |__\_ |__   ______
+ * \   __\/  _ \  \/  /  |/ ___\|  | |  || __ \ /  ___/
+ *  |  | (  <_> >    <|  \  \___|  |_|  || \_\ \\___ \ 
+ *  |__|  \____/__/\_ \__|\___  >____/__||___  /____  >
+ *                   \/       \/             \/     \/ 
+ *
+ * Copyright (c) 2006-2011 Karsten Schmidt
+ * 
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ * 
+ * http://creativecommons.org/licenses/LGPL/2.1/
+ * 
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
+ */
+
+package toxi.color;
+
+import java.util.ArrayList;
+import java.util.Collections;
+import java.util.Iterator;
+import java.util.List;
+
+import toxi.math.MathUtils;
+
+/**
+ * This class can be used to compute the distribution frequency of colors within
+ * a given {@link 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.
+ * 
+ */
+public class Histogram implements Iterable<HistEntry> {
+
+    /**
+     * 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
+     * {@link 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.
+     * 
+     * @see #compute(float, boolean)
+     * 
+     * @param pixels
+     *            source pixel buffer (in ARGB format), alpha is ignored though
+     * @param numSamples
+     *            number of random samples. If the number of samples equals or
+     *            exceeds the number of pixels, NO RANDOM samples are used.
+     * @param tolerance
+     *            normalized grouping tolerance, e.g. 0.2 = 20%
+     * @param blendCols
+     *            flag to enable automatic blending of result colors.
+     * @return histogram instance
+     */
+    public static Histogram newFromARGBArray(int[] pixels, int numSamples,
+            float tolerance, boolean blendCols) {
+        Histogram h = new Histogram(ColorList.createFromARGBArray(pixels,
+                numSamples, false));
+        h.compute(tolerance, blendCols);
+        return h;
+    }
+
+    /**
+     *
+     */
+    protected ColorList palette;
+
+    /**
+     *
+     */
+    protected ArrayList<HistEntry> entries;
+
+    /**
+     * Constructs a new instance for the given {@link ColorList}.
+     * 
+     * @param palette
+     *            list of source colors
+     */
+    public Histogram(ColorList palette) {
+        this.palette = palette;
+    }
+
+    /**
+     * Computes the histogram for the given {@link 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.
+     * 
+     * @see TColor#distanceToRGB(ReadonlyTColor)
+     * 
+     * @param tolerance
+     *            normalized grouping tolerance, 0.0 .. 1.0 interval, e.g. 0.2 =
+     *            20%
+     * @param blendCols
+     *            flag to enable automatic blending of result colors.
+     * @return sorted histogram as List of HistEntry
+     */
+    public List<HistEntry> compute(float tolerance, boolean blendCols) {
+        entries = new ArrayList<>(palette.size() / 4);
+        float maxFreq = 1;
+        tolerance /= MathUtils.SQRT3;
+        for (TColor c : palette) {
+            HistEntry existing = null;
+            for (HistEntry e : entries) {
+                if (e.col.distanceToRGB(c) < tolerance) {
+                    if (blendCols) {
+                        e.col.blend(c, 1f / (e.freq + 1));
+                    }
+                    existing = e;
+                    break;
+                }
+            }
+            if (existing != null) {
+                existing.freq++;
+                if (existing.freq > maxFreq) {
+                    maxFreq = existing.freq;
+                }
+            } else {
+                entries.add(new HistEntry(c));
+            }
+        }
+        Collections.sort(entries);
+        maxFreq = 1f / palette.size();
+        for (HistEntry e : entries) {
+            e.freq *= maxFreq;
+        }
+        return entries;
+    }
+
+    /**
+     * Returns the list of {@link HistEntry} elements produced by the
+     * {@link #compute(float, boolean)} method.
+     * 
+     * @return the histogram entries
+     */
+    public List<HistEntry> getEntries() {
+        return entries;
+    }
+
+    /**
+     * Returns the list of source colors
+     * 
+     * @return the palette
+     */
+    public ColorList getPalette() {
+        return palette;
+    }
+
+    /**
+     * Returns an iterator of the underlying list of {@link HistEntry} elements.
+     * That way, the Histogram instance itself can be directly used in for()
+     * loops processing the entries.
+     * @return 
+     */
+    public Iterator<HistEntry> iterator() {
+        return entries.iterator();
+    }
+
+    /**
+     * Configures the histogram instance to use a new list of source colors.
+     * 
+     * @param palette
+     *            the palette to set
+     */
+    public void setPalette(ColorList palette) {
+        this.palette = palette;
+    }
+}

data/src/toxi/color/Hue.java

@@ -0,0 +1,249 @@
+/*
+ * Some classes in this package have been partly inspired by & bits ported from
+ * Python code written by Tom De Smedt & Frederik De Bleser for the "colors" library
+ * of Nodebox.net.
+ * 
+ * http://nodebox.net/code/index.php/Colors
+ *
+ * Copyright (c) 2006-2011 Karsten Schmidt
+ * 
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ * 
+ * http://creativecommons.org/licenses/LGPL/2.1/
+ * 
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
+ */
+
+package toxi.color;
+
+import java.util.ArrayList;
+import java.util.HashMap;
+
+import toxi.math.MathUtils;
+
+/**
+ * This class defines color hues and allows them to be access by name. There are
+ * also methods to check if a hue is one of the 7 primary hues (rainbow) or to
+ * find the closest defined hue for a given color.
+ */
+public class Hue {
+
+    /**
+     *
+     */
+    protected static final HashMap<String, Hue> namedHues = new HashMap<>();
+
+    /**
+     *
+     */
+    protected static final ArrayList<Hue> primaryHues = new ArrayList<>();
+
+    /**
+     *
+     */
+    public static final Hue RED = new Hue("red", 0, true);
+
+    /**
+     *
+     */
+    public static final Hue ORANGE = new Hue("orange", 30 / 360.0f, true);
+
+    /**
+     *
+     */
+    public static final Hue YELLOW = new Hue("yellow", 60 / 360.0f, true);
+
+    /**
+     *
+     */
+    public static final Hue LIME = new Hue("lime", 90 / 360.0f);
+
+    /**
+     *
+     */
+    public static final Hue GREEN = new Hue("green", 120 / 360.0f, true);
+
+    /**
+     *
+     */
+    public static final Hue TEAL = new Hue("teal", 150 / 360.0f);
+
+    /**
+     *
+     */
+    public static final Hue CYAN = new Hue("cyan", 180 / 360.0f);
+
+    /**
+     *
+     */
+    public static final Hue AZURE = new Hue("azure", 210 / 360.0f);
+
+    /**
+     *
+     */
+    public static final Hue BLUE = new Hue("blue", 240 / 360.0f, true);
+
+    /**
+     *
+     */
+    public static final Hue INDIGO = new Hue("indigo", 270 / 360.0f);
+
+    /**
+     *
+     */
+    public static final Hue PURPLE = new Hue("purple", 300 / 360.0f, true);
+
+    /**
+     *
+     */
+    public static final Hue PINK = new Hue("pink", 330 / 360.0f, true);
+
+    /**
+     * Tolerance value for checking if a given hue is primary (default 0.01)
+     */
+    public static float PRIMARY_VARIANCE = 0.01f;
+
+    /**
+     * Finds the closest defined & named Hue for the given hue value.
+     * Optionally, the search can be limited to primary hues only.
+     * 
+     * @param hue
+     *            normalized hue (0.0 ... 1.0) will be automatically wrapped
+     * @param primaryOnly
+     *            only consider the 7 primary hues
+     * @return closest Hue instance
+     */
+    public static final Hue getClosest(float hue, boolean primaryOnly) {
+        hue %= 1;
+        float dist = Float.MAX_VALUE;
+        Hue closest = null;
+        Iterable<Hue> hues = (primaryOnly ? primaryHues : namedHues.values());
+        for (Hue h : hues) {
+            float d = MathUtils.min(MathUtils.abs(h.hue - hue),
+                    MathUtils.abs(1 + h.hue - hue));
+            if (d < dist) {
+                dist = d;
+                closest = h;
+            }
+        }
+        return closest;
+    }
+
+    /**
+     *
+     * @param name
+     * @return
+     */
+    public static final Hue getForName(String name) {
+        return namedHues.get(name.toLowerCase());
+    }
+
+    /**
+     *
+     * @param hue
+     * @return
+     */
+    public static boolean isPrimary(float hue) {
+        return isPrimary(hue, PRIMARY_VARIANCE);
+    }
+
+    /**
+     *
+     * @param hue
+     * @param variance
+     * @return
+     */
+    public static boolean isPrimary(float hue, float variance) {
+        boolean isPrimary = false;
+        for (Hue h : primaryHues) {
+            if (MathUtils.abs(hue - h.hue) < variance) {
+                isPrimary = true;
+                break;
+            }
+        }
+        return isPrimary;
+    }
+
+    /**
+     *
+     */
+    protected String name;
+
+    /**
+     *
+     */
+    protected float hue;
+
+    /**
+     *
+     */
+    protected boolean isPrimary;
+
+    /**
+     *
+     * @param name
+     * @param hue
+     */
+    public Hue(String name, float hue) {
+        this(name, hue, false);
+    }
+
+    /**
+     *
+     * @param name
+     * @param hue
+     * @param isPrimary
+     */
+    public Hue(String name, float hue, boolean isPrimary) {
+        this.name = name;
+        this.hue = hue;
+        this.isPrimary = isPrimary;
+        namedHues.put(name, this);
+        if (isPrimary) {
+            primaryHues.add(this);
+        }
+    }
+
+    /**
+     *
+     * @return
+     */
+    public float getHue() {
+        return hue;
+    }
+
+    /**
+     *
+     * @return
+     */
+    public String getName() {
+        return name;
+    }
+
+    /**
+     *
+     * @return
+     */
+    public boolean isPrimary() {
+        return isPrimary;
+    }
+
+    /**
+     *
+     * @return
+     */
+    @Override
+    public String toString() {
+        return "Hue: ID:" + name + " @ " + (int) (hue * 360) + " degrees";
+    }
+}

data/src/toxi/color/LuminanceAccessor.java

@@ -0,0 +1,78 @@
+/*
+ *   __               .__       .__  ._____.           
+ * _/  |_  _______  __|__| ____ |  | |__\_ |__   ______
+ * \   __\/  _ \  \/  /  |/ ___\|  | |  || __ \ /  ___/
+ *  |  | (  <_> >    <|  \  \___|  |_|  || \_\ \\___ \ 
+ *  |__|  \____/__/\_ \__|\___  >____/__||___  /____  >
+ *                   \/       \/             \/     \/ 
+ *
+ * Copyright (c) 2006-2011 Karsten Schmidt
+ * 
+ * This library is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 2.1 of the License, or (at your option) any later version.
+ * 
+ * http://creativecommons.org/licenses/LGPL/2.1/
+ * 
+ * This library is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+ * Lesser General Public License for more details.
+ * 
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with this library; if not, write to the Free Software
+ * Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA
+ */
+
+package toxi.color;
+
+/**
+ * Compares 2 colors by their luminance values.
+ */
+public class LuminanceAccessor extends AccessCriteria {
+
+    /**
+     *
+     * @param a
+     * @param b
+     * @return
+     */
+    @Override
+    public int compare(ReadonlyTColor a, ReadonlyTColor b) {
+        float lumA = a.luminance();
+        float lumB = b.luminance();
+        if (lumA < lumB) {
+            return -1;
+        }
+        if (lumA > lumB) {
+            return 1;
+        } else {
+            return 0;
+        }
+    }
+
+    /**
+     *
+     * @param col
+     * @return
+     */
+    @Override
+    public float getComponentValueFor(ReadonlyTColor col) {
+        return col.luminance();
+    }
+
+    /**
+     * The setter for this accessor is not doing anything, since the luminance
+     * of a color is a coputed value depending on 3 color channels.
+     * 
+     * @param col
+     * @param value
+     * @see toxi.color.AccessCriteria#setComponentValueFor(toxi.color.TColor,
+     *      float)
+     */
+    @Override
+    public void setComponentValueFor(TColor col, float value) {
+
+    }
+}