net.returnvoid.analytics

Class ColorClusteringBuilder

java.lang.Object

net.returnvoid.analytics.ColorClusteringBuilder

All Implemented Interfaces:

ImageUpdateObserver

public class ColorClusteringBuilder
extends java.lang.Object
implements ImageUpdateObserver

A class to build multiple color clusterings with the same trainings data but with different number of clusters. Finds a optimal k (number of clusters) within the given range of minK and maxK.

Author:

Diana Lange

Constructor Summary

Constructors

Constructor and Description
ColorClusteringBuilder(processing.core.PApplet parent) Builds a new ColorClusteringBuilder with minK=2, maxK=30 and RGBEuclidean as ColorDifferenceMeasure.
ColorClusteringBuilder(processing.core.PApplet parent, ColorDifferenceMeasure m) Builds a new ColorClusteringBuilder with minK=2, maxK=30 and m as ColorDifferenceMeasure.

Method Summary

Modifier and Type	Method and Description
void	drawAllClusterings(float x, float y, float w, float h) Draws all clusterings from minK to maxK with all cluster mean colors and all cluster members for each cluster within a rectangular area.
void	drawAllClusterings(processing.core.PGraphics g, float x, float y, float w, float h) Draws all clusterings from minK to maxK with all cluster mean colors and all cluster members for each cluster within a rectangular area.
void	drawAllClusteringsMeans(float x, float y, float w, float h) Draws all clusterings from minK to maxK with all cluster mean colors for each clustering within a rectangular area.
void	drawAllClusteringsMeans(processing.core.PGraphics g, float x, float y, float w, float h) Draws all clusterings from minK to maxK with all cluster mean colors for each clustering within a rectangular area.
void	drawAllClusteringsMembers(float x, float y, float w, float h) Draws all members of all clusters of all clusterings from minK to maxK (sorted by clustering and cluster) within a rectangular area.
void	drawAllClusteringsMembers(processing.core.PGraphics g, float x, float y, float w, float h) Draws all members of all clusters of all clusterings from minK to maxK (sorted by clustering and cluster) within a rectangular area.
void	drawClustering(float x, float y, float w, float h, int k) Draws the clustering (all cluster mean colors) with vertical stripes for the clustering with k clusters within a rectangular area.
void	drawClustering(processing.core.PGraphics g, float x, float y, float w, float h, int k) Draws the clustering (all cluster mean colors) with vertical stripes for the clustering with k clusters within a rectangular area.
void	drawImage(float x, float y, float w, float h) Draws the input image centered in the given rectangular area.
void	drawImage(processing.core.PGraphics g, float x, float y, float w, float h) Draws the input image centered in the given rectangular area.
void	drawImageWithClustering(float x, float y, float w, float h, int k) Draws the input image with an overlay of the clustering with k colors / clusters.
void	drawImageWithClustering(processing.core.PGraphics g, float x, float y, float w, float h, int k) Draws the input image with an overlay of the clustering with k colors / clusters.
void	drawInputColors(float x, float y, float w, float h)
void	drawInputColors(processing.core.PGraphics g, float x, float y, float w, float h)
void	drawLoss(float x, float y, float w, float h) Draws the the loss graph for minK to maxK within a rectangular area.
void	drawLoss(float x, float y, float w, float h, int highlight) Draws the the loss graph for minK to maxK within a rectangular area.
void	drawLoss(processing.core.PGraphics g, float x, float y, float w, float h, int highlight) Draws the the loss graph for minK to maxK within a rectangular area.
void	drawQuantizedImage(float x, float y, float w, float h, int k) Draws the quantized image for the given k centered in the given rectangular area.
void	drawQuantizedImage(processing.core.PGraphics g, float x, float y, float w, float h, int k) Draws the quantized image for the given k centered in the given rectangular area.
void	export(int k, java.lang.String fileName) Exports the current clustering with k clusters with 6 sample representations.
ColorClustering	get(int index) Returns the clustering with the given index (the index doesn't equal to k - the number of clusters).
ColorClustering	getClustering() Returns the clustering with optimal number of clusters for the given data.
ColorClustering	getClustering(int k) Returns the clustering with k number of clusters.
ColorDifferenceMeasure	getColorDifferenceMeasure() Returns the ColorDifferenceMeasure which defines the distance measure for the clustering process.
RColor[]	getColors() Returns the source for the clusterings - the training colors.
processing.core.PImage	getInputImg() Returns the source for the clusterings (colors will be sampled from this image) or null if no image is set.
int	getMaxK() Returns the maximal number of clusters for any clustering of this builder.
int	getMinK() Returns the minimal number of clusters for any clustering of this builder.
int	getOptimalK() Calculates the optimal k for the given input data (optimal number of clusters that represent the input).
processing.core.PImage	getQuantizedImage() Creates a quantized image to the given inputImage image.
processing.core.PImage	getQuantizedImage(int k) Creates a quantized image to the given inputImage image.
processing.core.PImage	getQuantizedImageFull() Creates a quantized image to the given inputImg image (source of clustering).
processing.core.PImage	getQuantizedImageFull(int k) Creates a quantized image to the given inputImg image (source of clustering).
processing.core.PImage	getQuantizedImagePreview() Creates a quantized image to the given inputImg image (source of clustering).
processing.core.PImage	getQuantizedImagePreview(int k) Creates a quantized image to the given inputImg image (source of clustering).
void	setColorDifferenceMeasure(ColorDifferenceMeasure m) Sets a new ColorDifferenceMeasure.
void	setColors(RColor[] inputColors) Sets the source for the clusterings (colors will be sampled from this colors).
void	setImage(processing.core.PImage inputImg) Sets the source for the clusterings (colors will be sampled from this image).
ColorClusteringBuilder	setMaxK(int k) Sets the maximal number of clusters for any clustering of this builder.
ColorClusteringBuilder	setTrainingSize(int trainingSize) Sets the number of colors which will be used to learn the clusterings.
int	size() Returns the number of clusterings for this builder.
void	update() Creates new clusterings for the given range of k.

Methods inherited from class java.lang.Object

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

Constructor Detail

ColorClusteringBuilder

public ColorClusteringBuilder(processing.core.PApplet parent)

Builds a new ColorClusteringBuilder with minK=2, maxK=30 and RGBEuclidean as ColorDifferenceMeasure. The clustering will be done after either setImage() or setColors() is called.

Parameters:

parent - The PApplet object.

ColorClusteringBuilder

public ColorClusteringBuilder(processing.core.PApplet parent,
                              ColorDifferenceMeasure m)

Builds a new ColorClusteringBuilder with minK=2, maxK=30 and m as ColorDifferenceMeasure. The clustering will be done after either setImage() or setColors() is called.

Parameters:

parent - The PApplet object.

Method Detail

setTrainingSize

public ColorClusteringBuilder setTrainingSize(int trainingSize)

Sets the number of colors which will be used to learn the clusterings. When inputColors are used and there are less inputColors than trainingSize, then all inputColors are used for training.

Parameters:

trainingSize - The number of colors used for learning the clusterings.

Returns:

The current builder object.

setMaxK

public ColorClusteringBuilder setMaxK(int k)

Sets the maximal number of clusters for any clustering of this builder.

Parameters:

k - The maximal number of clusters.

Returns:

The current builder object.

size

public int size()

Returns the number of clusterings for this builder. Use this to iterate over all clusterings. Example:

 for (int i = 0; i < myBuilder.size(); i++) {
        ColorClustering clustering = myBuilder.get(i);
 }
 

Returns:

The number of clusterings.

get

public ColorClustering get(int index)

Returns the clustering with the given index (the index doesn't equal to k - the number of clusters). Use this to iterate over all clusterings of this builder. Example:

 for (int i = 0; i < myBuilder.size(); i++) {
        ColorClustering clustering = myBuilder.get(i);
 }
 

Parameters:

index - The index of the clustering [0, size()).

Returns:

The clusering.

getClustering

public ColorClustering getClustering()

Returns the clustering with optimal number of clusters for the given data.

Returns:

The clustering.

getClustering

public ColorClustering getClustering(int k)

Returns the clustering with k number of clusters. Make sure k is in range of [minK, maxK]. Example usage:

 for (int k = myBuilder.getMinK(); k <= myBuilder.getMaxK(); k++) {
        myBuilder.getClustering(k);
 }
 

Parameters:

k - The number of clusters which maps to the desired clustering.

Returns:

The clustering with k clusters.

getColorDifferenceMeasure

public ColorDifferenceMeasure getColorDifferenceMeasure()

Returns the ColorDifferenceMeasure which defines the distance measure for the clustering process.

Returns:

The ColorDifferenceMeasure.

getInputImg

public processing.core.PImage getInputImg()

Returns the source for the clusterings (colors will be sampled from this image) or null if no image is set.

Returns:

The input image or null.

getColors

public RColor[] getColors()

Returns the source for the clusterings - the training colors.

Returns:

The set of colors which is used for the clusterings.

getMaxK

public int getMaxK()

Returns the maximal number of clusters for any clustering of this builder.

Returns:

The maximal number of clusters.

getMinK

public int getMinK()

Returns the minimal number of clusters for any clustering of this builder.

Returns:

The minimal number of clusters.

getOptimalK

public int getOptimalK()

Calculates the optimal k for the given input data (optimal number of clusters that represent the input).

Returns:

The optimal k.

setImage

public void setImage(processing.core.PImage inputImg)

Sets the source for the clusterings (colors will be sampled from this image). The clusterings will start after this method has been called.

Specified by:

setImage in interface ImageUpdateObserver

Parameters:

inputImg - The source for the clusterings.

setColors

public void setColors(RColor[] inputColors)

Sets the source for the clusterings (colors will be sampled from this colors). The clusterings will start after this method has been called.

Parameters:

inputColors - The source for the clusterings.

getQuantizedImage

public processing.core.PImage getQuantizedImage()

Creates a quantized image to the given inputImage image. The quantized image will only consists of colors which are found as a cluster mean in this clustering with optimal k cluster. If the quantized image with full resolution was already calculated this function will return the image with the full resolution. Otherwise it will return a version with reduced resolution (with long side = 600px).

Parameters:

k - The number of clusters / colors which will be used to build the quantized image. Make sure is within range of [minK, maxK].

Returns:

The quantized image.

getQuantizedImage

public processing.core.PImage getQuantizedImage(int k)

Creates a quantized image to the given inputImage image. The quantized image will only consists of colors which are found as a cluster mean in this clustering with the given k. If the quantized image with full resolution was already calculated this function will return the image with the full resolution. Otherwise it will return a version with reduced resolution (with long side = 600px).

Parameters:

k - The number of clusters / colors which will be used to build the quantized image. Make sure is within range of [minK, maxK].

Returns:

The quantized image.

getQuantizedImageFull

public processing.core.PImage getQuantizedImageFull()

Creates a quantized image to the given inputImg image (source of clustering). The quantized image will only consists of colors which are found as cluster mean in the clustering with optimal k clusters. Returns null if no inputImg is provided. In that case use getQuantizedImageFull(PImage) instead.

Returns:

The quantized image (same resolution as inputImg) or null.

getQuantizedImageFull

public processing.core.PImage getQuantizedImageFull(int k)

Creates a quantized image to the given inputImg image (source of clustering). The quantized image will only consists of colors which are found as cluster mean in the clustering with k clusters. Returns null if no inputImg is provided. In that case use getQuantizedImageFull(int, PImage) instead.

Parameters:

k - The number of clusters / colors which will be used to build the quantized image. Make sure is within range of [minK, maxK].

Returns:

The quantized image (same resolution as inputImg) or null.

getQuantizedImagePreview

public processing.core.PImage getQuantizedImagePreview()

Creates a quantized image to the given inputImg image (source of clustering). The quantized image will only consists of colors which are found as cluster mean in the clustering with optimal k clusters. Returns null if no inputImg is provided. In that case use getQuantizedImagePreview(PImage) instead.

Returns:

The quantized image (with max. 600x600px resolution) or null.

getQuantizedImagePreview

public processing.core.PImage getQuantizedImagePreview(int k)

Creates a quantized image to the given inputImg image (source of clustering). The quantized image will only consists of colors which are found as cluster mean in the clustering with k clusters. Returns null if no inputImg is provided. In that case use getQuantizedImagePreview(int, PImage) instead.

Parameters:

k - The number of clusters / colors which will be used to build the quantized image. Make sure is within range of [minK, maxK].

Returns:

The quantized image (with max. 600x600px resolution) or null.

update

public void update()

Creates new clusterings for the given range of k. Samples new training data as well.

setColorDifferenceMeasure

public void setColorDifferenceMeasure(ColorDifferenceMeasure m)

Sets a new ColorDifferenceMeasure. The training colors will be converted to the color space defined by that measure. All clusterings will be updated.

Parameters:

m - The new ColorDifferenceMeasure.

export

public void export(int k,
                   java.lang.String fileName)

Exports the current clustering with k clusters with 6 sample representations. These representations are:
(1) Quantized image.
(2) Loss graph.
(3) Clustering with k clusters.
(4) Input image with clustered colors as overlay.
(5) A graph with all clusterings from minK to maxK.
(6) The training data (sampled colors).

The images will be exported in a folder named "export" in the current sketch folder.

Parameters:

k - The number of clusters / colors which will be used to build the quantized image. Make sure is within range of [minK, maxK].

fileName - The (base) name of the images which will be exported.

drawQuantizedImage

public void drawQuantizedImage(float x,
                               float y,
                               float w,
                               float h,
                               int k)

Draws the quantized image for the given k centered in the given rectangular area. If no inputImage is provided no image will be drawn.

Parameters:

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

k - The number of clusters / colors which will be used to build the quantized image. Make sure is within range of [minK, maxK].

drawQuantizedImage

public void drawQuantizedImage(processing.core.PGraphics g,
                               float x,
                               float y,
                               float w,
                               float h,
                               int k)

Draws the quantized image for the given k centered in the given rectangular area. If no inputImage is provided no image will be drawn.

Parameters:

g - A recorder.

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

k - The number of clusters / colors which will be used to build the quantized image. Make sure is within range of [minK, maxK].

drawImage

public void drawImage(float x,
                      float y,
                      float w,
                      float h)

Draws the input image centered in the given rectangular area. If no inputImage is provided no image will be drawn.

Parameters:

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

drawImage

public void drawImage(processing.core.PGraphics g,
                      float x,
                      float y,
                      float w,
                      float h)

Draws the input image centered in the given rectangular area. If no inputImage is provided no image will be drawn.

Parameters:

g - A recorder.

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

drawLoss

public void drawLoss(float x,
                     float y,
                     float w,
                     float h)

Draws the the loss graph for minK to maxK within a rectangular area.

Parameters:

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

drawLoss

public void drawLoss(float x,
                     float y,
                     float w,
                     float h,
                     int highlight)

Draws the the loss graph for minK to maxK within a rectangular area.

Parameters:

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

highlight - The k which defines which loss will be highlighted. highlight should be in range of [minK, maxK] or out of range if no loss should be highlighted.

drawLoss

public void drawLoss(processing.core.PGraphics g,
                     float x,
                     float y,
                     float w,
                     float h,
                     int highlight)

Draws the the loss graph for minK to maxK within a rectangular area.

Parameters:

g - A recorder.

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

highlight - The k which defines which loss will be highlighted. highlight should be in range of [minK, maxK] or out of range if no loss should be highlighted.

drawClustering

public void drawClustering(float x,
                           float y,
                           float w,
                           float h,
                           int k)

Draws the clustering (all cluster mean colors) with vertical stripes for the clustering with k clusters within a rectangular area.

Parameters:

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

k - The number of clusters / colors which defines which clustering will be drawn. Make sure is within range of [minK, maxK].

drawClustering

public void drawClustering(processing.core.PGraphics g,
                           float x,
                           float y,
                           float w,
                           float h,
                           int k)

Draws the clustering (all cluster mean colors) with vertical stripes for the clustering with k clusters within a rectangular area.

Parameters:

g - A recorder.

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

k - The number of clusters / colors which defines which clustering will be drawn. Make sure is within range of [minK, maxK].

drawImageWithClustering

public void drawImageWithClustering(float x,
                                    float y,
                                    float w,
                                    float h,
                                    int k)

Draws the input image with an overlay of the clustering with k colors / clusters. If no inputImage is provided no image will be drawn. The image will be centered within the given rectangular area.

Parameters:

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

k - The number of clusters / colors which defines which clustering will be drawn. Make sure is within range of [minK, maxK].

drawImageWithClustering

public void drawImageWithClustering(processing.core.PGraphics g,
                                    float x,
                                    float y,
                                    float w,
                                    float h,
                                    int k)

Draws the input image with an overlay of the clustering with k colors / clusters. If no inputImage is provided no image will be drawn. The image will be centered within the given rectangular area.

Parameters:

g - A recorder.

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

k - The number of clusters / colors which defines which clustering will be drawn. Make sure is within range of [minK, maxK].

drawAllClusteringsMeans

public void drawAllClusteringsMeans(float x,
                                    float y,
                                    float w,
                                    float h)

Draws all clusterings from minK to maxK with all cluster mean colors for each clustering within a rectangular area.

Parameters:

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

drawAllClusteringsMeans

public void drawAllClusteringsMeans(processing.core.PGraphics g,
                                    float x,
                                    float y,
                                    float w,
                                    float h)

Draws all clusterings from minK to maxK with all cluster mean colors for each clustering within a rectangular area.

Parameters:

g - A recorder.

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

drawAllClusterings

public void drawAllClusterings(float x,
                               float y,
                               float w,
                               float h)

Draws all clusterings from minK to maxK with all cluster mean colors and all cluster members for each cluster within a rectangular area.

Parameters:

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

drawAllClusterings

public void drawAllClusterings(processing.core.PGraphics g,
                               float x,
                               float y,
                               float w,
                               float h)

Draws all clusterings from minK to maxK with all cluster mean colors and all cluster members for each cluster within a rectangular area.

Parameters:

g - A recorder.

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

drawAllClusteringsMembers

public void drawAllClusteringsMembers(float x,
                                      float y,
                                      float w,
                                      float h)

Draws all members of all clusters of all clusterings from minK to maxK (sorted by clustering and cluster) within a rectangular area.

Parameters:

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

drawAllClusteringsMembers

public void drawAllClusteringsMembers(processing.core.PGraphics g,
                                      float x,
                                      float y,
                                      float w,
                                      float h)

Draws all members of all clusters of all clusterings from minK to maxK (sorted by clustering and cluster) within a rectangular area.

Parameters:

g - A recorder.

x - The x-position (top left corner) of the rectangle.

y - The y-position (top left corner) of the rectangle.

w - The width of the rectangle.

h - The height of the rectangle.

drawInputColors

public void drawInputColors(float x,
                            float y,
                            float w,
                            float h)

Parameters:

x -

y -

w -

h -

drawInputColors

public void drawInputColors(processing.core.PGraphics g,
                            float x,
                            float y,
                            float w,
                            float h)

Parameters:

g -

x -

y -

w -

h -