net.returnvoid.color

Class ColorPalette

java.lang.Object

net.returnvoid.color.ColorPalette

public class ColorPalette
extends java.lang.Object

Class for storing multiple colors. The importance of the color within the color palette can be weighted. It is possible to retrieve colors of the palette by:
(1) index
(2) a given color (will return the most similar color of the palette to the input)
(3) random
(4) weighted random : more important colors will be returned more often the less important colors

Author:

Diana Lange

Constructor Summary

Constructors

Constructor and Description
ColorPalette() Builds an empty color palette.
ColorPalette(java.util.ArrayList<RColor> colors) Creates a color palette with the given colors.
ColorPalette(int[] colors) Creates a color palette with the given colors.
ColorPalette(RColor[] colors) Creates a color palette with the given colors.
ColorPalette(java.lang.String jsonString) Builds an ColorPalette out of a JSON-styled String.

Method Summary

Modifier and Type	Method and Description
ColorPalette	add(int c) Adds a color to this palette.
ColorPalette	add(int c, int importance) Adds a color to this palette.
ColorPalette	add(RColor c) Adds a color to this palette.
ColorPalette	add(RColor c, int importance) Adds a color to this palette.
ColorPalette	addTag(java.lang.String tag) Adds a tag (e.g.
ColorPalette	addTags(java.lang.String... tags) Adds one or more tags (e.g.
ColorPalette	applyImportance(int[] importances) Sets the importances of the palettes colors.
ColorPalette	applyImportance(int c, int importance) Sets the importance of a color.
ColorPalette	applyImportance(RColor c, int importance) Sets the importance of a color.
ColorPalette	copy() Creates a true copy of this palette.
ColorPalette	draw(processing.core.PApplet parent, float x, float y, float w, float h) Draws a simple representation of this color palette within a rectangular form.
RColor	find(float tplusi) Finds a lerped color within the color palette.
boolean	finishedImage(java.lang.String timestamp) Returns whether a quantization of an image is finished.
RColor	get(int index) Returns the color at the given index or null if the index is out of bounds.
java.lang.String	get(processing.core.PImage img) Replaces all colors of all pixels of the input image with a color of the palette.
RColor	get(RColor c) Returns a color of the palette which is similar to the input color.
ColorDifferenceMeasure	getColorDifferenceMeasure() Returns the current ColorDifferenceMeasure.
RColor[]	getColors() Returns all colors of this palette (Shallow copies).
ColorSpace	getColorSpace() Returns the current ColorSpace.
java.lang.String	getDithered(processing.core.PImage img, float dithering) Replaces all colors of all pixels of the input image with a color of the palette.
RColor	getDithered(RColor c, float dithering) Returns a color of the palette which is similar to the input color (but maybe not the most similar color).
int	getIndex(RColor c) Returns the index of the most similar color to the input color.
java.lang.Float	getMaxChroma() Returns the maximal chroma (perceived saturation) of the palette.
java.lang.Float	getMaxLuminance() Returns the maximal luminance (perceived brightness) of the palette.
java.lang.Float	getMinChroma() Returns the minimal chroma (perceived saturation) of the palette.
java.lang.Float	getMinLuminance() Returns the minimal luminance (perceived brightness) of the palette.
RColor	getMostImportantColor() Returns the most important color of this palette.
java.lang.String	getName() Returns the currently set name of this palette.
java.lang.String	getNoisy(processing.core.PImage img, float amt) Replaces all colors of all pixels of the input image with a color of the palette.
RColor	getNoisy(RColor c, float amt) Returns a color of the palette which is similar to the input color.
RColor	getRandom() Returns a random color of the color palette.
RColor	getRandomWeighted() Returns a random color of the color palette by the color's importance.
java.util.ArrayList<java.lang.String>	getTags() Returns all tags associated with this palette.
float	getWeighting(RColor c) Calculates the weighting of a color.
ColorPalette	increaseImportance(RColor c, int howMuch) Increases the importance of the given color.
ColorPalette	merge(ColorPalette other) Merges two color palettes - adds another color palette to this one.
ColorPalette	reduceSize(int size) Reduces the number of colors to the given size.
ColorPalette	remove(int c) Removes the given color from the palette.
ColorPalette	remove(RColor c) Removes the given color from the palette.
ColorPalette	removeName() Removes the currently set name for this palette.
ColorPalette	removeTag(java.lang.String tag) Removes the given tag from the tag list associated with this palette.
ColorPalette	resetImportance() Resets the importance of all member colors of the palette to 1 (all colors are weighted equally).
ColorPalette	save(processing.core.PApplet parent) This method saves a JSON file containing this palettes color information.
ColorPalette	save(processing.core.PApplet parent, java.lang.String folder) This method saves a JSON file containing this palettes color information.
ColorPalette	save(processing.core.PApplet parent, java.lang.String folder, java.lang.String name) This method saves a JSON file containing this palettes color information.
ColorPalette	save(java.lang.String path) This method saves a JSON file containing this palettes color information.
ColorPalette	save(java.lang.String path, java.lang.String name) This method saves a JSON file containing this palettes color information.
ColorPalette	setColorDifferenceMeasure(ColorDifferenceMeasure m) Sets the ColorDifferenceMeasure.
ColorPalette	setColorSpace(ColorSpace space) Sets the measure which will be used to calculate the most similar color from an input to one of the palette's color.
ColorPalette	setColorSpace(RColor c) Sets the measure which will be used to calculate the most similar color from an input to one of the palette's color.
ColorPalette	setName(java.lang.String name) Sets a name which will be associated with this palette.
int	size() Returns the number of colors in this palette.
ColorPalette	sort() Sorts the colors by luminance beginning with the lowest luminance.
ColorPalette	sort(java.lang.String how) Sorts the colors by a parameter beginning with the lowest.
int[]	toColors() Returns all colors of this palette.
java.lang.String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Constructor Detail

ColorPalette

public ColorPalette()

Builds an empty color palette.

ColorPalette

public ColorPalette(java.lang.String jsonString)

Builds an ColorPalette out of a JSON-styled String. The String should look like this:

 {
   "name" : "String",
   "tags" : ["String1","String2",...,"StringN"],
   "colors" : [
      {
        "hexString" : {
           "r" : "float",
           "g" : "float",
           "b" : "float"}
           "a" : "float",
           "importance" : "int"
        }
      }, ...]
 }
 

The ranges of r, g, b, a should be within the RGB color range [0, 255]. The importance should be >= 1.

Parameters:

jsonString - The String containing JSON color infos.

ColorPalette

public ColorPalette(RColor[] colors)

Creates a color palette with the given colors. All colors will be weighted equally important.

Parameters:

colors - The colors of the palette.

ColorPalette

public ColorPalette(java.util.ArrayList<RColor> colors)

Creates a color palette with the given colors. All colors will be weighted equally important.

Parameters:

colors - The colors of the palette.

ColorPalette

public ColorPalette(int[] colors)

Creates a color palette with the given colors. All colors will be weighted equally important. All input colors given will be converted to RColor.

Parameters:

colors - The colors of the palette.

Method Detail

getMaxLuminance

public java.lang.Float getMaxLuminance()

Returns the maximal luminance (perceived brightness) of the palette.

Returns:

The maximal Luminance of this palette.

getMinLuminance

public java.lang.Float getMinLuminance()

Returns the minimal luminance (perceived brightness) of the palette.

Returns:

The minimal Luminance of this palette.

getMaxChroma

public java.lang.Float getMaxChroma()

Returns the maximal chroma (perceived saturation) of the palette.

Returns:

- The maximal chroma of this palette.

getMinChroma

public java.lang.Float getMinChroma()

Returns the minimal chroma (perceived saturation) of the palette.

Returns:

The minimal chroma of this palette.

getMostImportantColor

public RColor getMostImportantColor()

Returns the most important color of this palette. If all colors are equally important the first color will be returned.

Returns:

The most important color.

getColorDifferenceMeasure

public ColorDifferenceMeasure getColorDifferenceMeasure()

Returns the current ColorDifferenceMeasure. The measure defines how the most similar color is calculated using the get(RColor) method and how colors are merged in reduceSize(int).

Returns:

The current ColorDifferenceMeasure.

getColorSpace

public ColorSpace getColorSpace()

Returns the current ColorSpace.

Returns:

The current ColorSpace.

setColorSpace

public ColorPalette setColorSpace(ColorSpace space)

Sets the measure which will be used to calculate the most similar color from an input to one of the palette's color. Used in get() method. When this called, the measure will be set to the Euclidean distance of the input color space.

Parameters:

space - The new color space of this palette.

Returns:

The current ColorPalette object.

setColorSpace

public ColorPalette setColorSpace(RColor c)

Sets the measure which will be used to calculate the most similar color from an input to one of the palette's color. Used in get() method. When this called, the measure will be set to the Euclidean distance of the input color space.

Parameters:

c - One color.

Returns:

The current ColorPalette object.

setColorDifferenceMeasure

public ColorPalette setColorDifferenceMeasure(ColorDifferenceMeasure m)

Sets the ColorDifferenceMeasure. The measure defines how the most similar color is calculated using the get(RColor) method and how colors are merged in reduceSize(int). All member colors are converted to the color space which correlates to this measure.

Parameters:

m - A ColorDifferenceMeasure. e.g. ColorDifferenceMeasure.RGBEuclidean.

Returns:

The current ColorPalette object.

getWeighting

public float getWeighting(RColor c)

Calculates the weighting of a color. The sum of all weightings of all color of the palette sums up to 1.

Parameters:

c - The color of which the weighing should be returned.

Returns:

The input's weighting or 0 if input is not member of the palette.

addTag

public ColorPalette addTag(java.lang.String tag)

Adds a tag (e.g. \'summer\', \'colorful\', ...) which should be associated to the palette.

Parameters:

tag - The tag.

Returns:

The current ColorPalette object.

addTags

public ColorPalette addTags(java.lang.String... tags)

Adds one or more tags (e.g. \'summer\', \'colorful\', ...) which should be associated to the palette.

Parameters:

tags - The tags.

Returns:

The current ColorPalette object.

removeTag

public ColorPalette removeTag(java.lang.String tag)

Removes the given tag from the tag list associated with this palette.

Parameters:

tag - The tag to be removed.

Returns:

The current ColorPalette object.

getTags

public java.util.ArrayList<java.lang.String> getTags()

Returns all tags associated with this palette.

Returns:

The tag list.

setName

public ColorPalette setName(java.lang.String name)

Sets a name which will be associated with this palette. The name will also be used for saving this palette (to file / json).

Parameters:

name - The new name of this palette.

Returns:

The current ColorPalette object.

removeName

public ColorPalette removeName()

Removes the currently set name for this palette.

Returns:

The current ColorPalette object.

getName

public java.lang.String getName()

Returns the currently set name of this palette.

Returns:

The palette's name.

add

public ColorPalette add(int c)

Adds a color to this palette. The importance will be weighted with 1. The input will be converted to RColor.

Parameters:

c - The color which will be added to the palette.

Returns:

The current ColorPalette object.

add

public ColorPalette add(int c,
                        int importance)

Adds a color to this palette. The input will be converted to RColor.

Parameters:

c - The color which will be added to the palette.

importance - The importance value > 1 of this color.

Returns:

The current ColorPalette object.

add

public ColorPalette add(RColor c)

Adds a color to this palette. The importance will be weighted with 1.

Parameters:

c - - The color which will be added to the palette.

Returns:

The current ColorPalette object.

add

public ColorPalette add(RColor c,
                        int importance)

Adds a color to this palette.

Parameters:

c - The color which will be added to the palette.

importance - The importance value > 1 of this color.

Returns:

The current ColorPalette object.

resetImportance

public ColorPalette resetImportance()

Resets the importance of all member colors of the palette to 1 (all colors are weighted equally).

Returns:

The current ColorPalette object.

increaseImportance

public ColorPalette increaseImportance(RColor c,
                                       int howMuch)

Increases the importance of the given color.

Parameters:

c - The color of which the importance should be increased.

howMuch - A positive number which will be added to the current importance.

Returns:

The current ColorPalette object.

applyImportance

public ColorPalette applyImportance(RColor c,
                                    int importance)

Sets the importance of a color. The given color should already be member of the palette.

Parameters:

c - - The color of which the importance should be set.

importance - - The importance value > 0 for the input color.

Returns:

The current ColorPalette object.

applyImportance

public ColorPalette applyImportance(int c,
                                    int importance)

Sets the importance of a color. The given color should already be member of the palette.

Parameters:

c - The color of which the importance should be set.

importance - The importance value > 0 for the input color.

Returns:

The current ColorPalette object.

applyImportance

public ColorPalette applyImportance(int[] importances)

Sets the importances of the palettes colors. The input array should be the same size as the number of colors of this palette as well as they should be alligned. The first importance value will be used for the first color of the palette and so on. Better use applyImportance(int c, int importance) or applyImportance(RColor c, int importance) if you are not sure about the color's sorting.

Parameters:

importances - - The importance values > 0 for all colors of the palette.

Returns:

The current ColorPalette object.

remove

public ColorPalette remove(RColor c)

Removes the given color from the palette.

Parameters:

c - The color which should be removed.

Returns:

The current ColorPalette object.

remove

public ColorPalette remove(int c)

Removes the given color from the palette.

Parameters:

c - The color which should be removed.

Returns:

The current ColorPalette object.

merge

public ColorPalette merge(ColorPalette other)

Merges two color palettes - adds another color palette to this one.

Parameters:

other - Any other color palette. Duplicate colors are allowed. "other" will not be changed by this method.

Returns:

The current ColorPalette object.

sort

public ColorPalette sort()

Sorts the colors by luminance beginning with the lowest luminance.

Returns:

The current color palette.

sort

public ColorPalette sort(java.lang.String how)

Sorts the colors by a parameter beginning with the lowest.

Parameters:

how - Defines how the palette is sorted. Possible parameters are: "luminance", "chroma", "hue" (hue in HSB), "huelch (hue in CieLCH), "brightness", "saturation", "red", "green", "blue", "weighting".

Returns:

The current color palette.

copy

public ColorPalette copy()

Creates a true copy of this palette.

Returns:

The copied palette.

reduceSize

public ColorPalette reduceSize(int size)

Reduces the number of colors to the given size. The reduction is done by detecting similar colors in the palette and incremental merging them.

Parameters:

size - The new number of colors for this palette (size > 1 and size < palette.size()).

Returns:

The current palette.

size

public int size()

Returns the number of colors in this palette.

Returns:

The number of colors in this palette.

getRandom

public RColor getRandom()

Returns a random color of the color palette.

Returns:

A color of the palette or null if there is no color in the palette.

getRandomWeighted

public RColor getRandomWeighted()

Returns a random color of the color palette by the color's importance. This means that this method will return the color with a high importance more often then the color with low importance.

Returns:

A color of the palette or null if there is no color in the palette.

getDithered

public RColor getDithered(RColor c,
                          float dithering)

Returns a color of the palette which is similar to the input color (but maybe not the most similar color).

Parameters:

c - The input color.

dithering - The value for the dithering (0, 1).

Returns:

A color of the palette.

getDithered

public java.lang.String getDithered(processing.core.PImage img,
                                    float dithering)

Replaces all colors of all pixels of the input image with a color of the palette. Creates a quantized and dithered image. The returned String can be used to determined wheter the quantization is fished or not. Example usage:

 String stamp = myPalette.getDithered(myImage, 0.25);
 
 ⁄⁄ return true when all pixels of the input image have been
 ⁄⁄ replaced
 boolean finished = myPalette.finishedImage(stamp);
 

Parameters:

img - The input image.

dithering - The value for the dithering (0, 1).

Returns:

A timestamp (time when the quanitization started).

getNoisy

public RColor getNoisy(RColor c,
                       float amt)

Returns a color of the palette which is similar to the input color. A little random is added so not everytime the function is called with same parameters the output will be the same. The amt value sets how much likely the color of the palette will be the most similar color to the input. The lower amt is, the more likely the output will be the most similar color to the input. The higher amt is, the more likely the output will be the second most similar color to the input. If amt ist smaller or equal to zero, the output will be the same as get(RColor). If not defined otherwise, the Euclidean distance of the colors space of the color palette's colors will be used for the calculation of the similarity.

Parameters:

c - The input color.

amt - The value for the noise (>= 0).

Returns:

A color of the palette.

getNoisy

public java.lang.String getNoisy(processing.core.PImage img,
                                 float amt)

Replaces all colors of all pixels of the input image with a color of the palette. Creates a noisy quantized. The returned String can be used to determined wheter the quantization is fished or not. Example usage:

 String stamp = myPalette.getNoisy(myImage, 0.25);
 
 ⁄⁄ return true when all pixels of the input image have been
 ⁄⁄ replaced
 boolean finished = myPalette.finishedImage(stamp);
 

Parameters:

img - The input image.

amt - The value for the noise (>= 0).

Returns:

A timestamp (time when the quanitization started).

get

public RColor get(RColor c)

Returns a color of the palette which is similar to the input color. If not defined otherwise, the Euclidean distance of the colors space of the color palette's colors will be used for the calculation of the similarity.

Parameters:

c - The input color.

Returns:

A color of the palette.

get

public java.lang.String get(processing.core.PImage img)

Replaces all colors of all pixels of the input image with a color of the palette. Creates a quantized image. The returned String can be used to determined wheter the quantization is fished or not. Example usage:

 String stamp = myPalette.get(myImage);
 
 ⁄⁄ return true when all pixels of the input image have been
 ⁄⁄ replaced
 boolean finished = myPalette.finishedImage(stamp);
 

Parameters:

img - The input image.

Returns:

A timestamp (time when the quanitization started).

get

public RColor get(int index)

Returns the color at the given index or null if the index is out of bounds. You can get the number of colors by using the ColorPalette's size() function.

Parameters:

index - The index of the color which should be returned.

Returns:

A color of the palette.

find

public RColor find(float tplusi)

Finds a lerped color within the color palette.

Parameters:

tplusi - The parameter describes the returned color's position within the palette. It is calculated with t + i, where t is a float in range of [0, 1) and i is an int in range of [0, size() - 1). For example, if the color in the middle of the first and second color of the palette should be returned, than i=1 and t=0.5 and therefor tplusi=1.5.

Returns:

A RColor.

getIndex

public int getIndex(RColor c)

Returns the index of the most similar color to the input color. If not defined otherwise, the Euclidean distance of the colors space of the color palette's colors will be used for the calculation of the similarity.

Parameters:

c - The input color.

Returns:

The index of the most similar color.

finishedImage

public boolean finishedImage(java.lang.String timestamp)

Returns whether a quantization of an image is finished. The input String should be the timestamp when the quantization started (this String is returned by the get(PImage), getDithered(PImage, float), getNoisy(PImage, float) methods).

Parameters:

timestamp - The timestamp of the start of quantization.

Returns:

True if quantization is still in process. False if quantization is finished or input String could not be found.

save

public ColorPalette save(processing.core.PApplet parent)

This method saves a JSON file containing this palettes color information. The filename will be a concatenation of this palettes name and the number of colors. If no name is set, a timestamp and the number of colors will be used as filename. The files will be saved in a folder named "export" in your current sketch folder. Example usage in Processing:

 myPalette.save(this);
 

Parameters:

parent - A PApplet object.

Returns:

The current ColorPalette object.

save

public ColorPalette save(processing.core.PApplet parent,
                         java.lang.String folder)

This method saves a JSON file containing this palettes color information. The filename will be a concatenation of this palettes name and the number of colors. If no name is set, a timestamp and the number of colors will be used as filename.

Parameters:

folder - The name of the folder, where the palette should be saved. Can also be a relative path to the folder. Make sure to escape the backslashes when providing a relative path. Example usage in Processing:

            // will save the file in the current sketch folder in a sub-folder named
 // "colors"
            myPalette.save(this, "colors");
 
            // will save the file in the folder "temp" which will be above the
 // current sketch folder
            myPalette.save(this, "..\\temp");
            

parent - A PApplet object.

Returns:

The current ColorPalette object.

save

public ColorPalette save(processing.core.PApplet parent,
                         java.lang.String folder,
                         java.lang.String name)

This method saves a JSON file containing this palettes color information.

Parameters:

folder - The name of the folder, where the palette should be saved. Can also be a relative path to the folder. Make sure to escape the backslashes when providing a relative path. Example usage in Processing:

            // will save the file in the current sketch folder in a sub-folder named
 // "colors"
            myPalette.save(this, "colors");
 
            // will save the file in the folder "temp" which will be above the
 // current sketch folder
            myPalette.save(this, "..\\temp");
            

name - The name of the file (without file extension) under which the palette should be saved. Make sure this is a valid file name. Read Wiki: Filename for further informations.

parent - A PApplet object.

Returns:

The current ColorPalette object.

save

public ColorPalette save(java.lang.String path)

This method saves a JSON file containing this palettes color information. The filename will be a concatenation of this palettes name and the number of colors. If no name is set, a timestamp and the number of colors will be used as filename.

Parameters:

path - An absolute path to the place where the palette should be saved. Make sure this path exists! Otherwise (e.g. if you want to provide a relative path) please use the save(PApplet) method.

Returns:

The current ColorPalette object.

save

public ColorPalette save(java.lang.String path,
                         java.lang.String name)

This method saves a JSON file containing this palettes color information.

Parameters:

path - An absolute path to the place where the palette should be saved. Make sure this path exists! Otherwise (e.g. if you want to provide a relative path) please use the save(PApplet) method.

name - The name of the file (without file extension) under which the palette should be saved. Make sure this is a valid file name. Read Wiki: Filename for further informations.

Returns:

The current ColorPalette object.

draw

public ColorPalette draw(processing.core.PApplet parent,
                         float x,
                         float y,
                         float w,
                         float h)

Draws a simple representation of this color palette within a rectangular form.

Parameters:

parent - A PApplet object (Canvas to draw to).

x - The x-value of the rectangle (left).

y - The y-value of the rectangle (top).

w - The with of the rectangle.

h - The height of the rectangle.

Returns:

The current ColorPalette object.

toColors

public int[] toColors()

Returns all colors of this palette. Usage:

 color[] theColors = myColorPalette.toColors();
 

getColors

public RColor[] getColors()

Returns all colors of this palette (Shallow copies). Usage:

 RColor[] theColors = myColorPalette.getColors();
 

toString

public java.lang.String toString()

Overrides:

toString in class java.lang.Object