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

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