Class: Color::RGB

Inherits:
Data
  • Object
show all
Includes:
Color
Defined in:
lib/color/rgb.rb,
lib/color.rb,
lib/color/rgb/colors.rb

Overview

The RGB color model is an additive color model where the primary colors (red, green, and blue) of light are added to produce millions of colors. RGB rendering is device-dependent and without color management, the same “red” color will render differently.

This class does not implement color management and is not RGB colorspace aware; that is, unless otherwise noted, it does not assume that the RGB represented is sRGB or Adobe RGB (opRGB).

RGB colors are immutable Data class instances. Array deconstruction is ‘[red, green, blue]` and hash deconstruction is `red:, g:, green:, b:, blue`. See #r, #red, #g, #green, #b, #blue.

Defined Under Namespace

Modules: Metallic

Constant Summary collapse

Black000 =

:nodoc:

new(r: 0x00, g: 0x00, b: 0x00)
WhiteFFF =

:nodoc:

new(r: 0xff, g: 0xff, b: 0xff)

Constants included from Color

EPSILON, TOLERANCE, VERSION

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Color

#==, #components, #css_value, #map, #map_with, normalize, #scale, translate_range, #zip

Constructor Details

#initialize(r:, g:, b:, names: nil) ⇒ RGB

Creates a RGB color object from fractional values (0.0 .. 1.0).

“‘ruby Color::RGB.from_fraction(0.3, 0.2, 0.1) # => RGB [#4d331a] Color::RGB.new(0.3, 0.2, 0.1) # => RGB [#4d331a] Color::RGB[r: 0.3, g: 0.2, b: 0.1] # => RGB [#4d331a] “`



62
63
64
# File 'lib/color/rgb.rb', line 62

def initialize(r:, g:, b:, names: nil)
  super(r: normalize(r), g: normalize(g), b: normalize(b), names: names)
end

Instance Attribute Details

#bObject (readonly)

Returns the value of attribute b

Returns:

  • (Object)

    the current value of b



48
49
50
# File 'lib/color.rb', line 48

def b
  @b
end

#gObject (readonly)

Returns the value of attribute g

Returns:

  • (Object)

    the current value of g



48
49
50
# File 'lib/color.rb', line 48

def g
  @g
end

#namesObject (readonly)

Returns the value of attribute names

Returns:

  • (Object)

    the current value of names



48
49
50
# File 'lib/color.rb', line 48

def names
  @names
end

#rObject (readonly)

Returns the value of attribute r

Returns:

  • (Object)

    the current value of r



48
49
50
# File 'lib/color.rb', line 48

def r
  @r
end

Class Method Details

.__create_named_colors(mod, *colors) ⇒ Object



7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
# File 'lib/color/rgb/colors.rb', line 7

def __create_named_colors(mod, *colors)
  @__by_hex ||= {}
  @__by_name ||= {}

  colors.each do |color|
    color => {rgb:, names:}

    raise ArgumentError, "Names cannot be empty" if names.nil? || names.empty?

    used = names - mod.constants.map(&:to_sym)

    if used.length < names.length
      raise ArgumentError, "#{names.join(", ")} already defined in #{mod}"
    end

    rgb = rgb.with(names: Array(names).flatten.compact.map { _1.to_s.downcase }.sort.uniq)
    names.each { mod.const_set(_1, rgb) }
    rgb.names.each { @__by_name[_1] = @__by_name[_1.to_s] = rgb }
    lower = rgb.name.downcase

    @__by_name[lower] = @__by_name[lower.to_s] = rgb
    @__by_hex[rgb.hex] = rgb
  end
end

.by_css(name_or_hex, &block) ⇒ Object

Return a color as identified by the color name, or by hex.



639
# File 'lib/color/rgb.rb', line 639

def by_css(name_or_hex, &block) = by_name(name_or_hex) { by_hex(name_or_hex, &block) }

.by_hex(hex) ⇒ Object

Find or create a color by an HTML hex code. This differs from the #from_html method in that if the color code matches a named color, the existing color will be returned.

“‘ruby Color::RGB.by_hex(’ff0000’).name # => ‘red’ Color::RGB.by_hex(‘ff0001’).name # => nil “‘

An exception will be raised if the value provided is not found or cannot be interpreted as a valid hex colour.



631
# File 'lib/color/rgb.rb', line 631

def by_hex(hex) = __by_hex.fetch(html_hexify(hex)) { from_html(hex) }

.by_name(name, &block) ⇒ Object

Return a color as identified by the color name.



635
# File 'lib/color/rgb.rb', line 635

def by_name(name, &block) = __by_name.fetch(name.to_s.downcase, &block)

.extract_colors(text, mode = :both) ⇒ Object

Extract named or hex colors from the provided text.



643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
# File 'lib/color/rgb.rb', line 643

def extract_colors(text, mode = :both)
  require "color/rgb/colors"
  text = text.downcase
  regex = case mode
  when :name
    Regexp.union(__by_name.keys)
  when :hex
    Regexp.union(__by_hex.keys)
  when :both
    Regexp.union(__by_hex.keys + __by_name.keys)
  else
    raise ArgumentError, "Unknown mode #{mode}"
  end

  text.scan(regex).map { |match|
    case mode
    when :name
      by_name(match)
    when :hex
      by_hex(match)
    when :both
      by_css(match)
    end
  }
end

.from_html(html_color) ⇒ Object

Creates a RGB color object from an HTML color descriptor (e.g., ‘“fed”` or `“#cabbed;”`.

“‘ruby Color::RGB.from_html(“fed”) Color::RGB.from_html(“#fed”) Color::RGB.from_html(“#cabbed”) Color::RGB.from_html(“cabbed”) “`



605
606
607
608
609
610
611
612
613
614
615
616
617
# File 'lib/color/rgb.rb', line 605

def from_html(html_color)
  h = html_color.scan(/\h/i)
  r, g, b = case h.size
  when 3
    h.map { |v| (v * 2).to_i(16) }
  when 6
    h.each_slice(2).map { |v| v.join.to_i(16) }
  else
    raise ArgumentError, "Not a supported HTML color type."
  end

  from_values(r, g, b)
end

.from_percentage(*args, **kwargs) ⇒ Object

Creates a RGB color object from percentage values (0.0 .. 100.0).

“‘ruby Color::RGB.from_percentage(10, 20, 30) “`



547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
# File 'lib/color/rgb.rb', line 547

def from_percentage(*args, **kwargs)
  r, g, b, names =
    case [args, kwargs]
    in [[r, g, b], {}]
      [r, g, b, nil]
    in [[_, _, _, _], {}]
      args
    in [[], {r:, g:, b:}]
      [r, g, b, nil]
    in [[], {r:, g:, b:, names:}]
      [r, g, b, names]
    else
      new(*args, **kwargs)
    end

  new(r: r / 100.0, g: g / 100.0, b: b / 100.0, names: names)
end

.from_values(*args, **kwargs) ⇒ Object

Creates a RGB color object from the standard three byte range (0 .. 255).

“‘ruby Color::RGB.from_values(32, 64, 128) Color::RGB.from_values(0x20, 0x40, 0x80) “`



571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
# File 'lib/color/rgb.rb', line 571

def from_values(*args, **kwargs)
  r, g, b, names =
    case [args, kwargs]
    in [[r, g, b], {}]
      [r, g, b, nil]
    in [[_, _, _, _], {}]
      args
    in [[], {r:, g:, b:}]
      [r, g, b, nil]
    in [[], {r:, g:, b:, names:}]
      [r, g, b, names]
    else
      new(*args, **kwargs)
    end

  new(r: r / 255.0, g: g / 255.0, b: b / 255.0, names: names)
end

Instance Method Details

#adjust_brightness(percent) ⇒ Object

Returns a new RGB color with the brightness adjusted by the specified percentage via Color::HSL. Negative percentages will darken the color; positive percentages will brighten the color.

“‘ruby dark_blue = Color::RGB::DarkBlue # => RGB [#00008b] dark_blue.adjust_brightness(10) # => RGB [#000099] dark_blue.adjust_brightness(-10) # => RGB [#00007d] “`



312
313
314
315
# File 'lib/color/rgb.rb', line 312

def adjust_brightness(percent)
  hsl = to_hsl
  hsl.with(l: hsl.l * percent_adjustment(percent)).to_rgb
end

#adjust_hue(percent) ⇒ Object

Returns a new RGB color with the hue adjusted by the specified percentage via Color::HSL. Negative percentages will reduce the hue; positive percentages will increase the hue.

“‘ruby dark_blue = Color::RGB::DarkBlue # => RGB [#00008b] dark_blue.adjust_hue(10) # => RGB [#38008b] dark_blue.adjust_hue(-10) # => RGB [#00388b] “`



342
343
344
345
# File 'lib/color/rgb.rb', line 342

def adjust_hue(percent)
  hsl = to_hsl
  hsl.with(h: hsl.h * percent_adjustment(percent)).to_rgb
end

#adjust_saturation(percent) ⇒ Object

Returns a new RGB color with the saturation adjusted by the specified percentage via Color::HSL. Negative percentages will reduce the saturation; positive percentages will increase the saturation.

“‘ruby dark_blue = Color::RGB::DarkBlue # => RGB [#00008b] dark_blue.adjust_saturation(10) # => RGB [#00008b] dark_blue.adjust_saturation(-10) # => RGB [#070784] “`



327
328
329
330
# File 'lib/color/rgb.rb', line 327

def adjust_saturation(percent)
  hsl = to_hsl
  hsl.with(s: hsl.s * percent_adjustment(percent)).to_rgb
end

#blueObject

:nodoc:



422
# File 'lib/color/rgb.rb', line 422

def blue = normalize(b * 255.0, 0.0..255.0) # :nodoc:

#blue_pObject

:nodoc:



425
# File 'lib/color/rgb.rb', line 425

def blue_p = normalize(b * 100.0, 0.0..100.0) # :nodoc:

#brightnessObject

Returns the brightness value for a color, a number between 0..1.

Based on the Y value of Color::YIQ encoding, representing luminosity, or perceived brightness.



300
# File 'lib/color/rgb.rb', line 300

def brightness = to_yiq.y

#closest_match(color_list, *args, **kwargs) ⇒ Object

Determines the closest match to this color from a list of provided colors or ‘nil` if `color_list` is empty or no color is found within the `threshold_distance`.

The default search uses the CIE ΔE* 1994 algorithm (CIE94) to find near matches based on the perceived visual differences between the colors. The default value for ‘algorithm` is `:delta_e94`.

‘threshold_distance` is used to determine the minimum color distance permitted. Uses the CIE ΔE* 1994 algorithm (CIE94) to find near matches based on perceived visual color. The default value (1000.0) is an arbitrarily large number. The values `:jnd` and `:just_noticeable` may be passed as the `threshold_distance` to use the value `2.3`.

All ΔE* formulae were designed to use 1.0 as a “just noticeable difference” (JND), but CIE ΔE*ab 1976 defined JND as 2.3.

:call-seq:

closest_match(color_list, algorithm: :delta_e94, threshold_distance: 1000.0)


366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
# File 'lib/color/rgb.rb', line 366

def closest_match(color_list, *args, **kwargs)
  color_list = [color_list].flatten(1)
  return nil if color_list.empty?

  algorithm = kwargs[:algorithm] || args.first || :delta_e94
  threshold_distance = kwargs[:threshold_distance] || args[1] || 1000.0

  threshold_distance =
    case threshold_distance
    when :jnd, :just_noticeable
      2.3
    else
      threshold_distance.to_f
    end

  closest_distance = threshold_distance
  best_match = nil

  color_list.each do |c|
    distance = contrast(c, algorithm)
    if distance < closest_distance
      closest_distance = distance
      best_match = c
    end
  end

  best_match
end

#coerce(other) ⇒ Object

Coerces the other Color object into RGB.



82
# File 'lib/color/rgb.rb', line 82

def coerce(other) = other.to_rgb

#contrast(other, *args, **kwargs) ⇒ Object

Outputs how much contrast this color has with another RGB color.

The ‘delta_e94` algorithm uses ΔE*94 for contrast calculations and the `delta_e2000` algorithm uses ΔE*2000.

The ‘naive` algorithm treats the foreground and background colors as the same. Any result over about 0.22 should have a high likelihood of being legible, but the larger the difference, the more contrast. Otherwise, to be safe go with something > 0.3.

:call-seq:

contrast(other, algorithm: :naive)
contrast(other, algorithm: :delta_e94)
contrast(other, algorithm: :delta_e2000)


471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
# File 'lib/color/rgb.rb', line 471

def contrast(other, *args, **kwargs)
  other = coerce(other)

  algorithm = kwargs[:algorithm] || args.first || :naive

  case algorithm
  when :delta_e94
    delta_e94(other)
  when :delta_e2000
    delta_e2000(other)
  when :naive
    # The following numbers have been set with some care.
    ((diff_brightness(other) * 0.65) +
     (diff_hue(other) * 0.20) +
     (diff_luminosity(other) * 0.15))
  else
    raise ARgumentError, "Unknown algorithm #{algorithm.inspect}"
  end
end

#css(alpha: nil) ⇒ Object

Present the color as an CSS ‘rgb` function with optional `alpha`.

“‘ruby rgb = Color::RGB.from_percentage(0, 50, 100) rgb.css # => rgb(0 50.00% 100.00%) rgb.css(alpha: 0.5) # => rgb(0 50.00% 100.00% / 0.50) “`



257
258
259
260
261
262
# File 'lib/color/rgb.rb', line 257

def css(alpha: nil)
  params = [css_value(red_p, :percent), css_value(green_p, :percent), css_value(blue_p, :percent)].join(" ")
  params = "#{params} / #{css_value(alpha)}" if alpha

  "rgb(#{params})"
end

#darken_by(percent) ⇒ Object

Mix the RGB hue with black so that the RGB hue is the specified percentage of the resulting color.

Strictly speaking, this isn’t a ‘darken_by` operation, but it mostly works.



280
# File 'lib/color/rgb.rb', line 280

def darken_by(percent) = mix_with(Color::RGB::Black000, percent)

#deconstruct_keys(_keys) ⇒ Object

:nodoc:



451
# File 'lib/color/rgb.rb', line 451

def deconstruct_keys(_keys) = {r:, g:, b:, red:, green:, blue:} # :nodoc:

#delta_e2000(other) ⇒ Object

Computes the ΔE* 2000 difference via Color::CIELAB. See Color::CIELAB#delta_e2000.



266
# File 'lib/color/rgb.rb', line 266

def delta_e2000(other) = to_lab.delta_e2000(coerce(other).to_lab)

#delta_e94Object

The Delta E (CIE94) algorithm en.wikipedia.org/wiki/Color_difference#CIE94

There is a newer version, CIEDE2000, that uses slightly more complicated math, but addresses “the perceptual uniformity issue” left lingering by the CIE94 algorithm.

Since our source is treated as sRGB, we use the “graphic arts” presets for k_L, k_1, and k_2

The calculations go through LCH(ab). (?)

See also www.brucelindbloom.com/index.html?Eqn_DeltaE_CIE94.html



407
# File 'lib/color/rgb.rb', line 407

def delta_e94(...) = to_lab.delta_e94(...)

#greenObject

:nodoc:



416
# File 'lib/color/rgb.rb', line 416

def green = normalize(g * 255.0, 0.0..255.0) # :nodoc:

#green_pObject

:nodoc:



419
# File 'lib/color/rgb.rb', line 419

def green_p = normalize(g * 100.0, 0.0..100.0) # :nodoc:

#hexObject

Present the color as an HTML/CSS RGB hex triplet (ccddee).



239
240
241
# File 'lib/color/rgb.rb', line 239

def hex
  "%02x%02x%02x" % [red, green, blue].map(&:round)
end

#htmlObject

Present the color as an HTML/CSS color string (#ccddee).



245
246
247
# File 'lib/color/rgb.rb', line 245

def html
  "##{hex}"
end

#inspectObject

:nodoc:



433
# File 'lib/color/rgb.rb', line 433

def inspect = "RGB [#{html}]" # :nodoc:

#lighten_by(percent) ⇒ Object

Mix the RGB hue with white so that the RGB hue is the specified percentage of the resulting color.

Strictly speaking, this isn’t a ‘lighten_by` operation, but it mostly works.



273
# File 'lib/color/rgb.rb', line 273

def lighten_by(percent) = mix_with(Color::RGB::WhiteFFF, percent)

#max_rgb_as_grayscaleObject

Return a Grayscale color object created from the largest of the ‘r`, `g`, and `b` values.



430
# File 'lib/color/rgb.rb', line 430

def max_rgb_as_grayscale = Color::Grayscale.from_fraction([r, g, b].max)

#mix_with(mask, opacity) ⇒ Object

Mix the mask color with the current color at the stated opacity percentage (0..100).



284
285
286
287
288
289
290
291
292
293
# File 'lib/color/rgb.rb', line 284

def mix_with(mask, opacity)
  opacity = normalize(opacity / 100.0)
  mask = coerce(mask)

  with(
    r: (r * opacity) + (mask.r * (1 - opacity)),
    g: (g * opacity) + (mask.g * (1 - opacity)),
    b: (b * opacity) + (mask.b * (1 - opacity))
  )
end

#nameObject

:nodoc:



78
# File 'lib/color/rgb.rb', line 78

def name = names&.first # :nodoc:

#pretty_print(q) ⇒ Object

:nodoc:



436
437
438
439
440
441
442
# File 'lib/color/rgb.rb', line 436

def pretty_print(q) # :nodoc:
  q.text "RGB"
  q.breakable
  q.group 2, "[", "]" do
    q.text html
  end
end

#redObject

:nodoc:



410
# File 'lib/color/rgb.rb', line 410

def red = normalize(r * 255.0, 0.0..255.0) # :nodoc:

#red_pObject

:nodoc:



413
# File 'lib/color/rgb.rb', line 413

def red_p = normalize(r * 100.0, 0.0..100.0) # :nodoc:

#to_aObject Also known as: deconstruct

:nodoc:



445
# File 'lib/color/rgb.rb', line 445

def to_a = [red, green, blue] # :nodoc:

#to_cmykObject

Converts the RGB color to Color::CMYK.

Most color experts strongly suggest that this is not a good idea (some suggesting that it’s a very bad idea). CMYK represents additive percentages of inks on white paper, whereas RGB represents mixed color intensities on an unlit (black) screen.

  1. Convert the R, G, and B components to C, M, and Y components.

    c = 1.0 - r
    m = 1.0 - g
    y = 1.0 - b
    
  2. Compute the minimum amount of black (K) required to smooth the color in inks.

    k = min(c, m, y)
    
  3. Perform undercolor removal on the C, M, and Y components of the colors because less of each color is needed for each bit of black. Also, regenerate the black (K) based on the undercolor removal so that the color is more accurately represented in ink.

    c = min(1.0, max(0.0, c - UCR(k)))
    m = min(1.0, max(0.0, m - UCR(k)))
    y = min(1.0, max(0.0, y - UCR(k)))
    k = min(1.0, max(0.0, BG(k)))
    

The undercolor removal function and the black generation functions return a value based on the brightness of the RGB color.



112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
# File 'lib/color/rgb.rb', line 112

def to_cmyk(...)
  c = 1.0 - r.to_f
  m = 1.0 - g.to_f
  y = 1.0 - b.to_f

  k = [c, m, y].min
  k -= (k * brightness)

  c = normalize(c - k)
  m = normalize(m - k)
  y = normalize(y - k)
  k = normalize(k)

  Color::CMYK.from_fraction(c, m, y, k)
end

#to_grayscaleObject

Convert RGB to Color::Grayscale via Color::HSL (for the luminance value).



133
# File 'lib/color/rgb.rb', line 133

def to_grayscale(...) = Color::Grayscale.from_fraction(to_hsl.l)

#to_hslObject

Converts RGB to Color::HSL.

The conversion here is based on formulas from www.easyrgb.com/math.php and elsewhere.



149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
# File 'lib/color/rgb.rb', line 149

def to_hsl(...)
  min, max = [r, g, b].minmax
  delta = (max - min).to_f

  l = (max + min) / 2.0

  if near_zero?(delta) # close to 0.0, so it's a gray
    h = 0
    s = 0
  else
    s = if near_zero_or_less?(l - 0.5)
      delta / (max + min).to_f
    else
      delta / (2 - max - min).to_f
    end

    # This is based on the conversion algorithm from
    # http://en.wikipedia.org/wiki/HSV_color_space#Conversion_from_RGB_to_HSL_or_HSV
    # Contributed by Adam Johnson
    sixth = 1 / 6.0
    if r == max # near_zero_or_less?(r - max)
      h = (sixth * ((g - b) / delta))
      h += 1.0 if g < b
    elsif g == max # near_zero_or_less(g - max)
      h = (sixth * ((b - r) / delta)) + (1.0 / 3.0)
    elsif b == max # near_zero_or_less?(b - max)
      h = (sixth * ((r - g) / delta)) + (2.0 / 3.0)
    end

    h += 1 if h < 0
    h -= 1 if h > 1
  end

  Color::HSL.from_fraction(h, s, l)
end

#to_internalObject

:nodoc:



454
# File 'lib/color/rgb.rb', line 454

def to_internal = [r, g, b] # :nodoc:

#to_labObject

Converts RGB to Color::CIELAB via Color::XYZ.

Based on the [XYZ to CIELAB] formula presented by Bruce Lindbloom.

[xyztolab]: www.brucelindbloom.com/index.html?Eqn_XYZ_to_Lab.html

The conversion is performed assuming the RGB value is in the sRGB color space. No other RGB color spaces are currently supported. By default, uses the D65 reference white for the conversion.

:call-seq:

to_lab(color_space: :sRGB, white: Color::XYZ::D65)


235
# File 'lib/color/rgb.rb', line 235

def to_lab(...) = to_xyz(...).to_lab(...)

#to_rgbObject



129
# File 'lib/color/rgb.rb', line 129

def to_rgb(...) = self

#to_xyz(*args, **kwargs) ⇒ Object

Converts RGB to Color::XYZ using the D65 reference white. This is based on conversion formulas presented by Bruce Lindbloom, in particular [RGB to XYZ].

[rgbxyz]: www.brucelindbloom.com/index.html?Eqn_RGB_to_XYZ.html

The conversion is performed assuming the RGB value is in the sRGB color space. No other RGB color spaces are currently supported.

:call-seq:

to_xyz(color_space: :srgb)


196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
# File 'lib/color/rgb.rb', line 196

def to_xyz(*args, **kwargs)
  color_space = kwargs[:color_space] || args.first || :sRGB

  case color_space.to_s.downcase
  when "srgb"
    # Inverse sRGB companding. Linearizes RGB channels with respect to energy.
    rr, gg, bb = [r, g, b].map {
      if _1 > 0.04045
        (((_1 + 0.055) / 1.055)**2.4)
      else
        (_1 / 12.92)
      end * 100.0
    }

    # Convert using the RGB/XYZ matrix at:
    # http://www.brucelindbloom.com/index.html?Eqn_RGB_XYZ_Matrix.html#WSMatrices
    Color::XYZ.from_values(
      rr * 0.4124564 + gg * 0.3575761 + bb * 0.1804375,
      rr * 0.2126729 + gg * 0.7151522 + bb * 0.0721750,
      rr * 0.0193339 + gg * 0.1191920 + bb * 0.9503041
    )
  else
    raise ArgumentError, "Unsupported color space #{color_space}."
  end
end

#to_yiqObject

Converts RGB to Color::YIQ.



137
138
139
140
141
142
# File 'lib/color/rgb.rb', line 137

def to_yiq(...)
  y = (r * 0.299) + (g * 0.587) + (b * 0.114)
  i = (r * 0.596) + (g * -0.275) + (b * -0.321)
  q = (r * 0.212) + (g * -0.523) + (b * 0.311)
  Color::YIQ.from_fraction(y, i, q)
end