sqed 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 5e49c9eab8df51ee536b44949c954468cb3d7705
+  data.tar.gz: 342dd83674453cc664ddff07ed5dad5b1f897507
+SHA512:
+  metadata.gz: dfc0fd88f66f86da1e0f1a848c91fa13afdf678a7b07dcea1cd1cfbab8a3962a862399f67c09379f6939b38de51f21d69ffd948c4b89e6ffa97fe76a4c8177bf
+  data.tar.gz: 2b3eb4475971484a0052c2ca000962f6d9818394fff227edb6a5140c437822166fc81845d592f295bd82b65fb2bbd9d4be70ee6f46b9340991fa63df90d11c6b

data/.gitignore

@@ -0,0 +1,27 @@
+*.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
+*.swp
+.idea/
+local/
+foo*.jpg
+SessionID_BarcodeImage.JPG
+
+/*.jpg

data/.rspec

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

data/.travis.yml

@@ -0,0 +1,18 @@
+
+#bundler_args: --without development
+language: ruby
+rvm:
+  - 2.1.2
+#before_install:
+#  - sudo add-apt-repository -y ppa:moti-p/cc
+#  - sudo apt-get update
+#  - sudo apt-get -y --reinstall install imagemagick
+#  - printf "\n" | pecl install imagick-beta
+branches:
+  only:
+    - master
+notifications:
+  email:
+    - diapriid@gmail.com 
+    - jrflood@illinois.edu
+  on_failure: change

data/Gemfile

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

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2014 Matt Yoder
+
+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,36 @@
+
+[![Continuous Integration Status][1]][2]
+
+# Sqed
+
+Stub for a gem that supports specimen digitization from images.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+    gem 'sqed'
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install sqed
+
+## Usage
+
+TODO: Write usage instructions here
+
+## Contributing
+
+1. Fork it ( http://github.com/SpeciesFileGroup/sqed/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
+
+[1]: https://secure.travis-ci.org/SpeciesFileGroup/sqed.png?branch=master
+[2]: http://travis-ci.org/SpeciesFileGroup/sqed?branch=master
+

data/Rakefile

@@ -0,0 +1,9 @@
+#!/usr/bin/env rake
+require "bundler/gem_tasks"
+
+require 'rspec/core/rake_task'
+
+RSpec::Core::RakeTask.new('spec')
+
+task :default => :spec
+

data/lib/sqed.rb

@@ -0,0 +1,111 @@
+# encoding: UTF-8
+
+recent_ruby = RUBY_VERSION >= '2.1.1'
+raise "IMPORTANT: sqed gem requires ruby >= 2.1.1" unless recent_ruby
+
+require "RMagick"
+include Magick
+require_relative 'sqed_config'
+require_relative "sqed/extractor"
+require_relative "sqed/result"
+
+# Instants take the following
+# 1) A base image @image
+# 2) A target extraction pattern
+#
+# Return a Sqed::Result
+#    
+#     a = Sqed.new(pattern: :right_t, image: image)
+#     b = a.result # => Sqed::Result instance
+#
+class Sqed
+  # initial image which is an instance of ImageMagick::image, containing background and stage, or just stage
+  attr_accessor :image
+
+  # the particular arrangement of the content, a symbol taken from SqedConfig::EXTRACTION_PATTERNS
+  attr_accessor :pattern
+
+  # the image that is the cropped content for parsing
+  attr_accessor :stage_image, :stage_boundary, :boundaries, :auto_detect_border, :boundary_color
+
+  def initialize(image: image, pattern: pattern, auto_detect_border: true, boundary_color: :green)
+    @image = image
+
+    @boundaries = nil
+    @stage_boundary = Sqed::Boundaries.new(:internal_box) # a.k.a. stage
+
+    @auto_detect_border = auto_detect_border
+
+    @pattern = pattern
+    @pattern ||= :standard_cross
+
+    @boundary_color = boundary_color
+
+    set_stage_boundary if @auto_detect_border && @image
+  end
+
+  # This handles the case of
+  #   s = Sqed.new()  # no image: @some_image on init
+  #   s.image = @some_image
+  #
+  def image=(value)
+    @image = value
+    set_stage_boundary if @auto_detect_border 
+  end
+
+  def boundaries(force = false)
+    @boundaries = get_section_boundaries if @boundaries.nil? || force
+    @boundaries
+  end
+
+  def native_boundaries
+    # check for @boundaries.complete first? OR handle partial detections  ?!
+    if @boundaries.complete
+      @boundaries.offset(@stage_boundary)
+    else
+      nil
+    end 
+  end
+
+  def stage_image
+    crop_image if @stage_boundary.complete && @stage_image.nil?
+    @stage_image 
+  end
+
+  def crop_image
+    if @stage_boundary.complete
+      @stage_image = @image.crop(*@stage_boundary.for(SqedConfig.index_for_section_type(:stage, :stage)))
+    else
+      @stage_image = @image 
+    end
+  end
+
+  def result
+    return false if @image.nil? || @pattern.nil? 
+    crop_image
+    extractor = Sqed::Extractor.new(
+      boundaries: @boundaries,
+      layout: SqedConfig::EXTRACTION_PATTERNS[@pattern][:layout],
+      image: @stage_image)
+    extractor.result
+  end
+
+  protected
+
+  def set_stage_boundary
+    @stage_boundary = Sqed::BoundaryFinder::StageFinder.new(image: @image).boundaries
+    if !@stage_boundary.complete
+      @stage_boundary.coordinates[0] = [0, 0, @image.columns, @image.rows] 
+    end
+  end
+
+  def get_section_boundaries
+    boundary_finder_class = SqedConfig::EXTRACTION_PATTERNS[@pattern][:boundary_finder]
+    options = {image: stage_image}
+    options.merge!( layout: SqedConfig::EXTRACTION_PATTERNS[@pattern][:layout] ) unless  boundary_finder_class.name == 'Sqed::BoundaryFinder::CrossFinder'
+    options.merge!( boundary_color: @boundary_color) if  boundary_finder_class.name == 'Sqed::BoundaryFinder::ColorLineFinder'
+
+    boundary_finder_class.new(options).boundaries
+  end
+
+end

data/lib/sqed/boundaries.rb

@@ -0,0 +1,79 @@
+# An Sqed::Boundaries is a simple wrapper for a hash that contains the co-ordinates for each section of a layout.
+
+# Layouts are Hashes defined in EXTRACTION_PATTERNS[<pattern>][<layout>]
+# 
+class Sqed::Boundaries 
+  include Enumerable
+
+  # stores a hash
+  # References the section by integer index!
+  # In the pattern integer => [x1,y1, width, height] (ImageMagick convention rectangle descriptors)
+  # e.g.
+  #   0 => [10,10,40,40]
+  attr_reader :coordinates
+
+  # An Sqed::Config::EXTRACTION_PATTERN layout
+  attr_accessor :layout
+
+  # Whether or not the last method to populate this object passed fully
+  attr_accessor :complete
+
+  def initialize(layout = nil)
+    @complete = false
+
+    @layout = layout
+    @coordinates = {}
+    initialize_coordinates if !@layout.nil?
+  end
+
+  def initialize_coordinates
+    SqedConfig::LAYOUTS[@layout].each do |k|
+      @coordinates.merge!(k => [nil, nil, nil, nil] )
+    end
+  end
+
+  def offset(boundary)
+    b = Sqed::Boundaries.new()    # the idea here is to create a deep copy of self, offsetting by boundary as we go
+    (0..self.coordinates.length - 1).each do |i|
+      b.coordinates[i] = []  # create the instance of the i-th coordinate, then populate it
+      b.coordinates[i][0] = self.x_for(i) + boundary.x_for(0)
+      b.coordinates[i][1] = self.y_for(i) + boundary.y_for(0)
+      b.coordinates[i][2] = self.width_for(i)
+      b.coordinates[i][3] = self.height_for(i)
+    end
+    b.complete = self.complete
+    b
+  end
+
+  def for(section)
+    @coordinates[section]
+  end
+
+  def each(&block)
+    @coordinates.each do |section_index, coords|
+      block.call([section_index, coords])
+    end
+  end
+
+  # Overrides Enumerable
+  def count
+    @coordinates.length
+  end
+
+  def x_for(index)
+    @coordinates[index][0]
+  end
+
+  def y_for(index)
+    @coordinates[index][1]
+  end
+
+  def width_for(index)
+    @coordinates[index][2]
+  end
+
+  def height_for(index)
+    @coordinates[index][3]
+  end
+
+end

data/lib/sqed/boundary_finder.rb

@@ -0,0 +1,150 @@
+require 'RMagick'
+
+# Sqed Boundary Finders find boundaries on images and return co-ordinates of those boundaries.  They do not
+# return derivative images. Finders operate on cropped images, i.e. only the "stage".
+#
+class Sqed::BoundaryFinder
+  # the passed image
+  attr_reader :img
+
+  # a symbol from SqedConfig::LAYOUTS
+  attr_reader :layout
+
+  # A Sqed::Boundaries instance, stores the coordinates of all of the layout sections 
+  attr_reader :boundaries
+
+  def initialize(image: image, layout: layout)
+    raise 'No layout provided.' if layout.nil?
+    raise 'No image provided.' if image.nil? || image.class != Magick::Image
+
+    @layout = layout
+    @img = image
+    true
+  end
+
+  # Returns a Sqed::Boundaries instance initialized to the number of sections in the passed layout.
+  def boundaries
+    @boundaries ||= Sqed::Boundaries.new(@layout)
+  end
+
+  # @return
+  #   the column (x position) in the middle of the single green vertical line dividing the stage
+  #
+  # @param image
+  #   the image to sample
+  #
+  # @param sample_subdivision_size
+  #   an Integer, the distance in pixels b/w samples
+  #
+  # @param sample_cutoff_factor: (0.0-1.0)
+  #   if provided over-rides the default cutoff calculation by reducing the number of pixels required to be considered a border hit
+  #     - for example, if you have an image of height 100 pixels, and a sample_subdivision_size of 10, and a sample_cutoff_factor of .8 
+  #       then only posititions with 8 ((100/10)*.8) or more hits
+  #     - when nil the cutoff defaults to the maximum of the pairwise difference between hit counts
+  #
+  # @param scan
+  #   (:rows|:columns), :rows finds vertical borders, :columns finds horizontal borders
+  #
+  def self.color_boundary_finder(image: image, sample_subdivision_size: 10, sample_cutoff_factor: nil, scan: :rows, boundary_color: :green) 
+    border_hits = {}
+    samples_to_take = (image.send(scan) / sample_subdivision_size).to_i - 1
+
+    (0..samples_to_take).each do |s|
+      # Create a sample image a single pixel tall
+      if scan == :rows
+        j = image.crop(0, s * sample_subdivision_size, image.columns, 1)
+      elsif scan == :columns
+        j = image.crop(s * sample_subdivision_size, 0, 1, image.rows)
+      else
+        raise
+      end
+
+      j.each_pixel do |pixel, c, r|
+        index = ( (scan == :rows) ? c : r)
+
+        # Our hit metric is dirt simple, if there is some percentage more of the boundary_color than the others, count + 1 for that column 
+        if send("is_#{boundary_color}?", pixel) 
+          # we have already hit that column previously, increment
+          if border_hits[index]
+            border_hits[index] += 1
+            # initialize the newly hit column 1 
+          else
+            border_hits[index] = 1
+          end
+        end
+      end
+    end
+
+    return nil if border_hits.length < 2
+
+    if sample_cutoff_factor.nil?
+      cutoff = max_difference(border_hits.values)
+    else
+      cutoff = (samples_to_take * sample_cutoff_factor).to_i
+    end
+
+    frequency_stats(border_hits, cutoff)
+  end
+
+  def self.is_green?(pixel)
+    (pixel.green > pixel.red*1.2) && (pixel.green > pixel.blue*1.2)  
+  end
+
+  def self.is_blue?(pixel)
+    (pixel.blue > pixel.red*1.2) && (pixel.blue > pixel.green*1.2)   
+  end
+
+  def self.is_red?(pixel)
+    (pixel.red > pixel.blue*1.2) && (pixel.red > pixel.green*1.2)   
+  end
+
+  def self.is_black?(pixel)
+    black_threshold = 65535*0.15    #tune for black
+    (pixel.red < black_threshold) &&  (pixel.blue < black_threshold) &&  (pixel.green < black_threshold)
+  end
+
+  # Takes a frequency hash of position => count key/values and returns
+  # the median position of all positions that have a count greater than the cutoff
+  def self.frequency_stats(frequency_hash, sample_cutoff = 0)
+    return nil if sample_cutoff.nil? ||  sample_cutoff < 1 
+    hit_ranges = [] 
+
+    frequency_hash.each do |position, count|
+      if count >= sample_cutoff 
+        hit_ranges.push(position)
+      end
+    end
+
+    return nil if hit_ranges.size < 3
+
+    # we have to sort because the keys (positions) we examined came unordered from a hash originally
+    hit_ranges.sort!
+
+    # return the position exactly in the middle of the array
+    [hit_ranges.first, hit_ranges[(hit_ranges.length / 2).to_i], hit_ranges.last]
+  end
+
+  # Returns an Integer, the maximum of the pairwise differences of the values in the array
+  # For example, given
+  #   [1,2,3,9,6,2,0]
+  # The resulting pairwise array is
+  #   [1,1,6,3,4,2]
+  # The max (value returned) is
+  #   6
+  def self.max_pairwise_difference(array)
+    (0..array.length-2).map{|i| (array[i] - array[i+1]).abs }.max
+  end
+
+  def self.max_difference(array)
+    array.max - array.min
+  end
+
+  def self.derivative_signs(array)
+    (0..array.length-2).map { |i| (array[i+1] - array[i]) <=> 0 }
+  end
+
+  def self.derivative(array)
+    (0..array.length-2).map { |i| array[i+1] - array[i] }
+  end
+
+end