org.gicentre.utils.colour

## Class CIELuv

- java.lang.Object
- - org.gicentre.utils.colour.CIELuv

-     public class CIELuv
      extends java.lang.Object

  Utilities for handling the CIELuv colour space. This space is approximately perceptually uniform in that two colours a fixed distance apart in the colour space should be equally distinguishable from each other regardless of their location.
  For details see en.wikipedia.org/wiki/CIELUV_color_space.
  Includes methods for creating colour tables from this space that maximise the use of the colour space with similar appearance to Brewer colour schemes. This is based on the process described by Wijffelaars, Vliegen, van Wijk and van der Linden (2008) Generating color palettes using intuitive parameters, Computer Graphics Forum,27(3).
  Version:
    3.4, 5th February, 2016.
  Author:
    Jo Wood, giCentre, City University London.

- - ### Constructor Summary

    Constructors
    Constructor and Description
    `CIELuv()` Creates a CIELuv converter using the default D65 illuminant with 2 degree observer position.

  - ### Method Summary

    All Methods Static Methods Instance Methods Concrete Methods
    Modifier and Type | Method and Description
    --- | ---
    `java.awt.Color` | `getColour(double L, double u, double v, boolean useNearest)` Finds the colour corresponding to the given CIELuv triplet.
    `java.awt.Color` | `getColourFromLCh(double L, double C, double h)` Finds the colour corresponding to the given CIELCh triplet.
    `java.awt.Color` | `getColourFromLCh(double L, double C, double h, boolean findNearest)` Finds the colour corresponding to the given CIELCh triplet.
    `processing.core.PVector` | `getLCh(java.awt.Color colour)` Finds the CIELCh triplet representing the given colour.
    `processing.core.PVector` | `getLuv(java.awt.Color colour)` Finds the CIELuv triplet representing the given colour.
    `static double[]` | `getMostSaturatedColour(double hue)` Finds the most saturated colour for the given hue.
    `ColourTable` | `getSequential(double hue1, double hue2, double saturation, double brightness, int numColours)` Provides a multi-hue sequential scheme using the given hues and having the given number of colours.
    `ColourTable` | `getSequential(double hue, double saturation, double brightness, int numColours)` Provides a single hue sequential scheme using the given hue and having the given number of colours.
    `ColourTable` | `getSequential(double hue, int numColours)` Provides a single hue sequential scheme using the given hue and having the given number of colours.

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

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

- - ### Constructor Detail

    - #### CIELuv

          public CIELuv()

      Creates a CIELuv converter using the default D65 illuminant with 2 degree observer position.

  - ### Method Detail

    - #### getLuv

          public processing.core.PVector getLuv(java.awt.Color colour)

      Finds the CIELuv triplet representing the given colour. CIELuv L value scaled between 0-100, and u and v values scaled between -100 and 100.
      Parameters:
        `colour` - Colour to convert.
      Returns:
        Vector holding CIELuv values where the x and y components hold the u and v values respectively and the z values holds the L value.

    - #### getLCh

          public processing.core.PVector getLCh(java.awt.Color colour)

      Finds the CIELCh triplet representing the given colour. CIELCh L value scaled between 0-100, and C between 0 and 100 and h the colour wheel between 0 and 360 degrees.
      Parameters:
        `colour` - Colour to convert.
      Returns:
        Vector holding CIELCh values where the x and y components hold the C and h values respectively and the z values holds the L value.

    - #### getColour

          public java.awt.Color getColour(double L,
                                          double u,
                                          double v,
                                          boolean useNearest)

      Finds the colour corresponding to the given CIELuv triplet. Out-of-gamut colours will be returned as null if `useNearest` is false, otherwise the approximate nearest visible colour will be returned. CIELuv L values should be scaled between 0-100, and a and b values scaled between -100 and 100.
      Parameters:
        `L` - CIELuv L value scaled between 0 and 100.
        `u` - CIELuv u value scaled between -100 and 100.
        `v` - CIELiv v value scaled between -100 and 100.
        `useNearest` - If true, out-of-gamut colours will be converted to their nearest visible equivalent. If not, out-of-gamut colours returned as null.
      Returns:
        Colour representing the given Luv values.

    - #### getColourFromLCh

          public java.awt.Color getColourFromLCh(double L,
                                                 double C,
                                                 double h)

      Finds the colour corresponding to the given CIELCh triplet. Out-of-gamut colours will be returned as null. CIE LCh L values should be scaled between 0-100, C (Chroma) values scaled between -100 and 100 and h between 0 and 360 degrees.
      Parameters:
        `L` - CIELuv Lightness value scaled between 0 and 100.
        `C` - CIELuv Chroma value scaled between 0 and 100.
        `h` - CIELiv Hue value scaled between 0 and 360 degrees.
      Returns:
        Colour representing the given LCh values or null if the colour is out-of-gamut.

    - #### getColourFromLCh

          public java.awt.Color getColourFromLCh(double L,
                                                 double C,
                                                 double h,
                                                 boolean findNearest)

      Finds the colour corresponding to the given CIELCh triplet. If `findNearest` is true, out-of-gamut colours will be clamped to their nearest visible colour, if not, out-of-gamut colours are returned as null. CIE LCh L values should be scaled between 0-100, C (Chroma) values scaled between 0 and 100 and h between 0 and 360 degrees.
      Parameters:
        `L` - CIELuv Lightness value scaled between 0 and 100.
        `C` - CIELuv Chroma value scaled between 0 and 100.
        `h` - CIELiv Hue value scaled between 0 and 360 degrees.
        `findNearest` - If true, nearest visible colour will be found.
      Returns:
        Colour representing the given LCh values.

    - #### getSequential

          public ColourTable getSequential(double hue,
                                           int numColours)

      Provides a single hue sequential scheme using the given hue and having the given number of colours. This version uses a default saturation value of 0.6 and brightness of 0.75.
      Parameters:
        `hue` - Hue upon which to base the scheme. This should be a value from 0 to 360 degrees.
        `numColours` - Number of colour values in the colour table, or 0 for continuous scheme.
      Returns:
        Colour table representing the sequential scheme.

    - #### getSequential

          public ColourTable getSequential(double hue,
                                           double saturation,
                                           double brightness,
                                           int numColours)

      Provides a single hue sequential scheme using the given hue and having the given number of colours. This version allows the saturation and brightness of the scheme to be set.
      Parameters:
        `hue` - Hue upon which to base the scheme. This should be a value from 0 to 360 degrees.
        `saturation` - Saturation of the scheme scaled between 0-1.
        `brightness` - Brightness of the scheme scaled between 0-1.
        `numColours` - Number of colour values in the colour table, or 0 for continuous scheme.
      Returns:
        Colour table representing the sequential scheme.

    - #### getSequential

          public ColourTable getSequential(double hue1,
                                           double hue2,
                                           double saturation,
                                           double brightness,
                                           int numColours)

      Provides a multi-hue sequential scheme using the given hues and having the given number of colours. This version allows the saturation and brightness of the scheme to be set.
      Parameters:
        `hue1` - First hue upon which to base the scheme. This should be a value from 0 to 360 degrees.
        `hue2` - Second hue upon which to base the scheme. This should be a value from 0 to 360 degrees.
        `saturation` - Saturation of the scheme scaled between 0-1.
        `brightness` - Brightness of the scheme scaled between 0-1.
        `numColours` - Number of colour values in the colour table, or 0 for continuous scheme.
      Returns:
        Colour table representing the sequential scheme.

    - #### getMostSaturatedColour

          public static double[] getMostSaturatedColour(double hue)

      Finds the most saturated colour for the given hue.
      Parameters:
        `hue` - Hue whose most saturated colour is to be found. This should be a value scaled between 0-360 degrees.
      Returns:
        Colour expressed in RGB coordinates.