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

    All Methods Instance Methods Concrete Methods
    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` -