kvg_character_recognition 0.1.0 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a14886233c4152851248456913d18768d9c8472a
-  data.tar.gz: f29d6c47b40ce1eb68a4db14c3b03961c275197c
+  metadata.gz: 2f5bd00df050f48f3ee955daaa966fd04b10a5f3
+  data.tar.gz: bb45a8db8023fb37f4f929a673f1f811756540fa
 SHA512:
-  metadata.gz: 339db4a0b7e01108b9d105f688dfb4bba6ea81420bb4255b70f1ff8ef51c5ae04cab3424464e453632f2ea17727f2e1629a95148d06379720f5e1cae448fa4a8
-  data.tar.gz: 2f57226b5dac0f9311bf0c5dec2750354aa6c40c5348e2f1df858b52a470aed242aa380be1d4aadfd2d9a1753e5fbad0a1a621a232d28d5e81b3dde4b2c929d9
+  metadata.gz: ae3a13b9370276c1714f19acebcf856cff091c27725514ae8f0a75f43ef754576d46bc69b7804d1203db5216524d0841e82b2deac7f29729ad5ebfe55441d080
+  data.tar.gz: 057e9896548709b6fd4187ffcf8d576b2d49fa0fb19f6b1cc3909e75befde49149aa934d54ea9c6bbab48d394f4fdf708404287ec6eae6857dab3b53b7a09650

data/Gemfile

@@ -3,6 +3,3 @@ source 'https://rubygems.org'
 # Specify your gem's dependencies in kvg_character_recognition.gemspec
 gemspec
 
-gem 'sequel'
-gem 'sqlite3'
-gem 'nokogiri'

data/README.md

@@ -4,21 +4,27 @@ A stroke is an array of points in the format [[x1, y1], [x2, y2], ...].
 For templates, we use svg data from the [KanjiVG project](http://kanjivg.tagaini.net/)
 
 The engine takes 3 steps to perform the recognition of an input pattern.
+
 1. Preprocessing
+
 The preprocessing step consists of smoothing, normalizing, interpolating and downsampling of the data points.
+
 2. Feature Extraction
+
 Smoothed heatmap, significant points and directional feature densities are used as features.
 A heatmap divides the input pattern in small grids and stores the number of data points in each grid.
 Significant points are defined as start and end point of a stroke, points on curve or edge.
 Directional feature densities are introduced in the paper "On-line Recognition of Freely Handwritten Japanese Character Using Directional Feature Density"
+
 3. Matching
+
 We use the significant points to perform a coarse recognition of the input pattern, that filters out template patterns with great distance to the input pattern. Next, a mixed distance score of directional feature density and smoothed heatmap is calculated.
 ## Installation
 
 Add this line to your application's Gemfile:
 
 ```ruby
-gem 'kvg_character_recognition'
+gem 'kvg_character_recognition', '~>0.1.1'
 ```
 
 And then execute:
@@ -31,15 +37,14 @@ Or install it yourself as:
 
 ## Usage
 
-1. Create a database(e.g. using sqlite3 data.db)
-
-2. Setup the characters table in the database and populate it with kanjivg templates from the [xml release](https://github.com/KanjiVG/kanjivg/releases)
+1. Setup a json datastore and populate it with kanjivg templates from the [xml release](https://github.com/KanjiVG/kanjivg/releases)
 ```ruby
 require 'kvg_character_recognition'
 
-KvgCharacterRecognition::Database.setup
+datastore = KvgCharacterRecognition::JSONDatastore.new("characters.json")
+#ignore the warning
 
-KvgCharacterRecognition::Database.populate_from_xml "kanjivg-20150615-2.xml"
+KvgCharacterRecognition::Trainer.populate_from_xml "kanjivg-20150615-2.xml", datastore
 ```
 
 3. Recognition
@@ -48,7 +53,8 @@ Use an input field of size 300x300 for the best recognition accuracy. The input
 ```ruby
 strokes = [[[99.0, 108.0], [100.0, 108.0], [101.0, 108.0], [101.0, 108.0], [103.0, 108.0], [105.0, 107.0], [107.0, 107.0], [108.0, 107.0], [111.0, 106.0], [111.0, 106.0], [112.0, 106.0], [113.0, 106.0], [114.0, 106.0], [115.0, 105.0], [116.0, 105.0], [118.0, 105.0], [120.0, 105.0], [121.0, 104.0], [122.0, 104.0], [122.0, 104.0], [123.0, 104.0], [124.0, 103.0], [125.0, 103.0], [126.0, 103.0], [127.0, 103.0], [129.0, 102.0], [130.0, 102.0], [132.0, 102.0], [132.0, 101.0], [133.0, 101.0], [135.0, 101.0], [136.0, 101.0], [137.0, 101.0], [138.0, 101.0], [140.0, 101.0], [141.0, 100.0], [142.0, 100.0], [143.0, 100.0], [144.0, 100.0], [145.0, 99.0], [148.0, 99.0], [150.0, 99.0], [151.0, 98.0], [152.0, 98.0], [153.0, 98.0], [154.0, 98.0], [156.0, 97.0], [157.0, 97.0], [158.0, 97.0], [159.0, 97.0], [161.0, 97.0], [162.0, 96.0], [162.0, 96.0], [164.0, 96.0], [165.0, 96.0], [166.0, 96.0], [167.0, 96.0], [169.0, 95.0], [170.0, 95.0], [171.0, 95.0], [172.0, 95.0], [173.0, 95.0], [174.0, 95.0]], [[53.0, 190.0], [54.0, 190.0], [56.0, 190.0], [57.0, 190.0], [59.0, 190.0], [61.0, 190.0], [63.0, 189.0], [66.0, 189.0], [67.0, 189.0], [68.0, 189.0], [69.0, 189.0], [71.0, 189.0], [72.0, 188.0], [72.0, 188.0], [74.0, 188.0], [76.0, 187.0], [78.0, 187.0], [80.0, 187.0], [81.0, 187.0], [82.0, 186.0], [84.0, 186.0], [87.0, 186.0], [89.0, 185.0], [91.0, 185.0], [93.0, 185.0], [95.0, 184.0], [98.0, 184.0], [100.0, 183.0], [102.0, 183.0], [104.0, 183.0], [106.0, 183.0], [110.0, 182.0], [111.0, 182.0], [112.0, 182.0], [115.0, 182.0], [118.0, 182.0], [120.0, 182.0], [122.0, 182.0], [125.0, 182.0], [128.0, 181.0], [130.0, 181.0], [133.0, 180.0], [136.0, 180.0], [141.0, 180.0], [143.0, 179.0], [146.0, 179.0], [150.0, 179.0], [152.0, 178.0], [155.0, 178.0], [158.0, 178.0], [159.0, 178.0], [162.0, 177.0], [164.0, 177.0], [167.0, 177.0], [170.0, 177.0], [173.0, 176.0], [176.0, 176.0], [179.0, 176.0], [182.0, 175.0], [187.0, 175.0], [189.0, 174.0], [192.0, 174.0], [194.0, 174.0], [196.0, 173.0], [199.0, 173.0], [202.0, 173.0], [204.0, 172.0], [206.0, 172.0], [209.0, 172.0], [211.0, 172.0], [212.0, 172.0], [215.0, 172.0], [217.0, 172.0], [219.0, 171.0], [221.0, 171.0], [221.0, 172.0]]]
 
-scores = KvgCharacterRecognition::Recognizer.scores strokes
+datastore = KvgCharacterRecognition::JSONDatastore.new("characters.json") #this will initialize datastore once for the entire usage
+scores = KvgCharacterRecognition::Recognizer.scores strokes, datastore
 
 irb(main):004:0> scores.take 10
 => [[1.524079282599697, 60, "二"], [2.8346163809971143, 1373, "工"], [3.0987422100694757, 7, "上"], [3.127346308294038, 365, "冫"], [3.439293212191952, 6, "三"], [3.4890481845638304, 3770, "立"], [3.541524904953307, 2721, "江"], [3.641178875851016, 569, "厂"], [3.6447144433336294, 72, "亠"], [3.7498483818966353, 2706, "氵"]]
@@ -73,9 +79,6 @@ Don't forget to redo the whole database step after changing the configuration.
   #from yaml file
   Kvgcharacterrecognition.configure_with(path_to_yml)
 
-  #configure database with yml
-  #TODO why is postgres slower than sqlite?
-  Kvgcharacterrecognition.configure_database(path_to_yml)
 ```
 
 

data/kvg_character_recognition.gemspec

@@ -26,15 +26,15 @@ Gem::Specification.new do |spec|
     raise "RubyGems 2.0 or newer is required to protect against public gem pushes."
   end
 
-  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
+  spec.files         = `git ls-files -z`.split("\x0").reject { |f| f == 'kvg_character_recognition-0.1.1.gem' || f.match(%r{^(test|spec|features)/}) }
   spec.bindir        = "exe"
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
+  spec.add_dependency "parallel"
   spec.add_dependency "nokogiri"
-  spec.add_dependency "sequel"
-  spec.add_dependency "sqlite3"
   spec.add_dependency "bundler", "~> 1.10"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "rspec"
+  spec.add_development_dependency "pry"
 end

data/lib/kvg_character_recognition.rb

@@ -6,7 +6,6 @@ Dir[File.join(File.dirname(__FILE__), '/kvg_character_recognition/*.rb')].each {
 
 module KvgCharacterRecognition
 
-  @db = Sequel.connect('sqlite://characters.db')
   CONFIG = {
     size: 109, #fixed canvas size of kanjivg data
     downsample_interval: 4,
@@ -34,22 +33,4 @@ module KvgCharacterRecognition
 
     configure(config)
   end
-
-  #Configure database
-  def self.configure_database(yml)
-    begin
-      db_config = YAML::load(IO.read(yml))
-    rescue Errno::ENOENT
-      log(:warning, "YAML configuration file couldn't be found. Using defaults."); return
-    rescue Psych::SyntaxError
-      log(:warning, "YAML configuration file contains invalid syntax. Using defaults."); return
-    end
-    @db = Sequel.connect(yml)
-  end
-
-  #getter
-  def self.db
-    @db
-  end
-
 end

data/lib/kvg_character_recognition/datastore.rb

@@ -0,0 +1,35 @@
+require 'json'
+
+module KvgCharacterRecognition
+  class JSONDatastore
+    def initialize filename = 'characters.json'
+      @data = load_file(filename)
+      @filename = filename
+    end
+
+    def load_file filename
+      begin
+        JSON.parse(File.read(filename, encoding: 'utf-8'), symbolize_names: true)
+      rescue
+        puts "WARNING: Can't load file, returning empty character collection."
+        []
+      end
+    end
+
+    def characters_in_stroke_range range
+      @data.select { |character| range === character[:number_of_strokes] }
+    end
+
+    def store character
+      @data.push character
+    end
+
+    def persist!
+      dump @filename
+    end
+
+    def dump filename
+      File.write(filename, @data.to_json)
+    end
+  end
+end

data/lib/kvg_character_recognition/preprocessor.rb

@@ -148,17 +148,6 @@ module KvgCharacterRecognition
       points
     end
 
-    #This methods calculates the euclidean distance between 2 points
-    #Params:
-    #- p1, p2: [x, y]
-    def self.euclidean_distance(p1, p2)
-      sum_of_squares = 0
-      p1.each_with_index do |p1_coord,index|
-        sum_of_squares += (p1_coord - p2[index]) ** 2
-      end
-      Math.sqrt( sum_of_squares )
-    end
-
     #This method interpolates points into a stroke with given distance
     #The algorithm is taken from the paper preprocessing techniques for online character recognition 
     def self.interpolate stroke, d=0.5
@@ -171,7 +160,7 @@ module KvgCharacterRecognition
         point = stroke[index]
 
         #only consider point with greater than d distance to current point
-        if euclidean_distance(current, point) < d
+        if Math.euclidean_distance(current, point) < d
           index += 1
         else
 

data/lib/kvg_character_recognition/recognizer.rb

@@ -1,27 +1,32 @@
 require 'matrix'
+require 'parallel'
 module KvgCharacterRecognition
   #This class contains methods calculating similarity scores between input pattern and template patterns
-  class Recognizer
+  module Recognizer
+    @thread_count = 10
 
     #This method selects all templates from the database which should be further examined
     #It filtered out those characters with a too great difference in number of strokes to the input character
-    def self.select_templates strokes
+    def self.select_templates strokes, datastore
       min = strokes.count <= 5 ? strokes.count : strokes.count - 5
       max = strokes.count + 10
-      KvgCharacterRecognition.db[:characters].where(:number_of_strokes => (min..max))
+      datastore.characters_in_stroke_range(min..max)
     end
 
     #This method uses heatmap of significant points to coarse recognize the input pattern
     #Params:
     #+strokes+:: strokes should be preprocessed
-    def self.coarse_recognize strokes
+    #+datastore+:: JSONDatastore or custom datastore type having method characters_in_stroke_range(min..max)
+    def self.coarse_recognize strokes, datastore
       heatmap = FeatureExtractor.heatmap(Preprocessor.significant_points(strokes), CONFIG[:significant_points_heatmap_grid], CONFIG[:size]).to_a
 
-      templates = select_templates strokes
-      templates.map do |candidate|
+      templates = select_templates strokes, datastore
+
+      # Use threads to accelerate the process
+      Parallel.map(templates, in_threads: @thread_count) do |candidate|
         candidate_heatmap = candidate[:heatmap_significant_points].split(",").map(&:to_f)
 
-        score = Preprocessor.euclidean_distance(heatmap, candidate_heatmap)
+        score = Math.euclidean_distance(heatmap, candidate_heatmap)
         [score.round(3), candidate]
       end
     end
@@ -31,7 +36,8 @@ module KvgCharacterRecognition
     #2. euclidean distance of directional feature densities in average
     #Params:
     #+strokes+:: strokes are not preprocessed
-    def self.scores strokes
+    #+datastore+:: JSONDatastore or custom datastore type having method characters_in_stroke_range(min..max)
+    def self.scores strokes, datastore
       #preprocess strokes
       #with smoothing
       strokes = Preprocessor.preprocess(strokes, CONFIG[:interpolate_distance], CONFIG[:downsample_interval], true)
@@ -42,18 +48,18 @@ module KvgCharacterRecognition
 
       #dump half of the templates after coarse recognition
       #collection is in the form [[score, c1], [score, c2] ...]
-      collection = coarse_recognize(strokes).sort{ |a, b| a[0] <=> b[0] }
+      collection = coarse_recognize(strokes, datastore).sort{ |a, b| a[0] <=> b[0] }
 
-      scores = collection.take(collection.count / 2).map do |cand|
-        direction_score = (Preprocessor.euclidean_distance(directions[0], cand[1][:direction_e1].split(",").map(&:to_f)) +
-                           Preprocessor.euclidean_distance(directions[1], cand[1][:direction_e2].split(",").map(&:to_f)) +
-                           Preprocessor.euclidean_distance(directions[2], cand[1][:direction_e3].split(",").map(&:to_f)) +
-                           Preprocessor.euclidean_distance(directions[3], cand[1][:direction_e4].split(",").map(&:to_f)) ) / 4
+      scores = Parallel.map(collection.take(collection.count / 2)) do |cand|
+        direction_score = (Math.euclidean_distance(directions[0], cand[1][:direction_e1].split(",").map(&:to_f)) +
+                           Math.euclidean_distance(directions[1], cand[1][:direction_e2].split(",").map(&:to_f)) +
+                           Math.euclidean_distance(directions[2], cand[1][:direction_e3].split(",").map(&:to_f)) +
+                           Math.euclidean_distance(directions[3], cand[1][:direction_e4].split(",").map(&:to_f)) ) / 4
 
-        heatmap_score = Preprocessor.euclidean_distance(heatmap_smoothed, cand[1][:heatmap_smoothed].split(",").map(&:to_f))
+        heatmap_score = Math.euclidean_distance(heatmap_smoothed, cand[1][:heatmap_smoothed].split(",").map(&:to_f))
 
         mix = (direction_score / 100) + heatmap_score
-        [mix/2, cand[1][:id], cand[1][:value]]
+        [mix/2, cand[1]]
       end
 
       scores.sort{ |a, b| a[0] <=> b[0] }

data/lib/kvg_character_recognition/{database.rb → trainer.rb}

@@ -1,49 +1,10 @@
-require 'matrix'
-require 'nokogiri'
-
 module KvgCharacterRecognition
-  #This class contains methods for database interactions
-  class Database
-
-    #This method creates a database table for storing the extracted features of the templates
-    #Arrays of points will be serialized and stored as string
-    #Following fields are created:
-    # - primary_key :id
-    # - String :value
-    # - Integer :codepoint
-    # - String :serialized_strokes i.e. [stroke, x, y]
-    # - String :direction_e1
-    # - String :direction_e2
-    # - String :direction_e3
-    # - String :direction_e4
-    # - String :heatmap_smoothed
-    # - String :heatmap_significant_points
-    def self.setup
-      KvgCharacterRecognition.db.create_table :characters do
-        primary_key :id
-        String :value
-        Integer :codepoint
-        Integer :number_of_strokes
-        String :serialized_strokes
-        String :direction_e1
-        String :direction_e2
-        String :direction_e3
-        String :direction_e4
-        String :heatmap_smoothed
-        String :heatmap_significant_points
-      end
-
-    end
-
-    #Drop created table
-    def self.drop
-      KvgCharacterRecognition.db.drop_table(:characters) if KvgCharacterRecognition.db.table_exists?(:characters)
-    end
-
-    #This method populates the database table with parsed template patterns from the kanjivg file in xml format
+  module Trainer
+    #This method populates the datastore with parsed template patterns from the kanjivg file in xml format
     #Params:
     #+xml+:: download the latest xml release from https://github.com/KanjiVG/kanjivg/releases
-    def self.populate_from_xml xml
+    #+datastore+:: JSONDatastore or custom datastore type having methods store, persist!
+    def self.populate_from_xml xml, datastore
       file = File.open(xml) { |f| Nokogiri::XML(f) }
 
       file.xpath("//kanji").each do |kanji|
@@ -85,7 +46,8 @@ module KvgCharacterRecognition
 
         #Store to database
         #--------------
-        KvgCharacterRecognition.db[:characters].insert value: value,
+        character = {
+          value: value,
           codepoint: codepoint.hex,
           number_of_strokes: strokes.count,
           serialized_strokes: serialized.join(","),
@@ -95,9 +57,12 @@ module KvgCharacterRecognition
           direction_e4: direction[3].join(","),
           heatmap_smoothed: heatmap_smoothed.to_a.join(","),
           heatmap_significant_points: heatmap_significant_points.to_a.join(",")
+        }
+
+        datastore.store character
       end
 
+      datastore.persist!
     end
-
   end
 end

data/lib/kvg_character_recognition/utils.rb

@@ -1,3 +1,17 @@
+module Math
+  #Add euclidean distance method to ruby Math module
+  #This methods calculates the euclidean distance between 2 points
+  #Params:
+  #- p1, p2: [x, y]
+  def self.euclidean_distance(p1, p2)
+    sum_of_squares = 0
+    p1.each_with_index do |p1_coord,index|
+      sum_of_squares += (p1_coord - p2[index]) ** 2
+    end
+    Math.sqrt( sum_of_squares )
+  end
+end
+
 module KvgCharacterRecognition
 
   #This class can be used for storing heatmap count and directional feature densities

data/lib/kvg_character_recognition/version.rb

@@ -1,3 +1,3 @@
 module KvgCharacterRecognition
-  VERSION = "0.1.0"
+  VERSION = "0.1.2"
 end

metadata

@@ -1,31 +1,17 @@
 --- !ruby/object:Gem::Specification
 name: kvg_character_recognition
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.1.2
 platform: ruby
 authors:
 - Jiayi Zheng
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-01-12 00:00:00.000000000 Z
+date: 2016-01-17 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
-  name: nokogiri
-  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: sequel
+  name: parallel
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -39,7 +25,7 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: nokogiri
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
@@ -94,6 +80,20 @@ dependencies:
     - - ">="
       - !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'
 description: "This gem contains a CJK-character recognition engine using pattern/template
   matching techniques.\n  It can recognize stroke-order and stroke-number free handwritten
   character patterns in the format [stroke1, stroke2 ...].\n  A stroke is an array
@@ -117,10 +117,11 @@ files:
 - bin/setup
 - kvg_character_recognition.gemspec
 - lib/kvg_character_recognition.rb
-- lib/kvg_character_recognition/database.rb
+- lib/kvg_character_recognition/datastore.rb
 - lib/kvg_character_recognition/feature_extractor.rb
 - lib/kvg_character_recognition/preprocessor.rb
 - lib/kvg_character_recognition/recognizer.rb
+- lib/kvg_character_recognition/trainer.rb
 - lib/kvg_character_recognition/utils.rb
 - lib/kvg_character_recognition/version.rb
 homepage: https://github.com/thebluber/kvg_character_recognition