gauguin 0.0.2

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 6a07d005423451283af94f40f2883014463654d6
+  data.tar.gz: 94c047bc3adbdfd5a9c312133b7650ad2558b379
+SHA512:
+  metadata.gz: 0b8d86912f76d6ec17cf14e400c346a89559b267d8c345d8697760fae9bbc1158c6cb50130c26f7f566b6b3e866885b407fd4316c307f088df2a093b82ef60fd
+  data.tar.gz: 3bf13e35ba5fcda29a71cf7b9242802da1bdeb0aaadf686d8af988264269b3e2095db8ac93a23c112b08c4862cc5b85c317e34f825a376f84e7209edc7f43404

data/.gitignore

@@ -0,0 +1,15 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+*.bundle
+*.so
+*.o
+*.a
+mkmf.log
+.DS_Store

data/.rspec

@@ -0,0 +1,3 @@
+--color
+--format documentation
+

data/.travis.yml

@@ -0,0 +1,9 @@
+language: ruby
+script:
+  - CODECLIMATE_REPO_TOKEN=edbf400c9cd2e92ef8eabf2dad1d03b0ed0cb2a83a20f12f70e4f8107c38de51 bundle exec rake
+rvm:
+  - 2.1
+notifications:
+  email:
+    - anna.slimak@lunarlogic.io
+

data/Gemfile

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

data/Guardfile

@@ -0,0 +1,6 @@
+guard :rspec, cmd: 'bundle exec rspec' do
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/lib/#{m[1]}_spec.rb" }
+  watch('spec/spec_helper.rb')  { "spec" }
+end
+

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Lunar Logic Polska http://lunarlogicpolska.com
+
+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,119 @@
+[![Build Status](https://travis-ci.org/LunarLogic/gauguin.svg?branch=master)](https://travis-ci.org/LunarLogic/gauguin)
+[![Code Climate](https://codeclimate.com/github/LunarLogic/gauguin/badges/gpa.svg)](https://codeclimate.com/github/LunarLogic/gauguin)
+[![Test Coverage](https://codeclimate.com/github/LunarLogic/gauguin/badges/coverage.svg)](https://codeclimate.com/github/LunarLogic/gauguin)
+
+<img src="http://gauguin.lunarlogic.io/assets/gauguin-b7a7737e8ede819b98df9d05f7df020a.png" alt="Guard Icon" align="left" />
+# Gauguin
+
+Retrieves palette of main colors, merging similar colors using [Lab color space](http://en.wikipedia.org/wiki/Lab_color_space).
+
+## Why not just use `RMagick`?
+
+How many colors do you recognize on the image below?
+
+![Black and white image](spec/support/pictures/gray_and_black.png)
+
+Many people would say `2`, but actually there are `1942`.
+
+It's because of the fact that to make image more smooth, borders of the figure are not pure black but consist of many gray scale colors.
+
+It's common that images includes very similar colors, so when you want to get useful color palette, you would need to process color histogram you get from `RMagick` yourself.
+
+This gem was created to do this for you.
+
+## Sample app
+
+Sample application available here: http://gauguin.lunarlogic.io
+
+## Requirements
+
+Gem depends on `RMagick` which requires `ImageMagick` to be installed.
+
+### Ubuntu
+
+    $ sudo apt-get install imagemagick
+
+### OSX
+
+    $ brew install imagemagick
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'gauguin'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install gauguin
+
+## Usage
+
+#### Palette
+
+```ruby
+palette = Gauguin::Painting.new("path/to/image.png").palette
+```
+
+Result for image above would be:
+
+```ruby
+  {
+    rgb(204, 204, 204)[0.5900935269505287] => [
+      rgb(77, 77, 77)[7.383706620723603e-05],
+      rgb(85, 85, 85)[0.00012306177701206005],
+      # ...
+      rgb(219, 220, 219)[1.2306177701206005e-05],
+      rgb(220, 220, 220)[7.383706620723603e-05]
+    ],
+    rgb(0, 0, 0)[0.40990647304947003] => [
+      rgb(0, 0, 0)[0.40990647304947003],
+      rgb(1, 1, 1)[0.007912872261875462],
+      # ...
+      rgb(64, 64, 64)[6.153088850603002e-05],
+      rgb(66, 66, 66)[6.153088850603002e-05]
+    ]
+  }
+```
+
+Where keys are instances of `Gauguin::Color` class and values are array of instances of `Gauguin::Color` class.
+
+#### Recolor
+
+There is also recolor feature - you can pass original image and the calculated palette and return new image, colored only with the main colours from the palette.
+
+```ruby
+painting.recolor(palette, 'path/where/recolored/file/will/be/placed')
+```
+
+## Custom configuration
+
+There are `4` parameters that you can configure:
+
+- `max_colors_count` (default value is `10`) - maximum number of colors that a palette will include
+- `colors_limit` (default value is `10000`) - maximum number of colors that will be considered while calculating a palette - if image has too many colors it is not efficient to calculate grouping for all of them, so only `colors_limit` of colors of the largest percentage are used
+- `min_percentage_sum` (default value is `0.981`) - parameter used while calculating which colors should be ignored. Colors are sorted by percentage in descending order, then colors which percentages sums to `min_percentage_sum` are taken into consideration
+- `color_similarity_threshold` (default value is `25`) - maximum distance in [Lab color space](http://en.wikipedia.org/wiki/Lab_color_space) to consider two colors as the same while grouping
+
+To configure any of above options you can use configuration block.
+For example changing `max_colors_count` would look like this:
+
+```ruby
+Gauguin.configuration do |config|
+  config.max_colors_count = 7
+end
+```
+
+## Contributing
+
+1. Fork it ( https://github.com/LunarLogic/gauguin/fork )
+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 a new Pull Request

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/gem_tasks"
+
+require 'rake'
+require 'rspec/core/rake_task'
+
+desc "Run all examples"
+RSpec::Core::RakeTask.new(:spec) do |t|
+  t.rspec_opts = %w[--color]
+end
+
+
+task :default => [:spec]
+

data/gauguin.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'gauguin/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "gauguin"
+  spec.version       = Gauguin::VERSION
+  spec.authors       = ["Ania Slimak"]
+  spec.email         = ["anna.slimak@lunarlogic.io"]
+  spec.summary       = %q{Tool for retrieving main colors from the image.}
+  spec.description   = %q{Retrieves palette of main colors, merging similar colors using Lab color space.}
+  spec.homepage      = "https://github.com/LunarLogic/gauguin"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(%r{^bin/}) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(%r{^(test|spec|features)/})
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "rmagick"
+
+  spec.add_development_dependency "bundler", "~> 1.7"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "simplecov"
+  spec.add_development_dependency "codeclimate-test-reporter"
+  spec.add_development_dependency "guard-rspec"
+  spec.add_development_dependency "pry"
+end

data/lib/gauguin/color.rb

@@ -0,0 +1,76 @@
+module Gauguin
+  class Color
+    attr_accessor :red, :green, :blue, :percentage, :transparent
+
+    def initialize(red, green, blue, percentage = 1, transparent = false)
+      self.red = red
+      self.green = green
+      self.blue = blue
+      self.percentage = percentage
+      self.transparent = transparent
+    end
+
+    def ==(other)
+      self.class == other.class && self.to_key == other.to_key
+    end
+
+    alias eql? ==
+
+    def hash
+      self.to_key.hash
+    end
+
+    def similar?(other_color)
+      self.transparent == other_color.transparent &&
+        self.distance(other_color) < Gauguin.configuration.color_similarity_threshold
+    end
+
+    def distance(other_color)
+      (self.to_lab - other_color.to_lab).r
+    end
+
+    def to_lab
+      rgb_vector = self.to_vector
+      xyz_vector = rgb_vector.to_xyz
+      xyz_vector.to_lab
+    end
+
+    def to_vector
+      ColorSpace::RgbVector[*to_rgb]
+    end
+
+    def to_rgb
+      [self.red, self.green, self.blue]
+    end
+
+    def to_a
+      to_rgb + [self.percentage, self.transparent]
+    end
+
+    def self.from_a(array)
+      red, green, blue, percentage, transparent = array
+      Color.new(red, green, blue, percentage, transparent)
+    end
+
+    def to_key
+      to_rgb + [self.transparent]
+    end
+
+    def to_s
+      "rgb(#{self.red}, #{self.green}, #{self.blue})"
+    end
+
+    def inspect
+      msg = "#{to_s}[#{percentage}]"
+      if transparent?
+        msg += "[transparent]"
+      end
+      msg
+    end
+
+    def transparent?
+      self.transparent
+    end
+  end
+end
+

data/lib/gauguin/color_space/lab_vector.rb

@@ -0,0 +1,6 @@
+module Gauguin
+  module ColorSpace
+    class LabVector < Vector
+    end
+  end
+end

data/lib/gauguin/color_space/rgb_vector.rb

@@ -0,0 +1,36 @@
+module Gauguin
+  module ColorSpace
+    class RgbVector < Vector
+      MAX_VAUE = 255.0
+
+      # Observer. = 2°, Illuminant = D65
+      RGB_TO_XYZ = Matrix[[0.4124, 0.2126, 0.0193],
+                          [0.3576, 0.7152, 0.1192],
+                          [0.1805, 0.0722, 0.9505]]
+
+      def pivot!
+        self.each.with_index do |component, i|
+          self[i] = pivot(component / MAX_VAUE)
+        end
+        self
+      end
+
+      def to_xyz
+        self.pivot!
+        matrix = Matrix[self] * RGB_TO_XYZ
+        XyzVector[*matrix.row_vectors.first.to_a]
+      end
+
+      private
+
+      def pivot(component)
+        component = if component > 0.04045
+          ((component + 0.055) / 1.055) ** 2.4
+        else
+          component / 12.92
+        end
+        component * 100.0
+      end
+    end
+  end
+end

data/lib/gauguin/color_space/xyz_vector.rb

@@ -0,0 +1,33 @@
+module Gauguin
+  module ColorSpace
+    class XyzVector < Vector
+      WHITE_REFERENCE = self[95.047, 100.000, 108.883]
+
+      EPSILON = 0.008856
+      KAPPA = 903.3
+
+      def to_lab
+        zipped = self.zip(XyzVector::WHITE_REFERENCE)
+        x, y, z = zipped.map do |component, white_component|
+          component / white_component
+        end
+
+        l = 116 * f(y) - 16
+        a = 500 * (f(x) - f(y))
+        b = 200 * (f(y) - f(z))
+
+        LabVector[l, a, b]
+      end
+
+      private
+
+      def f(x)
+        if x > EPSILON
+          x ** (1.0/3.0)
+        else
+          (KAPPA * x + 16.0) / 116.0
+        end
+      end
+    end
+  end
+end

data/lib/gauguin/color_space.rb

@@ -0,0 +1,4 @@
+require 'matrix'
+require "gauguin/color_space/rgb_vector"
+require "gauguin/color_space/xyz_vector"
+require "gauguin/color_space/lab_vector"

data/lib/gauguin/colors_clusterer.rb

@@ -0,0 +1,63 @@
+module Gauguin
+  class ColorsClusterer
+    def call(colors)
+      clusters = {}
+
+      while !colors.empty?
+        pivot = colors.shift
+        group = [pivot]
+
+        colors, pivot, group = find_all_similar(colors, pivot, group)
+
+        clusters[pivot] = group
+      end
+
+      update_pivots_percentages(clusters)
+
+      clusters
+    end
+
+    def clusters(colors)
+      clusters = self.call(colors)
+      clusters = clusters.sort_by { |color, _| color.percentage }.reverse
+      Hash[clusters[0...Gauguin.configuration.max_colors_count]]
+    end
+
+    def reversed_clusters(clusters)
+      reversed_clusters = {}
+
+      clusters.each do |pivot, group|
+        group.each do |color|
+          reversed_clusters[color] = pivot
+        end
+      end
+
+      reversed_clusters
+    end
+
+    private
+
+    def find_all_similar(colors, pivot, group)
+      loop do
+        similar_colors = colors.select { |c| c.similar?(pivot) }
+        break if similar_colors.empty?
+
+        group += similar_colors
+        colors -= similar_colors
+
+        pivot = group.sort_by(&:percentage).last
+      end
+
+      [colors, pivot, group]
+    end
+
+    def update_pivots_percentages(clusters)
+      clusters.each do |main_color, group|
+        percentage = group.inject(0) do |sum, color|
+          sum += color.percentage
+        end
+        main_color.percentage = percentage
+      end
+    end
+  end
+end

data/lib/gauguin/colors_limiter.rb

@@ -0,0 +1,14 @@
+module Gauguin
+  class ColorsLimiter
+    def call(colors)
+      colors_limit = Gauguin.configuration.colors_limit
+
+      if colors.count > colors_limit
+        colors = colors.sort_by { |key, group| key.percentage }.
+          reverse[0..colors_limit - 1]
+      end
+
+      colors
+    end
+  end
+end

data/lib/gauguin/colors_retriever.rb

@@ -0,0 +1,33 @@
+module Gauguin
+  class ColorsRetriever
+    def initialize(image)
+      @image = image
+    end
+
+    def colors
+      colors = {}
+
+      histogram = @image.color_histogram
+      image_size = @image.columns * @image.rows
+
+      histogram.each do |pixel, count|
+        image_pixel = @image.pixel(pixel)
+
+        red, green, blue = image_pixel.to_rgb
+        percentage = count.to_f / image_size
+        color = Gauguin::Color.new(red, green, blue, percentage,
+                                   image_pixel.transparent?)
+
+        # histogram can contain different magic pixels for
+        # the same colors with different opacity
+        if colors[color]
+          colors[color].percentage += color.percentage
+        else
+          colors[color] = color
+        end
+      end
+
+      colors.values
+    end
+  end
+end

data/lib/gauguin/image.rb

@@ -0,0 +1,55 @@
+require 'rmagick'
+require 'forwardable'
+
+module Gauguin
+  class Image
+    extend Forwardable
+    attr_accessor :image
+    delegate [:color_histogram, :columns, :rows, :write] => :image
+
+    def initialize(path = nil)
+      return unless path
+
+      list = Magick::ImageList.new(path)
+      self.image = list.first
+    end
+
+    def self.blank(columns, rows)
+      blank_image = Image.new
+      transparent_white = Magick::Pixel.new(255, 255, 255, Pixel::MAX_TRANSPARENCY)
+      blank_image.image = Magick::Image.new(columns, rows) do
+        self.background_color = transparent_white
+      end
+      blank_image
+    end
+
+    def pixel(magic_pixel)
+      Pixel.new(magic_pixel)
+    end
+
+    def pixel_color(row, column, *args)
+      magic_pixel = self.image.pixel_color(row, column, *args)
+      pixel(magic_pixel)
+    end
+
+    class Pixel
+      MAX_CHANNEL_VALUE = 257
+      MAX_TRANSPARENCY = 65535
+
+      def initialize(magic_pixel)
+        @magic_pixel = magic_pixel
+      end
+
+      def transparent?
+        @magic_pixel.opacity >= MAX_TRANSPARENCY
+      end
+
+      def to_rgb
+        [:red, :green, :blue].map do |color|
+          @magic_pixel.send(color) / MAX_CHANNEL_VALUE
+        end
+      end
+    end
+  end
+end
+

data/lib/gauguin/image_recolorer.rb

@@ -0,0 +1,29 @@
+module Gauguin
+  class ImageRecolorer
+    def initialize(image)
+      @image = image.dup
+    end
+
+    def recolor(new_colors)
+      columns = @image.columns
+      rows = @image.rows
+
+      new_image = Image.blank(columns, rows)
+
+      (0...columns).each do |column|
+        (0...rows).each do |row|
+          image_pixel = @image.pixel_color(column, row)
+          next if image_pixel.transparent?
+
+          color = Color.new(*image_pixel.to_rgb)
+          new_color = new_colors[color]
+
+          next unless new_color
+
+          new_image.pixel_color(column, row, new_color.to_s)
+        end
+      end
+      new_image
+    end
+  end
+end

data/lib/gauguin/image_repository.rb

@@ -0,0 +1,7 @@
+module Gauguin
+  class ImageRepository
+    def get(path)
+      Gauguin::Image.new(path)
+    end
+  end
+end

data/lib/gauguin/noise_reducer.rb

@@ -0,0 +1,26 @@
+module Gauguin
+  class NoiseReducer
+    def call(colors_clusters)
+      pivots = colors_clusters.keys.sort_by! { |key, group| key.percentage }.reverse
+
+      percentage_sum = 0
+      index = 0
+      pivots.each do |color|
+        percentage_sum += color.percentage
+        break if percentage_sum > Gauguin.configuration.min_percentage_sum
+        index += 1
+      end
+
+      reduced_clusters(colors_clusters, pivots, index)
+    end
+
+    private
+
+    def reduced_clusters(colors_clusters, pivots, cut_off_index)
+      reduced_pivots = pivots[0..cut_off_index]
+      colors_clusters.select do |c|
+        !c.transparent? && reduced_pivots.include?(c)
+      end
+    end
+  end
+end

data/lib/gauguin/painting.rb

@@ -0,0 +1,29 @@
+module Gauguin
+  class Painting
+    def initialize(path, image_repository = nil, colors_retriever = nil,
+                   colors_limiter = nil, noise_reducer = nil,
+                   colors_clusterer = nil, image_recolorer = nil)
+      @image_repository = image_repository || Gauguin::ImageRepository.new
+      @image = @image_repository.get(path)
+      @colors_retriever = colors_retriever || Gauguin::ColorsRetriever.new(@image)
+      @colors_limiter = colors_limiter || Gauguin::ColorsLimiter.new
+      @noise_reducer = noise_reducer || Gauguin::NoiseReducer.new
+      @colors_clusterer = colors_clusterer || Gauguin::ColorsClusterer.new
+      @image_recolorer = image_recolorer || Gauguin::ImageRecolorer.new(@image)
+    end
+
+    def palette
+      colors = @colors_retriever.colors
+      colors = @colors_limiter.call(colors)
+      colors_clusters = @colors_clusterer.clusters(colors)
+      @noise_reducer.call(colors_clusters)
+    end
+
+    def recolor(palette, path)
+      new_colors = @colors_clusterer.reversed_clusters(palette)
+      recolored_image = @image_recolorer.recolor(new_colors)
+      recolored_image.write(path)
+    end
+  end
+end
+

data/lib/gauguin/palette_serializer.rb

@@ -0,0 +1,22 @@
+require 'yaml'
+
+module Gauguin
+  class PaletteSerializer
+    def self.load(value)
+      return unless value
+
+      value = YAML.load(value)
+      value = value.to_a.map do |color_key, group|
+        [Gauguin::Color.from_a(color_key), group]
+      end
+      value = Hash[value]
+    end
+
+    def self.dump(value)
+      value = value.to_a.map { |color, group| [color.to_a, group] }
+      value = Hash[value]
+      YAML.dump(value)
+    end
+  end
+end
+