color-tools 1.2.0 → 1.3.0

data/lib/color/css.rb

@@ -0,0 +1,27 @@
+#--
+# Colour management with Ruby.
+#
+# Copyright 2005 Austin Ziegler
+#   http://rubyforge.org/ruby-pdf/
+#
+#   Licensed under a MIT-style licence.
+#
+# $Id: css.rb,v 1.1 2005/08/05 23:07:20 austin Exp $
+#++
+
+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)
+  end
+end

data/lib/color/grayscale.rb

@@ -3,22 +3,32 @@
 #
 # Copyright 2005 Austin Ziegler
 #   http://rubyforge.org/ruby-pdf/
+#
+#   Licensed under a MIT-style licence.
+#
+# $Id: grayscale.rb,v 1.3 2005/08/08 02:44:17 austin Exp $
 #++
 
   # A colour object representing shades of grey. Used primarily in PDF
   # document creation.
 class Color::GrayScale
-    # The format required to present the colour to a PDF document.
+    # 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.
+    # 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
 
-    # Creates a greyscale colour object from percentages 0 .. 100.
+    # Creates a greyscale colour object from percentages 0..100.
+    #
+    #   Color::GrayScale.new(50)
   def initialize(g = 0)
     @g = g / 100.0
   end
@@ -27,18 +37,23 @@ class Color::GrayScale
     # 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.
+    # #to_greyscale conversion, this will raise an exception. This will
+    # report that two GreyScale values are equivalent if they are within
+    # 1e-4 (0.0001) of each other.
   def ==(other)
     other = other.to_grayscale
-    other.kind_of?(Color::GrayScale) and (@g == other.g)
+    other.kind_of?(Color::GrayScale) and
+    ((@g - other.g).abs <= 1e-4)
   end
 
-    # Present the colour as a fill colour string for PDF.
+    # Present the colour as a DeviceGrey fill colour string for PDF. This
+    # will be removed from the default package in color-tools 2.0.
   def pdf_fill
     PDF_FORMAT_STR % [ @g, "g" ]
   end
 
-    # Present the colour as a stroke colour string for PDF.
+    # Present the colour as a DeviceGrey stroke colour string for PDF. This
+    # will be removed from the default package in color-tools 2.0.
   def pdf_stroke
     PDF_FORMAT_STR % [ @g, "G" ]
   end
@@ -50,19 +65,19 @@ class Color::GrayScale
 
     # Present the colour as an HTML/CSS colour string.
   def html
-    gs = "%02x" % @g.to_255
+    gs = "%02x" % to_255
     "##{gs * 3}"
   end
 
     # Convert the greyscale colour to CMYK.
   def to_cmyk
     k = 1.0 - @g.to_f
-    Color::CMYK.from_Fraction(0, 0, 0, k)
+    Color::CMYK.from_fraction(0, 0, 0, k)
   end
 
     # Convert the greyscale colour to RGB.
   def to_rgb(ignored = true)
-    g = @g.to_255
+    g = to_255
     Color::RGB.new(g, g, g)
   end
 
@@ -74,12 +89,12 @@ class Color::GrayScale
     # Lightens the greyscale colour by the stated percent.
   def lighten_by(percent)
     g = [@g + (@g * (percent / 100.0)), 1.0].min
-    Color::Grayscale.from_fraction(g)
+    Color::GrayScale.from_fraction(g)
   end
 
     # Darken the RGB hue by the stated percent.
   def darken_by(percent)
-    g = [@g - (@g * (percent / 100.0)), 1.0].max
+    g = [@g - (@g * (percent / 100.0)), 0.0].max
     Color::GrayScale.from_fraction(g)
   end
 
@@ -94,6 +109,11 @@ class Color::GrayScale
     Color::YIQ.from_fraction(y, i, q)
   end
 
+    # Returns the HSL colour encoding of the greyscale value.
+  def to_hsl
+    Color::HSL.from_fraction(0, 0, @g)
+  end
+
     # Returns the brightness value for this greyscale value; this is the
     # greyscale value.
   def brightness
@@ -101,5 +121,15 @@ class Color::GrayScale
   end
 
   attr_accessor :g
+  remove_method :g= ;
+  def g=(gg) #:nodoc:
+    gg = 1.0 if gg > 1
+    gg = 0.0 if gg < 0
+    @g = gg
+  end
+end
+
+module Color
+    # A synonym for Color::GrayScale.
+  GreyScale = GrayScale
 end
-Color::GreyScale = Color::GrayScale

data/lib/color/hsl.rb

@@ -0,0 +1,130 @@
+#--
+# Colour management with Ruby.
+#
+# Copyright 2005 Austin Ziegler
+#   http://rubyforge.org/ruby-pdf/
+#
+#   Licensed under a MIT-style licence.
+#
+# $Id: hsl.rb,v 1.2 2005/08/08 02:44:17 austin Exp $
+#++
+
+  # An HSL colour object. Internally, the hue (#h), saturation (#s), and
+  # luminosity (#l) values are dealt with as fractional values in the range
+  # 0..1.
+class Color::HSL
+  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
+    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 1e-4 (0.0001) of each
+    # other.
+  def ==(other)
+    other = other.to_hsl
+    other.kind_of?(Color::HSL) and
+    ((@h - other.h).abs <= 1e-4) and
+    ((@s - other.s).abs <= 1e-4) and
+    ((@l - other.l).abs <= 1e-4)
+  end
+
+    # Creates an HSL colour object from the standard values of degrees and
+    # percentages (e.g., 145�, 30%, 50%).
+  def initialize(h = 0, s = 0, l = 0)
+    @h = h / 360.0
+    @s = s / 100.0
+    @l = l / 100.0
+  end
+
+    # Present the colour as an HTML/CSS colour string.
+  def html
+    to_rgb.html
+  end
+
+    # Converting to HSL as adapted from Foley and Van-Dam from
+    # http://www.bobpowell.net/RGBHSB.htm.
+  def to_rgb(ignored = nil)
+      # If luminosity is zero, the colour is always black.
+    return Color::RGB.new if @l == 0
+      # If luminosity is one, the colour is always white.
+    return Color::RGB.new(0xff, 0xff, 0xff) if @l == 1
+      # If saturation is zero, the colour is always a greyscale colour.
+    return Color::RGB.new(@l, @l, @l) if @s <= 1e-5
+
+    if (@l - 0.5) < 1e-5
+      tmp2 = @l * (1.0 + @s.to_f)
+    else
+      tmp2 = @l + @s - (@l * @s.to_f)
+    end
+    tmp1 = 2.0 * @l - tmp2
+
+    t3  = [ @h + 1.0 / 3.0, @h, @h - 1.0 / 3.0 ]
+    t3 = t3.map { |tmp3|
+      tmp3 += 1.0 if tmp3 < 1e-5
+      tmp3 -= 1.0 if (tmp3 - 1.0) > 1e-5
+      tmp3
+    }
+
+    rgb = t3.map do |tmp3|
+      if ((6.0 * tmp3) - 1.0) < 1e-5
+        tmp1 + ((tmp2 - tmp1) * tmp3 * 6.0)
+      elsif ((2.0 * tmp3) - 1.0) < 1e-5
+        tmp2
+      elsif ((3.0 * tmp3) - 2.0) < 1e-5
+        tmp1 + (tmp2 - tmp1) * ((2 / 3.0) - tmp3) * 6.0
+      else
+        tmp1
+      end
+    end
+
+     Color::RGB.from_fraction(*rgb)
+  end
+
+    # Converts to RGB then YIQ.
+  def to_yiq
+    to_rgb.to_yiq
+  end
+
+    # Converts to RGB then CMYK.
+  def to_cmyk
+    to_rgb.to_cmyk
+  end
+
+    # Returns the luminosity (#l) of the colour.
+  def brightness
+    @l
+  end
+  def to_greyscale
+    Color::GrayScale.from_fraction(@l)
+  end
+  alias to_grayscale to_greyscale
+
+  attr_accessor :h, :s, :l
+  remove_method :h=, :s=, :l= ;
+  def h=(hh) #:nodoc:
+    hh = 1.0 if hh > 1
+    hh = 0.0 if hh < 0
+    @h = hh
+  end
+  def s=(ss) #:nodoc:
+    ss = 1.0 if ss > 1
+    ss = 0.0 if ss < 0
+    @s = ss
+  end
+  def l=(ll) #:nodoc:
+    ll = 1.0 if ll > 1
+    ll = 0.0 if ll < 0
+    @l = ll
+  end
+end

data/lib/color/palette.rb

@@ -3,6 +3,10 @@
 #
 # Copyright 2005 Austin Ziegler
 #   http://rubyforge.org/ruby-pdf/
+#
+#   Licensed under a MIT-style licence.
+#
+# $Id: palette.rb,v 1.2 2005/08/05 23:07:20 austin Exp $
 #++
 
 require 'color'

data/lib/color/palette/gimp.rb

@@ -3,30 +3,50 @@
 #
 # Copyright 2005 Austin Ziegler
 #   http://rubyforge.org/ruby-pdf/
+#
+#   Licensed under a MIT-style licence.
+#
+# $Id: gimp.rb,v 1.3 2005/08/08 02:44:17 austin Exp $
 #++
 
 require 'color/palette'
 
+  # A class that can read a GIMP (GNU Image Manipulation Program) palette
+  # file and provide a Hash-like interface to the contents. GIMP colour
+  # palettes are RGB values only.
+  #
+  # Because two or more entries in a GIMP palette may have the same name,
+  # all named entries are returned as an array.
+  #
+  #   pal = Color::Palette::Gimp.from_file(my_gimp_palette)
+  #   pal[0]          => Color::RGB<...>
+  #   pal["white"]    => [ Color::RGB<...> ]
+  #   pal["unknown"]  => [ Color::RGB<...>, Color::RGB<...>, ... ]
+  #
+  # GIMP Palettes are always indexable by insertion order (an integer key).
 class Color::Palette::Gimp
   include Enumerable
 
   class << self
+      # Create a GIMP palette object from the named file.
     def from_file(filename)
       File.open(filename, "rb") { |io| Color::Palette::Gimp.from_io(io) }
     end
 
+      # Create a GIMP palette object from the provided IO.
     def from_io(io)
       Color::Palette::Gimp.new(io.read)
     end
   end
 
+    # Create a new GIMP palette.
   def initialize(palette)
-    @colors   = {}
+    @colors   = []
+    @names    = {}
     @valid    = false
     @name     = "(unnamed)"
 
     index     = 0
-    collision = {}
 
     palette.split($/).each do |line|
       line.chomp!
@@ -47,26 +67,41 @@ class Color::Palette::Gimp
 
       line.gsub!(/^\s+/, '')
       data = line.split(/\s+/, 4)
-      name = data.pop
+      name = data.pop.strip
       data.map! { |el| el.to_i }
 
-      @colors[index] = Color::RGB.new(*data)
+      color = Color::RGB.new(*data)
 
-      if @colors.has_key?(name)
-        collision[name] = true
-      else
-        @colors[name] = @colors[index]
-      end
-    end
+      @colors[index]  = color
+      @names[name] ||= []
+      @names[name]  << color
 
-    collision.each_key { |key| @colors.delete_at(key) }
+      index += 1
+    end
   end
 
   def [](key)
-    @colors[key]
+    if key.kind_of?(Numeric)
+      @colors[key]
+    else
+      @names[key]
+    end
   end
 
+    # Loops through each colour.
   def each
     @colors.each { |el| yield el }
   end
+
+    # Loops through each named colour set.
+  def each_name #:yields color_name, color_set:#
+    @names.each { |color_name, color_set| yield color_name, color_set }
+  end
+
+    # Returns true if this is believed to be a valid GIMP palette.
+  def valid?
+    @valid
+  end
+
+  attr_reader :name
 end

data/lib/color/palette/monocontrast.rb

@@ -3,6 +3,10 @@
 #
 # Copyright 2005 Austin Ziegler
 #   http://rubyforge.org/ruby-pdf/
+#
+#   Licensed under a MIT-style licence.
+#
+# $Id: monocontrast.rb,v 1.3 2005/08/08 02:44:17 austin Exp $
 #++
 
 require 'color/palette'
@@ -26,7 +30,7 @@ class Color::Palette::MonoContrast
     # 0::       The starting colour.
     # +1..+5::  Lighter colours.
     # -1..-5::  Darker colours.
-  attr_accessor :background
+  attr_reader :background
     # Hash of CSS foreground colour values.
     # 
     # This is always 11 values:
@@ -34,30 +38,56 @@ class Color::Palette::MonoContrast
     # 0::       The starting colour.
     # +1..+5::  Lighter colours.
     # -1..-5::  Darker colours.
-  attr_accessor :foreground
+  attr_reader :foreground
+
+  DEFAULT_MINIMUM_BRIGHTNESS_DIFF = (125.0 / 255.0)
 
     # The minimum brightness difference between the background and the
-    # foreground. Setting this value will regenerate the palette based on
-    # the base colours. The default value for this is 125 / 255.0.
+    # foreground, and must be between 0..1. Setting this value will
+    # regenerate 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= ;
   def minimum_brightness_diff=(bd) #:nodoc:
-    @minimum_brightness_diff = bd
+    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
+      
     regenerate(@background[0], @foreground[0])
   end
 
+  DEFAULT_MINIMUM_COLOR_DIFF = (500.0 / 255.0)
+
     # The minimum colour difference between the background and the
-    # foreground. Setting this value will regenerate the palette based on
-    # the base colours.
+    # 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:
-    @minimum_color_diff = bd
+    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
     regenerate(@background[0], @foreground[0])
   end
 
     # Generate the initial palette.
   def initialize(background, foreground = nil)
-    @minimum_brightness_diff = 125 / 255.0
-    @minimum_color_diff = 500 / 765.0
+    @minimum_brightness_diff = DEFAULT_MINIMUM_BRIGHTNESS_DIFF
+    @minimum_color_diff = DEFAULT_MINIMUM_COLOR_DIFF
 
     regenerate(background, foreground)
   end
@@ -140,7 +170,7 @@ class Color::Palette::MonoContrast
     # 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
-    # value be at least approximately 1.96 (500 / 765.0) for proper contrast.
+    # value be at least approximately 1.96 (500 / 255.0) for proper contrast.
   def color_diff(c1, c2)
     r = (c1.r - c2.r).abs
     g = (c1.g - c2.g).abs