ripta-color-tools 1.4.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$
+#++
+
+# 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

@@ -0,0 +1,135 @@
+#--
+# Colour management with Ruby.
+#
+# Copyright 2005 Austin Ziegler
+#   http://rubyforge.org/ruby-pdf/
+#
+#   Licensed under a MIT-style licence.
+#
+# $Id$
+#++
+
+# A colour object representing shades of grey. Used primarily in PDF
+# document creation.
+class Color::GrayScale
+  # 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
+
+  # Creates a greyscale colour object from percentages 0..100.
+  #
+  #   Color::GrayScale.new(50)
+  def initialize(g = 0)
+    @g = g / 100.0
+  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
+  # 1e-4 (0.0001) of each other.
+  def ==(other)
+    other = other.to_grayscale
+    other.kind_of?(Color::GrayScale) and
+    ((@g - other.g).abs <= 1e-4)
+  end
+
+  # 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 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
+
+  def to_255
+    [(@g * 255).round, 255].min
+  end
+  private :to_255
+
+  # Present the colour as an HTML/CSS colour string.
+  def html
+    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)
+  end
+
+  # Convert the greyscale colour to RGB.
+  def to_rgb(ignored = true)
+    g = to_255
+    Color::RGB.new(g, g, g)
+  end
+
+  def to_grayscale
+    self
+  end
+  alias to_greyscale to_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)
+  end
+
+  # Darken the RGB hue by the stated percent.
+  def darken_by(percent)
+    g = [@g - (@g * (percent / 100.0)), 0.0].max
+    Color::GrayScale.from_fraction(g)
+  end
+
+  # Returns the YIQ (NTSC) colour encoding of the greyscale value. This
+  # is an approximation, as the values for I and Q are calculated by
+  # treating the greyscale value as an RGB value. The Y (intensity or
+  # brightness) value is the same as the greyscale value.
+  def to_yiq
+    y = @g
+    i = (@g * 0.596) + (@g * -0.275) + (@g * -0.321)
+    q = (@g * 0.212) + (@g * -0.523) + (@g *  0.311)
+    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
+    @g
+  end
+
+  attr_reader :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

data/lib/color/hsl.rb

@@ -0,0 +1,134 @@
+#--
+# Colour management with Ruby.
+#
+# Copyright 2005 Austin Ziegler
+#   http://rubyforge.org/ruby-pdf/
+#
+#   Licensed under a MIT-style licence.
+#
+# $Id$
+#++
+
+# 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_reader :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

@@ -0,0 +1,18 @@
+#--
+# Colour management with Ruby.
+#
+# Copyright 2005 Austin Ziegler
+#   http://rubyforge.org/ruby-pdf/
+#
+#   Licensed under a MIT-style licence.
+#
+# $Id$
+#++
+module Color
+  module Palette
+
+    autoload :Gimp, "color/palette/gimp"
+    autoload :MonoContrast, "color/palette/monocontrast"
+
+  end
+end

data/lib/color/palette/gimp.rb

@@ -0,0 +1,105 @@
+#--
+# Colour management with Ruby.
+#
+# Copyright 2005 Austin Ziegler
+#   http://rubyforge.org/ruby-pdf/
+#
+#   Licensed under a MIT-style licence.
+#
+# $Id$
+#++
+
+# 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   = []
+    @names    = {}
+    @valid    = false
+    @name     = "(unnamed)"
+
+    index     = 0
+
+    palette.split($/).each do |line|
+      line.chomp!
+      line.gsub!(/\s*#.*\Z/, '')
+
+      next if line.empty?
+
+      if line =~ /\AGIMP Palette\Z/
+        @valid = true
+        next
+      end
+
+      info = /(\w+):\s(.*$)/.match(line)
+      if info
+        @name = info.captures[1] if info.captures[0] =~ /name/i
+        next
+      end
+
+      line.gsub!(/^\s+/, '')
+      data = line.split(/\s+/, 4)
+      name = data.pop.strip
+      data.map! { |el| el.to_i }
+
+      color = Color::RGB.new(*data)
+
+      @colors[index]  = color
+      @names[name] ||= []
+      @names[name]  << color
+
+      index += 1
+    end
+  end
+
+  def [](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

@@ -0,0 +1,178 @@
+#--
+# Colour management with Ruby.
+#
+# Copyright 2005 Austin Ziegler
+#   http://rubyforge.org/ruby-pdf/
+#
+#   Licensed under a MIT-style licence.
+#
+# $Id$
+#++
+
+# Generates a monochromatic constrasting colour palette for background and
+# foreground. What does this mean?
+#
+# Monochromatic: A single colour is used to generate the base palette, and
+# this colour is lightened five times and darkened five times to provide
+# eleven distinct colours.
+#
+# Contrasting: The foreground is also generated as a monochromatic colour
+# palettte; however, all generated colours are tested to see that they are
+# appropriately contrasting to ensure maximum readability of the
+# foreground against the background.
+class Color::Palette::MonoContrast
+  # Hash of CSS background colour values.
+  # 
+  # This is always 11 values:
+  #
+  # 0::       The starting colour.
+  # +1..+5::  Lighter colours.
+  # -1..-5::  Darker colours.
+  attr_reader :background
+  # Hash of CSS foreground colour values.
+  # 
+  # This is always 11 values:
+  #
+  # 0::       The starting colour.
+  # +1..+5::  Lighter colours.
+  # -1..-5::  Darker colours.
+  attr_reader :foreground
+
+  DEFAULT_MINIMUM_BRIGHTNESS_DIFF = (125.0 / 255.0)
+
+  attr_reader :minimum_brightness_diff
+
+  # The minimum brightness difference between the background and the
+  # 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.
+  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
+
+    regenerate(@background[0], @foreground[0])
+  end
+
+  DEFAULT_MINIMUM_COLOR_DIFF = (500.0 / 255.0)
+
+  attr_reader :minimum_color_diff
+
+  # 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.
+  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
+    regenerate(@background[0], @foreground[0])
+  end
+
+  # Generate the initial palette.
+  def initialize(background, foreground = nil)
+    @minimum_brightness_diff = DEFAULT_MINIMUM_BRIGHTNESS_DIFF
+    @minimum_color_diff = DEFAULT_MINIMUM_COLOR_DIFF
+
+    regenerate(background, foreground)
+  end
+
+  # Generate the colour palettes.
+  def regenerate(background, foreground = nil)
+    foreground ||= background
+    background = background.to_rgb
+    foreground = foreground.to_rgb
+
+    @background = {}
+    @foreground = {}
+
+    @background[-5] = background.darken_by(10)
+    @background[-4] = background.darken_by(25)
+    @background[-3] = background.darken_by(50)
+    @background[-2] = background.darken_by(75)
+    @background[-1] = background.darken_by(85)
+    @background[ 0] = background
+    @background[+1] = background.lighten_by(85)
+    @background[+2] = background.lighten_by(75)
+    @background[+3] = background.lighten_by(50)
+    @background[+4] = background.lighten_by(25)
+    @background[+5] = background.lighten_by(10)
+
+    @foreground[-5] = calculate_foreground(@background[-5], foreground)
+    @foreground[-4] = calculate_foreground(@background[-4], foreground)
+    @foreground[-3] = calculate_foreground(@background[-3], foreground)
+    @foreground[-2] = calculate_foreground(@background[-2], foreground)
+    @foreground[-1] = calculate_foreground(@background[-1], foreground)
+    @foreground[ 0] = calculate_foreground(@background[ 0], foreground)
+    @foreground[+1] = calculate_foreground(@background[+1], foreground)
+    @foreground[+2] = calculate_foreground(@background[+2], foreground)
+    @foreground[+3] = calculate_foreground(@background[+3], foreground)
+    @foreground[+4] = calculate_foreground(@background[+4], foreground)
+    @foreground[+5] = calculate_foreground(@background[+5], foreground)
+  end
+
+  # Given a background colour and a foreground colour, modifies the
+  # foreground colour so that it will have enough contrast to be seen
+  # against the background colour.
+  #
+  # Uses #mininum_brightness_diff and #minimum_color_diff.
+  def calculate_foreground(background, foreground)
+    nfg = nil
+    # Loop through brighter and darker versions of the foreground color.
+    # The numbers here represent the amount of foreground color to mix
+    # with black and white.
+    [100, 75, 50, 25, 0].each do |percent|
+      dfg = foreground.darken_by(percent)
+      lfg = foreground.lighten_by(percent)
+
+      dbd = brightness_diff(background, dfg)
+      lbd = brightness_diff(background, lfg)
+
+      if lbd > dbd
+        nfg = lfg
+        nbd = lbd
+      else
+        nfg = dfg
+        nbd = dbd
+      end
+
+      ncd = color_diff(background, nfg)
+
+      break if nbd >= @minimum_brightness_diff and ncd >= @minimum_color_diff
+    end
+    nfg
+  end
+
+  # 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] suggest that this
+  # value be at least approximately 0.49 (125 / 255.0) for proper contrast.
+  def brightness_diff(c1, c2)
+    (c1.brightness - c2.brightness).abs
+  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
+  # 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
+    b = (c1.b - c2.b).abs
+    r + g + b
+  end
+end