color_contrast_calc 0.1.0

data/lib/color_contrast_calc/converter.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+require 'matrix'
+
+module ColorContrastCalc
+  ##
+  # Collection of modules that implement the main logic of instance
+  # methods of Color, +Color#new_*_color()+.
+
+  module Converter
+    using Shim unless 0.respond_to? :clamp
+
+    ##
+    # Values given as an array are passed to a given block, and new values
+    # returned from the block are rounded and clamped between 0 and 255,
+    # so that the resulting values can be treated as an RGB value.
+    #
+    # @param vals [Array<Numeric>] An array of three numbers
+    # @return [Array<Integer>] Value that can possibly be an RGB value
+
+    def self.rgb_map(vals)
+      if block_given?
+        return vals.map do |val|
+          new_val = yield val
+          new_val.round.clamp(0, 255)
+        end
+      end
+
+      vals.map {|val| val.round.clamp(0, 255) }
+    end
+
+    module Contrast
+      ##
+      # Return contrast adjusted RGB value of passed color.
+      #
+      # THe calculation is based on the definition found at
+      # https://www.w3.org/TR/filter-effects/#funcdef-contrast
+      # https://www.w3.org/TR/SVG/filters.html#TransferFunctionElementAttributes
+      # @param rgb [Array<Integer>] The Original RGB value before the adjustment
+      # @param ratio [Float] Adjustment ratio in percentage
+      # @return [Array<Integer>] Contrast adjusted RGB value
+
+      def self.calc_rgb(rgb, ratio = 100)
+        r = ratio.to_f
+        Converter.rgb_map(rgb) {|c| (c * r + 255 * (50 - r / 2)) / 100 }
+      end
+    end
+
+    module Brightness
+      ##
+      # Return brightness adjusted RGB value of passed color.
+      #
+      # THe calculation is based on the definition found at
+      # https://www.w3.org/TR/filter-effects/#funcdef-brightness
+      # https://www.w3.org/TR/SVG/filters.html#TransferFunctionElementAttributes
+      # @param rgb [Array<Integer>] The Original RGB value before the adjustment
+      # @param ratio [Float] Adjustment ratio in percentage
+      # @return [Array<Integer>] Brightness adjusted RGB value
+
+      def self.calc_rgb(rgb, ratio = 100)
+        r = ratio.to_f
+        Converter.rgb_map(rgb) {|c| c * r / 100 }
+      end
+    end
+
+    module Invert
+      ##
+      # Return an inverted RGB value of passed color.
+      #
+      # The calculation is based on the definition found at
+      # https://www.w3.org/TR/filter-effects/#funcdef-invert
+      # https://www.w3.org/TR/filter-effects-1/#invertEquivalent
+      # https://www.w3.org/TR/SVG/filters.html#TransferFunctionElementAttributes
+      # @param rgb [Array<Integer>] The Original RGB value before the inversion
+      # @param ratio [Float] Proportion of the conversion in percentage
+      # @return [Array<Integer>] Inverted RGB value
+
+      def self.calc_rgb(rgb, ratio)
+        r = ratio.to_f
+        rgb.map {|c| ((100 * c - 2 * c * r + 255 * r) / 100).round }
+      end
+    end
+
+    module HueRotate
+      # @private
+      CONST_PART = Matrix[[0.213, 0.715, 0.072],
+                          [0.213, 0.715, 0.072],
+                          [0.213, 0.715, 0.072]]
+
+      # @private
+      COS_PART = Matrix[[0.787, -0.715, -0.072],
+                        [-0.213, 0.285, -0.072],
+                        [-0.213, -0.715, 0.928]]
+
+      # @private
+      SIN_PART = Matrix[[-0.213, -0.715, 0.928],
+                        [0.143, 0.140, -0.283],
+                        [-0.787, 0.715, 0.072]]
+
+      ##
+      # Return a hue rotation applied RGB value of passed color.
+      #
+      # THe calculation is based on the definition found at
+      # https://www.w3.org/TR/filter-effects/#funcdef-hue-rotate
+      # https://www.w3.org/TR/SVG/filters.html#TransferFunctionElementAttributes
+      # @param rgb [Array<Integer>] The Original RGB value before the rotation
+      # @param deg [Float] Degrees of rotation (0 to 360)
+      # @return [Array<Integer>] Hue rotation applied RGB value
+
+      def self.calc_rgb(rgb, deg)
+        Converter.rgb_map((calc_rotation(deg) * Vector[*rgb]).to_a)
+      end
+
+      def self.deg_to_rad(deg)
+        Math::PI * deg / 180
+      end
+
+      private_class_method :deg_to_rad
+
+      def self.calc_rotation(deg)
+        rad = deg_to_rad(deg)
+        cos_part = COS_PART * Math.cos(rad)
+        sin_part = SIN_PART * Math.sin(rad)
+        CONST_PART + cos_part + sin_part
+      end
+
+      private_class_method :calc_rotation
+    end
+
+    module Saturate
+      # @private
+      CONST_PART = HueRotate::CONST_PART
+      # @private
+      SATURATE_PART = HueRotate::COS_PART
+
+      ##
+      # Return a saturated RGB value of passed color.
+      #
+      # The calculation is based on the definition found at
+      # https://www.w3.org/TR/filter-effects/#funcdef-saturate
+      # https://www.w3.org/TR/SVG/filters.html#feColorMatrixElement
+      # @param rgb [Array<Integer>] The Original RGB value before the saturation
+      # @param s [Float] Proprtion of the conversion in percentage
+      # @return [Array<Integer>] Saturated RGB value
+
+      def self.calc_rgb(rgb, s)
+        Converter.rgb_map((calc_saturation(s) * Vector[*rgb]).to_a)
+      end
+
+      def self.calc_saturation(s)
+        CONST_PART + SATURATE_PART * (s.to_f / 100)
+      end
+
+      private_class_method :calc_saturation
+    end
+
+    module Grayscale
+      # @private
+      CONST_PART = Matrix[[0.2126, 0.7152, 0.0722],
+                          [0.2126, 0.7152, 0.0722],
+                          [0.2126, 0.7152, 0.0722]]
+
+      # @private
+      RATIO_PART = Matrix[[0.7874, -0.7152, -0.0722],
+                          [-0.2126, 0.2848, -0.0722],
+                          [-0.2126, -0.7152, 0.9278]]
+
+      ##
+      # Convert passed a passed color to grayscale.
+      #
+      # The calculation is based on the definition found at
+      # https://www.w3.org/TR/filter-effects/#funcdef-grayscale
+      # https://www.w3.org/TR/filter-effects/#grayscaleEquivalent
+      # https://www.w3.org/TR/SVG/filters.html#feColorMatrixElement
+      # @param rgb [Array<Integer>] The Original RGB value before the conversion
+      # @param s [Float] Conversion ratio in percentage
+      # @return [Array<Integer>] RGB value of grayscale color
+
+      def self.calc_rgb(rgb, s)
+        Converter.rgb_map((calc_grayscale(s) * Vector[*rgb]).to_a)
+      end
+
+      def self.calc_grayscale(s)
+        r = 1 - [100, s].min.to_f / 100
+        CONST_PART + RATIO_PART * r
+      end
+
+      private_class_method :calc_grayscale
+    end
+  end
+end

data/lib/color_contrast_calc/data/color_keywords.json

@@ -0,0 +1,149 @@
+[
+  ["aliceblue", "#f0f8ff"],
+  ["antiquewhite", "#faebd7"],
+  ["aqua", "#00ffff"],
+  ["aquamarine", "#7fffd4"],
+  ["azure", "#f0ffff"],
+  ["beige", "#f5f5dc"],
+  ["bisque", "#ffe4c4"],
+  ["black", "#000000"],
+  ["blanchedalmond", "#ffebcd"],
+  ["blue", "#0000ff"],
+  ["blueviolet", "#8a2be2"],
+  ["brown", "#a52a2a"],
+  ["burlywood", "#deb887"],
+  ["cadetblue", "#5f9ea0"],
+  ["chartreuse", "#7fff00"],
+  ["chocolate", "#d2691e"],
+  ["coral", "#ff7f50"],
+  ["cornflowerblue", "#6495ed"],
+  ["cornsilk", "#fff8dc"],
+  ["crimson", "#dc143c"],
+  ["cyan", "#00ffff"],
+  ["darkblue", "#00008b"],
+  ["darkcyan", "#008b8b"],
+  ["darkgoldenrod", "#b8860b"],
+  ["darkgray", "#a9a9a9"],
+  ["darkgreen", "#006400"],
+  ["darkgrey", "#a9a9a9"],
+  ["darkkhaki", "#bdb76b"],
+  ["darkmagenta", "#8b008b"],
+  ["darkolivegreen", "#556b2f"],
+  ["darkorange", "#ff8c00"],
+  ["darkorchid", "#9932cc"],
+  ["darkred", "#8b0000"],
+  ["darksalmon", "#e9967a"],
+  ["darkseagreen", "#8fbc8f"],
+  ["darkslateblue", "#483d8b"],
+  ["darkslategray", "#2f4f4f"],
+  ["darkslategrey", "#2f4f4f"],
+  ["darkturquoise", "#00ced1"],
+  ["darkviolet", "#9400d3"],
+  ["deeppink", "#ff1493"],
+  ["deepskyblue", "#00bfff"],
+  ["dimgray", "#696969"],
+  ["dimgrey", "#696969"],
+  ["dodgerblue", "#1e90ff"],
+  ["firebrick", "#b22222"],
+  ["floralwhite", "#fffaf0"],
+  ["forestgreen", "#228b22"],
+  ["fuchsia", "#ff00ff"],
+  ["gainsboro", "#dcdcdc"],
+  ["ghostwhite", "#f8f8ff"],
+  ["gold", "#ffd700"],
+  ["goldenrod", "#daa520"],
+  ["gray", "#808080"],
+  ["green", "#008000"],
+  ["greenyellow", "#adff2f"],
+  ["grey", "#808080"],
+  ["honeydew", "#f0fff0"],
+  ["hotpink", "#ff69b4"],
+  ["indianred", "#cd5c5c"],
+  ["indigo", "#4b0082"],
+  ["ivory", "#fffff0"],
+  ["khaki", "#f0e68c"],
+  ["lavender", "#e6e6fa"],
+  ["lavenderblush", "#fff0f5"],
+  ["lawngreen", "#7cfc00"],
+  ["lemonchiffon", "#fffacd"],
+  ["lightblue", "#add8e6"],
+  ["lightcoral", "#f08080"],
+  ["lightcyan", "#e0ffff"],
+  ["lightgoldenrodyellow", "#fafad2"],
+  ["lightgray", "#d3d3d3"],
+  ["lightgreen", "#90ee90"],
+  ["lightgrey", "#d3d3d3"],
+  ["lightpink", "#ffb6c1"],
+  ["lightsalmon", "#ffa07a"],
+  ["lightseagreen", "#20b2aa"],
+  ["lightskyblue", "#87cefa"],
+  ["lightslategray", "#778899"],
+  ["lightslategrey", "#778899"],
+  ["lightsteelblue", "#b0c4de"],
+  ["lightyellow", "#ffffe0"],
+  ["lime", "#00ff00"],
+  ["limegreen", "#32cd32"],
+  ["linen", "#faf0e6"],
+  ["magenta", "#ff00ff"],
+  ["maroon", "#800000"],
+  ["mediumaquamarine", "#66cdaa"],
+  ["mediumblue", "#0000cd"],
+  ["mediumorchid", "#ba55d3"],
+  ["mediumpurple", "#9370db"],
+  ["mediumseagreen", "#3cb371"],
+  ["mediumslateblue", "#7b68ee"],
+  ["mediumspringgreen", "#00fa9a"],
+  ["mediumturquoise", "#48d1cc"],
+  ["mediumvioletred", "#c71585"],
+  ["midnightblue", "#191970"],
+  ["mintcream", "#f5fffa"],
+  ["mistyrose", "#ffe4e1"],
+  ["moccasin", "#ffe4b5"],
+  ["navajowhite", "#ffdead"],
+  ["navy", "#000080"],
+  ["oldlace", "#fdf5e6"],
+  ["olive", "#808000"],
+  ["olivedrab", "#6b8e23"],
+  ["orange", "#ffa500"],
+  ["orangered", "#ff4500"],
+  ["orchid", "#da70d6"],
+  ["palegoldenrod", "#eee8aa"],
+  ["palegreen", "#98fb98"],
+  ["paleturquoise", "#afeeee"],
+  ["palevioletred", "#db7093"],
+  ["papayawhip", "#ffefd5"],
+  ["peachpuff", "#ffdab9"],
+  ["peru", "#cd853f"],
+  ["pink", "#ffc0cb"],
+  ["plum", "#dda0dd"],
+  ["powderblue", "#b0e0e6"],
+  ["purple", "#800080"],
+  ["red", "#ff0000"],
+  ["rosybrown", "#bc8f8f"],
+  ["royalblue", "#4169e1"],
+  ["saddlebrown", "#8b4513"],
+  ["salmon", "#fa8072"],
+  ["sandybrown", "#f4a460"],
+  ["seagreen", "#2e8b57"],
+  ["seashell", "#fff5ee"],
+  ["sienna", "#a0522d"],
+  ["silver", "#c0c0c0"],
+  ["skyblue", "#87ceeb"],
+  ["slateblue", "#6a5acd"],
+  ["slategray", "#708090"],
+  ["slategrey", "#708090"],
+  ["snow", "#fffafa"],
+  ["springgreen", "#00ff7f"],
+  ["steelblue", "#4682b4"],
+  ["tan", "#d2b48c"],
+  ["teal", "#008080"],
+  ["thistle", "#d8bfd8"],
+  ["tomato", "#ff6347"],
+  ["turquoise", "#40e0d0"],
+  ["violet", "#ee82ee"],
+  ["wheat", "#f5deb3"],
+  ["white", "#ffffff"],
+  ["whitesmoke", "#f5f5f5"],
+  ["yellow", "#ffff00"],
+  ["yellowgreen", "#9acd32"]
+]

data/lib/color_contrast_calc/shim.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+module ColorContrastCalc
+  ##
+  # Provide methods that are not availabe in older versions of Ruby.
+
+  module Shim
+    refine Regexp do
+      ##
+      # Regexp.match?() is available for Ruby >= 2.4,
+      # and the following implementation does not satisfy
+      # the full specification of the original method.
+
+      def match?(str)
+        self === str
+      end
+    end
+
+    refine Numeric do
+      ##
+      # Comparable#clamp() is available for Ruby >= 2.4,
+      # and the following implementation does not satisfy
+      # the full specification of the original method.
+
+      def clamp(lower_bound, upper_bound)
+        return lower_bound if self < lower_bound
+        return upper_bound if self > upper_bound
+        self
+      end
+    end
+  end
+end

data/lib/color_contrast_calc/sorter.rb

@@ -0,0 +1,227 @@
+# frozen_string_literal: true
+
+require 'color_contrast_calc/color'
+
+module ColorContrastCalc
+  ##
+  # Provide two methods sort() and compile_compare_function()
+  #
+  # The other methods defined in this module should not be considered
+  # as stable interfaces.
+
+  module Sorter
+    using Shim unless //.respond_to? :match?
+
+    # @private The visitiblity ot this module is not changed just
+    #   because it is used in unit tests.
+
+    module ColorComponent
+      RGB = 'rgb'.chars
+      HSL = 'hsl'.chars
+    end
+
+    module CompFunc
+      # @private
+      ASCEND = proc {|x, y| x <=> y }
+      # @private
+      DESCEND = proc {|x, y| y <=> x }
+    end
+
+    private_constant :CompFunc
+
+    ##
+    # Constants used as a second argeument of Sorter.compile_compare_function()
+    #
+    # The constants COLOR, COMPONENTS and HEX are expected to be used as a
+    # second argument of Sorter.compile_compare_function()
+
+    module KeyTypes
+      # The function returned by Sorter.compile_compare_function() expects
+      # instances of Color as key values when this constants is specified.
+      COLOR = :color
+      # The function returned by Sorter.compile_compare_function() expects
+      # RGB or HSL values as key values when this constants is specified.
+      COMPONENTS = :components
+      # The function returned by Sorter.compile_compare_function() expects
+      # hex color codes as key values when this constants is specified.
+      HEX = :hex
+      # @private
+      CLASS_TO_TYPE = {
+        Color => COLOR,
+        Array => COMPONENTS,
+        String => HEX
+      }.freeze
+
+      ##
+      # Returns COLOR, COMPONENTS or HEX when a possible key value is passed.
+      #
+      # @param color [Color, Array<Numeric>, String] Possible key value
+      # @param key_mapper [Proc] Function which retrieves a key value from
+      #   +color+, that means <tt>key_mapper[color]</tt> returns a key value
+      # @return [:color, :components, :hex] Symbol that represents a key type
+
+      def self.guess(color, key_mapper = nil)
+        key = key_mapper ? key_mapper[color] : color
+        CLASS_TO_TYPE[key.class]
+      end
+    end
+
+    # @private shorthands for Utils.hex_to_rgb() and .hex_to_hsl()
+    HEX_TO_COMPONENTS = {
+      rgb: Utils.method(:hex_to_rgb),
+      hsl: Utils.method(:hex_to_hsl)
+    }.freeze
+
+    ##
+    # Sort colors in the order specified by +color_order+.
+    #
+    # Sort colors given as a list or tuple of Color instances or hex
+    # color codes.
+    #
+    # You can specify sorting order by giving a +color_order+ tring, such
+    # as "HSL" or "RGB". A component of +color_order+ on the left side
+    # has a higher sorting precedence, and an uppercase letter means
+    # descending order.
+    # @param colors [Array<Color>, Array<String>] Array of Color instances
+    #   or items from which color hex codes can be retrieved.
+    # @param color_order [String] String such as "HSL", "RGB" or "lsH"
+    # @param key_mapper [Proc, nil] Proc object used to retrive key values
+    #   from items to be sorted
+    # @return [Array<Color>, Array<String>] Array of of sorted colors
+
+    def self.sort(colors, color_order = 'hSL', key_mapper = nil)
+      key_type = KeyTypes.guess(colors[0], key_mapper)
+      compare = compile_compare_function(color_order, key_type, key_mapper)
+
+      colors.sort(&compare)
+    end
+
+    ##
+    # Return a Proc object to be passed to Array#sort().
+    #
+    # @param color_order [String] String such as "HSL", "RGB" or "lsH"
+    # @param key_type [Symbol] +:color+, +:components+ or +:hex+
+    # @param key_mapper [Proc, nil] Proc object to be used to retrive
+    #   key values from items to be sorted.
+    # @return [Proc] Proc object to be passed to Array#sort()
+
+    def self.compile_compare_function(color_order, key_type, key_mapper = nil)
+      case key_type
+      when KeyTypes::COLOR
+        compare = compile_color_compare_function(color_order)
+      when KeyTypes::COMPONENTS
+        compare = compile_components_compare_function(color_order)
+      when KeyTypes::HEX
+        compare = compile_hex_compare_function(color_order)
+      end
+
+      compose_function(compare, key_mapper)
+    end
+
+    # @private
+
+    def self.compose_function(compare_function, key_mapper = nil)
+      return compare_function unless key_mapper
+
+      proc do |color1, color2|
+        compare_function[key_mapper[color1], key_mapper[color2]]
+      end
+    end
+
+    # @private
+
+    def self.color_component_pos(color_order, ordered_components)
+      color_order.downcase.chars.map do |component|
+        ordered_components.index(component)
+      end
+    end
+
+    # @private
+
+    def self.parse_color_order(color_order)
+      ordered_components = ColorComponent::RGB
+      ordered_components = ColorComponent::HSL if hsl_order?(color_order)
+      pos = color_component_pos(color_order, ordered_components)
+      funcs = []
+      pos.each_with_index do |ci, i|
+        c = color_order[i]
+        funcs[ci] = Utils.uppercase?(c) ? CompFunc::DESCEND : CompFunc::ASCEND
+      end
+      { pos: pos, funcs: funcs }
+    end
+
+    # @private
+
+    def self.hsl_order?(color_order)
+      /[hsl]{3}/i.match?(color_order)
+    end
+
+    # @private
+
+    def self.compare_color_components(color1, color2, order)
+      funcs = order[:funcs]
+      order[:pos].each do |i|
+        result = funcs[i][color1[i], color2[i]]
+        return result unless result.zero?
+      end
+
+      0
+    end
+
+    # @private
+
+    def self.compile_components_compare_function(color_order)
+      order = parse_color_order(color_order)
+
+      proc do |color1, color2|
+        compare_color_components(color1, color2, order)
+      end
+    end
+
+    # @private
+
+    def self.compile_hex_compare_function(color_order)
+      order = parse_color_order(color_order)
+      converter = HEX_TO_COMPONENTS[:rgb]
+      converter = HEX_TO_COMPONENTS[:hsl] if hsl_order?(color_order)
+      cache = {}
+
+      proc do |hex1, hex2|
+        color1 = hex_to_components(hex1, converter, cache)
+        color2 = hex_to_components(hex2, converter, cache)
+
+        compare_color_components(color1, color2, order)
+      end
+    end
+
+    # @private
+
+    def self.hex_to_components(hex, converter, cache)
+      cached_components = cache[hex]
+      return cached_components if cached_components
+
+      components = converter[hex]
+      cache[hex] = components
+
+      components
+    end
+
+    private_class_method :hex_to_components
+
+    # @private
+
+    def self.compile_color_compare_function(color_order)
+      order = parse_color_order(color_order)
+
+      if hsl_order?(color_order)
+        proc do |color1, color2|
+          compare_color_components(color1.hsl, color2.hsl, order)
+        end
+      else
+        proc do |color1, color2|
+          compare_color_components(color1.rgb, color2.rgb, order)
+        end
+      end
+    end
+  end
+end