class Spectrum::RGB

An RGB colour object.

Constants

AliceBlue
AntiqueWhite
Aqua
Aquamarine
Azure
Beige
Bisque
Black
BlanchedAlmond
Blue
BlueViolet
Brown
BurlyWood
Burlywood
CadetBlue
Carnation
Cayenne
Chartreuse
Chocolate
Coral
CornflowerBlue
Cornsilk
Crimson
Cyan
DarkBlue
DarkCyan
DarkGoldenRod
DarkGoldenrod
DarkGray
DarkGreen
DarkGrey
DarkKhaki
DarkMagenta
DarkOliveGreen
DarkOrange
DarkOrchid
DarkRed
DarkSalmon
DarkSeaGreen
DarkSlateBlue
DarkSlateGray
DarkSlateGrey
DarkTurquoise
DarkViolet
DarkoliveGreen
Darkorange
Darksalmon
DeepPink
DeepSkyBlue
DimGray
DimGrey
DodgerBlue
Feldspar
FireBrick
Firebrick
FloralWhite
ForestGreen
Fuchsia
Gainsboro
GhostWhite
Gold
GoldenRod
Goldenrod
Gray
Gray10
Gray20
Gray30
Gray40
Gray50
Gray60
Gray70
Gray80
Gray90
Green
GreenYellow
Grey
Grey10
Grey20
Grey30
Grey40
Grey50
Grey60
Grey70
Grey80
Grey90
HoneyDew
Honeydew
HotPink
IndianRed
Indigo
Ivory
Khaki
Lavender
LavenderBlush
LawnGreen
LemonChiffon
LightBlue
LightCoral
LightCyan
LightGoldenRodYellow
LightGoldenrodYellow
LightGray
LightGreen
LightGrey
LightPink
LightSalmon
LightSeaGreen
LightSkyBlue
LightSlateBlue
LightSlateGray
LightSlateGrey
LightSteelBlue
LightYellow
Lightsalmon
LightsteelBlue
Lime
LimeGreen
Linen
Magenta
Maroon
MediumAquaMarine
MediumAquamarine
MediumBlue
MediumOrchid
MediumPurple
MediumSeaGreen
MediumSlateBlue
MediumSpringGreen
MediumTurquoise
MediumVioletRed
MidnightBlue
MintCream
MistyRose
Moccasin
OldLace
Olive
OliveDrab
Olivedrab
Orange
OrangeRed
Orchid
PDF_FORMAT_STR

The format of a DeviceRGB colour for PDF. In color-tools 2.0 this will be removed from this package and added back as a modification by the PDF::Writer package.

PaleGoldenRod
PaleGoldenrod
PaleGreen
PaleTurquoise
PaleVioletRed
PapayaWhip
PeachPuff
Peachpuff
Peru
Pink
Plum
PowderBlue
Purple
Red
RosyBrown
RoyalBlue
SaddleBrown
Salmon
SandyBrown
SeaGreen
SeaShell
Seashell
Sienna
Silver
SkyBlue
SlateBlue
SlateGray
SlateGrey
Snow
SpringGreen
SteelBlue
Tan
Teal
Thistle
Tomato
Turquoise
Violet
VioletRed
Wheat
White
WhiteSmoke
Yellow
YellowGreen

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.

Spectrum::RGB.from_fraction(.3, .2, .1)
# File lib/spectrum/rgb.rb, line 31
def from_fraction(r = 0.0, g = 0.0, b = 0.0)
  colour = Spectrum::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;".

Spectrum::RGB.from_html("fed")
Spectrum::RGB.from_html("#fed")
Spectrum::RGB.from_html("#cabbed")
Spectrum::RGB.from_html("cabbed")
# File lib/spectrum/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

  Spectrum::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.

Spectrum::RGB.from_percentage(10, 20 30)
# File lib/spectrum/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.

Spectrum::RGB.new(32, 64, 128)
Spectrum::RGB.new(0x20, 0x40, 0x80)
# File lib/spectrum/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/spectrum/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/spectrum/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/spectrum/rgb.rb, line 68
def ==(other)
  other = other.to_rgb
  other.kind_of?(Spectrum::RGB) and
  ((@r - other.r).abs <= Spectrum::COLOR_TOLERANCE) and
  ((@g - other.g).abs <= Spectrum::COLOR_TOLERANCE) and
  ((@b - other.b).abs <= Spectrum::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.

Spectrum::RGB::DarkBlue.adjust_brightness(10)
Spectrum::RGB::DarkBlue.adjust_brightness(-10)
# File lib/spectrum/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.

Spectrum::RGB::DarkBlue.adjust_hue(10)
Spectrum::RGB::DarkBlue.adjust_hue(-10)
# File lib/spectrum/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.

Spectrum::RGB::DarkBlue.adjust_saturation(10)
Spectrum::RGB::DarkBlue.adjust_saturation(-10)
# File lib/spectrum/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/spectrum/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/spectrum/rgb.rb, line 403
def b=(bb)
  @b = Spectrum.normalize(bb)
end
blue() click to toggle source

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

# File lib/spectrum/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/spectrum/rgb.rb, line 394
def blue=(bb)
  @b = Spectrum.normalize(bb / 255.0)
end
blue_p() click to toggle source

Returns the blue component of the colour as a percentage.

# File lib/spectrum/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/spectrum/rgb.rb, line 398
def blue_p=(bb)
  @b = Spectrum.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/spectrum/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/spectrum/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/spectrum/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/spectrum/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/spectrum/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/spectrum/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/spectrum/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/spectrum/rgb.rb, line 376
def g=(gg)
  @g = Spectrum.normalize(gg)
end
green() click to toggle source

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

# File lib/spectrum/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/spectrum/rgb.rb, line 367
def green=(gg)
  @g = Spectrum.normalize(gg / 255.0)
end
green_p() click to toggle source

Returns the green component of the colour as a percentage.

# File lib/spectrum/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/spectrum/rgb.rb, line 371
def green_p=(gg)
  @g = Spectrum.normalize(gg / 100.0)
end
html() click to toggle source

Present the colour as an HTML/CSS colour string.

# File lib/spectrum/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/spectrum/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/spectrum/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/spectrum/rgb.rb, line 443
def max_rgb_as_grayscale
    Spectrum::GrayScale.from_fraction([@r, @g, @b].max)
end
Also aliased as: max_rgb_as_greyscale
max_rgb_as_greyscale()
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/spectrum/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/spectrum/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/spectrum/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/spectrum/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/spectrum/rgb.rb, line 349
def r=(rr)
  @r = Spectrum.normalize(rr)
end
red() click to toggle source

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

# File lib/spectrum/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/spectrum/rgb.rb, line 340
def red=(rr)
  @r = Spectrum.normalize(rr / 255.0)
end
red_p() click to toggle source

Returns the red component of the colour as a percentage.

# File lib/spectrum/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/spectrum/rgb.rb, line 344
def red_p=(rr)
  @r = Spectrum.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/spectrum/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

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

Convert to grayscale.

# File lib/spectrum/rgb.rb, line 270
def to_grayscale
  Spectrum::GrayScale.from_fraction(to_hsl.l)
end
Also aliased as: to_greyscale
to_greyscale()
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/spectrum/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 Spectrum.near_zero?(delta) # close to 0.0, so it's a grey
    hue = 0
    sat = 0
  else
    if Spectrum.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 # Spectrum.near_zero_or_less?(@r - max)
      hue = (sixth * ((@g - @b) / delta))
      hue += 1.0 if @g < @b
    elsif @g == max # Spectrum.near_zero_or_less(@g - max)
      hue = (sixth * ((@b - @r) / delta)) + (1.0 / 3.0)
    elsif @b == max # Spectrum.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
  Spectrum::HSL.from_fraction(hue, sat, lum)
end
to_rgb(ignored = nil) click to toggle source
# File lib/spectrum/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/spectrum/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)
  Spectrum::YIQ.from_fraction(y, i, q)
end