kolors 0.0.1

data/.gitignore

@@ -0,0 +1,2 @@
+/pkg/
+/.DS_Store

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in kolors.gemspec
+gemspec

data/Gemfile.lock

@@ -0,0 +1,42 @@
+PATH
+  remote: .
+  specs:
+    kolors (0.0.1)
+      ai4r
+      cocaine
+      oily_png
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    activesupport (3.2.11)
+      i18n (~> 0.6)
+      multi_json (~> 1.0)
+    ai4r (1.12)
+    chunky_png (1.2.7)
+    climate_control (0.0.3)
+      activesupport (>= 3.0)
+    cocaine (0.5.1)
+      climate_control (>= 0.0.3, < 1.0)
+    diff-lcs (1.1.3)
+    i18n (0.6.1)
+    multi_json (1.5.0)
+    oily_png (1.0.3)
+      chunky_png (~> 1.2.1)
+    rake (10.0.3)
+    rspec (2.12.0)
+      rspec-core (~> 2.12.0)
+      rspec-expectations (~> 2.12.0)
+      rspec-mocks (~> 2.12.0)
+    rspec-core (2.12.2)
+    rspec-expectations (2.12.1)
+      diff-lcs (~> 1.1.3)
+    rspec-mocks (2.12.2)
+
+PLATFORMS
+  ruby
+
+DEPENDENCIES
+  kolors!
+  rake
+  rspec

data/LICENSE

@@ -0,0 +1,22 @@
+Copyright (c) 2013 Eric Larson
+
+MIT License
+
+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 the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,48 @@
+# Kolors
+
+Uses KMeans clustering and the L*A*B* colorspace to extract "approximate human vision" dominant colors from an image.  Optionally, map those dominant colors into preferred "color bins" for a search index facet-by-color solution.
+
+LARGELY based off the neat work of the [Miro gem](https://github.com/jonbuda/miro).  If you want faster, RGB-based dominant color extraction, use Miro.
+
+## Dependencies
+
+Requires Imagemagick.  On OSX use homebrew to install: brew install imagemagick
+
+## Installation
+
+$ gem install kolors
+
+## Usage
+
+```ruby
+require 'kolors'
+
+# Use path to a local image or URL for remote image
+kolors = Kolors::DominantColors.new('../colors/images/QFZMF57HPHVGJ8Z_thumb.png')
+
+# Return the dominant colors in LAB
+kolors.to_lab
+ => [[52.406, -18.186, 27.618], [88.523, -10.393, 16.203], [64.944, -16.181, 24.419], [28.486, -16.665, 22.73]]
+
+# Return the mapped color bins and color percentage for facet-by-color
+kolors.to_facets
+ => [{"Moss"=>50.05952380952381}, {"Mercury"=>9.880952380952381}, {"Aluminum"=>19.186507936507937}, {"Iron"=>20.873015873015873}]
+```
+
+## TODOS
+
+1. LAB to RGB conversion
+2. Simplify configuration of "color bins" for facet-by-color mapping
+3. Tests
+
+## Thanks
+
+Special thanks to my buddy [Nate Vack](https://github.com/njvack) for help getting this off of the ground.
+
+## Contributing
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request

data/README.textile

@@ -0,0 +1,31 @@
+h1. Colors
+
+A neat facet-by-color script (proof-of-concept).  
+
+* Uses "Miro":https://github.com/jonbuda/miro to pull the dominant colors from an image.
+* Uses "Euclidian distance":http://en.wikipedia.org/wiki/Euclidean_distance to map dominant colors into pre-defined facet color bins
+
+h3. To use
+
+Install ImageMagick, via Homebrew (OS X)
+Install Solr 4.0.0
+
+Install these fine gems:
+require 'mechanize'     # Crawl a UW Digital Collection for data, images
+require 'chunky_png'    # Pure Ruby image manipulation
+require 'miro'          # Detect dominant image colors
+require 'rsolr'         # Solr
+require 'fileutils'     # Save files, delete files, etc.
+require 'awesome_print'
+require 'active_support/core_ext/string'
+
+Start Solr:
+$> cd /apache-solr-4.0.0/example/
+$> java -jar start.jar
+
+Run the script:
+$> ./colors.rb
+
+h3. Todo
+
+This is just play for now, should make a *real* tool of this someday...

data/Rakefile

@@ -0,0 +1,7 @@
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new
+
+task :default => :spec
+task :test => :spec

data/kolors.gemspec

@@ -0,0 +1,27 @@
+# -*- encoding: utf-8 -*-
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'kolors/version'
+
+Gem::Specification.new do |gem|
+  gem.name          = "kolors"
+  gem.version       = Kolors::VERSION
+  gem.authors       = ["Eric Larson"]
+  gem.email         = ["ewlarson@gmail.com"]
+  gem.description   = %q{Uses KMeans clustering and the L*A*B* colorspace to extract "approximate human vision" dominant colors from an image. Optionally, use Euclidean Distance to map those dominant colors into preferred "color bins" for a search index facet-by-color solution.}
+  gem.summary       = %q{Uses KMeans clustering and the L*A*B* colorspace to extract "approximate human vision" dominant colors from an image.}
+  gem.homepage      = "https://github.com/ewlarson/kolors"
+  
+  gem.requirements  = 'ImageMagick'
+  gem.add_dependency 'ai4r'
+  gem.add_dependency 'cocaine'
+  gem.add_dependency 'oily_png'
+
+  gem.add_development_dependency 'rake'
+  gem.add_development_dependency 'rspec'
+
+  gem.files         = `git ls-files`.split($/)
+  gem.executables   = gem.files.grep(%r{^bin/}).map{ |f| File.basename(f) }
+  gem.test_files    = gem.files.grep(%r{^(test|spec|features)/})
+  gem.require_paths = ["lib"]
+end

data/lib/kolors.rb

@@ -0,0 +1,36 @@
+require 'kolors/version'
+require 'oily_png'        # Fast ChunkyPNG
+require 'ai4r'            # KMeans Clustering
+require 'cocaine'
+require 'open-uri'
+require "tempfile"
+
+require 'kolors/rgb'
+require 'kolors/dominant_colors'
+
+# Define a list of key LAB colors
+def key_colors
+  # OSX Crayons in LAB 
+  { [82.046, 0.004, -0.009] => 'Silver', [21.247, 0.002, -0.003] => 'Tungsten', [72.944, 0.004, -0.008] => 'Magnesium', [32.319, 0.002, -0.004] => 'Iron', [63.223, 0.004, -0.007] => 'Aluminum', [43.192, 0.003, -0.005] => 'Steel', [53.585, 0.003, -0.006] => 'Nickel', [53.193, 0.003, -0.006] => 'Tin', [25.531, 48.055, 38.060] => 'Cayenne', [51.868, -12.931, 56.677] => 'Asparagus', [46.229, -51.700, 49.898] => 'Clover', [48.256, -28.842, -8.481] => 'Teal', [12.975, 47.508, -64.704] => 'Midnight', [29.782, 58.940, -36.498] => 'Plum', [34.510, 23.976, 44.820] => 'Mocha', [47.660, -39.672, 51.639] => 'Fern', [46.722, -45.498, 26.354] => 'Moss', [27.367, 9.122, -41.018] => 'Ocean', [18.577, 50.163, -55.230] => 'Eggplant', [26.619, 50.976, 0.503] => 'Maroon', [53.233, 80.109, 67.220] => 'Maraschino', [97.138, -21.556, 94.482] => 'Lemon', [87.737, -86.185, 83.181] => 'Spring', [91.117, -48.080, -14.138] => 'Turquoise', [32.303, 79.197, -107.864] => 'Blueberry', [60.320, 98.254, -60.843] => 'Magenta', [67.050, 42.832, 74.026] => 'Tangerine', [89.910, -67.789, 85.826] => 'Lime', [88.485, -76.749, 46.572] => 'Sea Foam', [54.719, 18.790, -70.925] => 'Aqua', [40.911, 83.182, -93.300] => 'Grape', [54.885, 84.552, 4.066] => 'Strawberry', [63.112, 58.245, 30.548] => 'Salmon', [97.527, -18.441, 70.899] => 'Banana', [89.535, -69.168, 59.807] => 'Flora', [92.382, -39.947, -12.114] => 'Ice', [51.322, 43.621, -76.298] => 'Orchid', [68.008, 76.237, -48.630] => 'Bubblegum', [8.757, 0.001, -0.002] => 'Lead', [91.293, 0.005, -0.010] => 'Mercury', [84.692, 7.020, 56.682] => 'Cantaloupe', [94.019, -38.132, 66.065] => 'Honeydew', [91.100, -52.338, 12.396] => 'Spindrift', [78.011, -15.169, -33.928] => 'Sky', [61.273, 64.277, -59.740] => 'Lavender', [67.377, 65.168, -23.019] => "Carnation", [0.000, 0.000, 0.000] => "Licorice", [100.000, 0.005, -0.010] => 'Snow' }
+  
+  # Crayola Crayons - 16ct
+  # { [0.0, 0.0, 0.0] => 'Black', [47.909, 35.209, -82.012] => 'Blue', [56.951, -21.113, -26.486] => 'Blue Green', [42.436, 30.554, -49.715] => 'Blue Violet', [47.76, 32.728, 31.38] => 'Brown', [77.727, 37.465, -4.165] => 'Pink', [59.159, -50.156, 20.795] => 'Green', [62.726, 54.468, 64.68] => 'Orange', [50.193, 76.218, 36.382] => 'Red', [57.137, 70.48, 50.904] => 'Red Orange', [45.117, 60.767, -14.844] => 'Red Violet', [45.101, 31.746, -33.512] => 'Violet (Purple)', [100.0, 0.005, -0.01] => 'White', [91.412, -8.107, 59.726] => 'Yellow', [85.567, -25.05, 47.104] => 'Yellow Green', [77.236, 20.651, 64.455] => 'Yellow Orange' }
+end
+
+# Euclidean distance
+# - Take a dominant color from an image, return nearest key color
+def dist(p1, p2)
+ (0...p1.length).map {|i| (p1[i]-p2[i])**2}.inject(0) {|sum, i| sum+i}**0.5
+end
+
+module Kolors
+  class << self
+    def options
+      @options ||= {
+        :image_magick_path  => '/usr/local/bin/convert',
+        :resolution         => '100x100',
+        :color_count        => 4
+      }
+    end
+  end
+end

data/lib/kolors/dominant_colors.rb

@@ -0,0 +1,93 @@
+module Kolors
+  class DominantColors
+    attr_accessor :src_image_path
+    
+    def initialize(src_image_path)
+      @src_image_path = src_image_path
+    end
+
+    def to_facets
+      # Map each centroid to key_colors
+      facets = to_lab.each_with_index.collect do |color,index| 
+        { key_colors[key_colors.keys.sort_by {|c| dist(color, c) }.first] => kmeans_result.clusters[index].data_items.size}
+      end
+      percentize(group_hashes_sum_values(facets))
+    end
+    
+    def to_lab
+      kmeans_result.centroids.collect{|r,g,b| Kolors::Rgb.new(r,g,b).to_lab}
+    end
+    
+    def kmeans_result
+      @kmeans_result ||= extract_colors_from_image
+    end
+    
+    private
+    
+    def percentize(hash)
+      hash.collect{|color, count| {color => ((count.to_f / @colors.size.to_f)*100)}}
+    end
+    
+    def group_hashes_sum_values(array)
+      array.inject{|color, count| color.merge( count ){|k, old_v, new_v| old_v + new_v}}
+    end
+
+    def extract_colors_from_image
+      create_thumb_crop_and_convert_to_png!
+      colors = detect_dominant_colors
+      cleanup_temporary_files!
+      return colors
+    end
+
+    def remote_source_image?
+      @src_image_path =~ /^https?:\/\//
+    end
+
+    def create_thumb_crop_and_convert_to_png!
+      @source_image = open_source_image
+      @downsampled_image = open_downsampled_image
+
+      Cocaine::CommandLine.new(Kolors.options[:image_magick_path], "':in[0]' -resize :resolution -gravity Center -crop 90x80%+0+0 :out").
+        run(:in => File.expand_path(@source_image.path),
+            :resolution => Kolors.options[:resolution],
+            :out => File.expand_path(@downsampled_image.path))
+    end
+
+    def open_source_image
+      if remote_source_image?
+        original_extension = URI.parse(@src_image_path).path.split('.').last
+
+        tempfile = Tempfile.open(["source", ".#{original_extension}"])
+        remote_file_data = open(@src_image_path).read
+
+        tempfile.write(RUBY_VERSION =~ /1.9/ ? remote_file_data.force_encoding("UTF-8") : remote_file_data)
+        tempfile.close
+        return tempfile
+      else
+        return File.open(@src_image_path)
+      end
+    end
+
+    def open_downsampled_image
+      tempfile = Tempfile.open(["downsampled", '.png'])
+      tempfile.binmode
+      tempfile
+    end
+
+    def detect_dominant_colors
+      # Detect dominant colors
+      # - Fetches colors from ChunkyPNG directly
+      @colors = ChunkyPNG::Image.from_file(File.expand_path(@downsampled_image.path)).pixels.collect {|c| ChunkyPNG::Color.to_truecolor_bytes c }
+
+      # Kmeans cluster
+      data = Ai4r::Data::DataSet.new(:data_items => @colors)
+      kmeans = Ai4r::Clusterers::KMeans.new
+      result = kmeans.build(data, Kolors.options[:color_count])
+    end
+
+    def cleanup_temporary_files!
+      @source_image.close(true) if remote_source_image?
+      @downsampled_image.close(true)
+    end
+  end
+end

data/lib/kolors/rgb.rb

@@ -0,0 +1,98 @@
+module Kolors
+  class Rgb
+    attr_reader :r, :g, :b
+    attr_reader :l, :a, :b
+  
+    def initialize(r,g,b)
+      @r = r
+      @g = g
+      @b = b
+    end
+  
+    # EasyRGB - RGB to LAB
+    # - LAB gives us a perceptually accurate colorspace
+    def to_lab
+      x,y,z = rgb_to_xyz(@r,@g,@b)
+      l,a,b = xyz_to_lab(x,y,z)
+    end
+  
+    protected
+  
+    # EasyRGB - RGB to XYZ
+    def rgb_to_xyz(r,g,b)
+      r = r * 1.0
+      g = g * 1.0
+      b = b * 1.0
+
+      var_R = ( r / 255.0 )        #R from 0 to 255
+      var_G = ( g / 255.0 )        #G from 0 to 255
+      var_B = ( b / 255.0 )        #B from 0 to 255
+
+      if ( var_R > 0.04045 ) 
+        var_R = ( ( var_R + 0.055 ) / 1.055 ) ** 2.4
+      else                   
+        var_R = var_R / 12.92
+      end
+  
+      if ( var_G > 0.04045 ) 
+        var_G = ( ( var_G + 0.055 ) / 1.055 ) ** 2.4
+      else
+        var_G = var_G / 12.92
+      end
+
+      if ( var_B > 0.04045 )
+        var_B = ( ( var_B + 0.055 ) / 1.055 ) ** 2.4
+      else
+        var_B = var_B / 12.92
+      end
+
+      var_R = var_R * 100
+      var_G = var_G * 100
+      var_B = var_B * 100
+
+      # Observer. = 2°, Illuminant = D65
+      x = var_R * 0.4124 + var_G * 0.3576 + var_B * 0.1805
+      y = var_R * 0.2126 + var_G * 0.7152 + var_B * 0.0722
+      z = var_R * 0.0193 + var_G * 0.1192 + var_B * 0.9505
+  
+      return [x,y,z]
+    end
+
+    # EasyRGB - XYZ to CIELAB
+    def xyz_to_lab(x,y,z)
+      var_X = x / 95.047            #ref_X =  95.047   Observer= 2°, Illuminant= D65
+      var_Y = y / 100.000           #ref_Y = 100.000
+      var_Z = z / 108.883           #ref_Z = 108.883
+
+      if ( var_X > 0.008856 ) 
+        var_X = var_X ** ( 1.0/3.0 )
+      else
+        var_X = ( 7.787 * var_X ) + ( 16.0 / 116.0 )
+      end
+  
+      if ( var_Y > 0.008856 ) 
+        var_Y = var_Y ** ( 1.0/3.0 )
+      else
+        var_Y = ( 7.787 * var_Y ) + ( 16.0 / 116.0 )
+      end
+  
+      if ( var_Z > 0.008856 )
+        var_Z = var_Z ** ( 1.0/3.0 )
+      else
+        var_Z = ( 7.787 * var_Z ) + ( 16.0 / 116.0 )
+      end
+
+      l = ( 116.0 * var_Y ) - 16.0
+      a = 500.0 * ( var_X - var_Y )
+      b = 200.0 * ( var_Y - var_Z )
+
+      return [l.round(3),a.round(3),b.round(3)]
+    end
+
+    # EasyRGB - RGB to LAB
+    def rgb_to_lab(r,g,b)
+      x,y,z = rgb_to_xyz(r,g,b)
+      l,a,b = xyz_to_lab(x,y,z)
+    end
+  end
+end

data/lib/kolors/version.rb

@@ -0,0 +1,3 @@
+module Kolors
+  VERSION = "0.0.1"
+end

metadata

@@ -0,0 +1,143 @@
+--- !ruby/object:Gem::Specification
+name: kolors
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+  prerelease: 
+platform: ruby
+authors:
+- Eric Larson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-02-04 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: ai4r
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: cocaine
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: oily_png
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    none: false
+    requirements:
+    - - ! '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Uses KMeans clustering and the L*A*B* colorspace to extract "approximate
+  human vision" dominant colors from an image. Optionally, use Euclidean Distance
+  to map those dominant colors into preferred "color bins" for a search index facet-by-color
+  solution.
+email:
+- ewlarson@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- .gitignore
+- Gemfile
+- Gemfile.lock
+- LICENSE
+- README.md
+- README.textile
+- Rakefile
+- kolors.gemspec
+- lib/kolors.rb
+- lib/kolors/dominant_colors.rb
+- lib/kolors/rgb.rb
+- lib/kolors/version.rb
+homepage: https://github.com/ewlarson/kolors
+licenses: []
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  none: false
+  requirements:
+  - - ! '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements:
+- ImageMagick
+rubyforge_project: 
+rubygems_version: 1.8.24
+signing_key: 
+specification_version: 3
+summary: Uses KMeans clustering and the L*A*B* colorspace to extract "approximate
+  human vision" dominant colors from an image.
+test_files: []
+has_rdoc: