Module: ColorContrastCalc

Defined in:
lib/color_contrast_calc.rb,
lib/color_contrast_calc/shim.rb,
lib/color_contrast_calc/color.rb,
lib/color_contrast_calc/utils.rb,
lib/color_contrast_calc/sorter.rb,
lib/color_contrast_calc/checker.rb,
lib/color_contrast_calc/version.rb,
lib/color_contrast_calc/converter.rb,
lib/color_contrast_calc/deprecated.rb,
lib/color_contrast_calc/threshold_finder.rb,
lib/color_contrast_calc/transparency_calc.rb,
lib/color_contrast_calc/color_function_parser.rb,
lib/color_contrast_calc/invalid_color_representation_error.rb

Defined Under Namespace

Modules: Checker, ColorFunctionParser, Converter, Deprecated, Rgb, Shim, Sorter, ThresholdFinder, TransparencyCalc, Utils Classes: Color, InvalidColorRepresentationError

Constant Summary collapse

VERSION = 
'0.9.0'

Class Method Summary collapse

Class Method Details

.color_from(color_value, name = nil) ⇒ Color

Return an instance of Color.

As color_value, you can pass a predefined color name, an RGB value represented as an array of integers like [255, 255, 0], or a string such as a hex code like “#ffff00”. name is assigned to the returned instance.

Parameters:

  • color_value (String, Array<Integer>) —

    Name of a predefined color, hex color code, rgb/hsl/hwb functions or RGB value. Yellow, for example, can be given as [255, 255, 0], “#ffff00”, “rgb(255, 255, 255)”, “hsl(60deg, 100% 50%)” or “hwb(60deg 0% 0%)”.

  • name (String) (defaults to: nil) —

    Without specifying a name, a color keyword name (if exists) or the value of normalized hex color code is assigned to Color#name

Returns:

  • (Color) —

    Instance of Color



29
30
31
 
# File 'lib/color_contrast_calc.rb', line 29

def self.color_from(color_value, name = nil)
  Color.color_from(color_value, name)
end

.contrast_ratio(color1, color2) ⇒ Float

Calculate the contrast ratio of given colors.

The definition of contrast ratio is given at https://www.w3.org/TR/2008/REC-WCAG20-20081211/#contrast-ratiodef

Please note that this method may be slow, as it internally creates Color instances.

Parameters:

  • color1 (String, Array<Integer>, Color) —

    color given as a string, an array of integers or a Color instance. Yellow, for example, can be given as “#ffff00”, “#ff0”, “rgb(255, 255, 0)”, “hsl(60deg, 100%, 50%)”, “hwb(60deg 0% 0%)” or [255, 255, 0].

  • color2 (String, Array<Integer>, Color) —

    color given as a string, an array of integers or a Color instance.

Returns:

  • (Float) —

    Contrast ratio



75
76
77
 
# File 'lib/color_contrast_calc.rb', line 75

def self.contrast_ratio(color1, color2)
  Color.as_color(color1).contrast_ratio_against(Color.as_color(color2))
end

.contrast_ratio_with_opacity(foreground, background, base = Color::WHITE) ⇒ Float

Calculate the contrast ratio of transparent colors.

For the calculation, you have to specify three colors because when both of two colors to be compared are transparent, the third color put under them filters through them.

Parameters:

  • foreground (String, Array<Integer>, Color) —

    The uppermost color such as “rgb(255, 255, 0, 0.5)” or “hsl(60 100% 50% / 50%)”

  • background (String, Array<Integer>, Color) —

    The color placed between the others

  • base (String, Array<Integer>, Color) (defaults to: Color::WHITE) —

    The color placed in the bottom. When the backgound is completely opaque, this color is ignored.

Returns:

  • (Float) —

    Contrast ratio



95
96
97
98
99
100
101
102
103
 
# File 'lib/color_contrast_calc.rb', line 95

def self.contrast_ratio_with_opacity(foreground, background,
                                     base = Color::WHITE)
  params = [foreground, background, base].map do |c|
    color = Color.as_color(c)
    color.rgb + [color.opacity]
  end

  TransparencyCalc.contrast_ratio(*params)
end

.higher_contrast_base_color_for(color, light_base: Color::WHITE, dark_base: Color::BLACK) ⇒ String, ...

Select from two colors the one of which the contrast ratio is higher than the other’s, against a given color.

Note that this method is tentatively provided and may be changed later including its name.

Parameters:

  • color (String, Array<Integer>, Color) —

    A color against which the contrast ratio of other two colors will be calculated

  • light_base (String, Array<Integer>, Color) (defaults to: Color::WHITE) —

    One of two colors which will be returned depending their contrast ratio: This one will be returned when the contast ratio of the colors happen to be same.

  • dark_base (String, Array<Integer>, Color) (defaults to: Color::BLACK) —

    One of two colors which will be returned depending their contrast ratio

Returns:

  • (String, Array<Integer>, Color) —

    One of the values specified as light_base and dark_base



123
124
125
126
127
128
129
 
# File 'lib/color_contrast_calc.rb', line 123

def self.higher_contrast_base_color_for(color,
                                        light_base: Color::WHITE,
                                        dark_base: Color::BLACK)
  ratio_with_light = contrast_ratio(color, light_base)
  ratio_with_dark = contrast_ratio(color, dark_base)
  ratio_with_light < ratio_with_dark ? dark_base : light_base
end

.hsl_colors(s: 100, l: 50, h_interval: 1) ⇒ Array<Color>

Return a list of colors which share the same saturation and lightness.

By default, so-called pure colors are returned.

Parameters:

  • s (defaults to: 100) —

    100 [Float] Ratio of saturation in percentage

  • l (defaults to: 50) —

    50 [Float] Ratio of lightness in percentage

  • h_interval (defaults to: 1) —

    1 [Integer] Interval of hues in degrees. By default, the method returns 360 hues beginning from red.

Returns:

  • (Array<Color>) —

    Array of colors which share the same saturation and lightness



166
167
168
 
# File 'lib/color_contrast_calc.rb', line 166

def self.hsl_colors(s: 100, l: 50, h_interval: 1)
  Color::List.hsl_colors(s: s, l: l, h_interval: h_interval)
end

.named_colors(frozen: true) ⇒ Array<Color>

Return an array of named colors.

You can find the color names at www.w3.org/TR/SVG/types.html#ColorKeywords

Parameters:

  • frozen (true|false) (defaults to: true) —

    Set to false if you want an unfrozen array.

Returns:

  • (Array<Color>) —

    Named colors



139
140
141
142
 
# File 'lib/color_contrast_calc.rb', line 139

def self.named_colors(frozen: true)
  named_colors = Color::List::NAMED_COLORS
  frozen ? named_colors : named_colors.dup
end

.sort(colors, color_order = 'hSL', key_mapper = nil, &key_mapper_block) ⇒ Array<Color>, Array<String>

Sort colors in the order specified by color_order.

Sort colors given as an array of Color instances or hex color codes. (alias of Sorter.sort())

You can specify sorting order by giving a color_order string, 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.

Parameters:

  • colors (Array<Color>, Array<String>) —

    Array of Color instances or items from which color hex codes can be retrieved.

  • color_order (String) (defaults to: 'hSL') —

    String such as “HSL”, “RGB” or “lsH”

  • key_mapper (Proc, nil) (defaults to: nil) —

    Proc object used to retrive key values from items to be sorted

  • key_mapper_block (Proc) —

    Block that is used instead of key_mapper when the latter is not given

Returns:

  • (Array<Color>, Array<String>) —

    Array of sorted colors



52
53
54
55
56
 
# File 'lib/color_contrast_calc.rb', line 52

def self.sort(colors, color_order = 'hSL',
              key_mapper = nil, &key_mapper_block)
  key_mapper = key_mapper_block if !key_mapper && key_mapper_block
  Sorter.sort(colors, color_order, key_mapper)
end

.web_safe_colors(frozen: true) ⇒ Array<Color>

Return an array of web safe colors.

Parameters:

  • frozen (true|false) (defaults to: true) —

    Set to false if you want an unfrozen array.

Returns:

  • (Array<Color>) —

    Web safe colors



150
151
152
153
 
# File 'lib/color_contrast_calc.rb', line 150

def self.web_safe_colors(frozen: true)
  colors = Color::List::WEB_SAFE_COLORS
  frozen ? colors : colors.dup
end