net.returnvoid.analytics

## Class ColorClustering

- java.lang.Object
- - net.returnvoid.analytics.ColorClustering

- All Implemented Interfaces:
    Clustering

      public class ColorClustering
      extends java.lang.Object
      implements Clustering

  A class to store color clusterings. Instances of this class are meant to final. This means no changes of the clusters or to the content of any clusters should be made.
  Author:
    Diana Lange

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `ColorClustering(ColorCluster[] clusters, int k)` Builds a new clustering from a given set of clusters.

  - ### Method Summary

    All Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `drawMeans(processing.core.PApplet parent, float x, float y, float w, float h)` Draws the cluster means with horizontal striped within the given rectangular area.
    `void` | `drawMeans(processing.core.PGraphics g, float x, float y, float w, float h)` Draws the cluster means with horizontal striped within the given rectangular area.
    `void` | `drawMembers(processing.core.PApplet parent, float x, float y, float w, float h)` Draws the cluster members with horizontal striped within the given rectangular area.
    `void` | `drawMembers(processing.core.PGraphics g, float x, float y, float w, float h)` Draws the cluster members with horizontal striped within the given rectangular area.
    `ColorCluster` | `get(int index)` Returns the cluster with the given index.
    `ColorCluster` | `getCluster(int c)` Returns the cluster which is the most similar to the given color.
    `ColorCluster` | `getCluster(java.lang.Object c)` Returns the cluster which is the most similar to the given parameter.
    `ColorCluster` | `getCluster(RColor c)` Returns the cluster which is the most similar to the given color.
    `int` | `getClusterIndex(int c)` Returns the index of the cluster which is the most similar to the input color.
    `int` | `getClusterIndex(java.lang.Object c)` Returns the index of the cluster which is the most similar to the input color.
    `int` | `getClusterIndex(RColor c)` Returns the index of the cluster which is the most similar to the input color.
    `ColorCluster[]` | `getClusters()` Returns all clusters of this clustering.
    `ColorDifferenceMeasure` | `getColorDifferenceMeasure()` Returns the ColorDifferenceMeasure which is used to calculate the most similar cluster to a given color within the getCluster() and getClusterIndex() methods.
    `int` | `getK()` The number of clusters to this clustering. k might differ from the getClusters().length, when empty clusters (clusters with no members) are automatically removed.
    `java.lang.Float` | `getLoss()` Returns the loss of the clustering (= mean loss of all clusters).
    `java.lang.Float` | `getMaxLuminance()` Returns the maximal luminance of this clustering.
    `RColor[]` | `getMeans()` Returns all cluster means.
    `RColor[]` | `getMembers()` Returns a set of colors which contains all members of all clusters of this clustering.
    `java.lang.Float` | `getMinLuminance()` Returns the minimal luminance of this clustering.
    `int` | `size()` The number of clusters for this clustering.
    `ColorPalette` | `toColorPalette()` Builds a color palette from this clustering.
    `ColorPalette` | `toColorPalette(boolean useMeans)` Builds a color palette from this clustering.

    - ### Methods inherited from class java.lang.Object

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

- - ### Constructor Detail

    - #### ColorClustering

          public ColorClustering(ColorCluster[] clusters,
                                 int k)

      Builds a new clustering from a given set of clusters. The clusters should not be changed after the clustering has been build. All calculations / optimizations of the clusters should before building a clustering. The clusters will be sorted by luminance (first cluster = lowest luminance, last cluster = highest luminance).
      Parameters:
        `clusters` - The clusters with set means and cluster members. All clusters should uses the same ColorDifferenceMeasure.
        `k` - The number of clusters of this clustering. k might differ from the clusters.length, when empty clusters (clusters with no members) are automatically removed.

  - ### Method Detail

    - #### getLoss

          public java.lang.Float getLoss()

      Description copied from interface: `Clustering`
      Returns the loss of the clustering (= mean loss of all clusters).
      Specified by:
        `getLoss` in interface `Clustering`
      Returns:
        The loss of the clustering.

    - #### getK

          public int getK()

      Description copied from interface: `Clustering`
      The number of clusters to this clustering. k might differ from the getClusters().length, when empty clusters (clusters with no members) are automatically removed.
      Specified by:
        `getK` in interface `Clustering`
      Returns:
        The number of clusters.

    - #### getMinLuminance

          public java.lang.Float getMinLuminance()

      Returns the minimal luminance of this clustering.
      Returns:
        The minimal luminance of this clustering [0, 100].

    - #### getMaxLuminance

          public java.lang.Float getMaxLuminance()

      Returns the maximal luminance of this clustering.
      Returns:
        The maximal luminance of this clustering [0, 100].

    - #### toColorPalette

          public ColorPalette toColorPalette()

      Builds a color palette from this clustering. The palette will consist of the the means of the clusters.
      Returns:
        A new (weighted) color palette.

    - #### toColorPalette

          public ColorPalette toColorPalette(boolean useMeans)

      Builds a color palette from this clustering. If useMeans is false: The palette will only contain colors of the cluster members (will choose a cluster member for each cluster that is the closest to the mean). Otherwise the means of the clusters will build the palette.
      Parameters:
        `useMeans` - A parameter which defines if the palette should consist of cluster means or a representative.
      Returns:
        A new (weighted) color palette.

    - #### getMeans

          public RColor[] getMeans()

      Returns all cluster means.
      Returns:
        The cluster means.

    - #### getMembers

          public RColor[] getMembers()

      Returns a set of colors which contains all members of all clusters of this clustering.
      Returns:
        The set of colors.

    - #### size

          public int size()

      The number of clusters for this clustering. This should be used to iterate over all clusters. Example:

           for (int i = 0; i < myClustering.size(); i++) {
                  myClustering.get(i); // The cluster with index i
           }

      Returns:
        The number of clusters for this clustering.

    - #### get

          public ColorCluster get(int index)

      Returns the cluster with the given index. Make sure the index is within bounds, e.g. use the size() method to iterate over all clusters. Example:

           for (int i = 0; i < myClustering.size(); i++) {
                  myClustering.get(i); // The cluster with index i
           }

      Parameters:
        `index` - The index of the cluster.
      Returns:
        The cluster with the given index.

    - #### getClusterIndex

          public int getClusterIndex(java.lang.Object c)

      Returns the index of the cluster which is the most similar to the input color.
      Parameters:
        `c` - A color.
      Returns:
        The index of the cluster which is the most similar to the input or -1 if the input wasn't a color.

    - #### getClusterIndex

          public int getClusterIndex(int c)

      Returns the index of the cluster which is the most similar to the input color.
      Parameters:
        `c` - A color (e.g 0xFFFF0000).
      Returns:
        The index of the cluster which is the most similar to the input or -1 if the input wasn't a color.

    - #### getClusterIndex

          public int getClusterIndex(RColor c)

      Returns the index of the cluster which is the most similar to the input color.
      Parameters:
        `c` - A color object.
      Returns:
        The index of the cluster which is the most similar to the input or -1 if the input wasn't a color.

    - #### getCluster

          public ColorCluster getCluster(java.lang.Object c)

      Description copied from interface: `Clustering`
      Returns the cluster which is the most similar to the given parameter.
      Specified by:
        `getCluster` in interface `Clustering`
      Parameters:
        `c` - An element.
      Returns:
        The most similar cluster to the input or null if the input is not compatible to the data type of the cluster members.

    - #### getCluster

          public ColorCluster getCluster(int c)

      Returns the cluster which is the most similar to the given color.
      Parameters:
        `c` - A color (e.g 0xFFFF0000).
      Returns:
        The most similar cluster to the input.

    - #### getCluster

          public ColorCluster getCluster(RColor c)

      Returns the cluster which is the most similar to the given color.
      Parameters:
        `c` - A color.
      Returns:
        The most similar cluster to the input.

    - #### getColorDifferenceMeasure

          public ColorDifferenceMeasure getColorDifferenceMeasure()

      Returns the ColorDifferenceMeasure which is used to calculate the most similar cluster to a given color within the getCluster() and getClusterIndex() methods.
      Returns:
        The ColorDifferenceMeasure of this clustering.

    - #### getClusters

          public ColorCluster[] getClusters()

      Description copied from interface: `Clustering`
      Returns all clusters of this clustering.
      Specified by:
        `getClusters` in interface `Clustering`
      Returns:
        The clusters.

    - #### drawMembers

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

      Draws the cluster members with horizontal striped 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.

    - #### drawMembers

          public void drawMembers(processing.core.PApplet parent,
                                  float x,
                                  float y,
                                  float w,
                                  float h)

      Draws the cluster members with horizontal striped within the given rectangular area.
      Parameters:
        `parent` - 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.

    - #### drawMeans

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

      Draws the cluster means with horizontal striped within the given rectangular area.
      Parameters:
        `g` - A recorder or null.
        `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.

    - #### drawMeans

          public void drawMeans(processing.core.PApplet parent,
                                float x,
                                float y,
                                float w,
                                float h)

      Draws the cluster means with horizontal striped within the given rectangular area.
      Parameters:
        `parent` - A recorder or null.
        `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.