ocarina 0.0.1

data/lib/ocarina/error_stats.rb

@@ -0,0 +1,62 @@
+require_relative 'util'
+
+module Ocarina
+
+  # keeps track of running errors during evaluations
+  #
+  class ErrorStats
+
+    def initialize(config)
+      @num_outputs = config.num_outputs
+
+      @chars_seen  = 0
+      @chars_wrong = 0
+      @bits_seen   = 0
+      @bits_wrong  = 0
+    end
+
+    # check and record the error from the expected and actual integers
+    #
+    def check_error(expected, actual)
+      @chars_seen += 1
+      @bits_seen += @num_outputs
+
+      if expected != actual
+        @chars_wrong +=1
+        puts "char wrong, expected: #{expected.chr}, guessed: #{actual.chr}"
+
+        expected_binary_string = int_to_binary_string expected
+        actual_binary_string   = int_to_binary_string actual
+
+        @bits_wrong += count_differences expected_binary_string, actual_binary_string
+
+        #puts "expected: #{expected_binary_string}, decimal: #{expected}"
+        #puts "actual  : #{actual_binary_string}, decimal: #{actual}"
+      end
+
+    end
+
+    # assumes a.size == b.size
+    def count_differences(a, b)
+      a.split(//).each.with_index.inject(0) { |diffs, (char, i)| char == b[i] ? diffs : diffs + 1}
+    end
+
+
+    def report
+      puts "total characters evaluated: #@chars_seen"
+      puts "total characters wrong    : #@chars_wrong"
+      puts "character accuracy        : #{'%.2f' % character_accuracy}"
+      puts "bit accuracy              : #{'%.2f' % bit_accuracy}"
+    end
+
+    def character_accuracy
+      (@chars_seen - @chars_wrong).to_f / @chars_seen * 100
+    end
+
+    def bit_accuracy
+      (@bits_seen - @bits_wrong).to_f / @bits_seen * 100
+    end
+
+  end
+
+end

data/lib/ocarina/letterpress_character_generator.rb

@@ -0,0 +1,93 @@
+require 'RMagick'
+
+module Ocarina
+
+  # creates bitmap images for characters using letterpress board game images
+  #
+  # We create the reference character images by cropping game board tiles for
+  # three boards for which the letters are known ahead of time. Together, the three
+  # boards provide images for all the letters of the alphabet.
+  #
+  class LetterpressCharacterGenerator < CharacterGenerator
+
+    def initialize(config)
+      @config = config
+
+      # generate reference images
+      #
+      @reference_image_hash = process_letterpress_example_boards
+
+      # generate noise images
+      #
+      @noise_image_hash = { }
+
+      @config.char_set.each_char do |char|
+        @noise_image_hash[char] = generate_noise_gif_for_char char
+      end
+    end
+
+    private
+
+    # create and return reference images from letterpress game boards.
+    # returns tiles as a hash of char -> image
+    #
+    def process_letterpress_example_boards
+
+      # board games were generated randomly by the game.
+      # with these three game boards, we have the letters A-Z.
+
+      result = { }
+
+      result.merge! create_letterpress_tiles("#{IMAGES_DIR}/letterpress/board1.png",
+                                             [
+                                                 [ 'P', 'R', 'B', 'R', 'Z' ],
+                                                 [ 'T', 'A', 'V', 'Z', 'R' ],
+                                                 [ 'B', 'D', 'A', 'K', 'Y' ],
+                                                 [ 'G', 'I', 'G', 'K', 'F' ],
+                                                 [ 'R', 'Y', 'S', 'J', 'V' ]
+                                             ])
+
+      result.merge! create_letterpress_tiles("#{IMAGES_DIR}/letterpress/board2.png",
+                                             [
+                                                 [ 'Q', 'D', 'F', 'P', 'M' ],
+                                                 [ 'N', 'E', 'E', 'S', 'I' ],
+                                                 [ 'A', 'W', 'F', 'M', 'L' ],
+                                                 [ 'F', 'R', 'P', 'T', 'T' ],
+                                                 [ 'K', 'C', 'S', 'S', 'Y' ]
+                                             ])
+
+      result.merge! create_letterpress_tiles("#{IMAGES_DIR}/letterpress/board3.png",
+                                             [
+                                                 [ 'L', 'H', 'F', 'L', 'M' ],
+                                                 [ 'R', 'V', 'P', 'U', 'K' ],
+                                                 [ 'V', 'O', 'E', 'E', 'X' ],
+                                                 [ 'I', 'N', 'R', 'I', 'T' ],
+                                                 [ 'V', 'N', 'S', 'I', 'Q' ]
+                                             ])
+
+      result
+    end
+
+
+    # create character files from the given letterpress board image
+    # returns tiles as a hash
+    #
+    def create_letterpress_tiles(input_file, character_map)
+      board = Magick::Image.read(input_file).first
+
+      cropper = LetterpressCropper.new(@config)
+      tile_rows = cropper.crop board
+
+      result = { }
+      tile_rows.zip(character_map) do |tile_row, char_row|
+        tile_row.zip(char_row) do |tile, char|
+          result[char] = tile
+        end
+      end
+
+      result
+    end
+
+  end
+
+end

data/lib/ocarina/letterpress_cropper.rb

@@ -0,0 +1,84 @@
+require 'RMagick'
+
+module Ocarina
+
+  LETTERPRESS_TILES_ACROSS = 5
+  LETTERPRESS_TILES_DOWN   = 5
+  LETTERPRESS_TILE_PIXELS  = 128
+  LETTERPRESS_HEIGHT_OFFSET = 496
+  LETTERPRESS_EXPECTED_WIDTH = LETTERPRESS_TILES_ACROSS * LETTERPRESS_TILE_PIXELS  
+  LETTERPRESS_EXPECTED_HEIGHT = 1136
+
+  # creates tiles of character images from letterpress game boards
+  #
+  class LetterpressCropper
+    include Ocarina::Util
+
+    def initialize(config)
+      @config = config
+    end
+
+    # crops the board into tiles, runs recognizer on each of the tiles,
+    # and returns resulting array of array of chars
+    #
+    def decipher_board(network, board_image)
+      tile_rows = crop board_image
+
+      result = [ ]
+
+      tile_rows.each do |tile_row|
+        row = [ ]
+        tile_row.each do |tile|
+          row << network.recognize(tile).chr
+        end
+
+        result << row
+      end
+
+      result
+    end
+
+
+    # returns an N by N array of image tiles
+    #
+    def crop(image)
+      if image.columns != LETTERPRESS_EXPECTED_WIDTH || image.rows != LETTERPRESS_EXPECTED_HEIGHT
+        image = image.resize(LETTERPRESS_EXPECTED_WIDTH, LETTERPRESS_EXPECTED_HEIGHT)
+      end
+
+      image = quantize_image(image)
+
+      y_offset = LETTERPRESS_HEIGHT_OFFSET
+
+      rows = [ ]
+
+      border = 1
+
+      0.upto(LETTERPRESS_TILES_DOWN - 1) do
+        x_offset = 0
+        row = [ ]
+
+        0.upto(LETTERPRESS_TILES_ACROSS - 1) do
+
+          tile = image.crop(x_offset - border, y_offset + border, LETTERPRESS_TILE_PIXELS - border, LETTERPRESS_TILE_PIXELS - border, true)
+          box = tile.bounding_box
+          min_bound_width = 0.75 * @config.char_width
+          if box.width > min_bound_width
+            tile = tile.crop(box.x - border, box.y - border, box.width + 2 * border, box.height + 2 * border, true)
+          end
+
+          tile.resize!(@config.char_width, @config.char_height)
+          row << tile
+          x_offset += LETTERPRESS_TILE_PIXELS
+
+        end
+        rows << row
+
+        y_offset += LETTERPRESS_TILE_PIXELS
+      end
+
+      rows
+    end
+  end
+
+end

data/lib/ocarina/network.rb

@@ -0,0 +1,264 @@
+require_relative 'util'
+
+module Ocarina
+
+  # a network of neurons
+  #
+  class Network
+
+    include Ocarina::Util
+
+    attr_accessor :current_error, :config
+
+    def initialize(config)
+
+      @config         = config
+      @num_inputs     = config.num_inputs  # total of bits in the image
+
+      #@hidden_count   = (1.5 * num_inputs).to_i  # somewhat arbitrary
+      @hidden_count   = 25
+
+      @input_values   = []   # image bits
+      @input_weights  = []   # weights from inputs -> hidden nodes
+
+      @hidden_outputs = []   # after feed-forward, what the hidden nodes output
+
+      @output_weights = []   # weights from hidden nodes -> output nodes
+      @output_values  = []   # after feed-forward, what the output nodes output
+
+      @output_errors  = []
+      @hidden_errors  = []
+
+      assign_random_weights
+
+      #puts "@input_weights: #{@input_weights}"
+
+      total_input_weights = @input_weights.map { |array| array.reduce(:+) }.reduce(:+)
+      puts "total_input_weights: #{total_input_weights}"
+
+      total_output_weights = @output_weights.map { |array| array.reduce(:+) }.reduce(:+)
+      puts "total_output_weights: #{total_output_weights}"
+    end
+
+    # Attempt to recognize the character displayed on the given image.
+    # image should be an instance of Magick::Image.
+    #
+    # Returns the integer ASCII code for the recognized character.
+    #
+    def recognize(image)
+      # quantize to two-color
+      image = quantize_image(image)
+
+      # the binary string we expect to see from the output nodes
+      assign_inputs image
+
+      calculate_hidden_outputs
+      calculate_final_outputs
+
+      #@output_values.each.with_index { |v, i| puts "index: #{i} => #{v}" }
+
+      # process results
+      #
+      binary_string = quantized_result.inject("") { |accum, bit| "#{accum}#{bit.to_s}" }
+      binary_string.to_i(2)
+    end
+
+    # Train the network on the image, using target_char as the expected result.
+    #
+    # image should be an instance of Magick::Image.
+    #
+    def train(image, target_char)
+      # quantize to two-color
+      image = quantize_image(image)
+      #image.write(filename_for_quantized_image(target_char, 'gif'))
+
+      # the binary string we expect to see from the output nodes
+      @target_binary_string = char_to_binary_string(target_char)
+
+      assign_inputs image
+
+      calculate_hidden_outputs
+      calculate_final_outputs
+      calculate_output_errors
+      calculate_hidden_errors
+
+      # process results
+      #
+      adjust_output_weights
+      adjust_input_weights
+    end
+
+    # persist the network
+    #
+    def save_network_to_file(filepath)
+      File.open(filepath,'w') do|file|
+        Marshal.dump(self, file)
+      end
+    end
+
+    # load a previously-trained network
+    #
+    def self.load_network_from_file(filepath)
+      File.open(filepath) do |file|
+        Marshal.load(file)
+      end
+    end
+
+    private
+
+    def assign_inputs(image)
+
+      num_pixels = image.rows * image.columns
+
+      num_pixels.times do |n|
+        col = pixel_number_to_col(n, image)
+        row = pixel_number_to_row(n, image)
+
+        pixel = image.pixel_color(col, row)
+
+        @input_values[n] = pixel_to_bit(pixel)
+      end
+
+      #text = inputs_as_text image.columns
+      #puts text
+    end
+
+
+    def assign_random_weights
+      weight_range = 0.0001..0.9
+
+      # input -> hidden weights
+      #
+      @num_inputs.times do |input|
+
+        @input_weights[input] = [ ]
+
+        @hidden_count.times do |hidden|
+
+          # we want the overall sum of weights to be < 1
+          weight = rand(weight_range) / (@num_inputs * @hidden_count)
+          @input_weights[input][hidden] = weight
+
+          #puts "input_weights[#{input}][#{hidden}] => #{@input_weights[input][hidden]}"
+        end
+
+      end
+
+      # hidden -> output weights
+      #
+      @hidden_count.times do |hidden|
+
+        @output_weights[hidden] = [ ]
+
+        @config.num_outputs.times do |output|
+          # we want the overall sum of weights to be < 1
+          weight = rand(weight_range) / (@hidden_count * @config.num_outputs)
+          @output_weights[hidden][output] = weight
+        end
+
+      end
+
+    end
+
+    def calculate_hidden_outputs
+
+      @hidden_count.times do |hidden|
+        sum = 0
+        @input_values.count.times do |input|
+          val = @input_values[input] * @input_weights[input][hidden]
+          #puts "input: #{@input_values[input]} * weight: #{@input_weights[input][hidden]} = #{val}"
+
+          sum += val
+        end
+
+        #puts "@hidden_outputs[#{hidden}] = #{sum} (before sigma)"
+        sum = sigma(sum)
+        #puts "@hidden_outputs[#{hidden}] = #{sum} (after sigma)"
+
+        @hidden_outputs[hidden] = sum
+        #puts "@hidden_outputs[#{hidden}] = #{@hidden_outputs[hidden]}"
+      end
+
+    end
+
+    def calculate_final_outputs
+
+      @config.num_outputs.times do |output|
+        sum = 0
+
+        @hidden_count.times do |hidden|
+
+          val = @hidden_outputs[hidden] * @output_weights[hidden][output]
+          sum += val
+        end
+
+        #puts "output: #{sum}, sigma: #{sigma sum}"
+        @output_values[output] = sigma sum
+      end
+    end
+
+    def calculate_output_errors
+      accum_error = 0
+
+      @config.num_outputs.times do |output|
+        expected = @target_binary_string[output].to_i
+        error = (expected - @output_values[output]) * (1.0 - @output_values[output]) * @output_values[output]
+
+        #puts "expected: #{expected}"
+        #puts "output: #{@output_values[output]}"
+        #puts "error: #{'%.10f' % error}"
+        accum_error += error ** 2
+        @output_errors[output] = error
+      end
+
+      # TODO: @current_error only represents the error from the last trained character.
+      # We should keep a running average for the current set of characters for each training "run".
+      #
+      @current_error = Math.sqrt(accum_error)
+      #puts "@current_error: #{'%.10f' %  @current_error}"
+    end
+
+    def calculate_hidden_errors
+      @hidden_count.times do |hidden|
+        sum = 0
+        @config.num_outputs.times do |output|
+          sum += (@output_errors[output] * @output_weights[hidden][output])
+        end
+
+        #puts "sum is: #{sum}"
+        @hidden_errors[hidden] = @hidden_outputs[hidden] * (1 - @hidden_outputs[hidden]) * sum
+        #puts "@hidden_errors[#{hidden}] = #{@hidden_errors[hidden]}"
+      end
+
+    end
+
+    def adjust_output_weights
+      @hidden_count.times do |hidden|
+        @config.num_outputs.times do |output|
+          @output_weights[hidden][output] += (@output_errors[output] * @hidden_outputs[hidden])
+        end
+      end
+    end
+
+    def adjust_input_weights
+      @num_inputs.times do |input|
+        @hidden_count.times do |hidden|
+          @input_weights[input][hidden] += @hidden_errors[hidden] * @input_values[input]
+        end
+      end
+    end
+
+
+    # quantize each of the output nodes to zero or one, return as array
+    #
+    def quantized_result
+      @output_values.map { |output| output.round.to_i }
+    end
+
+    def result_as_binary_string
+      @output_values.inject("") { |accum, val| "#{accum}#{val.round}" }
+    end
+
+  end
+
+end