color_contrast_calc 0.1.0

data/lib/color_contrast_calc/threshold_finder.rb

@@ -0,0 +1,276 @@
+# frozen_string_literal: true
+
+require 'color_contrast_calc/color'
+
+module ColorContrastCalc
+  ##
+  # Collection of modules that implement the main logic of
+  # instance methods of Color, +Color#find_*_threshold()+.
+
+  module ThresholdFinder
+    # @private
+
+    module Criteria
+      class SearchDirection
+        attr_reader :level, :target_ratio
+
+        def initialize(level)
+          @level = level
+          @target_ratio = Checker.level_to_ratio(level)
+        end
+      end
+
+      class ToDarkerSide < SearchDirection
+        # @private
+
+        def round(r)
+          (r * 10).floor / 10.0
+        end
+
+        # @private
+
+        def increment_condition(contrast_ratio)
+          contrast_ratio > @target_ratio
+        end
+      end
+
+      class ToBrighterSide < SearchDirection
+        # @private
+
+        def round(r)
+          (r * 10).ceil / 10.0
+        end
+
+        # @private
+
+        def increment_condition(contrast_ratio)
+          @target_ratio > contrast_ratio
+        end
+      end
+    end
+
+    # @private
+
+    def self.threshold_criteria(level, fixed_color, other_color)
+      if should_scan_darker_side?(fixed_color, other_color)
+        return Criteria::ToDarkerSide.new(level)
+      end
+
+      Criteria::ToBrighterSide.new(level)
+    end
+
+    # @private
+
+    def self.should_scan_darker_side?(fixed_color, other_color)
+      fixed_color.higher_luminance_than?(other_color) ||
+        fixed_color.same_luminance_as?(other_color) && fixed_color.light_color?
+    end
+
+    # @private
+
+    def self.binary_search_width(init_width, min)
+      i = 1
+      init_width = init_width.to_f
+      d = init_width / 2**i
+
+      while d > min
+        yield d
+        i += 1
+        d = init_width / 2**i
+      end
+    end
+
+    ##
+    # Module that implements the main logic of the instance method
+    # +Color#find_brightness_threshold()+.
+
+    module Brightness
+      ##
+      # Try to find a color who has a satisfying contrast ratio.
+      #
+      # The color returned by this method will be created by changing the
+      # brightness of +other_color+. Even when a color that satisfies the
+      # specified level is not found, the method returns a new color anyway.
+      # @param fixed_color [Color] The color which remains unchanged
+      # @param other_color [Color] Color before the adjustment of brightness
+      # @param level [String] "A", "AA" or "AAA"
+      # @return [Color] New color whose brightness is adjusted from that of
+      #   +other_color+
+
+      def self.find(fixed_color, other_color, level = Checker::Level::AA)
+        criteria = ThresholdFinder.threshold_criteria(level,
+                                                      fixed_color, other_color)
+        w = calc_upper_ratio_limit(other_color) / 2.0
+
+        upper_color = upper_limit_color(fixed_color, other_color, w * 2, level)
+        return upper_color if upper_color
+
+        r, sufficient_r = calc_brightness_ratio(fixed_color.relative_luminance,
+                                                other_color.rgb, criteria, w)
+
+        generate_satisfying_color(fixed_color, other_color, criteria,
+                                  r, sufficient_r)
+      end
+
+      def self.upper_limit_color(fixed_color, other_color, max_ratio, level)
+        limit_color = other_color.new_brightness_color(max_ratio)
+
+        if exceed_upper_limit?(fixed_color, other_color, limit_color, level)
+          limit_color
+        end
+      end
+
+      private_class_method :upper_limit_color
+
+      def self.exceed_upper_limit?(fixed_color, other_color, limit_color, level)
+        other_color.higher_luminance_than?(fixed_color) &&
+          !limit_color.sufficient_contrast?(fixed_color, level)
+      end
+
+      private_class_method :exceed_upper_limit?
+
+      def self.calc_brightness_ratio(fixed_luminance, other_rgb, criteria, w)
+        target_ratio = criteria.target_ratio
+        r = w
+        sufficient_r = nil
+
+        ThresholdFinder.binary_search_width(w, 0.01) do |d|
+          contrast_ratio = calc_contrast_ratio(fixed_luminance, other_rgb, r)
+
+          sufficient_r = r if contrast_ratio >= target_ratio
+          break if contrast_ratio == target_ratio
+
+          r += criteria.increment_condition(contrast_ratio) ? d : -d
+        end
+
+        [r, sufficient_r]
+      end
+
+      private_class_method :calc_brightness_ratio
+
+      def self.generate_satisfying_color(fixed_color, other_color, criteria,
+                                         r, sufficient_r)
+        level = criteria.level
+        nearest = other_color.new_brightness_color(criteria.round(r))
+
+        if sufficient_r && !nearest.sufficient_contrast?(fixed_color, level)
+          return other_color.new_brightness_color(criteria.round(sufficient_r))
+        end
+
+        nearest
+      end
+
+      private_class_method :generate_satisfying_color
+
+      def self.calc_contrast_ratio(fixed_luminance, other_rgb, r)
+        new_rgb = Converter::Brightness.calc_rgb(other_rgb, r)
+        new_luminance = Checker.relative_luminance(new_rgb)
+        Checker.luminance_to_contrast_ratio(fixed_luminance, new_luminance)
+      end
+
+      private_class_method :calc_contrast_ratio
+
+      # @private
+
+      def self.calc_upper_ratio_limit(color)
+        return 100 if color.same_color?(Color::BLACK)
+        darkest = color.rgb.reject(&:zero?).min
+        ((255.0 / darkest) * 100).ceil
+      end
+    end
+
+    ##
+    # Module that implements the main logic of the instance method
+    # +Color#find_lightness_threshold()+.
+
+    module Lightness
+      ##
+      # Try to find a color who has a satisfying contrast ratio.
+      #
+      # The color returned by this method will be created by changing the
+      # lightness of +other_color+. Even when a color that satisfies the
+      # specified level is not found, the method returns a new color anyway.
+      # @param fixed_color [Color] The color which remains unchanged
+      # @param other_color [Color] Color before the adjustment of lightness
+      # @param level [String] "A", "AA" or "AAA"
+      # @return [Color] New color whose lightness is adjusted from that of
+      #   +other_color+
+
+      def self.find(fixed_color, other_color, level = Checker::Level::AA)
+        criteria = ThresholdFinder.threshold_criteria(level,
+                                                      fixed_color, other_color)
+        init_l = other_color.hsl[2]
+        max, min = determine_minmax(fixed_color, other_color, init_l)
+
+        boundary_color = lightness_boundary_color(fixed_color, max, min, level)
+        return boundary_color if boundary_color
+
+        l, sufficient_l = calc_lightness_ratio(fixed_color, other_color.hsl,
+                                               criteria, max, min)
+
+        generate_satisfying_color(fixed_color, other_color.hsl, criteria,
+                                  l, sufficient_l)
+      end
+
+      def self.determine_minmax(fixed_color, other_color, init_l)
+        scan_darker_side = ThresholdFinder.should_scan_darker_side?(fixed_color,
+                                                                    other_color)
+        scan_darker_side ? [init_l, 0] : [100, init_l] # [max, min]
+      end
+
+      private_class_method :determine_minmax
+
+      def self.lightness_boundary_color(color, max, min, level)
+        if min.zero? && !color.sufficient_contrast?(Color::BLACK, level)
+          return Color::BLACK
+        end
+
+        if max == 100 && !color.sufficient_contrast?(Color::WHITE, level)
+          return Color::WHITE
+        end
+      end
+
+      private_class_method :lightness_boundary_color
+
+      def self.calc_lightness_ratio(fixed_color, other_hsl, criteria, max, min)
+        h, s, = other_hsl
+        l = (max + min) / 2.0
+        sufficient_l = nil
+
+        ThresholdFinder.binary_search_width(max - min, 0.01) do |d|
+          contrast_ratio = calc_contrast_ratio(fixed_color, [h, s, l])
+
+          sufficient_l = l if contrast_ratio >= criteria.target_ratio
+          break if contrast_ratio == criteria.target_ratio
+
+          l += criteria.increment_condition(contrast_ratio) ? d : -d
+        end
+
+        [l, sufficient_l]
+      end
+
+      private_class_method :calc_lightness_ratio
+
+      def self.calc_contrast_ratio(fixed_color, hsl)
+        fixed_color.contrast_ratio_against(Utils.hsl_to_rgb(hsl))
+      end
+
+      private_class_method :calc_contrast_ratio
+
+      def self.generate_satisfying_color(fixed_color, other_hsl, criteria,
+                                         l, sufficient_l)
+        h, s, = other_hsl
+        level = criteria.level
+        nearest = Color.new_from_hsl([h, s, l])
+
+        if sufficient_l && !nearest.sufficient_contrast?(fixed_color, level)
+          return Color.new_from_hsl([h, s, sufficient_l])
+        end
+
+        nearest
+      end
+
+      private_class_method :generate_satisfying_color
+    end
+  end
+end

data/lib/color_contrast_calc/utils.rb

@@ -0,0 +1,240 @@
+# frozen_string_literal: true
+
+require 'color_contrast_calc/shim'
+
+module ColorContrastCalc
+  ##
+  # Utility functions that provide basic operations on colors.
+  #
+  # This module provides basic operations on colors given as RGB values
+  # (including their hex code presentations) or HSL values.
+
+  module Utils
+    using Shim unless //.respond_to? :match?
+
+    HSL_UPPER_LIMIT = [360, 100, 100].freeze
+
+    private_constant :HSL_UPPER_LIMIT
+
+    HEX_RE = /\A#?[0-9a-f]{3}([0-9a-f]{3})?\z/i
+
+    private_constant :HEX_RE
+
+    ##
+    # Convert a hex color code string to a RGB value.
+    #
+    # @param hex_code [String] Hex color code such as "#ffff00"
+    # @return [Array<Integer>] RGB value represented as an array of integers
+
+    def self.hex_to_rgb(hex_code)
+      hex_part = hex_code.start_with?('#') ? hex_code[1..-1] : hex_code
+
+      case hex_part.length
+      when 3
+        hex_part.chars.map {|c| c.hex * 17 }
+      when 6
+        [0, 2, 4].map {|i| hex_part[i, 2].hex }
+      end
+    end
+
+    ##
+    # Normalize a hex color code to a 6 digits, lowercased one.
+    #
+    # @param code [String] Hex color code such as "#ffff00", "#ff0" or "FFFF00"
+    # @param prefix [true, false] If set to False, "#" at the head of result is
+    #   removed
+    # @return [String] 6-digit hexadecimal string in lowercase, with/without
+    #   leading "#" depending on the value of +prefix+
+
+    def self.normalize_hex(code, prefix = true)
+      if code.length < 6
+        hex_part = code.start_with?('#') ? code[1..-1] : code
+        code = hex_part.chars.map {|c| c * 2 }.join
+      end
+
+      lowered = code.downcase
+      return lowered if prefix == lowered.start_with?('#')
+      prefix ? "##{lowered}" : lowered[1..-1]
+    end
+
+    ##
+    # Convert a RGB value to a hex color code.
+    #
+    # @param rgb [Array<Integer>] RGB value represented as an array of integers
+    # @return [String] Hex color code such as "#ffff00"
+
+    def self.rgb_to_hex(rgb)
+      format('#%02x%02x%02x', *rgb)
+    end
+
+    ##
+    # Convert HSL value to RGB value.
+    #
+    # @param hsl [Array<Float>] HSL value represented as an array of numbers
+    # @return [Array<Integer>] RGB value represented as an array of integers
+
+    def self.hsl_to_rgb(hsl)
+      # https://www.w3.org/TR/css3-color/#hsl-color
+      h = hsl[0] / 360.0
+      s = hsl[1] / 100.0
+      l = hsl[2] / 100.0
+      m2 = l <= 0.5 ? l * (s + 1) : l + s - l * s
+      m1 = l * 2 - m2
+      [h + 1 / 3.0, h, h - 1 / 3.0].map do |adjusted_h|
+        (hue_to_rgb(m1, m2, adjusted_h) * 255).round
+      end
+    end
+
+    # @private
+
+    def self.hue_to_rgb(m1, m2, h)
+      h += 1 if h < 0
+      h -= 1 if h > 1
+      return m1 + (m2 - m1) * h * 6 if h * 6 < 1
+      return m2 if h * 2 < 1
+      return m1 + (m2 - m1) * (2 / 3.0 - h) * 6 if h * 3 < 2
+      m1
+    end
+
+    private_class_method :hue_to_rgb
+
+    ##
+    # Convert HSL value to hex color code.
+    #
+    # @param hsl [Array<Float>] HSL value represented as an array of numbers
+    # @return [String] Hex color code such as "#ffff00"
+
+    def self.hsl_to_hex(hsl)
+      rgb_to_hex(hsl_to_rgb(hsl))
+    end
+
+    ##
+    # Convert RGB value to HSL value.
+    #
+    # @param rgb [Array<Integer>] RGB value represented as an array of integers
+    # @return [Array<Float>] HSL value represented as an array of numbers
+
+    def self.rgb_to_hsl(rgb)
+      [rgb_to_hue(rgb), rgb_to_saturation(rgb), rgb_to_lightness(rgb)]
+    end
+
+    # @private
+
+    def self.rgb_to_lightness(rgb)
+      (rgb.max + rgb.min) * 100 / 510.0
+    end
+
+    private_class_method :rgb_to_lightness
+
+    # @private
+
+    def self.rgb_to_saturation(rgb)
+      l = rgb_to_lightness(rgb)
+      minmax_with_diff(rgb) do |min, max, d|
+        (l <= 50 ? d / (max + min) : d / (510 - max - min)) * 100
+      end
+    end
+
+    private_class_method :rgb_to_saturation
+
+    # @private
+
+    def self.rgb_to_hue(rgb)
+      # References:
+      # Agoston, Max K. (2005).
+      # "Computer Graphics and Geometric Modeling: Implementation and Algorithms".
+      # London: Springer
+      #
+      # https://accessibility.kde.org/hsl-adjusted.php#hue
+
+      minmax_with_diff(rgb) do |_, _, d|
+        mi = rgb.each_with_index.max_by {|c| c[0] }[1] # max value index
+        h = mi * 120 + (rgb[(mi + 1) % 3] - rgb[(mi + 2) % 3]) * 60 / d
+
+        h < 0 ? h + 360 : h
+      end
+    end
+
+    private_class_method :rgb_to_hue
+
+    # @private
+
+    def self.minmax_with_diff(rgb)
+      min = rgb.min
+      max = rgb.max
+      return 0 if min == max
+      yield min, max, (max - min).to_f
+    end
+
+    private_class_method :minmax_with_diff
+
+    ##
+    # Convert hex color code to HSL value.
+    #
+    # @param hex_code [String] Hex color code such as "#ffff00"
+    # @return [Array<Float>] HSL value represented as an array of numbers
+
+    def self.hex_to_hsl(hex_code)
+      rgb_to_hsl(hex_to_rgb(hex_code))
+    end
+
+    ##
+    # Check if a given array is a valid representation of RGB color.
+    #
+    # @param rgb [Array<Integer>] RGB value represented as an array of integers
+    # @return [true, false] true if a valid RGB value is passed
+
+    def self.valid_rgb?(rgb)
+      rgb.length == 3 &&
+        rgb.all? {|c| c.is_a?(Integer) && c >= 0 && c <= 255 }
+    end
+
+    ##
+    # Check if a given array is a valid representation of HSL color.
+    #
+    # @param hsl [Array<Float>] HSL value represented as an array of numbers
+    # @return [true, false] true if a valid HSL value is passed
+
+    def self.valid_hsl?(hsl)
+      return false unless hsl.length == 3
+      hsl.each_with_index do |c, i|
+        return false if !c.is_a?(Numeric) || c < 0 || c > HSL_UPPER_LIMIT[i]
+      end
+      true
+    end
+
+    ##
+    # Check if a given string is a valid representation of RGB color.
+    #
+    # @param hex_code [String] RGB value in hex color code such as "#ffff00"
+    # @return [true, false] true if a vaild hex color code is passed
+
+    def self.valid_hex?(hex_code)
+      HEX_RE.match?(hex_code)
+    end
+
+    ##
+    # Check if given two hex color codes represent a same color.
+    #
+    # @param hex1 [String] RGB value in hex color code such as "#ffff00",
+    #   "#ffff00", "#FFFF00" or "#ff0"
+    # @param hex2 [String] RGB value in hex color code such as "#ffff00",
+    #   "#ffff00", "#FFFF00" or "#ff0"
+    # @return [true, false] true if given two colors are same
+
+    def self.same_hex_color?(hex1, hex2)
+      normalize_hex(hex1) == normalize_hex(hex2)
+    end
+
+    ##
+    # Check if a given string is consists of uppercase letters.
+    #
+    # @param str [String] string to be checked
+    # @return [true, false] true if letters in the passed string are all
+    #   in uppercase.
+
+    def self.uppercase?(str)
+      !/[[:lower:]]/.match?(str)
+    end
+  end
+end