toxi.color
Class ColorList

java.lang.Object
  extended by toxi.color.ColorList
All Implemented Interfaces:
java.lang.Iterable<TColor>

public class ColorList
extends java.lang.Object
implements java.lang.Iterable<TColor>

A container class of concrete colors. ColorLists can be built manually and are also created when working with ColorRanges. The class has various methods to manipulate all colors in the list in parallel, as well as sort them by various criteria.

See Also:
ColorRange, AccessCriteria

Constructor Summary
ColorList()
          Creates an empty list.
ColorList(java.util.Collection<TColor> colors)
          Creates a ColorList by wrapping the given ArrayList of colors.
ColorList(ColorList list)
          Creates a deep copy of the given ColorList.
ColorList(int[] argbArray)
          Creates a new color list from the array of ARGB int values.
ColorList(ReadonlyTColor... colorArray)
          Creates new ColorList from the given number of colors.
 
Method Summary
 ColorList add(ReadonlyTColor c)
          Adds the given color to the list
 ColorList addAll(java.util.Collection<TColor> collection)
          Adds all entries of the TColor collection to the list (shallow copy only, manipulating the new list will modify the original colors).
 ColorList adjustBrightness(float step)
          Adjusts the brightness component of all list colors by the given amount.
 ColorList adjustSaturation(float step)
          Adjusts the saturation component of all list colors by the given amount.
 ColorList clusterSort(AccessCriteria clusterCriteria, AccessCriteria subClusterCriteria, int numClusters, boolean isReversed)
          Sorts the list based on two criteria to create clusters/segments within the list.
 ColorList complement()
          Switches all list colors to their complementary color.
 boolean contains(ReadonlyTColor color)
          Checks if the given color is part of the list.
static ColorList createFromARGBArray(int[] pixels, int num, boolean uniqueOnly)
          Factory method.
static ColorList createFromARGBArray(int[] pixels, int num, boolean uniqueOnly, int maxIterations)
          Factory method.
static ColorList createUsingStrategy(ColorTheoryStrategy strategy, TColor c)
          Factory method.
static ColorList createUsingStrategy(java.lang.String name, TColor c)
          Factory method.
 TColor get(int i)
          Returns the color at the given index.
 ReadonlyTColor getAverage()
          Calculates and returns the average color of the list.
 ColorList getBlended(float amount)
          Creates a new ColorList by blending all colors in the list with each other (successive indices only)
 TColor getDarkest()
          Finds and returns the darkest color of the list.
 ReadonlyTColor getLightest()
          Finds and returns the lightest (luminance) color of the list.
 TColor getRandom()
           
 ColorList getReverse()
          Returns a reversed copy of the current list.
 ColorList invert()
          Inverts all colors in the list.
 java.util.Iterator<TColor> iterator()
          Returns an iterator over the internal list.
 ColorList reverse()
          Reverses the current order of the list.
 ColorList rotateRYB(float theta)
          Rotates the hues of all colors in the list by the given amount.
 ColorList rotateRYB(int angle)
          Rotates the hues of all colors in the list by the given amount.
 int size()
           
 ColorList sort()
          Convenience method.
 ColorList sortByComparator(java.util.Comparator<ReadonlyTColor> comp, boolean isReversed)
          Sorts the list using the given comparator.
 ColorList sortByCriteria(AccessCriteria criteria, boolean isReversed)
          Sorts the list using the given AccessCriteria.
 ColorList sortByDistance(boolean isReversed)
          Sorts the list by relative distance to each predecessor, starting with the darkest color in the list.
 ColorList sortByDistance(DistanceProxy proxy, boolean isReversed)
          Sorts the list by relative distance to each predecessor, starting with the darkest color in the list.
 ColorList sortByProximityTo(ReadonlyTColor target, boolean isReversed)
          Sorts the list by proximity to the given target color (using RGB distance metrics).
 ColorList sortByProximityTo(ReadonlyTColor target, DistanceProxy proxy, boolean isReversed)
          Sorts the list by proximity to the given target color using the given DistanceProxy implementation.
 int[] toARGBArray()
          Creates an ARGB integer array of the list items.
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

ColorList

public ColorList()
Creates an empty list.


ColorList

public ColorList(java.util.Collection<TColor> colors)
Creates a ColorList by wrapping the given ArrayList of colors. No copies of the given colors are created (shallow copy only).

Parameters:
colors -

ColorList

public ColorList(ColorList list)
Creates a deep copy of the given ColorList. Manipulating the new list does NOT change the colors of the original.

Parameters:
list - source list

ColorList

public ColorList(int[] argbArray)
Creates a new color list from the array of ARGB int values.

Parameters:
argbArray -

ColorList

public ColorList(ReadonlyTColor... colorArray)
Creates new ColorList from the given number of colors. Copies of the given colors are created (shallow copy only).

Parameters:
colorArray -
Method Detail

createFromARGBArray

public static final ColorList createFromARGBArray(int[] pixels,
                                                  int num,
                                                  boolean uniqueOnly)
Factory method. Creates a new ColorList of colors sampled from the given ARGB image array.

Parameters:
pixels - int array of ARGB pixels
num - number of colors samples (clipped automatically to number of pixels in the image)
uniqueOnly - flag if only unique samples are to be taken (doesn't guarantee unique colors though)
Returns:
new color list

createFromARGBArray

public static final ColorList createFromARGBArray(int[] pixels,
                                                  int num,
                                                  boolean uniqueOnly,
                                                  int maxIterations)
Factory method. Creates a new ColorList of colors sampled from the given ARGB image array.

Parameters:
pixels - int array of ARGB pixels
num - number of colors samples (clipped automatically to number of pixels in the image)
uniqueOnly - flag if only unique samples are to be taken (doesn't guarantee unique colors though)
maxIterations - max number of attempts to find a unique color
Returns:
new color list

createUsingStrategy

public static final ColorList createUsingStrategy(ColorTheoryStrategy strategy,
                                                  TColor c)
Factory method. Creates a new ColorList based on the given ColorTheoryStrategy instance and the given source color.

Parameters:
strategy -
c -
Returns:
new list

createUsingStrategy

public static final ColorList createUsingStrategy(java.lang.String name,
                                                  TColor c)
Factory method. Creates a ColorList based on the ColorTheoryStrategy name and the given source color.

Parameters:
name -
c -
Returns:
new color list or null, if the supplied strategy name is not mapped to a registered implementation.

add

public ColorList add(ReadonlyTColor c)
Adds the given color to the list

Parameters:
c -
Returns:
itself

addAll

public ColorList addAll(java.util.Collection<TColor> collection)
Adds all entries of the TColor collection to the list (shallow copy only, manipulating the new list will modify the original colors).

Parameters:
collection -
Returns:
itself

adjustBrightness

public ColorList adjustBrightness(float step)
Adjusts the brightness component of all list colors by the given amount.

Parameters:
step - adjustment value
Returns:
itself

adjustSaturation

public ColorList adjustSaturation(float step)
Adjusts the saturation component of all list colors by the given amount.

Parameters:
step - adjustment value
Returns:
itself

clusterSort

public ColorList clusterSort(AccessCriteria clusterCriteria,
                             AccessCriteria subClusterCriteria,
                             int numClusters,
                             boolean isReversed)
Sorts the list based on two criteria to create clusters/segments within the list.

Parameters:
clusterCriteria - main sort criteria
subClusterCriteria - secondary sort criteria
numClusters - number of clusters
isReversed - true, if reversed sort
Returns:
itself

complement

public ColorList complement()
Switches all list colors to their complementary color.

Returns:
itself

contains

public boolean contains(ReadonlyTColor color)
Checks if the given color is part of the list. Check is done by value, not instance.

Parameters:
color -
Returns:
true, if the color is present.

get

public TColor get(int i)
Returns the color at the given index.

Parameters:
i -
Returns:
color

getAverage

public ReadonlyTColor getAverage()
Calculates and returns the average color of the list.

Returns:
average color or null, if there're no entries yet.

getBlended

public ColorList getBlended(float amount)
Creates a new ColorList by blending all colors in the list with each other (successive indices only)

Parameters:
amount - blend amount
Returns:
new color list

getDarkest

public TColor getDarkest()
Finds and returns the darkest color of the list.

Returns:
darkest color or null if there're no entries yet.

getLightest

public ReadonlyTColor getLightest()
Finds and returns the lightest (luminance) color of the list.

Returns:
lightest color or null, if there're no entries yet.

getRandom

public TColor getRandom()

getReverse

public ColorList getReverse()
Returns a reversed copy of the current list.

Returns:
reversed copy of the list

invert

public ColorList invert()
Inverts all colors in the list.

Returns:
itself

iterator

public java.util.Iterator<TColor> iterator()
Returns an iterator over the internal list. This means the list can be accessed via standard Iterator loops.

Specified by:
iterator in interface java.lang.Iterable<TColor>
Returns:
list iterator

reverse

public ColorList reverse()
Reverses the current order of the list.

Returns:
itself

rotateRYB

public ColorList rotateRYB(float theta)
Rotates the hues of all colors in the list by the given amount.

Parameters:
theta - rotation angle in radians
Returns:
itself

rotateRYB

public ColorList rotateRYB(int angle)
Rotates the hues of all colors in the list by the given amount.

Parameters:
angle - rotation angle in degrees
Returns:
itself

size

public int size()
Returns:
the number of colors in the list

sort

public ColorList sort()
Convenience method. Sorts the list by hue.

Returns:
itself

sortByComparator

public ColorList sortByComparator(java.util.Comparator<ReadonlyTColor> comp,
                                  boolean isReversed)
Sorts the list using the given comparator.

Parameters:
comp - comparator
isReversed - true, if reversed sort
Returns:
itself

sortByCriteria

public ColorList sortByCriteria(AccessCriteria criteria,
                                boolean isReversed)
Sorts the list using the given AccessCriteria.

Parameters:
criteria - sort criteria
isReversed - true, if reversed sort
Returns:
itself

sortByDistance

public ColorList sortByDistance(boolean isReversed)
Sorts the list by relative distance to each predecessor, starting with the darkest color in the list.

Parameters:
isReversed - true, if list is to be sorted in reverse.
Returns:
itself

sortByDistance

public ColorList sortByDistance(DistanceProxy proxy,
                                boolean isReversed)
Sorts the list by relative distance to each predecessor, starting with the darkest color in the list.

Parameters:
isReversed - true, if list is to be sorted in reverse.
Returns:
itself

sortByProximityTo

public ColorList sortByProximityTo(ReadonlyTColor target,
                                   boolean isReversed)
Sorts the list by proximity to the given target color (using RGB distance metrics).

Parameters:
target - color
isReversed - true, if reverse sorted
Returns:
sorted list
See Also:
sortByProximityTo(ReadonlyTColor, DistanceProxy, boolean)

sortByProximityTo

public ColorList sortByProximityTo(ReadonlyTColor target,
                                   DistanceProxy proxy,
                                   boolean isReversed)
Sorts the list by proximity to the given target color using the given DistanceProxy implementation.

Parameters:
target - color
proxy - distance metrics
isReversed - true, if reverse sorted
Returns:
sorted list

toARGBArray

public int[] toARGBArray()
Creates an ARGB integer array of the list items.

Returns:
all list colors as ARGB values