color 1.5.1 → 1.6

checksums.yaml

@@ -1,15 +1,15 @@
 ---
 !binary "U0hBMQ==":
   metadata.gz: !binary |-
-    YjQwMTIxMzBkMGIzMmI2YmJjOWMwODE3ZDU5ZTlhYTFlNGM2YmQ0Zg==
+    NzUzZTAyZmI4OGRlNmJlZWJiZDdhZDk5NmFhNDFiNGU4ZjNmMTQxNA==
   data.tar.gz: !binary |-
-    M2VjNGUwNmFmOWRhMzQzZjA3OWZhMTM2MDgxYzcxMzc4NjYzOTZlZQ==
+    YzJhMDQ1ZjdkYjgzNWM3YzFhNWYzYzAwMTkwOTViZjUzZDhhOGRmMQ==
 SHA512:
   metadata.gz: !binary |-
-    MmYzNTFkZWZjYWM1ZTAxNjJhYzZkMTk0NGE2OTU5MTBiOGM1NWY4Mzg3NDA1
-    MmVjMjEzOTYzYzVkMGNkOGRmNDY0MTM0YmI0ZDc3YTYxMDAxMzE1OGZhNTNh
-    NmU4Y2Q5ZTY2ZjA1NDMwZThmYTA1ZDNjNTkzZTMzOGEwMzJlYmE=
+    NmQxOWEyNjJiZTJiNWQ1YzUxNGQzMzQ3MDhiYmI4MGRlN2Y1ZDg1OGIyNGY2
+    NGRmYzA1YTI5YmExZTYzNTAzMDFkOTIxNTYyYTliZGJlN2IwYzU2OWZiYjMz
+    YWMyNWViNWE5M2RiZGFmYzk1NDk2MzExZDk0NmI4YzVjNTg3NGM=
   data.tar.gz: !binary |-
-    NWIxY2I2NTVjN2RjZDQwMTc5NjQwZDRhODM5MmMwODJiMDQwMGNmM2M4Yzk3
-    ZDUxMzJhYjE1ODA3ZGY3NTZmMzJkODg0MmNjZTI2NzA5NjcxZjcxNTYzMzk2
-    YWQyZGQ3Y2RmY2RkOTc0NzkzMTYxODI1Mzg4MzA5MDA3YjEyYjQ=
+    ODkwMWY4NWNjMTRlMWJiOWY0ZjM0NzE0NjY2MDIwNWU0N2E5NjQxMmM1YTJi
+    MDFiZjYzMzY0MzBhOTZhYjk5MTVkOGRiYmIwNTdjNDQ3MWU2NmE5MTZkMjhh
+    MWYzMDk5YzY3NzA1OGQzZjg0OGNiYWRmZWJiOTNkOWI0YmM0NzM=

data/.autotest

@@ -0,0 +1,5 @@
+# -*- ruby encoding: utf-8 -*-
+
+Autotest.add_hook :initialize do |at|
+  at.testlib = ".minitest"
+end

data/.minitest.rb

@@ -0,0 +1,2 @@
+gem "minitest"
+require "minitest/autorun"

data/.travis.yml

@@ -0,0 +1,35 @@
+---
+language: ruby
+rvm:
+  - 2.1.0
+  - 2.0.0
+  - 1.9.3
+  - jruby-19mode
+  - rbx-2
+  - 1.8.7
+  - jruby-18mode
+  - ree
+  - ruby-head
+  - jruby-head
+matrix:
+  allow_failures:
+    - rvm: rbx-2
+gemfile:
+  - Gemfile
+before_script:
+  - |
+    case "${TRAVIS_RUBY_VERSION}" in
+      rbx*)
+        gem install psych
+        ;;
+    esac
+  - rake travis:before -t
+script: rake travis
+after_script:
+  - rake travis:after -t
+notifications:
+  email:
+    recipients:
+      - austin@rubyforge.org
+    on_success: change
+    on_failure: always

data/Contributing.rdoc

@@ -55,3 +55,6 @@ Here's the most direct way to get your work merged into the project:
 
 * Austin Ziegler created color-tools.
 * Matt Lyons created color.
+* Dave Heitzman (contrast comparison)
+* Thomas Sawyer
+* Aaron Hill (CIE94 colour matching)

data/Gemfile

@@ -0,0 +1,9 @@
+# -*- ruby -*-
+
+# NOTE: This file is present to keep Travis CI happy. Edits to it will not
+# be accepted.
+
+source "https://rubygems.org/"
+gemspec
+
+# vim: syntax=ruby

data/History.rdoc

@@ -1,3 +1,21 @@
+== 1.6 / 2014-05-19
+
+* Major enhancements:
+  * Aaron Hill (@armahillo) implemented the CIE Delta E 94 method by which an
+    RGB colour can be asked for the closest matching colour from a list of
+    provided colours. Fixes #5.
+  * To implement #closest_match and #delta_e94, conversion methods for sRGB to
+    XYZ and XYZ to L*a*b* space were implemented. These should be considered
+    experimental.
+
+* Tooling fixes:
+  * Ensured that the gem manifest was up-to-date. Fixes #4 reported by @boutil.
+    Thanks!
+  * Fixed problems with Travis builds. Note that Ruby 1.9.2 is no longer
+    tested. Rubinius remains in a “failure-tolerated” mode.
+  * Color 1.6 is, barring security patches, the last release of Color that will
+    support Ruby 1.8.
+
 == 1.5.1 / 2014-01-28
 
 * color 1.5 was a yanked release.

data/Licence.rdoc

@@ -2,7 +2,7 @@
 
 This software is available under an MIT-style licence.
 
-* Copyright 2005–2013 Austin Ziegler, Matt Lyon, and other contributors
+* Copyright 2005–2014 Austin Ziegler, Matt Lyon, and other contributors
 
 Permission is hereby granted, free of charge, to any person obtaining a copy of
 this software and associated documentation files (the "Software"), to deal in

data/Manifest.txt

@@ -1,4 +1,10 @@
+.autotest
+.gemtest
 .hoerc
+.minitest.rb
+.travis.yml
+Contributing.rdoc
+Gemfile
 History.rdoc
 Licence.rdoc
 Manifest.txt
@@ -13,10 +19,12 @@ lib/color/palette.rb
 lib/color/palette/adobecolor.rb
 lib/color/palette/gimp.rb
 lib/color/palette/monocontrast.rb
-lib/color/rgb/colors.rb
 lib/color/rgb.rb
+lib/color/rgb/colors.rb
+lib/color/rgb/contrast.rb
 lib/color/rgb/metallic.rb
 lib/color/yiq.rb
+test/minitest_helper.rb
 test/test_adobecolor.rb
 test/test_cmyk.rb
 test/test_color.rb

data/README.rdoc

@@ -4,8 +4,8 @@ home :: http://color.rubyforge.org
 code :: https://github.com/halostatue/color
 bugs :: https://github.com/halostatue/color/issues
 rdoc :: http://rubydoc.info/github/halostatue/color
-code climate :: {<img src="https://codeclimate.com/github/halostatue/color.png" />}[https://codeclimate.com/github/halostatue/color]
 continuous integration :: {<img src="https://travis-ci.org/halostatue/color.png" />}[https://travis-ci.org/halostatue/color]
+test coverage :: {<img src="https://coveralls.io/repos/halostatue/color/badge.png" alt="Coverage Status" />}[https://coveralls.io/r/halostatue/color]
 
 == Description
 
@@ -15,28 +15,20 @@ named RGB colours (184 with spelling variations) that are commonly supported in
 HTML, SVG, and X11 applications. A technique for generating monochromatic
 contrasting palettes is also included.
 
-The capabilities of the Color library are limited to pure mathematical
-manipulation of the colours based on colour theory without reference to colour
-profiles (such as sRGB or Adobe RGB). For most purposes, when working with the
-RGB and HSL colours, this won't matter. However, some colour models (like CIE
-L*a*b*) are not supported because Color does not yet support colour profiles,
-giving no meaningful way to convert colours in absolute colour spaces (like
-L*a*b*, XYZ) to non-absolute colour spaces (like RGB).
+The Color library performs purely mathematical manipulation of the colours
+based on colour theory without reference to colour profiles (such as sRGB or
+Adobe RGB). For most purposes, when working with RGB and HSL colour spaces,
+this won't matter. Absolute colour spaces (like CIE L*a*b* and XYZ) and cannot
+be reliably converted to relative colour spaces (like RGB) without colour
+profiles.
 
-Color version 1.5.1 is mostly a maintenance release, fixing some bugs that may
-have been introduced with the previous release on Ruby 1.8.7. New features
-include an experimental contrast comparison method for RGB colours (found in
-lib/color/rgb/contrast.rb) provided by Dave Heitzman, and methods suggested by
-Thomas Sawyer based on the Spectrum library.
+Color version 1.6 primarily adds a colour matching method for RGB and
+experimental CIE L*a*b* and XYZ conversion methods for use with the colour
+matching method.
 
-Barring bugs introduced in this release, this will be the last version of color
-that supports Ruby 1.8, so make sure that your gem specification is set
-properly, to <tt>~> 1.5</tt> if that matters for your application.
-
-=== Note about color 1.5
-
-Color 1.5 was released before the documetation was complete and has been
-yanked.
+Barring bugs introduced in this release, this is the last version of color that
+supports Ruby 1.8, so make sure that your gem specification is set properly (to
+<tt>~> 1.6</tt>) if that matters for your application.
 
 == History
 

data/Rakefile

@@ -8,24 +8,20 @@ Hoe.plugin :email
 Hoe.plugin :gemspec2
 Hoe.plugin :git
 Hoe.plugin :minitest
-Hoe.plugin :rubyforge
 Hoe.plugin :travis
+Hoe.plugin :email unless ENV['CI'] or ENV['TRAVIS']
 
 spec = Hoe.spec 'color' do
-  developer('Austin Ziegler', 'austin@rubyforge.org')
+  developer('Austin Ziegler', 'halostatue@gmail.com')
   developer('Matt Lyon', 'matt@postsomnia.com')
 
-  self.need_tar = true
-
-  # self.require_ruby_version '>= 1.9.2'
+  license 'MIT'
 
-  self.remote_rdoc_dir = '.'
-  self.rsync_args << ' --exclude=statsvn/'
+  self.need_tar = true
 
   self.history_file = 'History.rdoc'
   self.readme_file = 'README.rdoc'
   self.extra_rdoc_files = FileList["*.rdoc"].to_a
-  self.licenses = ["MIT"]
 
   self.extra_dev_deps << ['hoe-doofus', '~> 1.0']
   self.extra_dev_deps << ['hoe-gemspec2', '~> 1.1']
@@ -34,16 +30,36 @@ spec = Hoe.spec 'color' do
   self.extra_dev_deps << ['hoe-travis', '~> 1.2']
   self.extra_dev_deps << ['minitest', '~> 5.0']
   self.extra_dev_deps << ['rake', '~> 10.0']
+
+  if RUBY_VERSION >= '1.9' and (ENV['CI'] or ENV['TRAVIS'])
+    self.extra_dev_deps << ['simplecov', '~> 0.7']
+    self.extra_dev_deps << ['coveralls', '~> 0.7']
+  end
 end
 
-namespace :test do
-  desc "Runs test coverage. Only works Ruby 1.9+ and assumes 'simplecov' is installed."
-  task :coverage do
-    spec.test_prelude = [
-      'require "simplecov"',
-      'SimpleCov.start("test_frameworks") { command_name "Minitest" }',
-      'gem "minitest"'
-    ].join('; ')
-    Rake::Task['test'].execute
+if RUBY_VERSION >= '1.9'
+  namespace :test do
+    desc "Submit test coverage to Coveralls"
+    task :coveralls do
+      spec.test_prelude = [
+        'require "psych"',
+        'require "simplecov"',
+        'require "coveralls"',
+        'SimpleCov.formatter = Coveralls::SimpleCov::Formatter',
+      ].join('; ')
+      Rake::Task['test'].execute
+    end
+
+    desc "Runs test coverage. Only works Ruby 1.9+ and assumes 'simplecov' is installed."
+    task :coverage do
+      spec.test_prelude = [
+        'require "simplecov"',
+        'SimpleCov.start("test_frameworks") { command_name "Minitest" }',
+        'gem "minitest"'
+      ].join('; ')
+      Rake::Task['test'].execute
+    end
   end
+
+  Rake::Task['travis'].prerequisites.replace(%w(test:coveralls))
 end

data/lib/color.rb

@@ -3,7 +3,7 @@
 
 # = Colour Management with Ruby
 module Color
-  COLOR_VERSION = '1.5.1'
+  COLOR_VERSION = '1.6'
 
   class RGB; end
   class CMYK; end

data/lib/color/rgb.rb

@@ -7,102 +7,6 @@ class Color::RGB
   # PDF::Writer package.
   PDF_FORMAT_STR  = "%.3f %.3f %.3f %s"
 
-  class << self
-    # Creates an RGB colour object from percentages 0..100.
-    #
-    #   Color::RGB.from_percentage(10, 20 30)
-    def from_percentage(r = 0, g = 0, b = 0, &block)
-      new(r, g, b, 100.0, &block)
-    end
-
-    # Creates an RGB colour object from fractional values 0..1.
-    #
-    #   Color::RGB.from_fraction(.3, .2, .1)
-    def from_fraction(r = 0.0, g = 0.0, b = 0.0, &block)
-      new(r, g, b, 1.0, &block)
-    end
-
-    # Creates an RGB colour object from a grayscale fractional value 0..1.
-    def from_grayscale_fraction(l = 0.0, &block)
-      new(l, l, l, 1.0, &block)
-    end
-    alias_method :from_greyscale_fraction, :from_grayscale_fraction
-
-    # Creates an RGB colour object from an HTML colour descriptor (e.g.,
-    # <tt>"fed"</tt> or <tt>"#cabbed;"</tt>.
-    #
-    #   Color::RGB.from_html("fed")
-    #   Color::RGB.from_html("#fed")
-    #   Color::RGB.from_html("#cabbed")
-    #   Color::RGB.from_html("cabbed")
-    def from_html(html_colour, &block)
-      # When we can move to 1.9+ only, this will be \h
-      h = html_colour.scan(/[0-9a-f]/i)
-      case h.size
-      when 3
-        new(*h.map { |v| (v * 2).to_i(16) }, &block)
-      when 6
-        new(*h.each_slice(2).map { |v| v.join.to_i(16) }, &block)
-      else
-        raise ArgumentError, "Not a supported HTML colour type."
-      end
-    end
-
-    # Find or create a colour by an HTML hex code. This differs from the
-    # #from_html method in that if the colour code matches a named colour,
-    # the existing colour will be returned.
-    #
-    #     Color::RGB.by_hex('ff0000').name # => 'red'
-    #     Color::RGB.by_hex('ff0001').name # => nil
-    #
-    # If a block is provided, the value that is returned by the block will
-    # be returned instead of the exception caused by an error in providing a
-    # correct hex format.
-    def by_hex(hex, &block)
-      __by_hex.fetch(html_hexify(hex)) { from_html(hex) }
-    rescue
-      if block
-        block.call
-      else
-        raise
-      end
-    end
-
-    # Return a colour as identified by the colour name.
-    def by_name(name, &block)
-      __by_name.fetch(name.to_s.downcase, &block)
-    end
-
-    # Return a colour as identified by the colour name, or by hex.
-    def by_css(name_or_hex, &block)
-      by_name(name_or_hex) { by_hex(name_or_hex, &block) }
-    end
-
-    # Extract named or hex colours from the provided text.
-    def extract_colors(text, mode = :both)
-      text  = text.downcase
-      regex = case mode
-              when :name
-                Regexp.union(__by_name.keys)
-              when :hex
-                Regexp.union(__by_hex.keys)
-              when :both
-                Regexp.union(__by_hex.keys + __by_name.keys)
-              end
-
-      text.scan(regex).map { |match|
-        case mode
-        when :name
-          by_name(match)
-        when :hex
-          by_hex(match)
-        when :both
-          by_css(match)
-        end
-      }
-    end
-  end
-
   # Coerces the other Color object into RGB.
   def coerce(other)
     other.to_rgb
@@ -269,6 +173,78 @@ class Color::RGB
     Color::HSL.from_fraction(hue, sat, lum)
   end
 
+  # Returns the XYZ colour encoding of the value. Based on the
+  # {RGB to XYZ}[http://www.brucelindbloom.com/index.html?Eqn_RGB_to_XYZ.html]
+  # formula presented by Bruce Lindbloom.
+  #
+  # Currently only the sRGB colour space is supported.
+  def to_xyz(color_space = :sRGB)
+    unless color_space.to_s.downcase == 'srgb'
+      raise ArgumentError, "Unsupported colour space #{color_space}."
+    end
+
+    # Inverse sRGB companding. Linearizes RGB channels with respect to
+    # energy.
+    r, g, b = [ @r, @g, @b ].map { |v|
+      if (v > 0.04045)
+        (((v + 0.055) / 1.055) ** 2.4) * 100
+      else
+        (v / 12.92) * 100
+      end
+    }
+
+    # Convert using the RGB/XYZ matrix at:
+    # http://www.brucelindbloom.com/index.html?Eqn_RGB_XYZ_Matrix.html#WSMatrices
+    {
+      :x => (r * 0.4124564 + g * 0.3575761 + b * 0.1804375),
+      :y => (r * 0.2126729 + g * 0.7151522 + b * 0.0721750),
+      :z => (r * 0.0193339 + g * 0.1191920 + b * 0.9503041)
+    }
+  end
+
+  # Returns the L*a*b* colour encoding of the value via the XYZ colour
+  # encoding. Based on the
+  # {XYZ to Lab}[http://www.brucelindbloom.com/index.html?Eqn_XYZ_to_Lab.html]
+  # formula presented by Bruce Lindbloom.
+  #
+  # Currently only the sRGB colour space is supported and defaults to using
+  # a D65 reference white.
+  def to_lab(color_space = :sRGB, reference_white = [ 95.047, 100.00, 108.883 ])
+    xyz = to_xyz
+
+    # Calculate the ratio of the XYZ values to the reference white.
+    # http://www.brucelindbloom.com/index.html?Equations.html
+    xr = xyz[:x] / reference_white[0]
+    yr = xyz[:y] / reference_white[1]
+    zr = xyz[:z] / reference_white[2]
+
+    # NOTE: This should be using Rational instead of floating point values,
+    # otherwise there will be discontinuities.
+    # http://www.brucelindbloom.com/LContinuity.html
+    epsilon = (216 / 24389.0)
+    kappa   = (24389 / 27.0)
+
+    # And now transform
+    # http://en.wikipedia.org/wiki/Lab_color_space#Forward_transformation
+    # There is a brief explanation there as far as the nature of the calculations,
+    # as well as a much nicer looking modeling of the algebra.
+    fx, fy, fz = [ xr, yr, zr ].map { |t|
+      if (t > (epsilon))
+        t ** (1.0 / 3)
+      else # t <= epsilon
+        ((kappa * t) + 16) / 116.0
+        # The 4/29 here is for when t = 0 (black). 4/29 * 116 = 16, and 16 -
+        # 16 = 0, which is the correct value for L* with black.
+#       ((1.0/3)*((29.0/6)**2) * t) + (4.0/29)
+      end
+    }
+    {
+      :L => ((116 * fy) - 16),
+      :a => (500 * (fx - fy)),
+      :b => (200 * (fy - fz))
+    }
+  end
+
   # 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.
@@ -350,6 +326,117 @@ class Color::RGB
     hsl.to_rgb
   end
 
+  # TODO: Identify the base colour profile used for L*a*b* and XYZ
+  # conversions.
+
+  # Calculates and returns the closest match to this colour from a list of
+  # provided colours. Returns +nil+ if +color_list+ is empty or if there is
+  # no colour within the +threshold_distance+.
+  #
+  # +threshold_distance+ is used to determine the minimum colour distance
+  # permitted. Uses the CIE Delta E 1994 algorithm (CIE94) to find near
+  # matches based on perceived visual colour. The default value (1000.0) is
+  # an arbitrarily large number. The values <tt>:jnd</tt> and
+  # <tt>:just_noticeable</tt> may be passed as the +threshold_distance+ to
+  # use the value <tt>2.3</tt>.
+  def closest_match(color_list, threshold_distance = 1000.0)
+    color_list = [ color_list ].flatten(1)
+    return nil if color_list.empty?
+
+    threshold_distance = case threshold_distance
+                         when :jnd, :just_noticeable
+                           2.3
+                         else
+                           threshold_distance.to_f
+                         end
+    lab = to_lab
+    closest_distance = threshold_distance
+    best_match = nil
+
+    color_list.each do |c|
+      distance = delta_e94(lab, c.to_lab)
+      if (distance < closest_distance)
+        closest_distance = distance
+        best_match = c
+      end
+    end
+    best_match
+  end
+
+  # The Delta E (CIE94) algorithm
+  # http://en.wikipedia.org/wiki/Color_difference#CIE94
+  #
+  # There is a newer version, CIEDE2000, that uses slightly more complicated
+  # math, but addresses "the perceptual uniformity issue" left lingering by
+  # the CIE94 algorithm. color_1 and color_2 are both L*a*b* hashes,
+  # rendered by #to_lab.
+  #
+  # Since our source is treated as sRGB, we use the "graphic arts" presets
+  # for k_L, k_1, and k_2
+  #
+  # The calculations go through LCH(ab). (?)
+  #
+  # See also http://www.brucelindbloom.com/index.html?Eqn_DeltaE_CIE94.html
+  #
+  # NOTE: This should be moved to Color::Lab.
+  def delta_e94(color_1, color_2, weighting_type = :graphic_arts)
+    case weighting_type
+    when :graphic_arts
+      k_1 = 0.045
+      k_2 = 0.015
+      k_L = 1
+    when :textiles
+      k_1 = 0.048
+      k_2 = 0.014
+      k_L = 2
+    else
+      raise ArgumentError, "Unsupported weighting type #{weighting_type}."
+    end
+
+    # delta_E = Math.sqrt(
+    #   ((delta_L / (k_L * s_L)) ** 2) +
+    #   ((delta_C / (k_C * s_C)) ** 2) +
+    #   ((delta_H / (k_H * s_H)) ** 2)
+    # )
+    #
+    # Under some circumstances in real computers, delta_H could be an
+    # imaginary number (it's a square root value), so we're going to treat
+    # this as:
+    #
+    # delta_E = Math.sqrt(
+    #   ((delta_L / (k_L * s_L)) ** 2) +
+    #   ((delta_C / (k_C * s_C)) ** 2) +
+    #   (delta_H2 / ((k_H * s_H) ** 2)))
+    # )
+    #
+    # And not perform the square root when calculating delta_H2.
+
+    k_C = k_H = 1
+
+    l_1, a_1, b_1 = color_1.values_at(:L, :a, :b)
+    l_2, a_2, b_2 = color_2.values_at(:L, :a, :b)
+
+    delta_a = a_1 - a_2
+    delta_b = b_1 - b_2
+
+    c_1 = Math.sqrt((a_1 ** 2) + (b_1 ** 2))
+    c_2 = Math.sqrt((a_2 ** 2) + (b_2 ** 2))
+
+    delta_L = color_1[:L] - color_2[:L]
+    delta_C = c_1 - c_2
+
+    delta_H2 = (delta_a ** 2) + (delta_b ** 2) - (delta_C ** 2)
+
+    s_L = 1
+    s_C = 1 + k_1 * c_1
+    s_H = 1 + k_2 * c_1
+
+    composite_L = (delta_L / (k_L * s_L)) ** 2
+    composite_C = (delta_C / (k_C * s_C)) ** 2
+    composite_H = delta_H2 / ((k_H * s_H) ** 2)
+    Math.sqrt(composite_L + composite_C + composite_H)
+  end
+
   # Returns the red component of the colour in the normal 0 .. 255 range.
   def red
     @r * 255.0
@@ -454,7 +541,7 @@ class Color::RGB
   # Retrieve the maxmum RGB value from the current colour as a GrayScale
   # colour
   def max_rgb_as_grayscale
-      Color::GrayScale.from_fraction([@r, @g, @b].max)
+    Color::GrayScale.from_fraction([@r, @g, @b].max)
   end
   alias max_rgb_as_greyscale max_rgb_as_grayscale
 
@@ -486,6 +573,102 @@ class Color::RGB
   end
 end
 
+class << Color::RGB
+  # Creates an RGB colour object from percentages 0..100.
+  #
+  #   Color::RGB.from_percentage(10, 20, 30)
+  def from_percentage(r = 0, g = 0, b = 0, &block)
+    new(r, g, b, 100.0, &block)
+  end
+
+  # Creates an RGB colour object from fractional values 0..1.
+  #
+  #   Color::RGB.from_fraction(.3, .2, .1)
+  def from_fraction(r = 0.0, g = 0.0, b = 0.0, &block)
+    new(r, g, b, 1.0, &block)
+  end
+
+  # Creates an RGB colour object from a grayscale fractional value 0..1.
+  def from_grayscale_fraction(l = 0.0, &block)
+    new(l, l, l, 1.0, &block)
+  end
+  alias_method :from_greyscale_fraction, :from_grayscale_fraction
+
+  # Creates an RGB colour object from an HTML colour descriptor (e.g.,
+  # <tt>"fed"</tt> or <tt>"#cabbed;"</tt>.
+  #
+  #   Color::RGB.from_html("fed")
+  #   Color::RGB.from_html("#fed")
+  #   Color::RGB.from_html("#cabbed")
+  #   Color::RGB.from_html("cabbed")
+  def from_html(html_colour, &block)
+    # When we can move to 1.9+ only, this will be \h
+    h = html_colour.scan(/[0-9a-f]/i)
+    case h.size
+    when 3
+      new(*h.map { |v| (v * 2).to_i(16) }, &block)
+    when 6
+      new(*h.each_slice(2).map { |v| v.join.to_i(16) }, &block)
+    else
+      raise ArgumentError, "Not a supported HTML colour type."
+    end
+  end
+
+  # Find or create a colour by an HTML hex code. This differs from the
+  # #from_html method in that if the colour code matches a named colour,
+  # the existing colour will be returned.
+  #
+  #     Color::RGB.by_hex('ff0000').name # => 'red'
+  #     Color::RGB.by_hex('ff0001').name # => nil
+  #
+  # If a block is provided, the value that is returned by the block will
+  # be returned instead of the exception caused by an error in providing a
+  # correct hex format.
+  def by_hex(hex, &block)
+    __by_hex.fetch(html_hexify(hex)) { from_html(hex) }
+  rescue
+    if block
+      block.call
+    else
+      raise
+    end
+  end
+
+  # Return a colour as identified by the colour name.
+  def by_name(name, &block)
+    __by_name.fetch(name.to_s.downcase, &block)
+  end
+
+  # Return a colour as identified by the colour name, or by hex.
+  def by_css(name_or_hex, &block)
+    by_name(name_or_hex) { by_hex(name_or_hex, &block) }
+  end
+
+  # Extract named or hex colours from the provided text.
+  def extract_colors(text, mode = :both)
+    text  = text.downcase
+    regex = case mode
+            when :name
+              Regexp.union(__by_name.keys)
+            when :hex
+              Regexp.union(__by_hex.keys)
+            when :both
+              Regexp.union(__by_hex.keys + __by_name.keys)
+            end
+
+    text.scan(regex).map { |match|
+      case mode
+      when :name
+        by_name(match)
+      when :hex
+        by_hex(match)
+      when :both
+        by_css(match)
+      end
+    }
+  end
+end
+
 class << Color::RGB
   private
   def __named_color(mod, rgb, *names)

data/lib/color/rgb/contrast.rb

@@ -0,0 +1,57 @@
+# -*- ruby encoding: utf-8 -*-
+
+class Color::RGB
+  # Outputs how much contrast this color has with another RGB color.
+  # Computes the same regardless of which one is considered foreground. If
+  # the other color does not have a #to_rgb method, this will throw an
+  # exception. Anything over about 0.22 should have a high likelihood of
+  # being legible, but the larger the difference, the more contrast.
+  # Otherwise, to be safe go with something > 0.3
+  def contrast(other)
+    other = coerce(other)
+
+    # The following numbers have been set with some care.
+    ((diff_brightness(other) * 0.65) +
+     (diff_hue(other)        * 0.20) +
+     (diff_luminosity(other) * 0.15))
+  end
+
+  private
+  # Provides the luminosity difference between two rbg vals
+  def diff_luminosity(other)
+    other = coerce(other)
+    l1 = (0.2126 * (other.r) ** 2.2) +
+         (0.7152 * (other.b) ** 2.2) +
+         (0.0722 * (other.g) ** 2.2);
+
+    l2 = (0.2126 * (self.r) ** 2.2) +
+         (0.7152 * (self.b) ** 2.2) +
+         (0.0722 * (self.g) ** 2.2);
+
+    ((([l1, l2].max) + 0.05) / ( ([l1, l2].min) + 0.05 ) - 1) / 20.0
+  end
+
+  # Provides the brightness difference.
+  def diff_brightness(other)
+    other = other.to_rgb
+    br1 = (299 * other.r + 587 * other.g + 114 * other.b)
+    br2 = (299 * self.r + 587 * self.g + 114 * self.b)
+    (br1 - br2).abs / 1000.0;
+  end
+
+  # Provides the euclidean distance between the two color values
+  def diff_euclidean(other)
+    other = other.to_rgb
+    ((((other.r - self.r) ** 2) +
+      ((other.g - self.g) ** 2) +
+      ((other.b - self.b) ** 2)) ** 0.5) / 1.7320508075688772
+  end
+
+  # Difference in the two colors' hue
+  def diff_hue(other)
+    other = other.to_rgb
+    ((self.r - other.r).abs +
+     (self.g - other.g).abs +
+     (self.b - other.b).abs) / 3
+  end
+end

data/test/minitest_helper.rb

@@ -0,0 +1,6 @@
+# -*- ruby encoding: utf-8 -*-
+
+require 'color'
+
+gem 'minitest'
+require 'minitest/autorun'

data/test/test_rgb.rb

@@ -277,6 +277,47 @@ module TestColor
                    Color::RGB::Cayenne.to_yiq)
     end
 
+    def test_to_lab
+      # Luminosity can be an absolute.
+      assert_in_delta(0.0, Color::RGB::Black.to_lab[:L], Color::COLOR_TOLERANCE)
+      assert_in_delta(100.0, Color::RGB::White.to_lab[:L], Color::COLOR_TOLERANCE)
+
+      # It's not really possible to have absolute
+      # numbers here because of how L*a*b* works, but
+      # negative/positive comparisons work
+      assert(Color::RGB::Green.to_lab[:a] < 0)
+      assert(Color::RGB::Magenta.to_lab[:a] > 0)
+      assert(Color::RGB::Blue.to_lab[:b] < 0)
+      assert(Color::RGB::Yellow.to_lab[:b] > 0)
+    end
+
+    def test_closest_match
+      # It should match Blue to Indigo (very simple match)
+      match_from = [Color::RGB::Red, Color::RGB::Green, Color::RGB::Blue]
+      assert_equal(Color::RGB::Blue, Color::RGB::Indigo.closest_match(match_from))
+      # But fails if using the :just_noticeable difference.
+      assert_nil(Color::RGB::Indigo.closest_match(match_from, :just_noticeable))
+
+      # Crimson & Firebrick are visually closer than DarkRed and Firebrick
+      # (more precise match)
+      match_from += [Color::RGB::DarkRed, Color::RGB::Crimson]
+      assert_equal(Color::RGB::Crimson,
+                   Color::RGB::Firebrick.closest_match(match_from))
+      # Specifying a threshold low enough will cause even that match to
+      # fail, though.
+      assert_nil(Color::RGB::Firebrick.closest_match(match_from, 8.0))
+      # If the match_from list is an empty array, it also returns nil
+      assert_nil(Color::RGB::Red.closest_match([]))
+
+      # RGB::Green is 0,128,0, so we'll pick something VERY close to it, visually
+      jnd_green = Color::RGB.new(3, 132, 3)
+      assert_equal(Color::RGB::Green,
+                   jnd_green.closest_match(match_from, :jnd))
+      # And then something that's just barely out of the tolerance range
+      diff_green = Color::RGB.new(9, 142, 9)
+      assert_nil(diff_green.closest_match(match_from, :jnd))
+    end
+
     def test_add
       white = Color::RGB::Cyan + Color::RGB::Yellow
       refute_nil(white)

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: color
 version: !ruby/object:Gem::Version
-  version: 1.5.1
+  version: '1.6'
 platform: ruby
 authors:
 - Austin Ziegler
@@ -11,10 +11,10 @@ bindir: bin
 cert_chain:
 - !binary |-
   LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSUROakNDQWg2Z0F3SUJB
-  Z0lCQURBTkJna3Foa2lHOXcwQkFRVUZBREJCTVE4d0RRWURWUVFEREFaaGRY
+  Z0lCQVRBTkJna3Foa2lHOXcwQkFRVUZBREJCTVE4d0RRWURWUVFEREFaaGRY
   TjAKYVc0eEdUQVhCZ29Ka2lhSmsvSXNaQUVaRmdseWRXSjVabTl5WjJVeEV6
-  QVJCZ29Ka2lhSmsvSXNaQUVaRmdOdgpjbWN3SGhjTk1UTXdNakEwTURNek16
-  STNXaGNOTVRRd01qQTBNRE16TXpJM1dqQkJNUTh3RFFZRFZRUUREQVpoCmRY
+  QVJCZ29Ka2lhSmsvSXNaQUVaRmdOdgpjbWN3SGhjTk1UUXdNakl5TURNME1U
+  UXpXaGNOTVRVd01qSXlNRE0wTVRReldqQkJNUTh3RFFZRFZRUUREQVpoCmRY
   TjBhVzR4R1RBWEJnb0praWFKay9Jc1pBRVpGZ2x5ZFdKNVptOXlaMlV4RXpB
   UkJnb0praWFKay9Jc1pBRVoKRmdOdmNtY3dnZ0VpTUEwR0NTcUdTSWIzRFFF
   QkFRVUFBNElCRHdBd2dnRUtBb0lCQVFDMm1QTmY0TDM3R2hLSQpTUENZc3ZZ
@@ -25,19 +25,19 @@ cert_chain:
   Z3kxR1Z3VAppNnBrRHM4TGhaV1hkT0QrOTIxbDJaMU5aR1phOUtOYkpJZzZ2
   dGdZS1U5OGpRNXFyOWlZM2lrQkFzcEhyRmFzCks2VVN2R2dBZzhmQ0Q1WWlv
   dEJFdkNCTVl0ZnFtZnJocGRVMnArZ3ZUZ2VMVzFLYWV2d3FkN25nUW1GVXJG
-  RzEKZVVKU1VSdjVBZ01CQUFHak9UQTNNQWtHQTFVZEV3UUNNQUF3SFFZRFZS
-  ME9CQllFRkF0SktNcDZZWU5xbGdSMwo5VGlaTFdxdkxhZ1NNQXNHQTFVZER3
-  UUVBd0lFc0RBTkJna3Foa2lHOXcwQkFRVUZBQU9DQVFFQXBUUGt2RG04Cjdn
-  SmxVVDRGZnVtWFB2dHVxUDY3THhVdEdFOHN5dlIwQTRBcyswUC93eWxMSkZV
-  T3NHVFRkWll0VGhoeENTSkcKKzdLRzJGZkljSDRaejJkOTdhclpHQXpCb2k4
-  aVBodDIvVXRTbDFmQ2NVSTV2bUphMU1pWFpUMm9xZFc3V3lkcQpyQVpjQlBs
-  cllZdWl3dEdJMHlxSU9nQmZYU1pDV1dzSnN1eVRLRUxlcDZtQ0xnejBZWlVm
-  bXZLcjhXL0FiM2F4CkR1THpIOTJMU1JqWkp5anlBVXB3L1ZjMnJNNGdpaVA1
-  anRCeXJiMVkxZEduUWhIVE1IZjFHZnVjV203TncvVjkKdHdFUFZ3OCswZjg4
-  SlF1Y3hPVG1URjFOYkxGcGlSd1FVWjF6b1piTmcyZTdtU2hjL2VleG5WTFdL
-  Rkt4Um9QNgpLUGozV29EK3NwQjhmQT09Ci0tLS0tRU5EIENFUlRJRklDQVRF
+  RzEKZVVKU1VSdjVBZ01CQUFHak9UQTNNQWtHQTFVZEV3UUNNQUF3Q3dZRFZS
+  MFBCQVFEQWdTd01CMEdBMVVkRGdRVwpCQlFMU1NqS2VtR0RhcFlFZC9VNG1T
+  MXFyeTJvRWpBTkJna3Foa2lHOXcwQkFRVUZBQU9DQVFFQU5tMmFnVGRECjlT
+  Mk53WE1XMGphbnNJblh0UW1CNDRxay9wc1d1anRHbm4rb1QrYTlLWE81cC9n
+  eDJtbXg4aE1GMDJ3VUJ4MUgKazk2SFVJL2pSM0hkaFlDZkc2b0p1RXpnWHJG
+  aVNCSncvY09KaU04djNhSHNBd0kzTmVMZUlyUndCWUIza0kzagoxcWZKWGNP
+  V3c3YzYzVHJzRFgzN3hqMmU0UDBETkoxY1RyRG15RDJ5VFE1Nzc2TTEzR2I2
+  blhqcmVTZXEwdC9uCjYwTmo5MUoxb0hZazZMRmEwZW8vZ3lrVGJMeWFacnNh
+  WGxOYjNqN0NqaFV6T3BZT2hpQ1VIM3M5dEtUR1hkLysKTG1aN0J4VE1zRGha
+  SHkzay9FVEZoaSs3cElVV2xGbzBpbXJkeUxoZCtKdzNib1ZqM0NtdnloY3dt
+  cG9NMEs5bApBT21yVWlFbFVxTE9aQT09Ci0tLS0tRU5EIENFUlRJRklDQVRF
   LS0tLS0K
-date: 2014-01-28 00:00:00.000000000 Z
+date: 2014-05-20 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: minitest
@@ -45,28 +45,14 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '5.2'
+        version: '5.3'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '5.2'
-- !ruby/object:Gem::Dependency
-  name: rubyforge
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 2.0.4
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ! '>='
-      - !ruby/object:Gem::Version
-        version: 2.0.4
+        version: '5.3'
 - !ruby/object:Gem::Dependency
   name: rdoc
   requirement: !ruby/object:Gem::Requirement
@@ -171,14 +157,14 @@ dependencies:
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.8'
+        version: '3.12'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ~>
       - !ruby/object:Gem::Version
-        version: '3.8'
+        version: '3.12'
 description: ! 'Color is a Ruby library to provide basic RGB, CMYK, HSL, and other
   colourspace
 
@@ -191,52 +177,50 @@ description: ! 'Color is a Ruby library to provide basic RGB, CMYK, HSL, and oth
   contrasting palettes is also included.
 
 
-  The capabilities of the Color library are limited to pure mathematical
-
-  manipulation of the colours based on colour theory without reference to colour
-
-  profiles (such as sRGB or Adobe RGB). For most purposes, when working with the
+  The Color library performs purely mathematical manipulation of the colours
 
-  RGB and HSL colours, this won''t matter. However, some colour models (like CIE
+  based on colour theory without reference to colour profiles (such as sRGB or
 
-  L*a*b*) are not supported because Color does not yet support colour profiles,
+  Adobe RGB). For most purposes, when working with RGB and HSL colour spaces,
 
-  giving no meaningful way to convert colours in absolute colour spaces (like
+  this won''t matter. Absolute colour spaces (like CIE L*a*b* and XYZ) and cannot
 
-  L*a*b*, XYZ) to non-absolute colour spaces (like RGB).
+  be reliably converted to relative colour spaces (like RGB) without colour
 
+  profiles.
 
-  Color version 1.5.1 is mostly a maintenance release, fixing some bugs that may
 
-  have been introduced with the previous release on Ruby 1.8.7. New features
+  Color version 1.6 primarily adds a colour matching method for RGB and
 
-  include an experimental contrast comparison method for RGB colours (found in
+  experimental CIE L*a*b* and XYZ conversion methods for use with the colour
 
-  lib/color/rgb/contrast.rb) provided by Dave Heitzman, and methods suggested by
+  matching method.
 
-  Thomas Sawyer based on the Spectrum library.
 
+  Barring bugs introduced in this release, this is the last version of color that
 
-  Barring bugs introduced in this release, this will be the last version of color
+  supports Ruby 1.8, so make sure that your gem specification is set properly (to
 
-  that supports Ruby 1.8, so make sure that your gem specification is set
-
-  properly, to <tt>~> 1.5</tt> if that matters for your application.'
+  <tt>~> 1.6</tt>) if that matters for your application.'
 email:
-- austin@rubyforge.org
+- halostatue@gmail.com
 - matt@postsomnia.com
 executables: []
 extensions: []
 extra_rdoc_files:
+- Contributing.rdoc
 - History.rdoc
 - Licence.rdoc
 - Manifest.txt
 - README.rdoc
-- Contributing.rdoc
 files:
+- .autotest
 - .gemtest
 - .hoerc
+- .minitest.rb
+- .travis.yml
 - Contributing.rdoc
+- Gemfile
 - History.rdoc
 - Licence.rdoc
 - Manifest.txt
@@ -253,8 +237,10 @@ files:
 - lib/color/palette/monocontrast.rb
 - lib/color/rgb.rb
 - lib/color/rgb/colors.rb
+- lib/color/rgb/contrast.rb
 - lib/color/rgb/metallic.rb
 - lib/color/yiq.rb
+- test/minitest_helper.rb
 - test/test_adobecolor.rb
 - test/test_cmyk.rb
 - test/test_color.rb
@@ -286,7 +272,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: color
+rubyforge_project: 
 rubygems_version: 2.2.1
 signing_key: 
 specification_version: 4