threedaymonk-colormath 0.1.0

data/README.md

@@ -0,0 +1,42 @@
+ColorMath
+=========
+
+A simple Ruby library to perform operations on RGB and HSL colours.
+
+Usage
+-----
+
+Instantiate an RGB (red, green, blue) colour:
+
+    orange = ColorMath::RGB.new(1.0, 0.5, 0)
+
+Or from a hex value via a helper method:
+
+    white  = ColorMath::hex_color("#fff")
+    blue   = ColorMath::hex_color("#0000ff")
+
+Instantiate an HSL (hue, saturation, luminance) colour:
+
+    pink   = ColorMath::HSL.new(350, 1, 0.88)
+
+Retrieve the RGB components of a colour:
+
+    pink.red    # => 1.0
+    pink.green  # => 0.76
+    pink.blue   # => 0.8
+
+Or the HSL components:
+
+    orange.hue         # => 30.0
+    orange.saturation  # =>  1.0
+    orange.luminance   # =>  0.5
+
+Combine two colours via an alpha blend, e.g. 30% orange on white:
+
+    combined = ColorMath::Blend.alpha(white, orange, 0.3)
+
+Convert a colour to hexadecimal representation:
+
+    combined.hex  # => "#ffd8b2"
+
+That’s it. It only does the basics that I need for the job in hand, but it’s probably a good basis for extension.

data/lib/colormath.rb

@@ -0,0 +1,28 @@
+module ColorMath
+  ParsingError = Class.new(RuntimeError)
+
+  # Instantiate an RGB colour from a 3- or 6-digit hexadecimal representation.
+  # "#abc", "#abcdef", "abc", and "abcdef" are all valid.
+  #
+  # Invalid representations will raise a ParsingError.
+  #
+  def hex_color(s)
+    if m = s.match(/^#?([0-9a-f]{2})([0-9a-f]{2})([0-9a-f]{2})$/i)
+      RGB.new( m[1].to_i(16) / 255.0,
+               m[2].to_i(16) / 255.0,
+               m[3].to_i(16) / 255.0 )
+    elsif m = s.match(/^#?([0-9a-f])([0-9a-f])([0-9a-f])$/i)
+      RGB.new( (m[1] + m[1]).to_i(16) / 255.0,
+               (m[2] + m[2]).to_i(16) / 255.0,
+               (m[3] + m[3]).to_i(16) / 255.0 )
+    else
+      raise ParsingError, "invalid hex sequence '#{s}'"
+    end
+  end
+
+  extend self
+end
+
+require "colormath/color"
+require "colormath/blend"
+require "colormath/version"

data/lib/colormath/blend.rb

@@ -0,0 +1,23 @@
+module ColorMath
+
+  # Blend two or more colours and return a new colour.
+  #
+  module Blend
+
+    # Blend ca with cb. alpha represents the proportion of cb,
+    # i.e. alpha = 0 => ca; alpha = 1 => cb.
+    #
+    def alpha(ca, cb, alpha)
+      for_rgb(ca, cb){ |a, b| (alpha * b + (1 - alpha) * a) }
+    end
+
+    extend self
+
+  private
+    def for_rgb(a, b, &blk)
+      RGB.new(*([:red, :green, :blue].map{ |channel|
+        blk.call(a.__send__(channel), b.__send__(channel))
+      }))
+    end
+  end
+end

data/lib/colormath/color.rb

@@ -0,0 +1,36 @@
+module ColorMath
+
+  # Color can be mixed into any class that responds to red, green, and blue, where 0 <= c <= 1
+  #
+  module Color
+    EPSILON = 1/256.0
+
+    # Returns true if the RGB components of the two colours differ by less than EPSILON,
+    # i.e. they are the same when represented in 8 bits.
+    #
+    def ==(other)
+      deltas = [ other.red   - self.red,
+                 other.green - self.green,
+                 other.blue  - self.blue ].map{ |e| e.abs }
+      deltas.max < EPSILON
+    end
+
+    # The six-digit hexadecimal representation of the colour, e.g. "#cafe66"
+    #
+    def hex
+      "#%02x%02x%02x" % [red * 0xff, green * 0xff, blue * 0xff]
+    end
+
+    def inspect(*args)
+      "<%s r=%0.3f g=%0.3f b=%0.3f>" % [self.class.to_s, red, green, blue]
+    end
+
+  private
+    def force_range(v, min, max)
+      [[min, v].max, max].min
+    end
+  end
+end
+
+require "colormath/color/rgb"
+require "colormath/color/hsl"

data/lib/colormath/color/hsl.rb

@@ -0,0 +1,78 @@
+module ColorMath
+
+  # A colour represented and stored as hue, saturation and luminance components
+  #
+  class HSL
+    include Color
+
+    attr_reader :hue, :saturation, :luminance, :alpha
+
+    # Initialize an HSL colour where:
+    #     0 <= h <= 360
+    #     0 <= s <=   1
+    #     0 <= l <=   1
+    #
+    # Values outside these ranges will be clippped.
+    #
+    def initialize(h, s, l)
+      @hue        = force_range(h, 0, 360).to_f
+      @saturation = force_range(s, 0,   1).to_f
+      @luminance  = force_range(l, 0,   1).to_f
+    end
+
+    # The red component of the colour in RGB representation where 0 <= r <= 1
+    #
+    def red
+      t = component(hk + (1/3.0))
+    end
+
+    # The green component of the colour in RGB representation where 0 <= g <= 1
+    #
+    def green
+      t = component(hk)
+    end
+
+    # The blue component of the colour in RGB representation where 0 <= b <= 1
+    #
+    def blue
+      t = component(hk - (1/3.0))
+    end
+
+  private
+    def hk
+      hue / 360.0
+    end
+
+    def q
+      @q ||= if luminance < 0.5
+        luminance * (1.0 + saturation)
+      else
+        luminance + saturation - (luminance * saturation)
+      end
+    end
+
+    def p
+      @p ||= 2 * luminance - q
+    end
+
+    def component(t)
+      t = if t < 0
+        t + 1.0
+      elsif t > 1
+        t - 1.0
+      else
+        t
+      end
+
+      if t < (1/6.0)
+        p + ((q - p) * 6.0 * t)
+      elsif (1/6.0) <= t && t < 0.5
+        q
+      elsif 0.5 <= t && t < (2/3.0)
+        p + ((q - p) * 6.0 * (2/3.0 - t))
+      else
+        p
+      end
+    end
+  end
+end

data/lib/colormath/color/rgb.rb

@@ -0,0 +1,63 @@
+module ColorMath
+
+  # A colour represented and stored as red, green and blue components
+  #
+  class RGB
+    include Color
+
+    attr_reader :red, :green, :blue
+
+    # Initialize an RGB colour where:
+    #     0 <= r <= 1
+    #     0 <= g <= 1
+    #     0 <= b <= 1
+    #
+    # Values outside these ranges will be clippped.
+    #
+    def initialize(r, g, b)
+      @red   = force_range(r, 0, 1).to_f
+      @green = force_range(g, 0, 1).to_f
+      @blue  = force_range(b, 0, 1).to_f
+    end
+
+    # The hue component of the colour in HSL representation where 0 <= h < 360
+    #
+    def hue
+      case max
+      when red
+        (60.0 * ((green - blue) / (max - min))) % 360.0
+      when green
+        60.0 * ((blue - red) / (max - min)) + 120.0
+      when blue
+        60.0 * ((red - green) / (max - min)) + 240.0
+      end
+    end
+
+    # The saturation component of the colour in HSL representation where 0 <= s <= 1
+    #
+    def saturation
+      if max == min
+        0
+      elsif luminance <= 0.5
+        (max - min) / (2.0 * luminance)
+      else
+        (max - min) / (2.0 - 2.0 * luminance)
+      end
+    end
+
+    # The luminance component of the colour in HSL representation where 0 <= l <= 1
+    #
+    def luminance
+      0.5 * (max + min)
+    end
+
+  private
+    def min
+      [red, green, blue].min
+    end
+
+    def max
+      [red, green, blue].max
+    end
+  end
+end

data/lib/colormath/version.rb

@@ -0,0 +1,9 @@
+module ColorMath
+  module VERSION #:nodoc:
+    MAJOR = 0
+    MINOR = 1
+    TINY  = 0
+
+    STRING = [MAJOR, MINOR, TINY].join('.')
+  end
+end

data/test/blend_test.rb

@@ -0,0 +1,33 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require "test/unit"
+require "shoulda"
+require "colormath"
+
+class AlphaBlendTest < Test::Unit::TestCase
+  def blend(a, b, alpha)
+    ColorMath::Blend.alpha(ColorMath::hex_color(a), ColorMath::hex_color(b), alpha).hex
+  end
+
+  context "with sample colors" do
+    setup do
+      @background = "#ffffff"
+      @foreground = "#862e8b"
+    end
+
+    should "blend 0% sample" do
+      assert_equal @background, blend(@background, @foreground, 0.0)
+    end
+
+    should "blend 10% sample" do
+      assert_equal "#f2eaf3", blend(@background, @foreground, 0.1)
+    end
+
+    should "blend 30% sample" do
+      assert_equal "#dac0dc", blend(@background, @foreground, 0.3)
+    end
+
+    should "blend 100% sample" do
+      assert_equal @foreground, blend(@background, @foreground, 1.0)
+    end
+  end
+end

data/test/conversion_test.rb

@@ -0,0 +1,104 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require "test/unit"
+require "shoulda"
+require "colormath"
+
+class ConversionTest < Test::Unit::TestCase
+  EPSILON = 1e-2
+
+  EDGE_CASES = [
+    [[1,   0,   0], [  0, 1, 0.5 ]],
+    [[0.5, 1, 0.5], [120, 1, 0.75]],
+    [[0,   0, 0.5], [240, 1, 0.25]],
+  ]
+
+  context "with edge cases" do
+    EDGE_CASES.each do |(r,g,b), (h,s,l)|
+      should "convert RGB(#{r},#{g},#{b}) to HSL(#{h},#{s},#{l})" do
+        c = ColorMath::RGB.new(r, g, b)
+        assert_in_delta h, c.hue,        EPSILON
+        assert_in_delta s, c.saturation, EPSILON
+        assert_in_delta l, c.luminance,  EPSILON
+      end
+
+      should "convert HSL(#{h},#{s},#{l}) to RGB(#{r},#{g},#{b})" do
+        c = ColorMath::HSL.new(h, s, l)
+        assert_in_delta r, c.red,   EPSILON
+        assert_in_delta g, c.green, EPSILON
+        assert_in_delta b, c.blue,  EPSILON
+      end
+    end
+  end
+
+  HSL_SAMPLES = [
+    [267.0, 0.14, 0.17],
+    [322.0, 0.22, 0.54],
+    [211.0, 0.54, 0.19],
+    [347.0, 0.90, 0.38],
+    [184.0, 0.75, 0.13],
+    [177.0, 0.07, 0.14],
+    [ 97.0, 0.93, 0.70],
+    [139.0, 0.04, 0.37],
+    [ 17.0, 0.88, 0.67],
+    [162.0, 0.21, 0.61],
+    [358.0, 0.78, 0.50],
+    [104.0, 0.78, 0.63],
+    [280.0, 0.38, 0.66],
+    [298.0, 0.06, 0.72],
+    [162.0, 0.39, 0.86],
+    [305.0, 0.55, 0.16],
+    [248.0, 0.80, 0.84],
+    [109.0, 0.23, 0.23],
+    [328.0, 0.88, 0.88],
+    [ 26.0, 0.99, 0.52],
+  ]
+
+  context "roundtripping HSL -> RGB -> HSL" do
+    HSL_SAMPLES.each do |h,s,l|
+      should "roundtrip HSL(#{h},#{s},#{l})" do
+        hsl = ColorMath::HSL.new(h, s, l)
+        rgb = ColorMath::RGB.new(hsl.red, hsl.green, hsl.blue)
+
+        assert_in_delta h, rgb.hue,        EPSILON
+        assert_in_delta s, rgb.saturation, EPSILON
+        assert_in_delta l, rgb.luminance,  EPSILON
+      end
+    end
+  end
+
+  RGB_SAMPLES = [
+    [0.19, 0.41, 0.70],
+    [0.13, 0.22, 0.28],
+    [0.45, 0.44, 0.24],
+    [0.96, 0.94, 0.24],
+    [0.76, 0.01, 0.16],
+    [0.55, 0.96, 0.01],
+    [0.07, 0.61, 0.73],
+    [0.05, 0.58, 0.51],
+    [0.43, 0.05, 0.24],
+    [0.66, 0.80, 0.80],
+    [0.54, 0.35, 0.10],
+    [0.12, 0.41, 0.27],
+    [0.78, 0.32, 0.93],
+    [0.52, 0.15, 0.43],
+    [0.17, 0.26, 0.53],
+    [0.19, 0.96, 0.66],
+    [0.54, 0.36, 0.84],
+    [0.12, 0.89, 0.60],
+    [0.75, 0.03, 0.83],
+    [0.09, 0.35, 0.83],
+  ]
+
+  context "roundtripping RGB -> HSL -> RGB" do
+    RGB_SAMPLES.each do |r,g,b|
+      should "roundtrip RGB(#{r},#{g},#{b})" do
+        rgb = ColorMath::RGB.new(r, g, b)
+        hsl = ColorMath::HSL.new(rgb.hue, rgb.saturation, rgb.luminance)
+
+        assert_in_delta r, hsl.red,   EPSILON
+        assert_in_delta g, hsl.green, EPSILON
+        assert_in_delta b, hsl.blue,  EPSILON
+      end
+    end
+  end
+end

data/test/hex_decoding_test.rb

@@ -0,0 +1,56 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require "test/unit"
+require "shoulda"
+require "colormath"
+
+class HexDecodingTest < Test::Unit::TestCase
+  EPSILON = 1e-3
+
+  should "decode 6-digit hex string with leading #" do
+    c = ColorMath::hex_color("#abcd54")
+    assert_in_delta (0xab / 255.0), c.red,   EPSILON
+    assert_in_delta (0xcd / 255.0), c.green, EPSILON
+    assert_in_delta (0x54 / 255.0), c.blue,  EPSILON
+  end
+
+  should "decode 6-digit hex string without leading #" do
+    c = ColorMath::hex_color("abcd54")
+    assert_in_delta (0xab / 255.0), c.red,   EPSILON
+    assert_in_delta (0xcd / 255.0), c.green, EPSILON
+    assert_in_delta (0x54 / 255.0), c.blue,  EPSILON
+  end
+
+  should "decode 3-digit hex string with leading #" do
+    c = ColorMath::hex_color("#a1c")
+    assert_in_delta (0xaa / 255.0), c.red,   EPSILON
+    assert_in_delta (0x11 / 255.0), c.green, EPSILON
+    assert_in_delta (0xcc / 255.0), c.blue,  EPSILON
+  end
+
+  should "decode 3-digit hex string without leading #" do
+    c = ColorMath::hex_color("a1c")
+    assert_in_delta (0xaa / 255.0), c.red,   EPSILON
+    assert_in_delta (0x11 / 255.0), c.green, EPSILON
+    assert_in_delta (0xcc / 255.0), c.blue,  EPSILON
+  end
+
+  should "decode 6-digit hex string in upper case" do
+    c = ColorMath::hex_color("#ABCD54")
+    assert_in_delta (0xab / 255.0), c.red,   EPSILON
+    assert_in_delta (0xcd / 255.0), c.green, EPSILON
+    assert_in_delta (0x54 / 255.0), c.blue,  EPSILON
+  end
+
+  should "decode 3-digit hex string in upper case" do
+    c = ColorMath::hex_color("#A1C")
+    assert_in_delta (0xaa / 255.0), c.red,   EPSILON
+    assert_in_delta (0x11 / 255.0), c.green, EPSILON
+    assert_in_delta (0xcc / 255.0), c.blue,  EPSILON
+  end
+
+  should "raise a ParsingError when the hex string is invalid" do
+    assert_raises ColorMath::ParsingError do
+      ColorMath::hex_color("kjhhdfs")
+    end
+  end
+end

data/test/hsl_test.rb

@@ -0,0 +1,44 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require "test/unit"
+require "shoulda"
+require "colormath"
+
+class HSLTest < Test::Unit::TestCase
+  should "be equal if initialized with same values" do
+    assert_equal ColorMath::HSL.new(123, 0.5, 0.7), ColorMath::HSL.new(123, 0.5, 0.7)
+  end
+
+  should "not be equal if initialized with different values" do
+    assert_not_equal ColorMath::HSL.new(124, 0.4, 0.8), ColorMath::HSL.new(123, 0.5, 0.7)
+  end
+
+  should "force hue >= 0" do
+    c = ColorMath::HSL.new(-2, 0, 0)
+    assert_equal 0, c.hue
+  end
+
+  should "force hue <= 360" do
+    c = ColorMath::HSL.new(361, 0, 0)
+    assert_equal 360, c.hue
+  end
+
+  should "force saturation >= 0" do
+    c = ColorMath::HSL.new(0, -1, 0)
+    assert_equal 0, c.saturation
+  end
+
+  should "force saturation <= 1" do
+    c = ColorMath::HSL.new(0, 1.1, 0)
+    assert_equal 1, c.saturation
+  end
+
+  should "force luminance >= 0" do
+    c = ColorMath::HSL.new(0, 0, -1)
+    assert_equal 0, c.luminance
+  end
+
+  should "force luminance <= 1" do
+    c = ColorMath::HSL.new(0, 0, 1.1)
+    assert_equal 1, c.luminance
+  end
+end

data/test/rgb_test.rb

@@ -0,0 +1,44 @@
+$:.unshift(File.dirname(__FILE__) + '/../lib')
+require "test/unit"
+require "shoulda"
+require "colormath"
+
+class RGBTest < Test::Unit::TestCase
+  should "be equal if initialized with same values" do
+    assert_equal ColorMath::RGB.new(0.3, 0.5, 0.7), ColorMath::RGB.new(0.3, 0.5, 0.7)
+  end
+
+  should "not be equal if initialized with different values" do
+    assert_not_equal ColorMath::RGB.new(0.5, 0.4, 0.8), ColorMath::RGB.new(0.3, 0.5, 0.7)
+  end
+
+  should "force red >= 0" do
+    c = ColorMath::HSL.new(-2, 0, 0)
+    assert_equal 0, c.red
+  end
+
+  should "force red <= 1" do
+    c = ColorMath::RGB.new(1.1, 0, 0)
+    assert_equal 1, c.red
+  end
+
+  should "force green >= 0" do
+    c = ColorMath::RGB.new(0, -1, 0)
+    assert_equal 0, c.green
+  end
+
+  should "force green <= 1" do
+    c = ColorMath::RGB.new(0, 1.1, 0)
+    assert_equal 1, c.green
+  end
+
+  should "force blue >= 0" do
+    c = ColorMath::RGB.new(0, 0, -1)
+    assert_equal 0, c.blue
+  end
+
+  should "force blue <= 1" do
+    c = ColorMath::RGB.new(0, 0, 1.1)
+    assert_equal 1, c.blue
+  end
+end

metadata

@@ -0,0 +1,75 @@
+--- !ruby/object:Gem::Specification 
+name: threedaymonk-colormath
+version: !ruby/object:Gem::Version 
+  version: 0.1.0
+platform: ruby
+authors: 
+- Paul Battley
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-09-09 00:00:00 -07:00
+default_executable: 
+dependencies: 
+- !ruby/object:Gem::Dependency 
+  name: shoulda
+  type: :development
+  version_requirement: 
+  version_requirements: !ruby/object:Gem::Requirement 
+    requirements: 
+    - - ">="
+      - !ruby/object:Gem::Version 
+        version: "0"
+    version: 
+description: 
+email: pbattley@gmail.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: []
+
+files: 
+- README.md
+- test/blend_test.rb
+- test/conversion_test.rb
+- test/hex_decoding_test.rb
+- test/hsl_test.rb
+- test/rgb_test.rb
+- lib/colormath
+- lib/colormath/blend.rb
+- lib/colormath/color
+- lib/colormath/color/hsl.rb
+- lib/colormath/color/rgb.rb
+- lib/colormath/color.rb
+- lib/colormath/version.rb
+- lib/colormath.rb
+has_rdoc: false
+homepage: 
+post_install_message: 
+rdoc_options: []
+
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.2.0
+signing_key: 
+specification_version: 3
+summary: Colour manipulation library for Ruby
+test_files: []
+