chunky_png_subimage 0.1.2 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: b831ded7991e426e5ea0b3cb450e0babcdc9eea3
-  data.tar.gz: 2eed01e388eb872bea4212e28484dc451b901c18
+  metadata.gz: 6426dbb98ddd9eb1ec1f48050cbab98e45c44ea8
+  data.tar.gz: 6c0a714e56825f2f6d58a73be354e42944a66348
 SHA512:
-  metadata.gz: 4bd73017a35271c8805c42c4dab5b3b4f7574eeab48784989c464812add7bd6a369bbe4e0a3b199fa518705447141543470142e0def6b16ef7d089d78143d0f5
-  data.tar.gz: 1e0ad1dbdb047ab4caaf1a7c61e3ea39bc1fbe48ffbc49c9a5e3d436576021a5e54ffa9fbdf4ab3bc8b6c1a17328fedfb5d94700b6ee7c4409db411cb9cba3b8
+  metadata.gz: 111903fb0d4a9336f2c09bac57cdfe2714c7618f6a7fa8c0fba40f6af2aafb91a660dbe568e27b9a18353fdb79fb1575d50431a329e2ff96efe760dc7cb5c414
+  data.tar.gz: a674d5e4901cc83e5d871b2fd162bca7792a3458407352c1b2d5ca2c5016e644baf37c69c92455d676f1ff237c84b31405a04e65002d5fdbe6e234522d00a259

data/Rakefile

@@ -6,7 +6,13 @@ Rake::ExtensionTask.new('chunky_png_subimage') do |ext|
   #ext.config_options = '--with-cflags="-std=c99"'
 end
 
-#require 'rspec/core/rake_task'
-#RSpec::Core::RakeTask.new(:spec)
+require 'rspec/core/rake_task'
 
-task :default => [:compile]
+RSpec::Core::RakeTask.new(:spec) do |task|
+  task.pattern = "./spec/spec.rb"
+  task.rspec_opts = ['--color']
+end
+
+Rake::Task['spec'].prerequisites << :compile
+
+task :default => [:spec]

data/ext/chunky_png_subimage/chunky_png_subimage.c

@@ -1,10 +1,54 @@
+/** Ruby C extension 'chunky_png_subimage', source
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2014 Denis Mingulov
+ *
+ * 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.
+ */
+
 #include "chunky_png_subimage.h"
 
+/** Check that the color from subimage is usable to search
+ * @param color Color to be checked
+ * @return 0 whether color is not usable, non-0 otherwise
+ */
 static inline int is_color_usable(unsigned int color)
 {
+	/* currently - fully opaque points are used only */
 	return (color & 0xff) == 0xff;
 }
 
+/** Search a single subimage inside image
+ * @param img Pointer to uint colors for image (must be imgWidth * imgHeight)
+ * @param imgWidth Image width
+ * @param imgHeight Image height
+ * @param searchX Offset X of 1st possible point for subimage
+ * @param searchY Offset Y of 1st possible point for subimage
+ * @param searchWidth Width for the search region
+ * @param searchHeight Height for the search region
+ * @param sub Pointer to uint colors for subimage (must be subWidth * subHeight)
+ * @param subWidth Subimage width
+ * @param subHeight Subimage height
+ * @param singleMode 0 whether search every image, non-0 - to stop after 1st found
+ * @return Ruby array with [x, y] entries - found positions of subimage
+ */
 static VALUE search_single_subimage(const unsigned int *img, const int imgWidth, const int imgHeight,
 		const int searchX, const int searchY, const int searchWidth, const int searchHeight,
 		const unsigned int *sub, const int subWidth, const int subHeight, int singleMode)
@@ -76,7 +120,12 @@ static VALUE search_single_subimage(const unsigned int *img, const int imgWidth,
 	return result;
 }
 
-/* convert image to int*, xfree must be used later */
+/** convert image with Ruby values to unsigned int*, xfree must be used later
+ * @param imgPixels Pointer to 1st element of Ruby array with data points (should be imgWidth * imgHeight)
+ * @param imgWidth Width of the image
+ * @param imgHeight Height of the image
+ * @return Pointer to unsigned int values, xfree must be used later
+ */
 static unsigned int *convert_image(const VALUE *imgPixels, const int imgWidth, const int imgHeight)
 {
 	unsigned int *imgReady = xmalloc(sizeof(unsigned int) * imgWidth * imgHeight);
@@ -89,6 +138,18 @@ static unsigned int *convert_image(const VALUE *imgPixels, const int imgWidth, c
 	return imgReady;
 }
 
+/** Exportable function to ruby, to search subimages in the image
+ * @param argc Amount of elements in argv
+ * @param argv Parameters:
+ *             img array of pixels, img width, img height,
+ *             search offset x, search offset y, search width, search height,
+ *             singleMode (bit 1 - for subimage search, bit 0 - to stop after 1st found subimage),
+ *             amount of subimages,
+ *             for every subimage:
+ *                 subimage array of pixels, subimage width, subimage height
+ * @param self Object
+ * @return Array of found subimages' positions
+ */
 VALUE search_subimages(int argc, VALUE *argv, VALUE self)
 {
 	/*
@@ -164,6 +225,7 @@ VALUE search_subimages(int argc, VALUE *argv, VALUE self)
 
 		rb_ary_push(result, r);
 
+		/* stop if the proper single mode and result is found */
 		if ((singleMode & 1) && RARRAY_LEN(r) > 0)
 			break;
 
@@ -175,6 +237,7 @@ VALUE search_subimages(int argc, VALUE *argv, VALUE self)
 	return result;
 }
 
+/** Entry point for an initialization */
 void Init_chunky_png_subimage()
 {
 	VALUE mainModule = rb_define_module("ChunkyPNGSubimage");

data/ext/chunky_png_subimage/chunky_png_subimage.h

@@ -1,8 +1,34 @@
+/** Ruby C extension 'chunky_png_subimage', header
+ *
+ * The MIT License (MIT)
+ *
+ * Copyright (c) 2014 Denis Mingulov
+ *
+ * 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.
+ */
+
 #ifndef CHUNKY_PNG_SUBIMAGE_H
 #define CHUNKY_PNG_SUBIMAGE_H
 
 #include <ruby.h>
 
+/* Entry point for an initialization */
 void Init_chunky_png_subimage();
 
-#endif
+#endif

data/ext/chunky_png_subimage/extconf.rb

@@ -1,5 +1,3 @@
 require 'mkmf'
 
-#have_func("labs", "stdlib.h")
-
 create_makefile('chunky_png_subimage/chunky_png_subimage')

data/lib/chunky_png_subimage/search.rb

@@ -1,7 +1,57 @@
-require 'chunky_png'
+# = ChunkyPNGSubimage
+#
+# Search subimages inside image - fast as ruby C extension is used.
+#
+# == Synopsys
+#
+# require 'chunky_png'
+# require 'chunky_png_subimage'
+#
+# img = ChunkyPNG::Image.new(10, 10, ChunkyPNG::Color::WHITE)
+# sub1 = ChunkyPNG::Image.new(5, 5, ChunkyPNG::Color::BLACK)
+# sub2 = ChunkyPNG::Image.new(9, 9, ChunkyPNG::Color::WHITE)
+#
+# puts ChunkyPNGSubimage.search_subimage img, sub1
+# puts ChunkyPNGSubimage.search_subimage img, [sub1, sub2]
+#
+# == Introduction
+#
+# Quite often it is required to find the position of some image on the bigger image.
+# For example use case - a test with watir-webdriver for the external Flash page.
+# Or just some automation for the some other application with some other screenshot maker.
+# This library allows fastly to find subimages on the big image, so you might react
+# almost instantly to the change.
+# Of couse it can be used for any other reasons.
+
 require 'chunky_png_subimage/chunky_png_subimage'
 
 module ChunkyPNGSubimage
+
+  # Search subimages on the image.
+  # 
+  # ==== Attributes
+  #
+  # * +img+ - Image where search for subimages will be done
+  # * +subimages+ - Subimage or an array of subimages. Just fully opaque pixels are used from any subimage.
+  # * +single+ - 'single mode', when to stop if an subimage is found, possible values:
+  #   :single_everywhere - fully stop after 1st subimage is found;
+  #   :single_same_subimage - search maximum 1 subimage position, for every provided subimage;
+  #   :single_subimage - stop after 1st subimage is found, but find every possible position for that subimage;
+  #   anything else - search for every possible subimage multiple times.
+  # * +x+ - if find subimages inside some region of image - offset x (0 by default)
+  # * +y+ - if find subimages inside some region of image - offset y (0 by default)
+  # * +width+ - if find subimages inside some region of image - width of that region (full image by default)
+  # * +height+ - if find subimages inside some region of image - height of that region (full image by default)
+  #
+  # ==== Output
+  #
+  # Method returns:
+  # * An array of arrays with positions of found subimages.
+  # * If just single subimage is provided (without array) - then the output also does not contain outer array.
+  #
+  # ==== Examples
+  #
+  # ChunkyPNGSubimage.search_subimage img, sub
   #
   def self.search_subimage img, subimages, single = :single_same_subimage, x = 0, y = 0, width = 0, height = 0
     many_subimages = subimages.is_a? Array

data/lib/chunky_png_subimage/version.rb

@@ -1,3 +1,3 @@
 module ChunkyPNGSubimage
-  VERSION = "0.1.2"
+  VERSION = "0.2.0"
 end

data/lib/chunky_png_subimage.rb

@@ -1,4 +1,3 @@
-require 'chunky_png'
 require 'chunky_png_subimage/version'
 require 'chunky_png_subimage/chunky_png_subimage'
 require 'chunky_png_subimage/search'

data/spec/spec.rb

@@ -0,0 +1,39 @@
+require 'chunky_png_subimage'
+require 'chunky_png'
+
+describe ChunkyPNGSubimage do
+
+  before(:each) do
+    @white_big = ChunkyPNG::Image.new(10, 10, ChunkyPNG::Color::WHITE)
+    @white_medium = ChunkyPNG::Image.new(5, 5, ChunkyPNG::Color::WHITE)
+    @black_big = ChunkyPNG::Image.new(10, 10, ChunkyPNG::Color::BLACK)
+    @black_medium = ChunkyPNG::Image.new(5, 5, ChunkyPNG::Color::BLACK)
+    @black_big_tr = ChunkyPNG::Image.new(5, 5, ChunkyPNG::Color::BLACK)
+    @black_big_tr[1, 1] = ChunkyPNG::Color::WHITE
+    @black_big_tr[3, 1] = ChunkyPNG::Color::WHITE
+    @black_big_tr[1, 3] = ChunkyPNG::Color::WHITE
+    @black_big_tr[3, 3] = ChunkyPNG::Color::WHITE
+    @black_small_tr = ChunkyPNG::Image.new(3, 3, ChunkyPNG::Color::BLACK)
+    @black_small_tr[1, 1] = 0
+  end
+
+  describe '#search_subimage' do
+    #search_subimage img, subimages, single = :single_same_subimage, x = 0, y = 0, width = 0, height = 0
+    
+    it "white on black should not find anything" do
+      ChunkyPNGSubimage.search_subimage(@black_big, @white_medium).should == []
+      ChunkyPNGSubimage.search_subimage(@black_big, @white_medium, :single_same_subimage).should == []
+      ChunkyPNGSubimage.search_subimage(@black_big, @white_medium, :single_everywhere).should == []
+      ChunkyPNGSubimage.search_subimage(@black_big, @white_medium, :single_subimage).should == []
+      ChunkyPNGSubimage.search_subimage(@black_big, @white_medium, :everything).should == []
+    end
+
+    it "default mode is :single_same_subimage" do
+      ChunkyPNGSubimage.search_subimage(@black_big, @black_medium, :single_same_subimage).should == ChunkyPNGSubimage.search_subimage(@black_big, @black_medium)
+      ChunkyPNGSubimage.search_subimage(@white_big, @black_medium, :single_same_subimage).should == ChunkyPNGSubimage.search_subimage(@white_big, @black_medium)
+      ChunkyPNGSubimage.search_subimage(@white_big, @white_medium, :single_same_subimage).should == ChunkyPNGSubimage.search_subimage(@white_big, @white_medium)
+      ChunkyPNGSubimage.search_subimage(@black_big, [@black_medium, @black_small_tr], :single_same_subimage).should == ChunkyPNGSubimage.search_subimage(@black_big, [@black_medium, @black_small_tr])
+    end
+
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: chunky_png_subimage
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.2.0
 platform: ruby
 authors:
 - Denis Mingulov
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2014-04-17 00:00:00.000000000 Z
+date: 2014-04-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: chunky_png
@@ -102,6 +102,7 @@ files:
 - lib/chunky_png_subimage.rb
 - lib/chunky_png_subimage/search.rb
 - lib/chunky_png_subimage/version.rb
+- spec/spec.rb
 homepage: http://github.com/mingulov/chunky_png_subimage
 licenses:
 - MIT
@@ -126,4 +127,5 @@ rubygems_version: 2.2.2
 signing_key: 
 specification_version: 4
 summary: Support to search subimages for ChunkyPNG
-test_files: []
+test_files:
+- spec/spec.rb