Class Contrast


  • public final class Contrast
    extends java.lang.Object
    Color science for contrast utilities.

    Utility methods for calculating contrast given two colors, or calculating a color given one color and a contrast ratio.

    Contrast ratio is calculated using XYZ's Y. When linearized to match human perception, Y becomes HCT's tone and L*a*b*'s' L*.

    • Constructor Summary

      Constructors 
      Modifier Constructor Description
      private Contrast()  
    • Method Summary

      All Methods Static Methods Concrete Methods 
      Modifier and Type Method Description
      static double darker​(double tone, double ratio)
      Returns T in HCT, L* in L*a*b* <= tone parameter that ensures ratio with input T/L*.
      static double darkerUnsafe​(double tone, double ratio)
      Tone <= tone parameter that ensures ratio.
      static double lighter​(double tone, double ratio)
      Returns T in HCT, L* in L*a*b* >= tone parameter that ensures ratio with input T/L*.
      static double lighterUnsafe​(double tone, double ratio)
      Tone >= tone parameter that ensures ratio.
      static double ratioOfTones​(double t1, double t2)
      Contrast ratio of two tones.
      static double ratioOfYs​(double y1, double y2)
      Contrast ratio is a measure of legibility, its used to compare the lightness of two colors.
      • Methods inherited from class java.lang.Object

        clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
    • Constructor Detail

      • Contrast

        private Contrast()
    • Method Detail

      • ratioOfYs

        public static double ratioOfYs​(double y1,
                                       double y2)
        Contrast ratio is a measure of legibility, its used to compare the lightness of two colors. This method is used commonly in industry due to its use by WCAG.

        To compare lightness, the colors are expressed in the XYZ color space, where Y is lightness, also known as relative luminance.

        The equation is ratio = lighter Y + 5 / darker Y + 5.

      • ratioOfTones

        public static double ratioOfTones​(double t1,
                                          double t2)
        Contrast ratio of two tones. T in HCT, L* in L*a*b*. Also known as luminance or perpectual luminance.

        Contrast ratio is defined using Y in XYZ, relative luminance. However, relative luminance is linear to number of photons, not to perception of lightness. Perceptual luminance, L* in L*a*b*, T in HCT, is. Designers prefer color spaces with perceptual luminance since they're accurate to the eye.

        Y and L* are pure functions of each other, so it possible to use perceptually accurate color spaces, and measure contrast, and measure contrast in a much more understandable way: instead of a ratio, a linear difference. This allows a designer to determine what they need to adjust a color's lightness to in order to reach their desired contrast, instead of guessing & checking with hex codes.

      • lighter

        public static double lighter​(double tone,
                                     double ratio)
        Returns T in HCT, L* in L*a*b* >= tone parameter that ensures ratio with input T/L*. Returns -1 if ratio cannot be achieved.
        Parameters:
        tone - Tone return value must contrast with.
        ratio - Desired contrast ratio of return value and tone parameter.
      • lighterUnsafe

        public static double lighterUnsafe​(double tone,
                                           double ratio)
        Tone >= tone parameter that ensures ratio. 100 if ratio cannot be achieved.

        This method is unsafe because the returned value is guaranteed to be in bounds, but, the in bounds return value may not reach the desired ratio.

        Parameters:
        tone - Tone return value must contrast with.
        ratio - Desired contrast ratio of return value and tone parameter.
      • darker

        public static double darker​(double tone,
                                    double ratio)
        Returns T in HCT, L* in L*a*b* <= tone parameter that ensures ratio with input T/L*. Returns -1 if ratio cannot be achieved.
        Parameters:
        tone - Tone return value must contrast with.
        ratio - Desired contrast ratio of return value and tone parameter.
      • darkerUnsafe

        public static double darkerUnsafe​(double tone,
                                          double ratio)
        Tone <= tone parameter that ensures ratio. 0 if ratio cannot be achieved.

        This method is unsafe because the returned value is guaranteed to be in bounds, but, the in bounds return value may not reach the desired ratio.

        Parameters:
        tone - Tone return value must contrast with.
        ratio - Desired contrast ratio of return value and tone parameter.