image_svd 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 8c7595bcaa0980e88306b17c334eb96e97cc9d03
+  data.tar.gz: e5fd5e67bd0e4ae9138d736640aff240ea6d1e28
+SHA512:
+  metadata.gz: c5c5d15ea75980e4c0a785695e9c84909b6c8ae6796b18d0ee7484c76961e72cc8ded4c6b6261058058a125b88a3054a290652c35076a97739ce3c03ca7e5eef
+  data.tar.gz: 065244d4de86a95ea5e8cb6da141f177b23d94480a817f6a6a8b7eaa9e3ec0839284ce2dae41684efb1cb9a4d1ee573b2aced5cbc7abf3926e6c43e246b6cdc8

data/.gitignore

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

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Ilya Kavalerov
+
+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,29 @@
+# ImageSvd
+
+TODO: Write a gem description
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'image_svd'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install image_svd
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+1. Fork it ( http://github.com/<my-github-username>/image_svd/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,10 @@
+# encoding: utf-8
+
+require 'rubygems'
+require 'bundler/gem_tasks'
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new
+
+task test: :spec
+task default: :spec

data/bin/image_svd

@@ -0,0 +1,31 @@
+#!/usr/bin/env ruby
+# encoding: utf-8
+
+if RUBY_VERSION >= '1.9.2'
+  $LOAD_PATH.unshift(File.dirname(File.realpath(__FILE__)) + '/../lib')
+
+  # test for presence of imagemagick dependency
+  imagemagick_location = `which convert`
+  if imagemagick_location == ''
+    puts 'Image Svd requires the cmd line utility imagemagick.\
+      Install it with: brew install imagemagick'
+    exit(-1)
+  end
+
+  require 'image_svd'
+  require 'benchmark'
+  require 'trollop'
+
+  cli = ImageSvd::CLI.new
+
+  time = Benchmark.realtime do
+    opts = Trollop.options(&ImageSvd::Options.get)
+    cli.run(opts)
+  end
+
+  puts "Image svd finished in #{time} seconds"
+  exit(0)
+else
+  puts 'Image svd only supports Ruby versions 1.9.2 and above'
+  exit(-1)
+end

data/image_svd.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'image_svd/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = 'image_svd'
+  spec.version       = ImageSvd::VERSION
+  spec.authors       = ['Ilya Kavalerov']
+  spec.email         = ['ilya@artsymail.com']
+  spec.summary       = 'Compress images with Linear Algebra.'
+  spec.description   = <<-EOF
+    Break down grayscale image matricies into their
+    singular value decomposition. Space saving, but CPU intensive.
+  EOF
+  spec.homepage      = 'https://github.com/ilyakava/image_svd'
+  spec.license       = 'MIT'
+
+  spec.files         = `git ls-files -z`.split("\x0")
+  spec.executables   = spec.files.grep(/^bin\//) { |f| File.basename(f) }
+  spec.test_files    = spec.files.grep(/^(test|spec|features)\//)
+  spec.require_paths = ['lib']
+
+  spec.add_runtime_dependency 'pnm'
+  spec.add_runtime_dependency 'trollop', '~> 2.0'
+  spec.add_development_dependency 'bundler', '~> 1.5'
+  spec.add_development_dependency 'rake'
+  spec.add_development_dependency 'pry'
+  spec.add_development_dependency 'rspec'
+end

data/lib/image_svd.rb

@@ -0,0 +1,5 @@
+# encoding: utf-8
+
+require 'image_svd/version'
+require 'image_svd/cli'
+require 'image_svd/image_matrix'

data/lib/image_svd/cli.rb

@@ -0,0 +1,74 @@
+# encoding: utf-8
+
+module ImageSvd
+  # This class is responsible for handling the command line interface
+  class CLI
+    # The entry point for the application logic
+    # rubocop:disable MethodLength
+    def run(opts)
+      if opts[:read] == true
+        app = ImageSvd::ImageMatrix.new_from_svd_savefile(opts[:input_file])
+        app.to_image(opts[:output_name])
+      else
+        app = ImageSvd::ImageMatrix.new(opts[:num_singular_values])
+        app.read_image(opts[:input_file])
+        if opts[:archive] == true
+          app.save_svd(opts[:output_name])
+        elsif opts[:convert] == true
+          app.to_image(opts[:output_name])
+        end
+      end
+    end
+  end
+  # rubocop:enable MethodLength
+
+  # This module holds custom behavior for dealing with the gem trollop
+  module Options
+    # rubocop:disable MethodLength
+    def self.get
+      proc do
+        version "Image Svd #{ImageSvd::VERSION} (c) 2014 Ilya Kavalerov"
+        banner <<-EOS
+          Image Svd is a utilty that performs Singular Value Decomposition
+          on a grayscale image. It can be useful for compressing images, or
+          creating interesting visual effects to distort images when
+          compression is set very high.
+
+          Usage:
+                 image_svd [options]
+          where [options] are:
+        EOS
+        opt :input_file,
+            'An input file (Preferably a jpg).',
+            type: :io,
+            required: true
+        opt :num_singular_values,
+            'The number of singular values to keep for an image. Lower'\
+              ' numbers mean lossier compression; smaller files and more'\
+              ' distorted images.',
+            default: 50,
+            short: '-n'
+        opt :output_name,
+            'A path/name for an output file (Extension will be ignored).'\
+              ' If no path/name is provided, a file will be written in'\
+              ' the current directory',
+            default: 'svd_image_output',
+            short: '-o'
+        opt :convert,
+            'Convert the input file now.',
+            default: true,
+            short: '-c'
+        opt :archive,
+            'Save the Image Svd archive without converting the input image.',
+            default: false,
+            short: '-a'
+        opt :read,
+            'Read an Image Svd archive (*.svdim) and output the image'\
+              ' it contains.',
+            default: false,
+            short: '-r'
+      end
+    end
+    # rubocop:enable MethodLength
+  end
+end

data/lib/image_svd/image_matrix.rb

@@ -0,0 +1,127 @@
+require 'matrix'
+require 'json'
+require 'pnm'
+
+module ImageSvd
+  # This class is responsible for almost everything :(
+  # Reading an image or archive to a matrix
+  # Saving a matrix to an image
+  # Performing Singular Value Decomposition on a matrix
+  class ImageMatrix
+    # rubocop:disable SymbolName
+    # rubocop:disable VariableName
+    attr_reader :num_singular_values
+    attr_accessor :sigma_vTs, :us, :m, :n
+
+    def initialize(num_singular_values)
+      @num_singular_values = num_singular_values
+    end
+
+    def read_image(image_path)
+      puts 'Reading image and converting to matrix...'
+      intermediate = extension_swap(image_path.path, 'pgm')
+      %x(convert #{image_path.path} #{intermediate})
+      image = PNM.read intermediate
+      decompose Matrix[*image.pixels]
+      %x(rm #{intermediate})
+      self
+    end
+
+    # @todo abstract this to another class
+    # always place the new extension, even if there is nothing to swap out
+    def extension_swap(path, new_ext, suffix = '')
+      head = path.gsub(/\..{1,5}$/, '')
+      "#{head}#{suffix}.#{new_ext}"
+    end
+
+    # The most time consuming method
+    # Launches the decomposition and saves the two lists
+    # of vectors needed to reconstruct the image
+    # rubocop:disable MethodLength
+    def decompose(m_A)
+      m_AT = m_A.transpose
+      @m, @n = m_A.to_a.length, m_A.to_a.first.length
+      m_ATA = m_AT * m_A
+      # linear regression from several images over 200px wide
+      eta = (0 < (t = (0.0003541 * (@m * @n) - 10.541)) ? t : 0)
+      puts "Searching for eigenvalues... Estimated Time: #{eta.floor} seconds"
+      dcmp = Matrix::EigenvalueDecomposition.new(m_ATA)
+      evs = dcmp.eigenvalues
+      # eigenvectors are already normalized and in same order as eigenvalues
+      sorted_eigenvectors = dcmp.eigenvectors.each_with_index
+        .sort_by { |_v, i| -evs[i] }
+        .map { |v, _idx| v }
+      both = (0...@num_singular_values).map do |idx|
+        u = sorted_eigenvectors[idx]
+        sigma_vT = (m_A * u).covector
+        [u, sigma_vT]
+      end
+      @sigma_vTs = both.map { |p| p.last }
+      @us = both.map { |p| p.first }
+    end
+    # rubocop:enable MethodLength
+
+    def reconstruct_matrix
+      zero_matrix = Matrix[*Array.new(@n) { Array.new(@m) { 0 } }]
+      (0...@num_singular_values).reduce(zero_matrix) do |acc, idx|
+        acc + (@us[idx] * @sigma_vTs[idx])
+      end.transpose
+    end
+
+    def to_image(path)
+      out_path = extension_swap(path, 'jpg')
+      intermediate = extension_swap(path, 'pgm', '_tmp_outfile')
+      cleansed_matrix = matrix_to_valid_pixels(reconstruct_matrix)
+      PNM::Image.new(cleansed_matrix).write(intermediate)
+      %x(convert #{intermediate} #{out_path})
+      %x(rm #{intermediate})
+      true
+    end
+
+    # conforms a matrix to pnm requirements for pixels: positive integers
+    # rubocop:disable MethodLength
+    def matrix_to_valid_pixels(matrix)
+      matrix.to_a.map do |row|
+        row.map do |number|
+          rounded = number.round
+          if rounded > 255
+            255
+          elsif rounded < 0
+            0
+          else
+            rounded
+          end
+        end
+      end
+    end
+    # rubocop:enable MethodLength
+
+    def save_svd(path)
+      out_path = extension_swap(path, 'svdim')
+      string = {
+        'sigma_vTs' => @sigma_vTs.map(&:to_a),
+        'us' => @us.map(&:to_a),
+        'm' => @m,
+        'n' => @n
+      }.to_json
+      File.open(out_path, 'w') do |f|
+        f.puts string
+      end
+    end
+
+    # @todo error handling code here
+    # @todo serialization is kind of silly as is
+    def self.new_from_svd_savefile(path)
+      h = JSON.parse(File.open(path, &:readline))
+      instance = new(h['sigma_vTs'].length)
+      instance.sigma_vTs = h['sigma_vTs']
+        .map { |arr| Vector[*arr.flatten].covector }
+      instance.us = h['us'].map { |arr| Vector[*arr.flatten] }
+      instance.n = h['n']
+      instance.m = h['m']
+      instance
+    end
+    # rubocop:enable SymbolName
+    # rubocop:enable VariableName
+  end
+end

data/lib/image_svd/version.rb

@@ -0,0 +1,4 @@
+# This module holds the gem's code
+module ImageSvd
+  VERSION = '0.0.1'
+end

data/spec/cli_spec.rb

@@ -0,0 +1,58 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe 'CLI' do
+  describe 'integration spec' do
+    let(:cli) { ImageSvd::CLI.new }
+    let(:orig) { File.new('./spec/fixtures/2x2.jpg') }
+
+    it 'converts an image without too great errors' do
+      conv = './spec/fixtures/svd_image_output'
+      cli.run(
+        input_file: orig,
+        convert: true,
+        num_singular_values: 2,
+        output_name: conv
+      )
+      i = ImageSvd::ImageMatrix.new(2)
+      i.read_image(orig)
+      i2 = ImageSvd::ImageMatrix.new(2)
+      i2.read_image(File.new("#{conv}.jpg"))
+      diff_matrix = i.reconstruct_matrix - i2.reconstruct_matrix
+      diff_matrix.to_a.flatten.each do |diff_component|
+        diff_component.abs.should be < 5
+      end
+
+      # cleanup
+      %x(rm #{conv}.jpg)
+    end
+
+    it 'archives, reads, and converts an image without too great errors' do
+      conv = './spec/fixtures/svd_image_output'
+      # archive
+      cli.run(
+        input_file: orig,
+        archive: true,
+        num_singular_values: 2,
+        output_name: conv
+      )
+      # read archive and write and image
+      cli.run(
+        input_file: "#{conv}.svdim",
+        read: true,
+        output_name: "#{conv}_2"
+      )
+      i = ImageSvd::ImageMatrix.new(2)
+      i.read_image(orig)
+      i2 = ImageSvd::ImageMatrix.new(2)
+      i2.read_image(File.new("#{conv}_2.jpg"))
+      diff_matrix = i.reconstruct_matrix - i2.reconstruct_matrix
+      diff_matrix.to_a.flatten.each do |diff_component|
+        diff_component.abs.should be < 5
+      end
+      # cleanup
+      %x(rm #{conv}_2.jpg #{conv}.svdim)
+    end
+  end
+end

data/spec/image_matrix_spec.rb

@@ -0,0 +1,17 @@
+# encoding: utf-8
+
+require 'spec_helper'
+
+describe ImageSvd::ImageMatrix do
+  before :each do
+    @m = Matrix[[0, 1, 1], [1, 1, 0]]
+  end
+
+  it 'recovers a 2x3 matrix' do
+    i = ImageSvd::ImageMatrix.new(2)
+    i.decompose(@m)
+    rounded_matrix = Matrix[*i.matrix_to_valid_pixels(i.reconstruct_matrix)]
+    # due to numerical instability, even a 2x3 matrix needs to be rounded
+    @m.should eq(rounded_matrix)
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,11 @@
+# encoding: utf-8
+
+$LOAD_PATH.unshift(File.dirname(__FILE__) + '/../lib')
+require 'image_svd'
+require 'pry'
+
+RSpec.configure do |config|
+  config.treat_symbols_as_metadata_keys_with_true_values = true
+  config.run_all_when_everything_filtered = true
+  config.filter_run :focus
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: image_svd
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Ilya Kavalerov
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2014-05-21 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: pnm
+  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: trollop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.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: pry
+  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'
+description: |2
+      Break down grayscale image matricies into their
+      singular value decomposition. Space saving, but CPU intensive.
+email:
+- ilya@artsymail.com
+executables:
+- image_svd
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/image_svd
+- image_svd.gemspec
+- lib/image_svd.rb
+- lib/image_svd/cli.rb
+- lib/image_svd/image_matrix.rb
+- lib/image_svd/version.rb
+- spec/cli_spec.rb
+- spec/fixtures/2x2.jpg
+- spec/image_matrix_spec.rb
+- spec/spec_helper.rb
+homepage: https://github.com/ilyakava/image_svd
+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.1
+signing_key: 
+specification_version: 4
+summary: Compress images with Linear Algebra.
+test_files:
+- spec/cli_spec.rb
+- spec/fixtures/2x2.jpg
+- spec/image_matrix_spec.rb
+- spec/spec_helper.rb