color_sort 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 81e0d767639e5bb6b4ffd6915f0b4607ce65b05d
+  data.tar.gz: b399a98a8bcede7671af2d587e08bc5593a93bc7
+SHA512:
+  metadata.gz: 0c090a1934e79feb4dc86f608b0fc61da779f30de431fc5973aaa3eaafb2b0fd639505c9158e67577cefd79d3e20d67b2dba64f3e7a22d05a725bf6462bd6f82
+  data.tar.gz: 0ad0740c0cdca320c4f10c10c24abf10f5db10f20623437b47ba082c000a3d1d5031dca9cbb8c0fedefb4726bd9970b7cd939c65b4e197f6bf68b7c1e4406e7b

data/.gitignore

@@ -0,0 +1,17 @@
+*.gem
+*.rbc
+.bundle
+.config
+.yardoc
+Gemfile.lock
+InstalledFiles
+_yardoc
+coverage
+doc/
+lib/bundler/man
+pkg
+rdoc
+spec/reports
+test/tmp
+test/version_tmp
+tmp

data/.rspec

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

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Pip Taylor
+
+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,78 @@
+# ColorSort
+
+ColorSort sorts an array of colors perceptually, using the
+[CIEDE2000](http://en.wikipedia.org/wiki/Color_difference#CIEDE2000)
+color distance function.
+
+*Unsorted* | *Sorted*
+---------- | --------
+![200 unsorted lines of color](http://ms-digital-labs.github.io/unsorted.png) | ![200 sorted lines of color](http://ms-digital-labs.github.io/sorted.png)
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'color_sort'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install color_sort
+
+## Usage
+
+Call `ColorSort.sort` with an array of RGB colors in hex form (with or without preceeding #):
+
+```ruby
+unsorted_colors = ["35c047", "7f40ed", "39ae1e", "5f9d4c", "94ec1e", "93e482"]
+
+sorted_colors = ColorSort.sort(unsorted_colors)
+	# => ["94ec1e", "93e482", "39ae1e", "35c047", "5f9d4c", "7f40ed"]
+```
+
+## How it works
+
+Often when dealing with colors on computers, we're working with the [RGB color model](http://en.wikipedia.org/wiki/Color_model#RGB_color_model). As each color has three components, we can think of it as a point in 3D space. This allows us to use the [Euclidean distance](http://en.wikipedia.org/wiki/Euclidean_distance) to see how far apart two colors are.
+
+Unfortunately, the RGB color space doesn't model how people perceive colors, so a pair of colors that are close together in RGB space may actually look quite different, and vice-versa. We can solve this by using the [Lab color space](http://en.wikipedia.org/wiki/Lab_color_space) and [CIEDE2000 distance function](http://en.wikipedia.org/wiki/Color_difference#CIEDE2000). This color space and distance function are tuned to give a smaller distance for perceputally close colors.
+
+Now we have a way of determining the perceptual distance between two colors, but we can't use this with a normal sorting algorithm because we can't define a [Total order](http://en.wikipedia.org/wiki/Total_order) over all colors. What we really need to do is find the shortest path through our colors in Lab color space, using the CIEDE2000 distance function.
+
+This turns out to be the [Travelling salesman problem](http://en.wikipedia.org/wiki/Travelling_salesman_problem). We first tried the [Nearest neighbour](http://en.wikipedia.org/wiki/Nearest_neighbour_algorithm) heuristic, but found that it left ugly discontinuities in the sorted colors.
+
+Next we tried [Simulated annealing](http://en.wikipedia.org/wiki/Simulated_annealing), but found that it didn't converge on a solution anywhere near quickly enough to be useful.
+
+The solution we settled on was to iteratively build of a list of colors, inserting each one in to the list at the point at which it causes the lowest increase in the total distance between all the colors currently in the list. This allows us to sort a few hundred colors in a couple of seconds, and produces visually pleasing results.
+
+#### Other approaches
+
+Wikipedia lists [several other approaches for solving TSP](http://en.wikipedia.org/wiki/Travelling_salesman_problem#Computing_a_solution) - both exact solutions and approximate solutions. We didn't explore these because we couldn't find libraries that implemented them and didn't have the time to implement them ourselves.
+
+It's almost certain that there's a better approach to solving this particular case of TSP, but we ran out of time/motivation to investigate further. If you know a better approach, please let us know!
+
+## Performance
+
+The algorithm used by this gem has complexity O(n<sup>2</sup>) in the size of the list being sorted. Some example timings on a MacBook Pro:
+
+Number of colors | Time (seconds)
+---------------- | --------------
+100              | 0.11
+200              | 0.37
+300              | 0.72
+500              | 2.14
+1000             | 9.01
+
+## A note on naming
+
+This gem was authored in the UK, where color is usually spelt colour. However, this gem depends on two others ([color](http://color.rubyforge.org/) and [colorscore](https://github.com/quadule/colorscore)) that spell it without the u, so for the sake of consistency it's spelt as color in this gem too.
+
+## Contributing
+
+1. Fork it ( https://github.com/ms-digital-labs/color_sort/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 new Pull Request

data/Rakefile

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

data/color_sort.gemspec

@@ -0,0 +1,27 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'color_sort/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "color_sort"
+  spec.version       = ColorSort::VERSION
+  spec.authors       = ["Pip Taylor"]
+  spec.email         = ["pip@evilgeek.co.uk"]
+  spec.summary       = %q{Sorts colors perceptually}
+  spec.homepage      = "https://github.com/ms-digital-labs/color_sort"
+  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 "colorscore"
+  spec.add_dependency "color"
+
+  spec.add_development_dependency "bundler", "~> 1.5"
+  spec.add_development_dependency "rake"
+  spec.add_development_dependency "rspec"
+  spec.add_development_dependency "rspec-radar"
+end

data/lib/color_sort/color_space_converter.rb

@@ -0,0 +1,8 @@
+module ColorSort
+  module ColorSpaceConverter
+    def self.hex_rgb_to_lab(hex)
+      rgb = Color::RGB.from_html(hex)
+      Colorscore::Metrics.xyz_to_lab(*Colorscore::Metrics.rgb_to_xyz(rgb))
+    end
+  end
+end

data/lib/color_sort/distance.rb

@@ -0,0 +1,16 @@
+require "colorscore"
+
+module ColorSort
+  module Distance
+    def self.ciede2000(lab_color_a, lab_color_b)
+      cache_key = [lab_color_a, lab_color_b].sort
+      ciede2000_cache[cache_key] ||=
+        Colorscore::Metrics.delta_e_cie_2000(*lab_color_a, *lab_color_b)
+    end
+
+  private
+    def self.ciede2000_cache
+      @ciede2000_cache ||= {}
+    end
+  end
+end

data/lib/color_sort/ordering.rb

@@ -0,0 +1,41 @@
+require "color_sort/distance"
+
+module ColorSort
+  class Ordering
+    attr_reader :colors
+
+    def initialize
+      @colors = []
+    end
+
+    def add_lab_color(color)
+      if colors.size < 2
+        colors << color
+      else
+        min_delta = distance(color, colors.first)
+        min_delta_index = 0
+
+        (1...colors.size).each do |i|
+          remove_distance = distance(colors[i-1], colors[i])
+          add_distance = distance(colors[i-1], color) + distance(color, colors[i])
+          delta = add_distance - remove_distance
+          if delta < min_delta
+            min_delta = delta
+            min_delta_index = i
+          end
+        end
+
+        if distance(colors.last, color) < min_delta
+          min_delta_index = colors.size
+        end
+
+        colors.insert(min_delta_index, color)
+      end
+    end
+
+  private
+    def distance(color_a, color_b)
+      ColorSort::Distance.ciede2000(color_a, color_b)
+    end
+  end
+end

data/lib/color_sort/sorter.rb

@@ -0,0 +1,35 @@
+module ColorSort
+  class Sorter
+    def initialize(colors)
+      @colors = colors
+    end
+
+    def sorted
+      ordering.colors.map { |lab_color|
+        color_map[lab_color]
+      }
+    end
+
+  private
+    attr_reader :colors
+
+    def color_map
+      @color_map ||= colors.each_with_object({}) { |hex_rgb_color, hash|
+        lab_color = ColorSort::ColorSpaceConverter.hex_rgb_to_lab(hex_rgb_color)
+        hash[lab_color] = hex_rgb_color
+      }
+    end
+
+    def lab_colors
+      @lab_colors ||= colors.map { |hex_rgb_color|
+        ColorSort::ColorSpaceConverter.hex_rgb_to_lab(hex_rgb_color)
+      }
+    end
+
+    def ordering
+      @ordering ||= lab_colors.each_with_object(Ordering.new) { |lab_color, ordering|
+        ordering.add_lab_color(lab_color)
+      }
+    end
+  end
+end

data/lib/color_sort/version.rb

@@ -0,0 +1,3 @@
+module ColorSort
+  VERSION = "1.0.0"
+end

data/lib/color_sort.rb

@@ -0,0 +1,11 @@
+require "color_sort/version"
+require "color_sort/ordering"
+require "color_sort/distance"
+require "color_sort/color_space_converter"
+require "color_sort/sorter"
+
+module ColorSort
+  def self.sort(colors)
+    Sorter.new(colors).sorted
+  end
+end

data/spec/color_sort_spec.rb

@@ -0,0 +1,13 @@
+require 'spec_helper'
+
+describe ColorSort do
+  it 'should have a version number' do
+    ColorSort::VERSION.should_not be_nil
+  end
+
+  describe ".sort" do
+    it "passes the colors to ColorSort::Sorter and calls #sorted" do
+      expect(ColorSort.sort(["#123456"])).to eq(["#123456"])
+    end
+  end
+end

data/spec/lib/color_space_converter_spec.rb

@@ -0,0 +1,23 @@
+require "spec_helper"
+
+describe ColorSort::ColorSpaceConverter do
+  describe "#hex_rgb_to_lab" do
+    subject { ColorSort::ColorSpaceConverter }
+
+    let(:expected_lab_result) {
+      [21.041610053894317, 1.0523062624117063, -24.099168114444936]
+    }
+
+    context "with a preceeding #" do
+      it "converts hex RGB color to LAB" do
+        expect(subject.hex_rgb_to_lab("#123456")).to eq(expected_lab_result)
+      end
+    end
+
+    context "with a preceeding #" do
+      it "converts hex RGB color to LAB" do
+        expect(subject.hex_rgb_to_lab("123456")).to eq(expected_lab_result)
+      end
+    end
+  end
+end

data/spec/lib/distance_spec.rb

@@ -0,0 +1,24 @@
+require "spec_helper"
+
+describe ColorSort::Distance do
+  describe "#ciede2000" do
+    let(:distance) { double(:distance) }
+
+    it "splats the lab colors and passes them to Colorscore" do
+      expect(Colorscore::Metrics).to receive(:delta_e_cie_2000)
+                                      .with(1, 2, 3, 4, 5, 6)
+
+      ColorSort::Distance.ciede2000([1, 2, 3], [4, 5, 6])
+    end
+
+    it "only calls in to Colorscore once for each pair of colors" do
+      expect(Colorscore::Metrics).to receive(:delta_e_cie_2000)
+                                      .with(1, 2, 3, 4, 5, 6)
+                                      .once
+                                      .and_return(distance)
+
+      expect(ColorSort::Distance.ciede2000([1, 2, 3], [4, 5, 6])).to eq(distance)
+      expect(ColorSort::Distance.ciede2000([4, 5, 6], [1, 2, 3])).to eq(distance)
+    end
+  end
+end

data/spec/lib/ordering_spec.rb

@@ -0,0 +1,77 @@
+require "spec_helper"
+
+describe ColorSort::Ordering do
+  let(:red) { double(:red) }
+  let(:green) { double(:green) }
+  let(:blue) { double(:blue) }
+
+  before do
+    set_distance(red, red, 0)
+    set_distance(green, green, 0)
+    set_distance(blue, blue, 0)
+
+    set_distance(red, blue, 1)
+    set_distance(blue, green, 2)
+    set_distance(red, green, 3)
+  end
+
+  describe "#add_lab_color" do
+    context "with an empty ordering" do
+      it "adds the color to the end of the array" do
+        subject.add_lab_color(red)
+
+        expect(subject.colors).to eq([red])
+      end
+    end
+
+    context "with one color in the ordering" do
+      it "adds the color to the end of the array" do
+        subject.add_lab_color(red)
+        subject.add_lab_color(green)
+
+        expect(subject.colors).to eq([red, green])
+      end
+    end
+
+    context "with multiple colors in the ordering" do
+      context "best position is at the beginning" do
+        it "adds the color in the position that minimises total distance" do
+          subject.add_lab_color(blue)
+          subject.add_lab_color(green)
+          subject.add_lab_color(red)
+
+          expect(subject.colors).to eq([red, blue, green])
+        end
+      end
+
+      context "best position is in the middle" do
+        it "adds the color in the position that minimises total distance" do
+          subject.add_lab_color(red)
+          subject.add_lab_color(green)
+          subject.add_lab_color(blue)
+
+          expect(subject.colors).to eq([red, blue, green])
+        end
+      end
+
+      context "best position is at the end" do
+        it "adds the color in the position that minimises total distance" do
+          subject.add_lab_color(green)
+          subject.add_lab_color(blue)
+          subject.add_lab_color(red)
+
+          expect(subject.colors).to eq([green, blue, red])
+        end
+      end
+    end
+  end
+
+  def set_distance(color_a, color_b, distance)
+    allow(ColorSort::Distance).to receive(:ciede2000)
+                                    .with(color_a, color_b)
+                                    .and_return(distance)
+    allow(ColorSort::Distance).to receive(:ciede2000)
+                                    .with(color_b, color_a)
+                                    .and_return(distance)
+  end
+end

data/spec/lib/sorter_spec.rb

@@ -0,0 +1,20 @@
+require "spec_helper"
+
+describe ColorSort::Sorter do
+  describe "#sorted" do
+    let(:red_1) { "#ff0000" }
+    let(:red_2) { "#cc0000" }
+    let(:green_1) { "#00ff00" }
+    let(:green_2) { "#00cc00" }
+    let(:blue_1) { "#0000ff" }
+    let(:blue_2) { "#0000cc" }
+
+    let(:colors) { [red_1, blue_1, green_1, red_2, blue_2, green_2] }
+
+    subject { described_class.new(colors) }
+
+    it "orders the colors perceptually" do
+      expect(subject.sorted).to eq([red_1, red_2, blue_2, blue_1, green_2, green_1])
+    end
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,3 @@
+$LOAD_PATH.unshift File.expand_path('../../lib', __FILE__)
+require 'color_sort'
+require "rspec/radar"

metadata

@@ -0,0 +1,153 @@
+--- !ruby/object:Gem::Specification
+name: color_sort
+version: !ruby/object:Gem::Version
+  version: 1.0.0
+platform: ruby
+authors:
+- Pip Taylor
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-04-29 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: colorscore
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: color
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.5'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: rspec-radar
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- pip@evilgeek.co.uk
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".rspec"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- color_sort.gemspec
+- lib/color_sort.rb
+- lib/color_sort/color_space_converter.rb
+- lib/color_sort/distance.rb
+- lib/color_sort/ordering.rb
+- lib/color_sort/sorter.rb
+- lib/color_sort/version.rb
+- spec/color_sort_spec.rb
+- spec/lib/color_space_converter_spec.rb
+- spec/lib/distance_spec.rb
+- spec/lib/ordering_spec.rb
+- spec/lib/sorter_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/ms-digital-labs/color_sort
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.2.2
+signing_key: 
+specification_version: 4
+summary: Sorts colors perceptually
+test_files:
+- spec/color_sort_spec.rb
+- spec/lib/color_space_converter_spec.rb
+- spec/lib/distance_spec.rb
+- spec/lib/ordering_spec.rb
+- spec/lib/sorter_spec.rb
+- spec/spec_helper.rb