Class: ColorContrastCalc::Color

Inherits:
Object
  • Object
show all
Extended by:
Factory
Includes:
Deprecated::Color
Defined in:
lib/color_contrast_calc/color.rb

Overview

Represent specific colors.

This class also provides lists of predefined colors represented as instances of Color class.

Defined Under Namespace

Modules: Factory, List

Instance Attribute Summary collapse

Instance Method Summary collapse

Methods included from Factory

as_color, color_from, from_hex, from_hsl, from_name, from_rgb

Methods included from Deprecated::Color::Factory

#new_from_hsl

Methods included from Deprecated::Color

#new_brightness_color, #new_contrast_color, #new_grayscale_color, #new_hue_rotate_color, #new_invert_color, #new_saturate_color

Constructor Details

#initialize(rgb, name = nil) ⇒ Color

Create a new instance of Color.

Parameters:

  • rgb (Array<Integer>, String) —

    RGB value represented as an array of integers or hex color code such as [255, 255, 0] or “#ffff00”.

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

    You can name the color to be created. Without this option, a color keyword name (if exists) or the value of normalized hex color code is assigned instead.



195
196
197
198
199
200
 
# File 'lib/color_contrast_calc/color.rb', line 195

def initialize(rgb, name = nil)
  @rgb = rgb.is_a?(String) ? Utils.hex_to_rgb(rgb) : rgb
  @hex = Utils.rgb_to_hex(@rgb)
  @name = name || common_name
  @relative_luminance = Checker.relative_luminance(@rgb)
end

Instance Attribute Details

#hex ⇒ String (readonly)

Returns Hex color code of the color.

Returns:

  • (String) —

    Hex color code of the color



183
 
# File 'lib/color_contrast_calc/color.rb', line 183

attr_reader :rgb, :hex, :name, :relative_luminance

#name ⇒ String (readonly)

Returns Name of the color.

Returns:

  • (String) —

    Name of the color



183
 
# File 'lib/color_contrast_calc/color.rb', line 183

attr_reader :rgb, :hex, :name, :relative_luminance

#relative_luminance ⇒ Object (readonly)

Returns the value of attribute relative_luminance.



183
 
# File 'lib/color_contrast_calc/color.rb', line 183

attr_reader :rgb, :hex, :name, :relative_luminance

#rgb ⇒ Array<Integer> (readonly)

Returns RGB value of the color.

Returns:

  • (Array<Integer>) —

    RGB value of the color



183
184
185
 
# File 'lib/color_contrast_calc/color.rb', line 183

def rgb
  @rgb
end

Instance Method Details

#common_name ⇒ String

Return a color keyword name when the name corresponds to the hex code of the color. Otherwise the hex code will be returned.

Returns:

  • (String) —

    Color keyword name or hex color code



223
224
225
226
 
# File 'lib/color_contrast_calc/color.rb', line 223

def common_name
  named_color = List::HEX_TO_COLOR[@hex]
  named_color && named_color.name || @hex
end

#complementary(name = nil) ⇒ Color

Return a complementary color of the original color.

Parameters:

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

    You can name the color to be created. Without this option, the value of normalized hex color code is assigned instead.

Returns:

  • (Color) —

    New complementary color



313
314
315
316
 
# File 'lib/color_contrast_calc/color.rb', line 313

def complementary(name = nil)
  minmax = rgb.minmax.reduce {|min, max| min + max }
  self.class.new(rgb.map {|c| minmax - c }, name)
end

#contrast_level(other_color) ⇒ String

Return the level of contrast ratio defined by WCAG 2.0.

Parameters:

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

    Another instance of Color, RGB value or hex color code

Returns:

  • (String) —

    “A”, “AA” or “AAA” if the contrast ratio meets the criteria of WCAG 2.0, otherwise “-”



376
377
378
 
# File 'lib/color_contrast_calc/color.rb', line 376

def contrast_level(other_color)
  Checker.ratio_to_level(contrast_ratio_against(other_color))
end

#contrast_ratio_against(other_color) ⇒ Float

Calculate the contrast ratio against another color.

Parameters:

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

    Another instance of Color, RGB value or hex color code

Returns:

  • (Float) —

    Contrast ratio



359
360
361
362
363
364
365
366
 
# File 'lib/color_contrast_calc/color.rb', line 359

def contrast_ratio_against(other_color)
  unless other_color.is_a? Color
    return Checker.contrast_ratio(rgb, other_color)
  end

  Checker.luminance_to_contrast_ratio(relative_luminance,
                                      other_color.relative_luminance)
end

#find_brightness_threshold(other_color, level = Checker::Level::AA) ⇒ Color

Try to find a color who has a satisfying contrast ratio.

The returned color is gained by modifying the brightness of another color. Even when a color that satisfies the specified level is not found, it returns a new color anyway.

Parameters:

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

    Color before the adjustment of brightness

  • level (String) (defaults to: Checker::Level::AA) —

    “A”, “AA” or “AAA”

Returns:

  • (Color) —

    New color whose brightness is adjusted from that of other_color



330
331
332
333
 
# File 'lib/color_contrast_calc/color.rb', line 330

def find_brightness_threshold(other_color, level = Checker::Level::AA)
  other_color = Color.new(other_color) unless other_color.is_a? Color
  Color.new(ThresholdFinder::Brightness.find(rgb, other_color.rgb, level))
end

#find_lightness_threshold(other_color, level = Checker::Level::AA) ⇒ Color

Try to find a color who has a satisfying contrast ratio.

The returned color is gained by modifying the lightness of another color. Even when a color that satisfies the specified level is not found, it returns a new color anyway.

Parameters:

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

    Color before the adjustment of lightness

  • level (String) (defaults to: Checker::Level::AA) —

    “A”, “AA” or “AAA”

Returns:

  • (Color) —

    New color whose brightness is adjusted from that of other_color



347
348
349
350
 
# File 'lib/color_contrast_calc/color.rb', line 347

def find_lightness_threshold(other_color, level = Checker::Level::AA)
  other_color = Color.new(other_color) unless other_color.is_a? Color
  Color.new(ThresholdFinder::Lightness.find(rgb, other_color.rgb, level))
end

#higher_luminance_than?(other_color) ⇒ Boolean

Check if the color has higher luminance than another color.

Parameters:

  • other_color (Color) —

    Another color

Returns:

  • (Boolean) —

    true if the relative luminance of self is higher than that of other_color



463
464
465
 
# File 'lib/color_contrast_calc/color.rb', line 463

def higher_luminance_than?(other_color)
  relative_luminance > other_color.relative_luminance
end

#hsl ⇒ Array<Float>

Return HSL value of the color.

The value is calculated from the RGB value, so if you create the instance by Color.from_hsl method, the value used to create the color does not necessarily correspond to the value of this property.

Returns:

  • (Array<Float>) —

    HSL value represented as an array of numbers



212
213
214
 
# File 'lib/color_contrast_calc/color.rb', line 212

def hsl
  @hsl ||= Utils.rgb_to_hsl(@rgb)
end

#light_color? ⇒ Boolean

Check if the contrast ratio against black is higher than against white.

Returns:

  • (Boolean) —

    true if the contrast ratio against white is qual to or less than the ratio against black



484
485
486
 
# File 'lib/color_contrast_calc/color.rb', line 484

def light_color?
  Checker.light_color?(rgb)
end

#max_contrast? ⇒ Boolean

Check if the color reachs already the max contrast.

The max contrast in this context means that of colors modified by the operation defined at

Returns:

  • (Boolean) —

    true if self.with_contrast® where r is greater than 100 returns the same color as self.



440
441
442
 
# File 'lib/color_contrast_calc/color.rb', line 440

def max_contrast?
  rgb.all? {|c| RGB_LIMITS.include? c }
end

#min_contrast? ⇒ Boolean

Check if the color reachs already the min contrast.

The min contrast in this context means that of colors modified by the operation defined at

Returns:

  • (Boolean) —

    true if self is the same color as “#808080”



452
453
454
 
# File 'lib/color_contrast_calc/color.rb', line 452

def min_contrast?
  rgb == GRAY.rgb
end

#same_color?(other_color) ⇒ Boolean

Check it two colors have the same RGB value.

Parameters:

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

    Another instance of Color, RGB value or hex color code

Returns:

  • (Boolean) —

    true if other_color has the same RGB value



420
421
422
423
424
425
426
427
428
429
 
# File 'lib/color_contrast_calc/color.rb', line 420

def same_color?(other_color)
  case other_color
  when Color
    hex == other_color.hex
  when Array
    hex == Utils.rgb_to_hex(other_color)
  when String
    hex == Utils.normalize_hex(other_color)
  end
end

#same_luminance_as?(other_color) ⇒ Boolean

Check if two colors has the same relative luminance.

Parameters:

  • other_color (Color) —

    Another color

Returns:

  • (Boolean) —

    true if the relative luminance of self and other_color are same.



474
475
476
 
# File 'lib/color_contrast_calc/color.rb', line 474

def same_luminance_as?(other_color)
  relative_luminance == other_color.relative_luminance
end

#sufficient_contrast?(other_color, level = Checker::Level::AA) ⇒ Boolean

Check if the contrast ratio with another color meets a WCAG 2.0 criterion.

Parameters:

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

    Another instance of Color, RGB value or hex color code

  • level (String) (defaults to: Checker::Level::AA) —

    “A”, “AA” or “AAA”

Returns:

  • (Boolean) —

    true if the contrast ratio meets the specified level



408
409
410
411
 
# File 'lib/color_contrast_calc/color.rb', line 408

def sufficient_contrast?(other_color, level = Checker::Level::AA)
  ratio = Checker.level_to_ratio(level)
  contrast_ratio_against(other_color) >= ratio
end

#to_s(base = 16) ⇒ String

Return a string representation of the color.

Parameters:

  • base (Ingeger, nil) (defaults to: 16) —

    16, 10 or nil. when base = 16, a hex color code such as “#ffff00” is returned, and when base = 10, a code in RGB notation such as “rgb(255, 255, 0)”

Returns:

  • (String) —

    String representation of the color



388
389
390
391
392
393
394
395
396
397
 
# File 'lib/color_contrast_calc/color.rb', line 388

def to_s(base = 16)
  case base
  when 16
    hex
  when 10
    @rgb_code ||= format('rgb(%d,%d,%d)', *rgb)
  else
    name
  end
end

#with_brightness(ratio, name = nil) ⇒ Color

Return a new instance of Color with adjusted brightness.

Parameters:

  • ratio (Float) —

    Adjustment ratio in percentage

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

    You can name the color to be created. Without this option, the value of normalized hex color code is assigned instead.

Returns:

  • (Color) —

    New color with adjusted brightness



250
251
252
 
# File 'lib/color_contrast_calc/color.rb', line 250

def with_brightness(ratio, name = nil)
  generate_new_color(Converter::Brightness, ratio, name)
end

#with_contrast(ratio, name = nil) ⇒ Color

Return a new instance of Color with adjusted contrast.

Parameters:

  • ratio (Float) —

    Adjustment ratio in percentage

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

    You can name the color to be created. Without this option, the value of normalized hex color code is assigned instead.

Returns:

  • (Color) —

    New color with adjusted contrast



237
238
239
 
# File 'lib/color_contrast_calc/color.rb', line 237

def with_contrast(ratio, name = nil)
  generate_new_color(Converter::Contrast, ratio, name)
end

#with_grayscale(ratio = 100, name = nil) ⇒ Color

Return a grayscale of the original color.

Parameters:

  • ratio (Float) (defaults to: 100) —

    Conversion ratio in percentage

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

    You can name the color to be created. Without this option, the value of normalized hex color code is assigned instead.

Returns:

  • (Color) —

    New grayscale color



302
303
304
 
# File 'lib/color_contrast_calc/color.rb', line 302

def with_grayscale(ratio = 100, name = nil)
  generate_new_color(Converter::Grayscale, ratio, name)
end

#with_hue_rotate(degree, name = nil) ⇒ Color

Return a hue rotation applied color as an instance of Color.

Parameters:

  • degree (Float) —

    Degrees of rotation (0 to 360)

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

    You can name the color to be created. Without this option, the value of normalized hex color code is assigned instead.

Returns:

  • (Color) —

    New hue rotation applied color



276
277
278
 
# File 'lib/color_contrast_calc/color.rb', line 276

def with_hue_rotate(degree, name = nil)
  generate_new_color(Converter::HueRotate, degree, name)
end

#with_invert(ratio = 100, name = nil) ⇒ Color

Return an inverted color as an instance of Color.

Parameters:

  • ratio (Float) (defaults to: 100) —

    Proportion of the conversion in percentage

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

    You can name the color to be created. Without this option, the value of normalized hex color code is assigned instead.

Returns:

  • (Color) —

    New inverted color



263
264
265
 
# File 'lib/color_contrast_calc/color.rb', line 263

def with_invert(ratio = 100, name = nil)
  generate_new_color(Converter::Invert, ratio, name)
end

#with_saturate(ratio, name = nil) ⇒ Color

Return a saturated color as an instance of Color.

Parameters:

  • ratio (Float) —

    Proprtion of the conversion in percentage

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

    You can name the color to be created. Without this option, the value of normalized hex color code is assigned instead.

Returns:

  • (Color) —

    New saturated color



289
290
291
 
# File 'lib/color_contrast_calc/color.rb', line 289

def with_saturate(ratio, name = nil)
  generate_new_color(Converter::Saturate, ratio, name)
end