sqed 0.3.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 764316ed1537a871299cafd5c1f1df6045c525ec
-  data.tar.gz: ebc12360ba5d9eabe0b895c4238d7785bb1d8d4f
+  metadata.gz: 97003b6e21e84313180a638df393052b18a7eb25
+  data.tar.gz: e125134f5ed864b06fd4b8280228261e7d1eac40
 SHA512:
-  metadata.gz: dcee70b54a7cc400fcdf220de15f2c79a479102cb0fa1cd57e6e81ca9e4d92247c9a40fad717f43051adaae40d30c511be4eff3dcd84e60baf7bdad5eef7e189
-  data.tar.gz: e191bbc0ca11a86c0ec7a6a06bf0068a0cfa78e97766e6533f1182bb9e6f73c790fbd3ff7ba3702910b1dc8749554cba779664d509700d40e81107f941be0ba7
+  metadata.gz: cd0e7287ef11ba6fef8784be32c24898784125dde881e2b8082b15d1f19a5995c55e434924057f2bdd8ef27419a51b9e118351f20ebbff594b9a7d7e4f500a6b
+  data.tar.gz: 2e87fa5f7e6cd1bb0f5db13158e6c5e41e812a547cd2f90f44ce5104de8105d6595a60c86a2794ff5804615a5a5659da51c9daaed5ede8236661d0a85fb39c0b

data/.ruby-version

@@ -1 +1 @@
-2.3.1
+2.4.3

data/Guardfile

@@ -0,0 +1,66 @@
+# A sample Guardfile
+# More info at https://github.com/guard/guard#readme
+
+## Uncomment and set this to only include directories you want to watch
+# directories %w(app lib config test spec features) \
+#  .select{|d| Dir.exists?(d) ? d : UI.warning("Directory #{d} does not exist")}
+
+## Note: if you are using the `directories` clause above and you are not
+## watching the project directory ('.'), then you will want to move
+## the Guardfile to a watched dir and symlink it back, e.g.
+#
+#  $ mkdir config
+#  $ mv Guardfile config/
+#  $ ln -s config/Guardfile .
+#
+# and, you'll have to watch "config/Guardfile" instead of "Guardfile"
+
+guard :minitest do
+  # with Minitest::Unit
+  watch(%r{^test/(.*)\/?test_(.*)\.rb$})
+  watch(%r{^lib/(.*/)?([^/]+)\.rb$})     { |m| "test/#{m[1]}test_#{m[2]}.rb" }
+  watch(%r{^test/test_helper\.rb$})      { 'test' }
+
+  # with Minitest::Spec
+  # watch(%r{^spec/(.*)_spec\.rb$})
+  # watch(%r{^lib/(.+)\.rb$})         { |m| "spec/#{m[1]}_spec.rb" }
+  # watch(%r{^spec/spec_helper\.rb$}) { 'spec' }
+
+end
+
+# Note: The cmd option is now required due to the increasing number of ways
+#       rspec may be run, below are examples of the most common uses.
+#  * bundler: 'bundle exec rspec'
+#  * bundler binstubs: 'bin/rspec'
+#  * spring: 'bin/rspec' (This will use spring if running and you have
+#                          installed the spring binstubs per the docs)
+#  * zeus: 'zeus rspec' (requires the server to be started separately)
+#  * 'just' rspec: 'rspec'
+
+guard :rspec, cmd: "bundle exec rspec" do
+  require "guard/rspec/dsl"
+  dsl = Guard::RSpec::Dsl.new(self)
+
+  # Feel free to open issues for suggestions and improvements
+
+  # RSpec files
+  rspec = dsl.rspec
+  watch(rspec.spec_helper) { rspec.spec_dir }
+  watch(rspec.spec_support) { rspec.spec_dir }
+  watch(rspec.spec_files)
+
+  # Ruby files
+  ruby = dsl.ruby
+  dsl.watch_spec_files_for(ruby.lib_files)
+
+  # Turnip features and steps
+  #   watch(%r{^spec/acceptance/(.+)\.feature$})
+  # watch(%r{^spec/acceptance/steps/(.+)_steps\.rb$}) do |m|
+  #  Dir[File.join("**/#{m[1]}.feature")][0] || "spec/acceptance"
+  # end
+end
+
+# guard :rubocop do
+#   watch(%r{.+\.rb$})
+# watch(%r{(?:.+/)?\.rubocop\.yml$}) { |m| File.dirname(m[0]) }
+# end

data/lib/sqed.rb

@@ -1,12 +1,12 @@
 # encoding: UTF-8
 
-recent_ruby = RUBY_VERSION >= '2.1.1'
-raise "IMPORTANT: sqed gem requires ruby >= 2.1.1" unless recent_ruby
+recent_ruby = RUBY_VERSION >= '2.4.1'
+raise 'IMPORTANT: sqed gem requires ruby >= 2.4.1' unless recent_ruby
 
-require "rmagick"
+require 'rmagick'
 
 # Instances take the following
-# 1) A base image @image
+# 1) An :image @image
 # 2) A target extraction pattern, or individually specified attributes
 #
 # Return a Sqed::Result
@@ -17,85 +17,78 @@ require "rmagick"
 class Sqed
 
   require_relative 'sqed_config'
-  require_relative "sqed/extractor"
-  require_relative "sqed/result"
+  require_relative 'sqed/extractor'
+  require_relative 'sqed/result'
 
   # initial image which is an instance of ImageMagick::Image, containing background and stage, or just stage
   attr_accessor :image
 
-  # !optional! A lookup macro that if provided sets boundary_finder, layout, and metadata_map.  These can be individually overwritten.
+  # !optional! A lookup macro that if provided sets boundary_finder, layout, and metadata_map.
+  # These can be individually overwritten.
   # Legal values are symbols taken from SqedConfig::EXTRACTION_PATTERNS.
-  # DO NOT pass pattern outside of a sqed instance!
   #
-  # !! Always passed as an option :target_pattern, an persisted as :pattern
+  # !! Patterns are not intended to be persisted in external databases (they may change names). !!
+  # To persist Sqed metadata in something like Postgres reference individual
+  # attributes (e.g. layout, metadata_map, boundary_finder).
+  #
+  # @return [Symbol] like `:seven_slot`, see Sqed::CONFIG for valid options,
+  # default value is `nil`
+  #   not required if layout, metadata_map, and boundary_finder are provided
   attr_accessor :pattern
 
-  # Provide a specific layout, overrides layout metadata taken from pattern
+  # @return [Symbol] like `:cross`
+  # !! Provide a specific layout, passed as option :layout, overrides layout metadata taken from :pattern, defaults to `:cross`
   attr_accessor :layout
 
   # the image that is the cropped content for parsing
   attr_accessor :stage_image
 
-  # a Sqed::Boundaries instance that stores the coordinates of the stage
+  # @return [Sqed::Boundaries instance]
+  #   stores the coordinates of the stage
   attr_accessor :stage_boundary
 
-  # a Sqed::Boundaries instances that contains the coordinates of the interan stage sections
+  # @return [Sqed::Boundaries instance]
+  #   contains the coordinates of the internal stage sections
   attr_accessor :boundaries
 
-  # Boolean, whether to detect the border on initialization, i.e. new()
+  # @return [Boolean] defaults to `true`
+  #   when true detects border on initialization
   attr_accessor :has_border
 
-  # a symbol, :red, :green, :blue, describing the boundary color within the stage
+  # @return [Symbol] like `:red`, `:green`, `:blue`, defaults to `:green`
+  # describing the boundary color within the stage
   attr_accessor :boundary_color
 
-  # Boolean, whether to do the boundary detection (not stage detection at present) against a thumbnail version of the passed image (faster, less accurate, true be default)
+  # @return [Boolean] defaults to `true` (faster, less accurate)
+  #  if `true` do the boundary detection (not stage detection at present)
+  # against a thumbnail version of the passed image
   attr_accessor :use_thumbnail
 
-  # Provide a metadata map, overrides metadata taken from pattern.
-  # !! Always passed as an option :target_metadata_map, an persisted as :metadata_map
+  # Provide a metadata map, overrides metadata taken from pattern
   attr_accessor :metadata_map
 
   # Provide a boundary_finder, overrides metadata taken from pattern
   attr_accessor :boundary_finder
 
-  def initialize(target_image: nil, target_pattern: nil, target_layout: nil, has_border: true, boundary_color: :green, use_thumbnail: true, boundary_finder: nil, target_metadata_map: nil)
-    raise 'extraction pattern not defined' if target_pattern && !SqedConfig::EXTRACTION_PATTERNS.keys.include?(target_pattern)
-
-    # data, and stubs for results
-    @image = target_image
-    @boundaries = nil
-    @stage_boundary = Sqed::Boundaries.new(:internal_box)
-
+  def initialize(**opts)
     # extraction metadata
-    @pattern = target_pattern  # not required if target_layout, target_metadata_map, and boundary_finder are provided
-
-    @has_border = has_border
-    @boundary_finder = boundary_finder.constantize if boundary_finder
-    @layout = target_layout
-    @layout ||= SqedConfig::EXTRACTION_PATTERNS[pattern][:layout] if pattern
+    @image = opts[:image]
 
-    @metadata_map = target_metadata_map
-    @boundary_color = boundary_color
-    @use_thumbnail = use_thumbnail
-
-    set_stage_boundary if @image
+    configure(opts)
+    stub_results
   end
 
   # @return [Hash]
-  #   federate extraction options and apply user provided over-rides
+  #   federate extraction options
   def extraction_metadata
-    data = {}
-    data = SqedConfig::EXTRACTION_PATTERNS[pattern] if pattern
-
-    # if pattern is not provided, these must be
-    data[:boundary_finder]  = @boundary_finder if boundary_finder
-    data[:target_layout] = layout if layout
-    data[:target_metadata_map] = metadata_map if metadata_map
-
-    data[:boundary_color] = boundary_color
-    data[:has_border] = has_border
-    data[:use_thumbnail] = use_thumbnail
-    data
+    {
+        boundary_finder: boundary_finder,
+        layout: layout,
+        metadata_map: metadata_map,
+        boundary_color: boundary_color,
+        has_border: has_border,
+        use_thumbnail: use_thumbnail
+    }
   end
 
   # @return [ImageMagick::Image]
@@ -117,14 +110,13 @@ class Sqed
   end
 
   def stage_image
-   crop_image if @stage_image.nil?
-   @stage_image
+    crop_image if @stage_image.nil?
+    @stage_image
   end
 
-  # Return [Sqed::Boundaries instance]
+  # @return [Sqed::Boundaries instance, nil]
   #   a boundaries instance that has the original image (prior to cropping stage) coordinates
   def native_boundaries
-    # check for @boundaries.complete first? OR handle partial detections  ?!
     if @boundaries.complete
       @boundaries.offset(stage_boundary)
     else
@@ -132,7 +124,7 @@ class Sqed
     end
   end
 
-  # return [Image]
+  # @return [Image]
   #   crops the stage if not done, then sets/returns @stage_image
   def crop_image
     if has_border
@@ -145,19 +137,20 @@ class Sqed
 
   def result
     return false if image.nil?
-    return false if pattern.nil? && (metadata_map.nil? && layout.nil? && boundary_finder.nil?)
 
     extractor = Sqed::Extractor.new(
-      target_boundaries: boundaries,
-      target_metadata_map: extraction_metadata[:target_metadata_map],
-      target_image: stage_image)
+      boundaries: boundaries,
+      metadata_map: metadata_map, #  extraction_metadata[:metadata_map],
+      image: stage_image
+    )
+
     extractor.result
   end
 
   # @return [Hash]
   #   an overview of data/metadata, for debugging purposes only
   def attributes
-    { target_image: image,
+    { image: image,
       boundaries: boundaries,
       stage_boundary: stage_boundary
     }.merge!(extraction_metadata)
@@ -165,9 +158,76 @@ class Sqed
 
   protected
 
+  def configure(opts)
+    configure_from_pattern(opts[:pattern])
+    configure_boundary_finder(opts)
+    configure_layout(opts)
+    configure_metadata_map(opts)
+
+    @has_border = opts[:has_border]
+    @has_border = true if @has_border.nil?
+
+    @boundary_color = opts[:boundary_color]
+    @boundary_color ||= :green
+
+    @use_thumbnail = opts[:use_thumbnail]
+    @use_thumbnail = true if @use_thumbnail.nil?
+  end
+
+  def configure_from_pattern(value)
+    return if value.nil?
+    value = value.to_sym
+    raise "provided extraction pattern '#{value}' not defined" if !SqedConfig::EXTRACTION_PATTERNS.keys.include?(value)
+    @pattern = value
+    a = SqedConfig::EXTRACTION_PATTERNS[pattern]
+    @boundary_finder = a[:boundary_finder]
+    @layout = a[:layout]
+    @metadata_map = a[:metadata_map]
+    true
+  end
+
+  def configure_boundary_finder(opts)
+    @boundary_finder = opts[:boundary_finder].constantize if !opts[:boundary_finder].nil?
+    @boundary_finder ||= Sqed::BoundaryFinder::CrossFinder
+  end
+
+  def configure_layout(opts)
+    @layout = opts[:layout]
+    if p = opts[:pattern]
+      @layout ||= SqedConfig::EXTRACTION_PATTERNS[p][:layout]
+    end
+    @layout ||= :cross
+  end
+
+  def configure_metadata_map(opts)
+    @metadata_map = opts[:metadata_map] unless opts[:metadata_map].nil?
+  end
+
+  # stubs for data and results
+  def stub_results
+    @boundaries = nil
+    @stage_boundary = Sqed::Boundaries.new(:internal_box)
+    set_stage_boundary if @image
+  end
+
+  def get_section_boundaries
+    boundary_finder.new(section_params).boundaries
+  end
+
+  # @return [Hash]
+  #   variables for the isolated stage image
+  def section_params
+    {
+       image: stage_image,
+       use_thumbnail: use_thumbnail,
+       layout: layout,
+       boundary_color: boundary_color
+    }
+  end
+
   def set_stage_boundary
     if has_border
-      boundary = Sqed::BoundaryFinder::StageFinder.new(target_image: image).boundaries
+      boundary = Sqed::BoundaryFinder::StageFinder.new(image: image).boundaries
       if boundary.populated?
         @stage_boundary.set(0, boundary.for(0))
       else
@@ -178,12 +238,4 @@ class Sqed
     end
   end
 
-  def get_section_boundaries
-    options = {target_image: stage_image, use_thumbnail: use_thumbnail}
-    options.merge!( target_layout: extraction_metadata[:target_layout] ) unless extraction_metadata[:boundary_finder].name == 'Sqed::BoundaryFinder::CrossFinder'
-    options.merge!( boundary_color: boundary_color) if extraction_metadata[:boundary_finder].name == 'Sqed::BoundaryFinder::ColorLineFinder'
-
-    extraction_metadata[:boundary_finder].new(options).boundaries
-  end
-
 end

data/lib/sqed/boundaries.rb

@@ -1,8 +1,11 @@
-# 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 
+class Sqed
+
+  # 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 Boundaries
   include Enumerable
 
   # stores a hash
@@ -12,11 +15,12 @@ class Sqed::Boundaries
   #   0 => [10,10,40,40]
   attr_reader :coordinates
 
-  # A symbol from Sqed::Config::LAYOUTS.keys 
+  # A symbol from Sqed::Config::LAYOUTS.keys
   #   :right_t
   attr_accessor :layout
 
-  # Boolean, whether or not the last method to populate this object passed fully
+  # @return [Boolean] whether or not the last method to populate this object
+  # executed to completion
   attr_accessor :complete
 
   def initialize(layout = nil)
@@ -34,17 +38,19 @@ class Sqed::Boundaries
     end
   end
 
+  # @return [Sqed::Boundaries instance]
+  #   the idea here is to create a deep copy of self, offsetting by boundary
+  #   as we go
   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.set(i, 
-            [(self.x_for(i) + boundary.x_for(0)),
-             (self.y_for(i) + boundary.y_for(0)),
-             self.width_for(i),
-             self.height_for(i)]
-           )
+    b = Sqed::Boundaries.new
+    (0..coordinates.length - 1).each do |i|
+      b.set(i,
+            [(x_for(i) + boundary.x_for(0)),
+             (y_for(i) + boundary.y_for(0)),
+             width_for(i),
+             height_for(i)])
     end
-    b.complete = self.complete
+    b.complete = complete
     b
   end
 
@@ -84,25 +90,24 @@ class Sqed::Boundaries
   end
 
   def populated?
-    self.each do |index, coords|
+    each do |index, coords|
       coords.each do |c|
         return false if c.nil?
       end
     end
-    true 
+    true
   end
 
   def zoom(width_factor, height_factor)
     coordinates.keys.each do |i|
-      set(i, [   
-        (x_for(i).to_f * width_factor).to_i,
-        (y_for(i).to_f * height_factor).to_i,
-        (width_for(i).to_f * width_factor).to_i,
-        (height_for(i).to_f * height_factor).to_i
+      set(i, [
+          (x_for(i).to_f * width_factor).to_i,
+          (y_for(i).to_f * height_factor).to_i,
+          (width_for(i).to_f * width_factor).to_i,
+          (height_for(i).to_f * height_factor).to_i
       ])
-    
-    end  
+    end
   end
 
-
+  end
 end