color 1.4.1 → 1.8

data/lib/color/css.rb

@@ -1,28 +1,7 @@
-#--
-# Color
-# Colour management with Ruby
-# http://rubyforge.org/projects/color
-#   Version 1.4.1
-#
-# Licensed under a MIT-style licence. See Licence.txt in the main
-# distribution for full licensing information.
-#
-# Copyright (c) 2005 - 2010 Austin Ziegler and Matt Lyon
-#++
-
-require 'color'
-
 # This namespace contains some CSS colour names.
 module Color::CSS
   # Returns the RGB colour for name or +nil+ if the name is not valid.
   def self.[](name)
-    @colors[name.to_s.downcase.to_sym]
-  end
-
-  @colors = {}
-  Color::RGB.constants.each do |const|
-    next if const == "PDF_FORMAT_STR"
-    next if const == "Metallic"
-    @colors[const.downcase.to_sym] ||= Color::RGB.const_get(const)
+    Color::RGB.by_name(name) { nil }
   end
 end

data/lib/color/grayscale.rb

@@ -1,57 +1,40 @@
-#--
-# Color
-# Colour management with Ruby
-# http://rubyforge.org/projects/color
-#   Version 1.4.1
-#
-# Licensed under a MIT-style licence. See Licence.txt in the main
-# distribution for full licensing information.
-#
-# Copyright (c) 2005 - 2010 Austin Ziegler and Matt Lyon
-#++
-
 # A colour object representing shades of grey. Used primarily in PDF
 # document creation.
 class Color::GrayScale
+  include Color
+
   # The format of a DeviceGrey 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.
   PDF_FORMAT_STR  = "%.3f %s"
 
-  # Creates a greyscale colour object from fractional values 0..1.
-  #
-  #   Color::GreyScale.from_fraction(0.5)
-  def self.from_fraction(g = 0)
-    color = Color::GrayScale.new
-    color.g = g
-    color
-  end
+  class << self
+    # Creates a greyscale colour object from fractional values 0..1.
+    #
+    #   Color::GreyScale.from_fraction(0.5)
+    def from_fraction(g = 0, &block)
+      new(g, 1.0, &block)
+    end
 
-  # Creates a greyscale colour object from percentages 0..100.
-  #
-  #   Color::GrayScale.from_percent(50)
-  def self.from_percent(g = 0)
-    Color::GrayScale.new(g)
+    # Creates a greyscale colour object from percentages 0..100.
+    #
+    #   Color::GrayScale.from_percent(50)
+    def from_percent(g = 0, &block)
+      new(g, &block)
+    end
   end
 
   # Creates a greyscale colour object from percentages 0..100.
   #
   #   Color::GrayScale.new(50)
-  def initialize(g = 0)
-    @g = g / 100.0
+  def initialize(g = 0, radix = 100.0, &block) # :yields self:
+    @g = Color.normalize(g / radix)
+    block.call if block
   end
 
-  # Compares the other colour to this one. The other colour will be
-  # converted to GreyScale before comparison, so the comparison between a
-  # GreyScale colour and a non-GreyScale colour will be approximate and
-  # based on the other colour's #to_greyscale conversion. If there is no
-  # #to_greyscale conversion, this will raise an exception. This will report
-  # that two GreyScale values are equivalent if they are within
-  # COLOR_TOLERANCE of each other.
-  def ==(other)
-    other = other.to_grayscale
-    other.kind_of?(Color::GrayScale) and
-    ((@g - other.g).abs <= Color::COLOR_TOLERANCE)
+  # Coerces the other Color object to grayscale.
+  def coerce(other)
+    other.to_grayscale
   end
 
   # Present the colour as a DeviceGrey fill colour string for PDF. This will
@@ -85,8 +68,8 @@ class Color::GrayScale
 
   # Present the colour as an RGBA (with alpha) HTML/CSS colour string (e.g.,
   # "rgb(0%, 50%, 100%, 1)").
-  def css_rgba
-    "rgba(%3.2f%%, %3.2f%%, %3.2f%%, %1.2f)" % [ gray, gray, gray, 1 ]
+  def css_rgba(alpha = 1)
+    "rgba(%3.2f%%, %3.2f%%, %3.2f%%, %1.2f)" % [ gray, gray, gray, alpha ]
   end
 
   # Present the colour as an HSL HTML/CSS colour string (e.g., "hsl(180,
@@ -182,10 +165,7 @@ class Color::GrayScale
   # The addition is done using the grayscale accessor methods to ensure a
   # valid colour in the result.
   def +(other)
-    other = other.to_grayscale
-    ng = self.dup
-    ng.g += other.g
-    ng
+    self.class.from_fraction(g + other.to_grayscale.g)
   end
 
   # Subtracts another colour to the current colour. The other colour will be
@@ -195,18 +175,23 @@ class Color::GrayScale
   # The subtraction is done using the grayscale accessor methods to ensure a
   # valid colour in the result.
   def -(other)
-    other = other.to_grayscale 
-    ng = self.dup
-    ng.g -= other.g
-    ng
+    self + (-other)
   end
 
   def inspect
     "Gray [%.2f%%]" % [ gray ]
   end
-end
 
-module Color
-  # A synonym for Color::GrayScale.
-  GreyScale = GrayScale
+  def to_a
+    [ g ]
+  end
+
+  def -@
+    gs = self.dup
+    gs.instance_variable_set(:@g, -g)
+    gs
+  end
 end
+
+# A synonym for Color::GrayScale.
+Color::GreyScale = Color::GrayScale

data/lib/color/hsl.rb

@@ -1,51 +1,30 @@
-#--
-# Color
-# Colour management with Ruby
-# http://rubyforge.org/projects/color
-#   Version 1.4.1
-#
-# Licensed under a MIT-style licence. See Licence.txt in the main
-# distribution for full licensing information.
-#
-# Copyright (c) 2005 - 2010 Austin Ziegler and Matt Lyon
-#++
+# -*- ruby encoding: utf-8 -*-
 
 # An HSL colour object. Internally, the hue (#h), saturation (#s), and
 # luminosity/lightness (#l) values are dealt with as fractional values in
 # the range 0..1.
 class Color::HSL
+  include Color
+
   class << self
     # Creates an HSL colour object from fractional values 0..1.
-    def from_fraction(h = 0.0, s = 0.0, l = 0.0)
-      colour = Color::HSL.new
-      colour.h = h
-      colour.s = s
-      colour.l = l
-      colour
+    def from_fraction(h = 0.0, s = 0.0, l = 0.0, &block)
+      new(h, s, l, 1.0, 1.0, &block)
     end
   end
 
-  # Compares the other colour to this one. The other colour will be
-  # converted to HSL before comparison, so the comparison between a HSL
-  # colour and a non-HSL colour will be approximate and based on the other
-  # colour's #to_hsl conversion. If there is no #to_hsl conversion, this
-  # will raise an exception. This will report that two HSL values are
-  # equivalent if all component values are within Color::COLOR_TOLERANCE of
-  # each other.
-  def ==(other)
-    other = other.to_hsl
-    other.kind_of?(Color::HSL) and
-    ((@h - other.h).abs <= Color::COLOR_TOLERANCE) and
-    ((@s - other.s).abs <= Color::COLOR_TOLERANCE) and
-    ((@l - other.l).abs <= Color::COLOR_TOLERANCE)
+  # Coerces the other Color object into HSL.
+  def coerce(other)
+    other.to_hsl
   end
 
   # Creates an HSL colour object from the standard values of degrees and
   # percentages (e.g., 145 deg, 30%, 50%).
-  def initialize(h = 0, s = 0, l = 0)
-    @h = h / 360.0
-    @s = s / 100.0
-    @l = l / 100.0
+  def initialize(h = 0, s = 0, l = 0, radix1 = 360.0, radix2 = 100.0, &block) # :yields self:
+    @h = Color.normalize(h / radix1)
+    @s = Color.normalize(s / radix2)
+    @l = Color.normalize(l / radix2)
+    block.call if block
   end
 
   # Present the colour as an HTML/CSS colour string.
@@ -63,8 +42,8 @@ class Color::HSL
   # 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.
-  def css_rgba
-    to_rgb.css_rgba
+  def css_rgba(alpha = 1)
+    to_rgb.css_rgba(alpha)
   end
 
   # Present the colour as an HSL HTML/CSS colour string (e.g., "hsl(180,
@@ -79,46 +58,30 @@ class Color::HSL
     "hsla(%3.2f, %3.2f%%, %3.2f%%, %3.2f)" % [ hue, saturation, luminosity, 1 ]
   end
 
-  # Converting to HSL as adapted from Foley and Van-Dam from
-  # http://www.bobpowell.net/RGBHSB.htm.
+  # Converting from HSL to RGB. As with all colour conversions, this is
+  # approximate at best. The code here is adapted from fvd and van Dam,
+  # originally found at [1] (implemented similarly at [2]).
   #
-  # NOTE:
-  # * If the colour's luminosity is near zero, the colour is always black.
-  # * If the colour's luminosity is near one, the colour is always white.
-  # * If the colour's saturation is near zero, the colour is always a shade
-  #   of grey and is based only on the luminosity of the colour.
+  # This simplifies the calculations with the following assumptions:
+  # - Luminance values <= 0 always translate to Color::RGB::Black.
+  # - Luminance values >= 1 always translate to Color::RGB::White.
+  # - Saturation values <= 0 always translate to a shade of gray using
+  #   luminance as a percentage of gray.
   #
-  def to_rgb(ignored = nil)
-    return Color::RGB.new if Color.near_zero_or_less?(@l)
-    return Color::RGB.new(0xff, 0xff, 0xff) if Color.near_one_or_more?(@l)
-    return Color::RGB.from_fraction(@l, @l, @l) if Color.near_zero?(@s)
-
-    # Is the value less than 0.5?
-    if Color.near_zero_or_less?(@l - 0.5)
-      tmp2 = @l * (1.0 + @s.to_f)
+  # [1] http://bobpowell.net/RGBHSB.aspx
+  # [2] http://support.microsoft.com/kb/29240
+  def to_rgb(*)
+    if Color.near_zero_or_less?(l)
+      Color::RGB::Black
+    elsif Color.near_one_or_more?(l)
+      Color::RGB::White
+    elsif Color.near_zero?(s)
+      Color::RGB.from_grayscale_fraction(l)
     else
-      tmp2 = @l + @s - (@l * @s.to_f)
+      # Only needed for Ruby 1.8. For Ruby 1.9+, we can do:
+      # Color::RGB.new(*compute_fvd_rgb, 1.0)
+      Color::RGB.new(*(compute_fvd_rgb + [ 1.0 ]))
     end
-    tmp1 = 2.0 * @l - tmp2
-
-    tmp3  = [ @h + (1.0 / 3.0), @h, @h - (1.0 / 3.0) ]
-
-    rgb = tmp3.map { |hue|
-      hue += 1.0 if Color.near_zero_or_less?(hue)
-      hue -= 1.0 if Color.near_one_or_more?(hue)
-
-      if Color.near_zero_or_less?((6.0 * hue) - 1.0)
-        tmp1 + ((tmp2 - tmp1) * hue * 6.0)
-      elsif Color.near_zero_or_less?((2.0 * hue) - 1.0)
-        tmp2
-      elsif Color.near_zero_or_less?((3.0 * hue) - 2.0)
-        tmp1 + (tmp2 - tmp1) * ((2 / 3.0) - hue) * 6.0
-      else
-        tmp1
-      end
-    }
-
-     Color::RGB.from_fraction(*rgb)
   end
 
   # Converts to RGB then YIQ.
@@ -209,13 +172,69 @@ class Color::HSL
   # Mix the mask colour (which will be converted to an HSL colour) with the
   # current colour at the stated mix percentage as a decimal value.
   #
-  # NOTE::  This differs from Color::RGB#mix_with.
+  # NOTE:: This differs from Color::RGB#mix_with.
   def mix_with(color, mix_percent = 0.5)
-    color   = color.to_hsl
-    _h = ((color.h - self.h) * mix_percent) + self.h
-    _s = ((color.s - self.s) * mix_percent) + self.s
-    _l = ((color.l - self.l) * mix_percent) + self.l
+    v = to_a.zip(coerce(color).to_a).map { |(x, y)|
+      ((y - x) * mix_percent) + x
+    }
+    self.class.from_fraction(*v)
+  end
+
+  def to_a
+    [ h, s, l ]
+  end
+
+  private
+
+  # This algorithm calculates based on a mixture of the saturation and
+  # luminance, and then takes the RGB values from the hue + 1/3, hue, and
+  # hue - 1/3 positions in a circular representation of colour divided into
+  # four parts (confusing, I know, but it's the way that it works). See
+  # #hue_to_rgb for more information.
+  def compute_fvd_rgb
+    t1, t2 = fvd_mix_sat_lum
+    [ h + (1 / 3.0), h, h - (1 / 3.0) ].map { |v|
+      hue_to_rgb(rotate_hue(v), t1, t2)
+    }
+  end
 
-    self.class.from_fraction(_h, _s, _l)
+  # Mix saturation and luminance for use in hue_to_rgb. The base value is
+  # different depending on whether luminance is <= 50% or > 50%.
+  def fvd_mix_sat_lum
+    t = if Color.near_zero_or_less?(l - 0.5)
+             l * (1.0 + s.to_f)
+           else
+             l + s - (l * s.to_f)
+           end
+    [ 2.0 * l - t, t ]
+  end
+
+  # In HSL, hues are referenced as degrees in a colour circle. The flow
+  # itself is endless; therefore, we can rotate around. The only thing our
+  # implementation restricts is that you should not be > 1.0.
+  def rotate_hue(h)
+    h += 1.0 if Color.near_zero_or_less?(h)
+    h -= 1.0 if Color.near_one_or_more?(h)
+    h
+  end
+
+  # We calculate the interaction of the saturation/luminance mix (calculated
+  # earlier) based on the position of the hue in the circular colour space
+  # divided into quadrants. Our hue range is [0, 1), not [0, 360º).
+  #
+  # - The first quadrant covers the first 60º [0, 60º].
+  # - The second quadrant covers the next 120º (60º, 180º].
+  # - The third quadrant covers the next 60º (180º, 240º].
+  # - The fourth quadrant covers the final 120º (240º, 360º).
+  def hue_to_rgb(h, t1, t2)
+    if Color.near_zero_or_less?((6.0 * h) - 1.0)
+      t1 + ((t2 - t1) * h * 6.0)
+    elsif Color.near_zero_or_less?((2.0 * h) - 1.0)
+      t2
+    elsif Color.near_zero_or_less?((3.0 * h) - 2.0)
+      t1 + (t2 - t1) * ((2 / 3.0) - h) * 6.0
+    else
+      t1
+    end
   end
 end

data/lib/color/palette.rb

@@ -1,15 +1,3 @@
-#--
-# Color
-# Colour management with Ruby
-# http://rubyforge.org/projects/color
-#   Version 1.4.1
-#
-# Licensed under a MIT-style licence. See Licence.txt in the main
-# distribution for full licensing information.
-#
-# Copyright (c) 2005 - 2010 Austin Ziegler and Matt Lyon
-#++
-
 require 'color'
 
 module Color::Palette

data/lib/color/palette/adobecolor.rb

@@ -1,15 +1,3 @@
-#--
-# Color
-# Colour management with Ruby
-# http://rubyforge.org/projects/color
-#   Version 1.4.1
-#
-# Licensed under a MIT-style licence. See Licence.txt in the main
-# distribution for full licensing information.
-#
-# Copyright (c) 2005 - 2010 Austin Ziegler and Matt Lyon
-#++
-
 require 'color/palette'
 
 # A class that can read an Adobe Color palette file (used for Photoshop

data/lib/color/palette/gimp.rb

@@ -1,15 +1,3 @@
-#--
-# Color
-# Colour management with Ruby
-# http://rubyforge.org/projects/color
-#   Version 1.4.1
-#
-# Licensed under a MIT-style licence. See Licence.txt in the main
-# distribution for full licensing information.
-#
-# Copyright (c) 2005 - 2010 Austin Ziegler and Matt Lyon
-#++
-
 require 'color/palette'
 
 # A class that can read a GIMP (GNU Image Manipulation Program) palette file

data/lib/color/palette/monocontrast.rb

@@ -1,15 +1,3 @@
-#--
-# Color
-# Colour management with Ruby
-# http://rubyforge.org/projects/color
-#   Version 1.4.1
-#
-# Licensed under a MIT-style licence. See Licence.txt in the main
-# distribution for full licensing information.
-#
-# Copyright (c) 2005 - 2010 Austin Ziegler and Matt Lyon
-#++
-
 require 'color/palette'
 
 # Generates a monochromatic constrasting colour palette for background and
@@ -25,7 +13,7 @@ require 'color/palette'
 # against the background.
 class Color::Palette::MonoContrast
   # Hash of CSS background colour values.
-  # 
+  #
   # This is always 11 values:
   #
   # 0::       The starting colour.
@@ -33,7 +21,7 @@ class Color::Palette::MonoContrast
   # -1..-5::  Darker colours.
   attr_reader :background
   # Hash of CSS foreground colour values.
-  # 
+  #
   # This is always 11 values:
   #
   # 0::       The starting colour.
@@ -48,19 +36,17 @@ class Color::Palette::MonoContrast
   # the palette based on the base colours. The default value for this is 125
   # / 255.0. If this value is set to +nil+, it will be restored to the
   # default.
-  attr_accessor :minimum_brightness_diff
-  remove_method :minimum_brightness_diff= ;
+  attr_reader :minimum_brightness_diff
   def minimum_brightness_diff=(bd) #:nodoc:
-    if bd.nil?
-      @minimum_brightness_diff = DEFAULT_MINIMUM_BRIGHTNESS_DIFF
-    elsif bd > 1.0
-      @minimum_brightness_diff = 1.0
-    elsif bd < 0.0
-      @minimum_brightness_diff = 0.0
-    else
-      @minimum_brightness_diff = bd
-    end
-      
+    @minimum_brightness_diff = if bd.nil?
+                                 DEFAULT_MINIMUM_BRIGHTNESS_DIFF
+                               elsif bd > 1.0
+                                 1.0
+                               elsif bd < 0.0
+                                 0.0
+                               else
+                                 bd
+                               end
     regenerate(@background[0], @foreground[0])
   end
 
@@ -69,18 +55,17 @@ class Color::Palette::MonoContrast
   # The minimum colour difference between the background and the foreground,
   # and must be between 0..3. Setting this value will regenerate the palette
   # based on the base colours. The default value for this is 500 / 255.0.
-  attr_accessor :minimum_color_diff
-  remove_method :minimum_color_diff= ;
-  def minimum_color_diff=(cd) #:noco:
-    if cd.nil?
-      @minimum_color_diff = DEFAULT_MINIMUM_COLOR_DIFF
-    elsif cd > 3.0
-      @minimum_color_diff = 3.0
-    elsif cd < 0.0
-      @minimum_color_diff = 0.0
-    else
-      @minimum_color_diff = cd
-    end
+  attr_reader :minimum_color_diff
+  def minimum_color_diff=(cd) #:nodoc:
+    @minimum_color_diff = if cd.nil?
+                            DEFAULT_MINIMUM_COLOR_DIFF
+                          elsif cd > 3.0
+                            3.0
+                          elsif cd < 0.0
+                            0.0
+                          else
+                            cd
+                          end
     regenerate(@background[0], @foreground[0])
   end
 
@@ -88,7 +73,6 @@ class Color::Palette::MonoContrast
   def initialize(background, foreground = nil)
     @minimum_brightness_diff = DEFAULT_MINIMUM_BRIGHTNESS_DIFF
     @minimum_color_diff = DEFAULT_MINIMUM_COLOR_DIFF
-
     regenerate(background, foreground)
   end
 
@@ -160,7 +144,7 @@ class Color::Palette::MonoContrast
 
   # Returns the absolute difference between the brightness levels of two
   # colours. This will be a decimal value between 0 and 1. W3C accessibility
-  # guidelines for colour contrast[http://www.w3.org/TR/AERT#color-contrast]
+  # guidelines for {colour contrast}[http://www.w3.org/TR/AERT#color-contrast]
   # suggest that this value be at least approximately 0.49 (125 / 255.0) for
   # proper contrast.
   def brightness_diff(c1, c2)
@@ -168,8 +152,8 @@ class Color::Palette::MonoContrast
   end
 
   # Returns the contrast between to colours, a decimal value between 0 and
-  # 3. W3C accessibility guidelines for colour
-  # contrast[http://www.w3.org/TR/AERT#color-contrast] suggest that this
+  # 3. W3C accessibility guidelines for {colour
+  # contrast}[http://www.w3.org/TR/AERT#color-contrast] suggest that this
   # value be at least approximately 1.96 (500 / 255.0) for proper contrast.
   def color_diff(c1, c2)
     r = (c1.r - c2.r).abs