class Color::RGB

An RGB colour object.

Public Class Methods

from_fraction(r = 0.0, g = 0.0, b = 0.0) click to toggle source

Creates an RGB colour object from fractional values 0..1.

Color::RGB.from_fraction(.3, .2, .1)
# File lib/color/rgb.rb, line 31
def from_fraction(r = 0.0, g = 0.0, b = 0.0)
  colour = Color::RGB.new
  colour.r = r
  colour.g = g
  colour.b = b
  colour
end
from_html(html_colour) click to toggle source

Creates an RGB colour object from an HTML colour descriptor (e.g., "fed" or "#cabbed;".

Color::RGB.from_html("fed")
Color::RGB.from_html("#fed")
Color::RGB.from_html("#cabbed")
Color::RGB.from_html("cabbed")
# File lib/color/rgb.rb, line 46
def from_html(html_colour)
  html_colour = html_colour.gsub(%r{[#;]}, '')
  case html_colour.size 
  when 3
    colours = html_colour.scan(%r{[0-9A-Fa-f]}).map { |el| (el * 2).to_i(16) }
  when 6
    colours = html_colour.scan(%r<[0-9A-Fa-f]{2}>).map { |el| el.to_i(16) }
  else
    raise ArgumentError
  end

  Color::RGB.new(*colours)
end
from_percentage(r = 0, g = 0, b = 0) click to toggle source

Creates an RGB colour object from percentages 0..100.

Color::RGB.from_percentage(10, 20 30)
# File lib/color/rgb.rb, line 24
def from_percentage(r = 0, g = 0, b = 0)
  from_fraction(r / 100.0, g / 100.0, b / 100.0)
end
new(r = 0, g = 0, b = 0) click to toggle source

Creates an RGB colour object from the standard range 0..255.

Color::RGB.new(32, 64, 128)
Color::RGB.new(0x20, 0x40, 0x80)
# File lib/color/rgb.rb, line 80
def initialize(r = 0, g = 0, b = 0)
  @r = r / 255.0
  @g = g / 255.0
  @b = b / 255.0
end

Public Instance Methods

+(other) click to toggle source

Adds another colour to the current colour. The other colour will be converted to RGB before addition. This conversion depends upon a to_rgb method on the other colour.

The addition is done using the RGB Accessor methods to ensure a valid colour in the result.

# File lib/color/rgb.rb, line 413
def +(other)
  other = other.to_rgb
  rgb = self.dup

  rgb.r += other.r
  rgb.g += other.g
  rgb.b += other.b

  rgb
end
-(other) click to toggle source

Subtracts another colour to the current colour. The other colour will be converted to RGB before subtraction. This conversion depends upon a to_rgb method on the other colour.

The subtraction is done using the RGB Accessor methods to ensure a valid colour in the result.

# File lib/color/rgb.rb, line 430
def -(other) 
  other = other.to_rgb 
  rgb = self.dup

  rgb.r -= other.r
  rgb.g -= other.g
  rgb.b -= other.b

  rgb
end
==(other) click to toggle source

Compares the other colour to this one. The other colour will be converted to RGB before comparison, so the comparison between a RGB colour and a non-RGB colour will be approximate and based on the other colour's default to_rgb conversion. If there is no to_rgb conversion, this will raise an exception. This will report that two RGB colours are equivalent if all component values are within COLOR_TOLERANCE of each other.

# File lib/color/rgb.rb, line 68
def ==(other)
  other = other.to_rgb
  other.kind_of?(Color::RGB) and
  ((@r - other.r).abs <= Color::COLOR_TOLERANCE) and
  ((@g - other.g).abs <= Color::COLOR_TOLERANCE) and
  ((@b - other.b).abs <= Color::COLOR_TOLERANCE)
end
adjust_brightness(percent) click to toggle source

Returns a new colour with the brightness adjusted by the specified percentage. Negative percentages will darken the colour; positive percentages will brighten the colour.

Color::RGB::DarkBlue.adjust_brightness(10)
Color::RGB::DarkBlue.adjust_brightness(-10)
# File lib/color/rgb.rb, line 281
def adjust_brightness(percent)
  percent /= 100.0
  percent += 1.0
  percent  = [ percent, 2.0 ].min
  percent  = [ 0.0, percent ].max

  hsl      = to_hsl
  hsl.l   *= percent
  hsl.to_rgb
end
adjust_hue(percent) click to toggle source

Returns a new colour with the hue adjusted by the specified percentage. Negative percentages will reduce the hue; positive percentages will increase the hue.

Color::RGB::DarkBlue.adjust_hue(10)
Color::RGB::DarkBlue.adjust_hue(-10)
# File lib/color/rgb.rb, line 315
def adjust_hue(percent)
  percent  /= 100.0
  percent  += 1.0
  percent  = [ percent, 2.0 ].min
  percent  = [ 0.0, percent ].max

  hsl      = to_hsl
  hsl.h   *= percent
  hsl.to_rgb
end
adjust_saturation(percent) click to toggle source

Returns a new colour with the saturation adjusted by the specified percentage. Negative percentages will reduce the saturation; positive percentages will increase the saturation.

Color::RGB::DarkBlue.adjust_saturation(10)
Color::RGB::DarkBlue.adjust_saturation(-10)
# File lib/color/rgb.rb, line 298
def adjust_saturation(percent)
  percent  /= 100.0
  percent  += 1.0
  percent  = [ percent, 2.0 ].min
  percent  = [ 0.0, percent ].max

  hsl      = to_hsl
  hsl.s   *= percent
  hsl.to_rgb
end
b() click to toggle source

Returns the blue component of the colour as a fraction in the range 0.0 .. 1.0.

# File lib/color/rgb.rb, line 390
def b
  @b
end
b=(bb) click to toggle source

Sets the blue component of the colour as a fraction in the range 0.0 .. 1.0.

# File lib/color/rgb.rb, line 403
def b=(bb)
  @b = Color.normalize(bb)
end
blue() click to toggle source

Returns the blue component of the colour in the normal 0 .. 255 range.

# File lib/color/rgb.rb, line 381
def blue
  @b * 255.0
end
blue=(bb) click to toggle source

Sets the blue component of the colour in the normal 0 .. 255 range.

# File lib/color/rgb.rb, line 394
def blue=(bb)
  @b = Color.normalize(bb / 255.0)
end
blue_p() click to toggle source

Returns the blue component of the colour as a percentage.

# File lib/color/rgb.rb, line 385
def blue_p
  @b * 100.0
end
blue_p=(bb) click to toggle source

Sets the blue component of the colour as a percentage.

# File lib/color/rgb.rb, line 398
def blue_p=(bb)
  @b = Color.normalize(bb / 100.0)
end
brightness() click to toggle source

Returns the brightness value for a colour, a number between 0..1. Based on the Y value of YIQ encoding, representing luminosity, or perceived brightness.

This may be modified in a future version of color-tools to use the luminosity value of HSL.

# File lib/color/rgb.rb, line 266
def brightness
  to_yiq.y
end
css_hsl() click to toggle source

Present the colour as an HSL HTML/CSS colour string (e.g., "hsl(180, 25%, 35%)"). Note that this will perform a to_hsl operation using the default conversion formula.

# File lib/color/rgb.rb, line 129
def css_hsl
  to_hsl.css_hsl
end
css_hsla() click to toggle source

Present the colour as an HSLA (with alpha) HTML/CSS colour string (e.g., "hsla(180, 25%, 35%, 1)"). Note that this will perform a to_hsl operation using the default conversion formula.

# File lib/color/rgb.rb, line 136
def css_hsla
  to_hsl.css_hsla
end
css_rgb() click to toggle source

Present the colour as an RGB HTML/CSS colour string (e.g., "rgb(0%, 50%, 100%)"). Note that this will perform a to_rgb operation using the default conversion formula.

# File lib/color/rgb.rb, line 115
def css_rgb
  "rgb(%3.2f%%, %3.2f%%, %3.2f%%)" % [ red_p, green_p, blue_p ]
end
css_rgba() click to toggle source

Present the colour as an RGBA (with alpha) HTML/CSS colour string (e.g., "rgb(0%, 50%, 100%, 1)"). Note that this will perform a to_rgb operation using the default conversion formula.

# File lib/color/rgb.rb, line 122
def css_rgba
  "rgba(%3.2f%%, %3.2f%%, %3.2f%%, %3.2f)" % [ red_p, green_p, blue_p, 1 ]
end
darken_by(percent) click to toggle source

Mix the RGB hue with Black so that the RGB hue is the specified percentage of the resulting colour. Strictly speaking, this isn't a #darken_by operation.

# File lib/color/rgb.rb, line 243
def darken_by(percent)
  mix_with(Black, percent)
end
g() click to toggle source

Returns the green component of the colour as a fraction in the range 0.0 .. 1.0.

# File lib/color/rgb.rb, line 363
def g
  @g
end
g=(gg) click to toggle source

Sets the green component of the colour as a fraction in the range 0.0 .. 1.0.

# File lib/color/rgb.rb, line 376
def g=(gg)
  @g = Color.normalize(gg)
end
green() click to toggle source

Returns the green component of the colour in the normal 0 .. 255 range.

# File lib/color/rgb.rb, line 354
def green
  @g * 255.0
end
green=(gg) click to toggle source

Sets the green component of the colour in the normal 0 .. 255 range.

# File lib/color/rgb.rb, line 367
def green=(gg)
  @g = Color.normalize(gg / 255.0)
end
green_p() click to toggle source

Returns the green component of the colour as a percentage.

# File lib/color/rgb.rb, line 358
def green_p
  @g * 100.0
end
green_p=(gg) click to toggle source

Sets the green component of the colour as a percentage.

# File lib/color/rgb.rb, line 371
def green_p=(gg)
  @g = Color.normalize(gg / 100.0)
end
html() click to toggle source

Present the colour as an HTML/CSS colour string.

# File lib/color/rgb.rb, line 99
def html
  r = (@r * 255).round
  r = 255 if r > 255

  g = (@g * 255).round
  g = 255 if g > 255

  b = (@b * 255).round
  b = 255 if b > 255

  "#%02x%02x%02x" % [ r, g, b ]
end
inspect() click to toggle source
# File lib/color/rgb.rb, line 448
def inspect
  "RGB [#{html}]"
end
lighten_by(percent) click to toggle source

Mix the RGB hue with White so that the RGB hue is the specified percentage of the resulting colour. Strictly speaking, this isn't a #darken_by operation.

# File lib/color/rgb.rb, line 236
def lighten_by(percent)
  mix_with(White, percent)
end
max_rgb_as_grayscale() click to toggle source

Retrieve the maxmum RGB value from the current colour as a GrayScale colour

# File lib/color/rgb.rb, line 443
def max_rgb_as_grayscale
    Color::GrayScale.from_fraction([@r, @g, @b].max)
end
Also aliased as: max_rgb_as_greyscale
max_rgb_as_greyscale() click to toggle source
mix_with(mask, opacity) click to toggle source

Mix the mask colour (which must be an RGB object) with the current colour at the stated opacity percentage (0..100).

# File lib/color/rgb.rb, line 249
def mix_with(mask, opacity)
  opacity /= 100.0
  rgb = self.dup
  
  rgb.r = (@r * opacity) + (mask.r * (1 - opacity))
  rgb.g = (@g * opacity) + (mask.g * (1 - opacity))
  rgb.b = (@b * opacity) + (mask.b * (1 - opacity))

  rgb
end
pdf_fill() click to toggle source

Present the colour as a DeviceRGB fill colour string for PDF. This will be removed from the default package in color-tools 2.0.

# File lib/color/rgb.rb, line 88
def pdf_fill
  PDF_FORMAT_STR % [ @r, @g, @b, "rg" ]
end
pdf_stroke() click to toggle source

Present the colour as a DeviceRGB stroke colour string for PDF. This will be removed from the default package in color-tools 2.0.

# File lib/color/rgb.rb, line 94
def pdf_stroke
  PDF_FORMAT_STR % [ @r, @g, @b, "RG" ]
end
r() click to toggle source

Returns the red component of the colour as a fraction in the range 0.0 .. 1.0.

# File lib/color/rgb.rb, line 336
def r
  @r
end
r=(rr) click to toggle source

Sets the red component of the colour as a fraction in the range 0.0 .. 1.0.

# File lib/color/rgb.rb, line 349
def r=(rr)
  @r = Color.normalize(rr)
end
red() click to toggle source

Returns the red component of the colour in the normal 0 .. 255 range.

# File lib/color/rgb.rb, line 327
def red
  @r * 255.0
end
red=(rr) click to toggle source

Sets the red component of the colour in the normal 0 .. 255 range.

# File lib/color/rgb.rb, line 340
def red=(rr)
  @r = Color.normalize(rr / 255.0)
end
red_p() click to toggle source

Returns the red component of the colour as a percentage.

# File lib/color/rgb.rb, line 331
def red_p
  @r * 100.0
end
red_p=(rr) click to toggle source

Sets the red component of the colour as a percentage.

# File lib/color/rgb.rb, line 344
def red_p=(rr)
  @r = Color.normalize(rr / 100.0)
end
to_cmyk() click to toggle source

Converts the RGB colour to CMYK. Most colour experts strongly suggest that this is not a good idea (some even suggesting that it's a very bad idea). CMYK represents additive percentages of inks on white paper, whereas RGB represents mixed colour intensities on a black screen.

However, the colour conversion can be done. The basic method is multi-step:

  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 colour in inks.

    k = min(c, m, y)
  3. Perform undercolour removal on the C, M, and Y components of the colours because less of each colour is needed for each bit of black. Also, regenerate the black (K) based on the undercolour removal so that the colour 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 undercolour removal function and the black generation functions return a value based on the brightness of the RGB colour.

# File lib/color/rgb.rb, line 166
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 - (k * brightness)

  c = [1.0, [0.0, c - k].max].min
  m = [1.0, [0.0, m - k].max].min
  y = [1.0, [0.0, y - k].max].min
  k = [1.0, [0.0, k].max].min

  Color::CMYK.from_fraction(c, m, y, k)
end
to_grayscale() click to toggle source

Convert to grayscale.

# File lib/color/rgb.rb, line 270
def to_grayscale
  Color::GrayScale.from_fraction(to_hsl.l)
end
Also aliased as: to_greyscale
to_greyscale() click to toggle source
Alias for: to_grayscale
to_hsl() click to toggle source

Returns the HSL colour encoding of the RGB value. The conversions here are based on forumlas from www.easyrgb.com/math.php and elsewhere.

# File lib/color/rgb.rb, line 197
def to_hsl
  min   = [ @r, @g, @b ].min
  max   = [ @r, @g, @b ].max
  delta = (max - min).to_f

  lum   = (max + min) / 2.0

  if Color.near_zero?(delta) # close to 0.0, so it's a grey
    hue = 0
    sat = 0
  else
    if Color.near_zero_or_less?(lum - 0.5)
      sat = delta / (max + min).to_f
    else
      sat = 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 # Color.near_zero_or_less?(@r - max)
      hue = (sixth * ((@g - @b) / delta))
      hue += 1.0 if @g < @b
    elsif @g == max # Color.near_zero_or_less(@g - max)
      hue = (sixth * ((@b - @r) / delta)) + (1.0 / 3.0)
    elsif @b == max # Color.near_zero_or_less?(@b - max)
      hue = (sixth * ((@r - @g) / delta)) + (2.0 / 3.0)
    end

    hue += 1 if hue < 0
    hue -= 1 if hue > 1
  end
  Color::HSL.from_fraction(hue, sat, lum)
end
to_rgb(ignored = nil) click to toggle source
# File lib/color/rgb.rb, line 182
def to_rgb(ignored = nil)
  self
end
to_yiq() click to toggle source

Returns the YIQ (NTSC) colour encoding of the RGB value.

# File lib/color/rgb.rb, line 187
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