camalian 0.1.0 → 0.1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bdc6f4d61421eac9f0017baf9e6f290c37e47b633ee4533e18d00883fd162b54
-  data.tar.gz: 5cb477be826b4c0706a9385ce31699a34aab8b27c66c5c57140d1818650ca60e
+  metadata.gz: 01c8d4bae81e85284d554a538c52e90741f0db58ddba1d6d9e921761cf041d91
+  data.tar.gz: c5a301ed8505a08e31ed1c65cc4e5c8b0b1ccc832fad6e8279cb279f4750dadd
 SHA512:
-  metadata.gz: 912bcad8d3db3362d2997877fe42b9d2df01c806b9bbfe965463d5df8e530dab55f716820f414e44910e5818ff86ac1ac256f8c9d1a2d760ca75d38c69492dcc
-  data.tar.gz: fe6989ee96c21f12482857c26aed89f7db69e6d1a41616c9aaed3a11732ccf76c8376c6711b49dc375cbb8d29adfef1ff09ba3ea3c5780c4f70cdce0431041eb
+  metadata.gz: '0418f17dfb07d45db856e30e9b333b532be7a38045aa4be3aae32192e62de4c803837a6730df08a797f3c662bd9a3fc0f21a5e780edfcf8545b3c085440af2d0'
+  data.tar.gz: 0e1144ff5d5d9a8faef915c23518759b98bebd6efdb6a4b39ea7a11ecd67d63e07847b05982853a20b0a719a855d16a1dcba45f28ac97383478a319ef9281488

data/.rubocop.yml

@@ -27,6 +27,10 @@ Metrics/PerceivedComplexity:
 Metrics/CyclomaticComplexity:
   Max: 15
 
+Metrics/BlockLength:
+  Exclude:
+    - test/**/*
+
 Metrics/AbcSize:
   Max: 20
   IgnoredMethods:

data/README.md

@@ -10,7 +10,7 @@ Ruby gem to extract color palettes from images and play with their saturation
 
 Add this line to your application's Gemfile:
 
-    gem 'camalian', '~> 0.1.0'
+    gem 'camalian', '~> 0.1.1'
 
 And then execute:
 
@@ -22,10 +22,43 @@ Or install it yourself as:
 
 ## Usage
 
-    image = Camalian::load('file_path')
-    colors = image.prominent_colors(15)
-    colors = colors.sort_similar_colors
-    colors.light_colors(0, 40)
+```ruby
+image = Camalian::load('file_path')
+colors = image.prominent_colors(15)
+colors = colors.sort_similar_colors
+colors.light_colors(0, 40)
+```
+    
+### Quantization Algorithms
+Currently following algorithms are implemented. 
+
+**Histogram**
+
+Its a most common algorithm for color quantization and used different bucket technique to group the colors together. You can read more about this technique here https://en.wikipedia.org/wiki/Color_histogram. It can be accessed by `Camalian::QUANTIZATION_HISTOGRAM` constant. This is used as default method as well.   
+
+
+**K Means**
+
+This algorithm uses color distancing in RGB space to group the similar colors. You can learn more about this technique here https://en.wikipedia.org/wiki/K-means_clustering. It can be accessed by `Camalian::QUANTIZATION_K_MEANS` constant.  
+
+
+You can set default quantization method globally as: 
+
+```ruby
+Camalian.options[:quantization] = Camalian::QUANTIZATION_K_MEANS
+```
+
+or you can set at the time of extracting colors by.
+
+```ruby
+image = Camalian::load('file_path')
+colors = image.prominent_colors(15, quantization: Camalian::QUANTIZATION_K_MEANS)
+```
+
+## Usage
+You can find a working example with detail explanation and reference code here on [this link](https://basicdrift.com/color-extraction-library-build-color-search-engine-fdf369678d5a). Here we will build a functional color based image search engine in Ruby on Rails.
+
+NOTE: Since its a compute intensive operation so for production use its suggested to use under a background job and not within a request/response cycle. 
 
 ## Contributing
 

data/lib/camalian.rb

@@ -9,9 +9,11 @@ require 'camalian/color'
 require 'camalian/palette'
 require 'camalian/image'
 require 'camalian/quantization/histogram'
+require 'camalian/quantization/k_means'
 
 module Camalian # :nodoc:
-  QUANTIZATION_HISTOGRAM = 'histogram'
+  QUANTIZATION_HISTOGRAM = Camalian::Quantization::Histogram
+  QUANTIZATION_K_MEANS = Camalian::Quantization::KMeans
 
   class << self
     def options

data/lib/camalian/color.rb

@@ -10,7 +10,12 @@ module Camalian
     end
 
     def self.from_hex(hex_value)
-      r, g, b = extract_rgb(hex_value)
+      color_hash = hex_value[0..6]
+      color_hash = color_hash[1..6] if color_hash[0] == '#'
+      r = color_hash[0..1].to_i(16)
+      g = color_hash[2..3].to_i(16)
+      b = color_hash[4..5].to_i(16)
+
       Color.new(r, g, b)
     end
 
@@ -22,17 +27,23 @@ module Camalian
       "##{r.to_s(16).rjust(2, '0')}#{g.to_s(16).rjust(2, '0')}#{b.to_s(16).rjust(2, '0')}"
     end
 
-    def distance(color)
+    # Used for array uniqueness
+    def hash
+      "#{r}#{g}#{b}".to_i
+    end
+
+    # Used for object comparison
+    def ==(other)
+      r == other.r && g == other.g && b == other.b
+    end
+    alias eql? ==
+
+    def hue_distance(color)
       [(h - color.h) % 360, (color.h - h) % 360].min
     end
 
-    def extract_rgb(color_hash)
-      color_hash = color_hash[0..6]
-      color_hash = color_hash[1..6] if color_hash[0] == '#'
-      r = color_hash[0..1].to_i(16)
-      g = color_hash[2..3].to_i(16)
-      b = color_hash[4..5].to_i(16)
-      [r, g, b]
+    def rgb_distance(color)
+      Math.sqrt(((r - color.r)**2) + ((g - color.g)**2) + ((b - color.b)**2))
     end
 
     private

data/lib/camalian/image.rb

@@ -22,7 +22,7 @@ module Camalian
         )
       end
 
-      quantize = Object.const_get("Camalian::Quantization::#{quantization.capitalize}").new
+      quantize = quantization.new
 
       palette = quantize.process(colors, count)
 

data/lib/camalian/palette.rb

@@ -34,5 +34,9 @@ module Camalian
       table = dup
       Palette.new(table.delete_if { |color| color.l > max or color.l < min })
     end
+
+    def to_hex
+      map(&:to_hex)
+    end
   end
 end

data/lib/camalian/quantization/histogram.rb

@@ -13,7 +13,7 @@ module Camalian
           buckets[key].push(color)
         end
 
-        Palette.new(buckets.map { |_, value| value.average_color })
+        Palette.new(buckets.map { |_, value| value.average_color }[0...count])
       end
 
       private

data/lib/camalian/quantization/k_means.rb

@@ -0,0 +1,59 @@
+# frozen_string_literal: true
+
+module Camalian
+  module Quantization
+    class KMeans # :nodoc:
+      INIT_TRIES = 10
+
+      def process(colors, count)
+        # Its faster to extract unique colors once
+        colors = colors.uniq
+        means = initial_means(colors, count)
+
+        done = false
+
+        until done
+          groups = group_by_means(colors, means)
+          new_means = groups.map do |group|
+            Palette.new(group).average_color
+          end
+          common = means & new_means
+
+          done = common.size == means.size
+          means = new_means
+        end
+
+        Palette.new(means)
+      end
+
+      private
+
+      def initial_means(colors, count)
+        count = colors.size if count > colors.size
+        means = []
+        tries = 0
+        while means.size != count && tries < INIT_TRIES
+          (count - means.size).times { means << colors[rand(colors.size)] }
+          means.uniq!
+          tries += 1
+        end
+
+        means
+      end
+
+      def group_by_means(pixels, means)
+        groups = {}
+
+        pixels.each do |p|
+          distances = means.map { |m| p.rgb_distance(m) }
+          min_distance_index = distances.index(distances.min)
+
+          groups[min_distance_index] ||= []
+          groups[min_distance_index] << p
+        end
+
+        groups.values
+      end
+    end
+  end
+end

data/lib/camalian/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Camalian
-  VERSION = '0.1.0'
+  VERSION = '0.1.1'
 end

data/test/test_helper.rb

@@ -2,3 +2,7 @@
 
 require 'simplecov'
 SimpleCov.start
+
+require 'minitest/autorun'
+require 'minitest/spec'
+require 'camalian'

data/test/test_quantization.rb

@@ -0,0 +1,47 @@
+# frozen_string_literal: true
+
+require 'test_helper'
+
+describe Camalian::Quantization do
+  [Camalian::Quantization::KMeans, Camalian::Quantization::Histogram].each do |klass|
+    describe klass.name.to_s do
+      it 'should extract distinct colors' do
+        colors = %w[#FF0000 #00FF00 #0000FF].map { |c| Camalian::Color.from_hex(c) }
+        result = klass.new.process(colors, 3)
+
+        _(result.size).must_equal 3
+        _(result).must_equal colors
+      end
+
+      it 'should extract distinct colors lesser than pixels' do
+        colors = %w[#FF0000 #00FF00 #0000FF].map { |c| Camalian::Color.from_hex(c) }
+        result = klass.new.process(colors, 2)
+
+        _(result.size).must_equal 2
+      end
+
+      it 'should extract distinct colors not more than pixels' do
+        colors = %w[#FF0000 #00FF00 #0000FF].map { |c| Camalian::Color.from_hex(c) }
+        result = klass.new.process(colors, 4)
+
+        _(result.size).must_equal 3
+      end
+
+      it 'should extract same color' do
+        colors = %w[#FF0000 #FF0000 #FF0000].map { |c| Camalian::Color.from_hex(c) }
+        result = klass.new.process(colors, 3)
+
+        _(result.size).must_equal 1
+        _(result.to_hex).must_equal ['#ff0000']
+      end
+
+      it 'should extract multiple colors' do
+        colors = %w[#FF0000 #FF0000 #00FF00 #0000FF].map { |c| Camalian::Color.from_hex(c) }
+        result = klass.new.process(colors, 3)
+
+        _(result.size).must_equal 3
+        _(result.to_hex).must_equal %w[#ff0000 #00ff00 #0000ff]
+      end
+    end
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: camalian
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.1
 platform: ruby
 authors:
 - Nazar Hussain
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-11-21 00:00:00.000000000 Z
+date: 2020-11-29 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: chunky_png
@@ -95,11 +95,13 @@ files:
 - lib/camalian/image.rb
 - lib/camalian/palette.rb
 - lib/camalian/quantization/histogram.rb
+- lib/camalian/quantization/k_means.rb
 - lib/camalian/version.rb
 - test/assets/palette.png
 - test/test_color.rb
 - test/test_helper.rb
 - test/test_palette.rb
+- test/test_quantization.rb
 homepage: https://github.com/nazarhussain/camalian
 licenses:
 - MIT
@@ -129,3 +131,4 @@ test_files:
 - test/test_color.rb
 - test/test_helper.rb
 - test/test_palette.rb
+- test/test_quantization.rb