Package toxi.color

Class ColorList

java.lang.Object
toxi.color.ColorList
All Implemented Interfaces:
Iterable<TColor>
public class ColorList extends Object implements 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:

  • Constructor Details

    • ColorList

      public ColorList()
      Creates an empty list.

    • ColorList

      public ColorList(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 or its color entries does NOT change the colors of the original.
      Parameters:
      list - source list to copy

    • ColorList

      public ColorList(int[] argbArray)
      Creates a new color list from the array of ARGB int values. In most cases this will be the pixel buffer of an image.
      Parameters:
      argbArray -

    • ColorList

      public ColorList(ReadonlyTColor... colorArray)
      Creates new ColorList from the given colors. Copies of the given colors are created. This is a varargs constructor allowing these two parameter formats: 
       // individual parameters
 ColorList cols=new ColorList(TColor.BLACK,TColor.WHITE,TColor.newRGB(1,0,0));
 
 // or array of colors
 ReadonlyTColor[] colArray=new ReadonlyTColor[] {
   TColor.BLACK,TColor.WHITE,TColor.newRGB(1,0,0);
 };
 ColorList cols=new ColorList(colArray);
      Parameters:
      colorArray -

  • Method Details

    • 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. If the number of samples equals or exceeds the number of pixels in the image and no unique colors are required, the function will simply return the same as ColorList(int[]).
      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 randomly sampled from the given ARGB image array. If the number of samples equals or exceeds the number of pixels in the source image and no unique colors are required, the function will simply return the same as ColorList(int[]).
      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. If no more unique colors can be found the search is terminated.
      Returns:
      new color list of samples

    • 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. The number of colors returned will vary with the strategy chosen.
      Parameters:
      strategy -
      c -
      Returns:
      new list

    • createUsingStrategy

      public static final ColorList createUsingStrategy(String name, TColor c)
      Factory method. Creates a ColorList based on the name of a ColorTheoryStrategy and the given source color.
      Parameters:
      name - strategy 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 a copy of the given color to the list
      Parameters:
      c -
      Returns:
      itself

    • addAll

      public ColorList addAll(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. This function follows Python convention, in that if the index is negative, it is considered relative to the list end. Therefore the color at index -1 is the last color in the list.
      Parameters:
      i - index
      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 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 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(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

      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