net.returnvoid.color

## Class XYZColor

- java.lang.Object
- - net.returnvoid.color.XYZColor

- All Implemented Interfaces:
    RColor

      public class XYZColor
      extends java.lang.Object
      implements RColor

  A model for color in XYZ color space. A XYZColor can be converted to any other color model. To use this in Processing use the getColor() Method:

       fill(myXYZObject.getColor());

  The difference between multiple color objects can be calculated with the methods of ColorDifference class.
  X [0, XYZColor.REFERENCE_X] = [0, 95.047]
  Y [0, XYZColor.REFERENCE_Y] = [0, 100]
  Z [0, XYZColor.REFERENCE_Z] = [0, 108.883]
  A = alpha = transparency [0, 100]
  Author:
    Diana Lange

- - ### Field Summary

    Fields
    Modifier and Type | Field and Description
    --- | ---
    `static ColorSpace` | `NAME` The ColorSpace of RGB colors.
    `static float` | `REFERENCE_X` X Value for the specific illuminants and observers (2° [CIE 1931] - D65 - Daylight, sRGB, Adobe-RGB conversion)
    `static float` | `REFERENCE_Y` Y Value for the specific illuminants and observers (2° [CIE 1931] - D65 - Daylight, sRGB, Adobe-RGB conversion)
    `static float` | `REFERENCE_Z` Z Value for the specific illuminants and observers (2° [CIE 1931] - D65 - Daylight, sRGB, Adobe-RGB conversion)

  - ### Constructor Summary

    Constructors
    Constructor and Description
    `XYZColor(float... channels)` Creates a new XYZColor object.
    `XYZColor(java.lang.Float x, java.lang.Float y, java.lang.Float z)` Creates a new opaque XYZColor object.
    `XYZColor(java.lang.Float x, java.lang.Float y, java.lang.Float z, java.lang.Float alpha)` Creates a new XYZColor object.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `XYZColor` | `copy()` Creates a deep copy of the object.
    `boolean` | `equals(RColor other)` Checks if the input color is equal to this object.
    `java.lang.Float` | `getAlpha()` Returns the value of alpha / transparency.
    `int` | `getColor()` Returns a int representation of the current color.
    `ColorSpace` | `getColorSpace()` Returns the color space of the color.
    `java.lang.String` | `getHexString()` Returns a String representation of the current color using hexadecimal numbers.
    `static java.lang.Float` | `getLoss(RColor rvMean, java.util.ArrayList<RColor> lColors, ColorDifferenceMeasure m)` Calculates the loss - the mean distance of all members of colors to rvMean.
    `static java.lang.Float` | `getLoss(RColor rvMean, java.util.ArrayList<RColor> lColors, ColorDifferenceMeasure m, int start, int end)` Calculates the loss - the mean distance of all members of colors to rvMean.
    `static java.lang.Float` | `getLoss(RColor rvMean, RColor[] colors, ColorDifferenceMeasure m)` Calculates the loss - the mean distance of all members of colors to rvMean.
    `static java.lang.Float` | `getLoss(RColor rvMean, RColor[] colors, ColorDifferenceMeasure m, int start, int end)` Calculates the loss - the mean distance of all members of colors to rvMean.
    `static XYZColor` | `getMeanColor(java.util.ArrayList<RColor> colors)` Calculates the mean color of the input colors
    `static XYZColor` | `getMeanColor(int start, int end, java.util.ArrayList<RColor> colors)` Calculates the mean color of the input colors.
    `static XYZColor` | `getMeanColor(int start, int end, RColor... colors)` Calculates the mean color of the input colors.
    `static XYZColor` | `getMeanColor(RColor... colors)` Calculates the mean color of the input colors
    `java.lang.String` | `getName()` Returns the name of the color space e.g.
    `int` | `getOpColor()` Returns a int representation of the current color - but ignoring the alpha value.
    `java.lang.String` | `getOpHexString()` Returns a String representation of the current color using hexadecimal numbers.
    `static XYZColor` | `getRandomXYZ()` Creates a new opaque XYZColor with random values.
    `float[]` | `getValues()` Returns the color values of the current object.
    `float[]` | `getValuesNormalized()` Returns the normalized color values of the current object.
    `java.lang.Float` | `getX()` Returns the current value of x of this color.
    `java.lang.Float` | `getY()` Returns the current value of y of this color.
    `java.lang.Float` | `getZ()` Returns the current value of z of this color.
    `static XYZColor` | `lerpColors(RColor input1, RColor input2, float amt)` Lerps the two input colors and creates a new color.
    `XYZColor` | `setAlpha(java.lang.Float alpha)` Sets the value of alpha / transparency.
    `XYZColor` | `setAlpha(int alpha)` Sets the value of alpha / transparency.
    `XYZColor` | `setX(java.lang.Float x)` Sets the x value.
    `XYZColor` | `setX(int x)` Sets the x value.
    `XYZColor` | `setY(java.lang.Float y)` Sets the y value.
    `XYZColor` | `setY(int y)` Sets the y value.
    `XYZColor` | `setZ(java.lang.Float z)` Sets the z value.
    `XYZColor` | `setZ(int z)` Sets the z value.
    `HSBColor` | `toHSB()` Returns a HSBColor representation of the current color.
    `LabColor` | `toLab()` Returns a LabColor representation of the current color.
    `LCHColor` | `toLCH()` Returns a LCHColor representation of the current color.
    `RGBColor` | `toRGB()` Returns a RGBColor representation of the current color.
    `java.lang.String` | `toString()`
    `XYZColor` | `toXYZ()` Returns a XYZColor representation of the current color.

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

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

- - ### Field Detail

    - #### NAME

          public static final ColorSpace NAME

      The ColorSpace of RGB colors.

    - #### REFERENCE_X

          public static final float REFERENCE_X

      X Value for the specific illuminants and observers (2° [CIE 1931] - D65 - Daylight, sRGB, Adobe-RGB conversion)
      See Also:
        Constant Field Values

    - #### REFERENCE_Y

          public static final float REFERENCE_Y

      Y Value for the specific illuminants and observers (2° [CIE 1931] - D65 - Daylight, sRGB, Adobe-RGB conversion)
      See Also:
        Constant Field Values

    - #### REFERENCE_Z

          public static final float REFERENCE_Z

      Z Value for the specific illuminants and observers (2° [CIE 1931] - D65 - Daylight, sRGB, Adobe-RGB conversion)
      See Also:
        Constant Field Values

  - ### Constructor Detail

    - #### XYZColor

          public XYZColor(java.lang.Float x,
                          java.lang.Float y,
                          java.lang.Float z)

      Creates a new opaque XYZColor object. The input values will be constrained to the valid range of XYZ.
      Parameters:
        `x` - The x value [0, REFERENCE_X] = [0, 95.047]
        `y` - The y value [0, REFERENCE_Y] = [0, 100]
        `z` - The z value [0, REFERENCE_Z] = [0, 108.883]

    - #### XYZColor

          public XYZColor(java.lang.Float x,
                          java.lang.Float y,
                          java.lang.Float z,
                          java.lang.Float alpha)

      Creates a new XYZColor object. The input values will be constrained to the valid range of XYZ.
      Parameters:
        `x` - The x value [0, REFERENCE_X] = [0, 95.047]
        `y` - The y value [0, REFERENCE_Y] = [0, 100]
        `z` - The z value [0, REFERENCE_Z] = [0, 108.883]
        `alpha` - THe alpha value [0, 100]

    - #### XYZColor

          public XYZColor(float... channels)

      Creates a new XYZColor object. The input values will be constrained to the valid range of XYZColor.
      Parameters:
        `channels` - Either [x, y, z] or [x, y, z, alpha].

  - ### Method Detail

    - #### getColor

          public int getColor()

      Description copied from interface: `RColor`
      Returns a int representation of the current color. The range will be between 0xFFFFFFFF and 0x00000000. Using this, the color object can be used to set the color within Processing. Example:

           HSBColor hsb = new HSBColor(244, 100, 100);
           fill(hsb.getColor());

      Specified by:
        `getColor` in interface `RColor`
      Returns:
        the color value of the object.

    - #### setAlpha

          public XYZColor setAlpha(java.lang.Float alpha)

      Description copied from interface: `RColor`
      Sets the value of alpha / transparency. The range of alpha depends on the model of the color space. For RGB alpha will have a range of [0, 255]. For all other color spaces the range is [0, 100]. Zero always means that the color is completely transparent. The high value means that the color is completely opaque.
      Specified by:
        `setAlpha` in interface `RColor`
      Parameters:
        `alpha` - The value of the colors transparency.
      Returns:
        The current color object.

    - #### setAlpha

          public XYZColor setAlpha(int alpha)

      Sets the value of alpha / transparency. The range of alpha is [0, 100]. Zero always means that the color is completely transparent. The high value means that the color is completely opaque.
      Parameters:
        `alpha` - The value of the colors transparency.
      Returns:
        The current color object.

    - #### getAlpha

          public java.lang.Float getAlpha()

      Description copied from interface: `RColor`
      Returns the value of alpha / transparency. The range of alpha depends on the model of the color space. For RGB alpah will have a range of [0, 255]. For all other color spaces the range is [0, 100]. Zero always means that the color is completely transparent. The high value means that the color is completely opaque.
      Specified by:
        `getAlpha` in interface `RColor`
      Returns:
        The value of transparency.

    - #### setX

          public XYZColor setX(java.lang.Float x)

      Sets the x value. The input value will be constrained to the valid range of XYZ.
      Parameters:
        `x` - The new x value [0, REFERENCE_X] = [0, 95.047].
      Returns:
        The current XYZColor object.

    - #### setX

          public XYZColor setX(int x)

      Sets the x value. The input value will be constrained to the valid range of XYZ.
      Parameters:
        `x` - The new x value [0, REFERENCE_X] = [0, 95.047].
      Returns:
        The current XYZColor object.

    - #### setY

          public XYZColor setY(java.lang.Float y)

      Sets the y value. The input value will be constrained to the valid range of XYZ.
      Parameters:
        `y` - The new y value [0, REFERENCE_Y] = [0, 100].
      Returns:
        The current XYZColor object.

    - #### setY

          public XYZColor setY(int y)

      Sets the y value. The input value will be constrained to the valid range of XYZ.
      Parameters:
        `y` - The new y value [0, REFERENCE_Y] = [0, 100].
      Returns:
        The current XYZColor object.

    - #### setZ

          public XYZColor setZ(java.lang.Float z)

      Sets the z value. The input value will be constrained to the valid range of XYZ.
      Parameters:
        `z` - The new z value [0, REFERENCE_Z] = [0, 108.883].
      Returns:
        The current XYZColor object.

    - #### setZ

          public XYZColor setZ(int z)

      Sets the z value. The input value will be constrained to the valid range of XYZ.
      Parameters:
        `z` - The new z value [0, REFERENCE_Z] = [0, 108.883].
      Returns:
        The current XYZColor object.

    - #### getX

          public java.lang.Float getX()

      Returns the current value of x of this color.
      Returns:
        The x of this color.

    - #### getY

          public java.lang.Float getY()

      Returns the current value of y of this color.
      Returns:
        The y of this color.

    - #### getZ

          public java.lang.Float getZ()

      Returns the current value of z of this color.
      Returns:
        The z of this color.

    - #### getHexString

          public java.lang.String getHexString()

      Description copied from interface: `RColor`
      Returns a String representation of the current color using hexadecimal numbers. The range will be between "FFFFFFFF" and "00000000". Example:

           RGBColor rgb = new RGBColor(255, 0, 128, 0);
           rgb.getHexString(); // "00FF0080"

      Specified by:
        `getHexString` in interface `RColor`
      Returns:
        the color value of the object.

    - #### getOpColor

          public int getOpColor()

      Description copied from interface: `RColor`
      Returns a int representation of the current color - but ignoring the alpha value. The output will always be opaque ('Op' in method name stands for Opaque). The range will be between 0xFFFFFFFF and 0xFF000000. Using this, the color object can be used to set the color within Processing. Example:

           HSBColor hsb = new HSBColor(244, 100, 100, 50);
           fill(hsb.getOpColor());

      Specified by:
        `getOpColor` in interface `RColor`
      Returns:
        the color value of the object.

    - #### getOpHexString

          public java.lang.String getOpHexString()

      Description copied from interface: `RColor`
      Returns a String representation of the current color using hexadecimal numbers. The alpha value will be ignored ('Op' in method name stands for Opaque). The range will be between "FFFFFF" and "000000". Example:

           RGBColor rgb = new RGBColor(255, 0, 128, 0);
           rgb.getOpHexString(); // "FF0080"

      Specified by:
        `getOpHexString` in interface `RColor`
      Returns:
        the color value of the object.

    - #### getValues

          public float[] getValues()

      Description copied from interface: `RColor`
      Returns the color values of the current object. Depending on the color space these are:
      [0] = red [1] = green [2] = blue [3] = alpha
      [0] = hue [1] = saturation [2] = brightness [3] = alpha
      [0] = x [1] = y [2] = z [3] = alpha
      [0] = L [1] = a [2] = b [3] = alpha
      [0] = L [1] = C [2] = Hue [3] = alpha
      Specified by:
        `getValues` in interface `RColor`
      Returns:
        the colors.

    - #### getValuesNormalized

          public float[] getValuesNormalized()

      Description copied from interface: `RColor`
      Returns the normalized color values of the current object. The ranges of all values will be between [0,1]. Depending on the color space the values are:
      [0] = red [1] = green [2] = blue [3] = alpha
      [0] = hue [1] = saturation [2] = brightness [3] = alpha
      [0] = x [1] = y [2] = z [3] = alpha
      [0] = L [1] = a [2] = b [3] = alpha
      [0] = L [1] = C [2] = Hue [3] = alpha
      Specified by:
        `getValuesNormalized` in interface `RColor`
      Returns:
        the colors.

    - #### getName

          public java.lang.String getName()

      Description copied from interface: `RColor`
      Returns the name of the color space e.g. "RGBColor"
      Specified by:
        `getName` in interface `RColor`
      Returns:
        The name of the color space.

    - #### getColorSpace

          public ColorSpace getColorSpace()

      Description copied from interface: `RColor`
      Returns the color space of the color.
      Specified by:
        `getColorSpace` in interface `RColor`
      Returns:
        The color space.

    - #### copy

          public XYZColor copy()

      Description copied from interface: `RColor`
      Creates a deep copy of the object.
      Specified by:
        `copy` in interface `RColor`
      Returns:
        The copied object.

    - #### equals

          public boolean equals(RColor other)

      Checks if the input color is equal to this object. Two colors are equal if they are member of the same color space and all channel values are equal.
      Specified by:
        `equals` in interface `RColor`
      Parameters:
        `other` - The other color
      Returns:
        True if both colors are considered the same;

    - #### toString

          public java.lang.String toString()

      Overrides:
        `toString` in class `java.lang.Object`

    - #### getMeanColor

          public static XYZColor getMeanColor(RColor... colors)

      Calculates the mean color of the input colors
      Parameters:
        `colors` - Colors (1 or more).
      Returns:
        The new XYZColor object that represents the mean color.

    - #### getMeanColor

          public static XYZColor getMeanColor(java.util.ArrayList<RColor> colors)

      Calculates the mean color of the input colors
      Parameters:
        `colors` - Colors.
      Returns:
        The new XYZColor object that represents the mean color.

    - #### getMeanColor

          public static XYZColor getMeanColor(int start,
                                              int end,
                                              RColor... colors)

      Calculates the mean color of the input colors. With start and end a subset is defined. Just this subset will be used to calculate the mean.
      Parameters:
        `start` - Start index of the subset of the input colors (start < end). start will be member of the subset.
        `end` - End index of the subset of the input colors (start < end). end will not be member of the subset.
        `colors` - Colors (1 or more).
      Returns:
        The new XYZColor object that represents the mean color.

    - #### getMeanColor

          public static XYZColor getMeanColor(int start,
                                              int end,
                                              java.util.ArrayList<RColor> colors)

      Calculates the mean color of the input colors. With start and end a subset is defined. Just this subset will be used to calculate the mean.
      Parameters:
        `start` - Start index of the subset of the input colors (start < end). start will be member of the subset.
        `end` - End index of the subset of the input colors (start < end). end will not be member of the subset.
        `colors` - Colors.
      Returns:
        The new XYZColor object that represents the mean color.

    - #### getLoss

          public static java.lang.Float getLoss(RColor rvMean,
                                                RColor[] colors,
                                                ColorDifferenceMeasure m)

      Calculates the loss - the mean distance of all members of colors to rvMean.
      Parameters:
        `rvMean` - A base color which will be used to calculate the distance to.
        `colors` - Colors.
        `m` - The measure which defines how the loss is calculated and which color model will be used. This should be an RGB color difference measure.
      Returns:
        The mean loss value.

    - #### getLoss

          public static java.lang.Float getLoss(RColor rvMean,
                                                RColor[] colors,
                                                ColorDifferenceMeasure m,
                                                int start,
                                                int end)

      Calculates the loss - the mean distance of all members of colors to rvMean. With start and end a subset is defined. Just this subset will be used to calculate the loss. start and end should be in the array range; otherwise this will produce an ArrayIndexOutOfBounds Exception.
      Parameters:
        `rvMean` - A base color which will be used to calculate the distance to.
        `colors` - Colors.
        `m` - The measure which defines how the loss is calculated and which color model will be used. This should be an RGB color difference measure.
        `start` - Start index of the subset of the input colors (start < end). start will be member of the subset.
        `end` - End index of the subset of the input colors (start < end). end will not be member of the subset.
      Returns:
        The mean loss value.

    - #### getLoss

          public static java.lang.Float getLoss(RColor rvMean,
                                                java.util.ArrayList<RColor> lColors,
                                                ColorDifferenceMeasure m)

      Calculates the loss - the mean distance of all members of colors to rvMean.
      Parameters:
        `rvMean` - A base color which will be used to calculate the distance to.
        `lColors` - Colors.
        `m` - The measure which defines how the loss is calculated and which color model will be used. This should be an RGB color difference measure.
      Returns:
        The mean loss value.

    - #### getLoss

          public static java.lang.Float getLoss(RColor rvMean,
                                                java.util.ArrayList<RColor> lColors,
                                                ColorDifferenceMeasure m,
                                                int start,
                                                int end)

      Calculates the loss - the mean distance of all members of colors to rvMean. With start and end a subset is defined. Just this subset will be used to calculate the loss. start and end should be in the array range; otherwise this will produce an ArrayIndexOutOfBounds Exception.
      Parameters:
        `rvMean` - A base color which will be used to calculate the distance to.
        `lColors` - Colors.
        `m` - The measure which defines how the loss is calculated and which color model will be used. This should be an RGB color difference measure.
        `start` - Start index of the subset of the input colors (start < end). start will be member of the subset.
        `end` - End index of the subset of the input colors (start < end). end will not be member of the subset.
      Returns:
        The mean loss value.

    - #### lerpColors

          public static XYZColor lerpColors(RColor input1,
                                            RColor input2,
                                            float amt)

      Lerps the two input colors and creates a new color. The values of the colors will be interpolated linear. The interpolation is defined by the amt parameter. For amt=0 the outcome will be input1, for amt=1 the outcome will be input2.
      Parameters:
        `input1` - The first color.
        `input2` - The second color.
        `amt` - The lerping value [0, 1].
      Returns:
        A new 'mixed' color.

    - #### getRandomXYZ

          public static XYZColor getRandomXYZ()

      Creates a new opaque XYZColor with random values.
      Returns:
        The new color.

    - #### toRGB

          public RGBColor toRGB()

      Description copied from interface: `RColor`
      Returns a RGBColor representation of the current color. If the color is already a RGBColor, the original object will be return otherwise a new object will be created with converted color values. The resulting color referes to sRGB.
      Specified by:
        `toRGB` in interface `RColor`
      Returns:
        The RGBColor of the object.

    - #### toHSB

          public HSBColor toHSB()

      Description copied from interface: `RColor`
      Returns a HSBColor representation of the current color. If the color is already a HSBColor, the original object will be return otherwise a new object will be created with converted color values.
      Specified by:
        `toHSB` in interface `RColor`
      Returns:
        The HSBColor of the object.

    - #### toXYZ

          public XYZColor toXYZ()

      Description copied from interface: `RColor`
      Returns a XYZColor representation of the current color. If the color is already a XYZColor, the original object will be return otherwise a new object will be created with converted color values. The XYZColor refers to a D65/2° standard illuminant.
      Specified by:
        `toXYZ` in interface `RColor`
      Returns:
        The XYZColor of the object.

    - #### toLab

          public LabColor toLab()

      Description copied from interface: `RColor`
      Returns a LabColor representation of the current color. If the color is already a LabColor, the original object will be return otherwise a new object will be created with converted color values. The conversion is done using the XYZColor.REFERENCE_X,Y and Z values as specific illuminants and observers.
      Specified by:
        `toLab` in interface `RColor`
      Returns:
        The LabColor of the object.

    - #### toLCH

          public LCHColor toLCH()

      Description copied from interface: `RColor`
      Returns a LCHColor representation of the current color. If the color is already a LCHColor, the original object will be return otherwise a new object will be created with converted color values.
      Specified by:
        `toLCH` in interface `RColor`
      Returns:
        The LCHColor of the object.