Class: Color::RGB

### Home Classes Methods

### In Files

- lib/color.rb
- lib/color/rgb-colors.rb
- lib/color/rgb.rb

### Parent

Object

### Namespace

- MODULE Color::RGB::Metallic

### Methods

- ::from_fraction
- ::from_html
- ::from_percentage
- ::new
- #+
- #-
- #==
- #adjust_brightness
- #adjust_hue
- #adjust_saturation
- #b
- #b=
- #blue
- #blue=
- #blue_p
- #blue_p=
- #brightness
- #css_hsl
- #css_hsla
- #css_rgb
- #css_rgba
- #darken_by
- #g
- #g=
- #green
- #green=
- #green_p
- #green_p=
- #html
- #inspect
- #lighten_by
- #max_rgb_as_grayscale
- #max_rgb_as_greyscale
- #mix_with
- #pdf_fill
- #pdf_stroke
- #r
- #r=
- #red
- #red=
- #red_p
- #red_p=
- #to_cmyk
- #to_grayscale
- #to_greyscale
- #to_hsl
- #to_rgb
- #to_yiq

### Files

- History.rdoc
- Manifest.txt

### Class/Module Index

Quicksearch

- Color
- Color::CMYK
- Color::CSS
- Color::GrayScale
- Color::GrayScale
- Color::HSL
- Color::Palette
- Color::Palette::AdobeColor
- Color::Palette::Gimp
- Color::Palette::MonoContrast
- Color::RGB
- Color::RGB::Metallic
- Color::YIQ
- Object
- Object::GreyScale

No matching classes.

# Color::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
NavajoWhite
Navy
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.

    Color::RGB.from_fraction(.3, .2, .1)

    # File lib/color/rgb.rb, line 19
    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 34
    def from_html(html_colour)
      html_colour = html_colour.gsub(%{[#;]}, '')
      case html_colour.size
      when 3
        colours = html_colour.scan(%{[0-9A-Fa-f]}).map { |el| (el * 2).to_i(16) }
      when 6
        colours = html_colour.scan(%<[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 12
    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 68
    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 401
    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 418
    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 56
    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 269
    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 303
    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 286
    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 378
    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 391
    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 369
    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 382
    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 373
    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 386
    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 254
    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 117
    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 124
    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 103
    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 110
    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 231
    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 351
    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 364
    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 342
    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 355
    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 346
    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 359
    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 87
    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 436
    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 224
    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 431
    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
Alias for: max_rgb_as_grayscale
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 237
    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 76
    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 82
    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 324
    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 337
    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 315
    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 328
    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 319
    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 332
    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 154
    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 258
    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 185
    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 170
    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 175
    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

[Validate]

Generated with the Darkfish Rdoc Generator 2.