special_input_device 0.0.0

data/lib/special_input_device/attributes_equal_checker.rb

@@ -0,0 +1,13 @@
+# The <code>AttributesEqualChecker</code> mixin is used by classes who need to compare two object by comparing all their
+# attributes.
+module SpecialInputDevice::AttributesEqualChecker
+
+  # Compares two objects by using all the attributes of the receiver, return true if all attributes are equal(using
+  # <code>==</code> operator).
+  # @param [Object] other other object
+  # @return [FalseClass, TrueClass]
+  def ==(other)
+    instance_variables.all? { |x| instance_variable_get(x) == other.instance_variable_get(x) }
+  end
+
+end

data/lib/special_input_device/color.rb

@@ -0,0 +1,156 @@
+require_relative('attributes_equal_checker')
+
+# <code>Color</code> object contain 8-bit value of the levels of RGB, can represent a full color.
+class SpecialInputDevice::Color
+
+  include(SpecialInputDevice::AttributesEqualChecker)
+
+  # @return [Fixnum] the level of alpha
+  attr_reader :alpha
+  # @param [Fixnum] value the level of alpha
+  def alpha=(value)
+    @alpha = [value.to_i, 0, 255].sort[1];
+  end
+
+  # @return [Fixnum] the level of blue
+  attr_reader :blue
+  # @param [Fixnum] value the level of blue
+  def blue=(value)
+    @blue = [value.to_i, 0, 255].sort[1];
+  end
+
+  # @return [Fixnum] the level of green
+  attr_reader :green
+  # @param [Fixnum] value the level of green
+  def green=(value)
+    @green = [value.to_i, 0, 255].sort[1];
+  end
+
+  # @return [Fixnum] the level of red
+  attr_reader :red
+  # @param [Fixnum] value the level of red
+  def red=(value)
+    @red = [value.to_i, 0, 255].sort[1];
+  end
+
+  # @!scope class
+  # @overload new(red, green, blue, alpha = 255)
+  #   Returns a new instance of <code>Color</code>.
+  #   @param [Fixnum] red the level of red
+  #   @param [Fixnum] green the level of green
+  #   @param [Fixnum] blue the level of blue
+  #   @param [Fixnum] alpha the level of alpha
+  #   @return [SpecialInputDevice::Color] a new instance of <code>Color</code>
+  def initialize(red, green, blue, alpha = 255)
+    self.red   = red
+    self.green = green
+    self.blue  = blue
+    self.alpha = alpha
+  end
+
+  # Calculate the similarity between two colors. There are difference methods to calculate.
+  # @see SpecialInputDevice.color_compare_method
+  # @param [SpecialInputDevice::Color] other other color
+  # @return [Float] the similarity between 0.0 and 1.0
+  def =~(other)
+    raise(TypeError, "Expecting SpecialInputDevice::Color, #{other.class} gavin") unless other.is_a?(SpecialInputDevice::Color)
+    case SpecialInputDevice.color_compare_method
+      when SpecialInputDevice::COLOR_COMPARE_METHOD::EUCLIDEAN_METRIC_IN_HSL_BIPYRAMIDAL
+        self_hsl                                     = self.hsl
+        other_hsl                                    = other.hsl
+        self_hue, self_saturation, self_lightness    = self_hsl
+        other_hue, other_saturation, other_lightness = other_hsl
+        self_radius                                  = 0.5 - (self_lightness - 0.5).abs
+        other_radius                                 = 0.5 - (other_lightness - 0.5).abs
+        self_xyz                                     = [self_saturation * Math.cos(self_hue) * self_radius, self_saturation * Math.sin(self_hue) * self_radius, self_lightness]
+        other_xyz                                    = [other_saturation * Math.cos(other_hue) * other_radius, other_saturation * Math.sin(other_hue) * other_radius, other_lightness]
+        1 - self_xyz.zip(other_xyz).map { |x| (x[0] - x[1]) ** 2 }.reduce(:+) ** 0.5
+      when SpecialInputDevice::COLOR_COMPARE_METHOD::EUCLIDEAN_METRIC_IN_HSV_CONE
+        self_hsv                                 = self.hsv
+        other_hsv                                = other.hsv
+        self_hue, self_saturation, self_value    = self_hsv
+        other_hue, other_saturation, other_value = other_hsv
+        self_radius                              = self_value / 2
+        other_radius                             = other_value / 2
+        self_xyz                                 = [self_saturation * Math.cos(self_hue) * self_radius, self_saturation * Math.sin(self_hue) * self_radius, self_value]
+        other_xyz                                = [other_saturation * Math.cos(other_hue) * other_radius, other_saturation * Math.sin(other_hue) * other_radius, other_value]
+        1 - (self_xyz.zip(other_xyz).map { |x| (x[0] - x[1]) ** 2 }.reduce(:+) / 1.5) ** 0.5
+      when SpecialInputDevice::COLOR_COMPARE_METHOD::EUCLIDEAN_METRIC_IN_RGB_CUBE
+        1 - (rgb.zip(other.rgb).map { |x| (x[0] - x[1]) ** 2 }.reduce(:+) / 3) ** 0.5
+      else
+        raise(RuntimeError, "Undefined color compare method '#{SpecialInputDevice.color_compare_method.to_s}'.")
+    end
+  end
+
+  # @return [Array(Float, Float, Float)] the three value of RGB model in floating point representation
+  # @see https://en.wikipedia.org/wiki/RGB_color_model Wikipedia - RGB color model
+  def rgb
+    [red, green, blue].map { |x| x / 255.0 }
+  end
+
+  # @return [Array(Float, Float, Float)] the three value of HSL model in radius and floating point representation
+  # @see https://en.wikipedia.org/wiki/HSL_and_HSV Wikipedia - HSL and HSV
+  def hsl
+    rgb              = self.rgb
+    red, green, blue = rgb
+    max              = rgb.max
+    min              = rgb.min
+    different        = max - min
+    if different > 0
+      hue        = case max
+                     when red
+                       ((green - blue) / different % 6) * (Math::PI / 3)
+                     when green
+                       ((blue - red) / different + 2) * (Math::PI / 3)
+                     when blue
+                       ((red - green) / different + 4) * (Math::PI / 3)
+                     else
+                       raise
+                   end
+      saturation = different / (1 - (max + min - 1).abs)
+    else
+      hue        = 0
+      saturation = 0
+    end
+    lightness = (max + min) / 2
+    [hue, saturation, lightness]
+  end
+
+  # @return [Array(Float, Float, Float)] the three value of HSV model in radius and floating point representation
+  # @see https://en.wikipedia.org/wiki/HSL_and_HSV Wikipedia - HSL and HSV
+  def hsv
+    rgb              = self.rgb
+    red, green, blue = rgb
+    max              = rgb.max
+    min              = rgb.min
+    different        = max - min
+    if different > 0
+      hue = case max
+              when red
+                (green - blue) / different % 6 * Math::PI / 3
+              when green
+                (blue - red) / different + 2 * Math::PI / 3
+              when blue
+                (red - green) / different + 4 * Math::PI / 3
+              else
+                raise
+            end
+    else
+      hue = 0
+    end
+    saturation = max > 0 ? different / max : 0
+    value      = max
+    [hue, saturation, value]
+  end
+
+  # @!visibility private
+  def inspect
+    '#%02x%02x%02x%02X' % [alpha, red, green, blue]
+  end
+
+  # @!visibility private
+  def to_s
+    '#%02x%02x%02x%02X' % [alpha, red, green, blue]
+  end
+
+end

data/lib/special_input_device/image.rb

@@ -0,0 +1,170 @@
+require_relative('table_2d')
+
+# <code>SpecialInputDevice::Image</code> object represent an image.
+class SpecialInputDevice::Image < SpecialInputDevice::Table2D
+
+  # A container of all return methods used by <code>#find</code> method.
+  # @see #find
+  module RETURN_METHOD
+    # Returning the first match.
+    FIRST   = :first
+    # Returning the highest similarity match.
+    CLOSEST = :closest
+  end
+
+  # Load an image from a file.
+  # @param [File, String] argument the file need to load
+  # @return [SpecialInputDevice::Image] a new image
+  def self.load(argument)
+    case argument
+      when String
+        file = File.open(argument, 'rb')
+      when File
+        file = argument
+        file.binmode
+      else
+        raise(TypeError, "Expecting String or File, #{argument.class} gavin")
+    end
+    extension = file.path[/(?<=\.)(?<!\/\.)(?<!\\\.)\w+\Z/].upcase
+    # noinspection RubyResolve
+    image     = const_get(extension).load(file)
+    file.close unless argument == file
+    image
+  end
+
+  # Save this image to a file.
+  # @param [File, String] argument the target file
+  # @return [SpecialInputDevice::Image] self
+  def save(argument)
+    case argument
+      when String
+        file = File.open(argument, 'wb')
+      when File
+        file = argument
+        file.binmode
+      else
+        raise(TypeError, "Expecting String or File, #{argument.class} gavin")
+    end
+    extension = file.path[/(?<=\.)(?<!\/\.)(?<!\\\.)\w+\Z/].upcase
+    SpecialInputDevice::Image.const_get(extension).save(self, file)
+    file.close unless argument == file
+    self
+  end
+
+  # Calculate similarity between a section of this image and another smaller image which provided by parameter
+  # <code>image</code>. The parameters <code>x</code> and <code>y</code> indicate the position of the upper-left corner
+  # of the section. The size of section is same as the size of smaller image. This method compares each pixel in two
+  # image at the same position.
+  # @param [Integer] x the x-coordinate of the upper-left corner of the section
+  # @param [Integer] y the y-coordinate of the upper-left corner of the section
+  # @param [SpecialInputDevice::Image] image another image, should be smaller
+  # @param [Float] minimum_similarity minimum limit of similarity
+  # @return [Float, NilClass] similarity the similarity or nil if similarity is lower than minimum limit
+  def similarity_at(x, y, image, minimum_similarity = 0.0)
+    image_width  = image.width
+    image_height = image.height
+    return nil unless width - x >= image_width && height - y >= image_height
+    current_similarity = 1.0
+    image_size         = image_width * image_height
+    (0...image_width).each do |x0|
+      (0...image_height).each do |y0|
+        current_similarity -= (1 - (self[x + x0, y + y0] =~ image[x0, y0])) / image_size
+        return nil if current_similarity < minimum_similarity
+      end
+    end
+    current_similarity
+  end
+
+  # Find the position of another smaller image in this image.
+  # @param [SpecialInputDevice::Image] image another image, should be smaller
+  # @param [Float] similarity minimum limit of similarity
+  # @param [Symbol] _return indicate the behavior of this method, see SpecialInputDevice::Image::RETURN_METHOD
+  # @return [SpecialInputDevice::Rectangle, NilClass] the position
+  # @see SpecialInputDevice::Image::RETURN_METHOD
+  def find(image, similarity: 1.0, _return: RETURN_METHOD::FIRST)
+    methods = RETURN_METHOD.constants(false).map { |x| RETURN_METHOD.const_get(x) }
+    raise("Undefined return method '#{_return.to_s}' passed, Defined methods are [#{methods.join(', ')}].") unless methods.include?(_return)
+    closest_similarity   = 0.0
+    closest_similarity_x = nil
+    closest_similarity_y = nil
+    find_path(image) do |x0, y0|
+      next unless (current_similarity = similarity_at(x0, y0, image, similarity))
+      case _return
+        when RETURN_METHOD::FIRST
+          return SpecialInputDevice::Rectangle.new(x0, y0, image.width, image.height)
+        when RETURN_METHOD::CLOSEST
+          return SpecialInputDevice::Rectangle.new(x0, y0, image.width, image.height) if current_similarity == 1.0
+          if current_similarity > closest_similarity
+            closest_similarity   = current_similarity
+            closest_similarity_x = x0
+            closest_similarity_y = y0
+          end
+        else
+          raise(RuntimeError, "Undefined return method '#{_return.to_s}'.")
+      end
+    end
+    return nil unless closest_similarity_x || closest_similarity_y
+    SpecialInputDevice::Rectangle.new(closest_similarity_x, closest_similarity_y, image.width, image.height)
+  end
+
+  # Override this method if validation is needed. In this method, raise an <code>Exception</code> if it is not valid.
+  # @param [Integer] x the x coordinate
+  # @param [Integer] y the y coordinate
+  # @param [Object] value the object at the specific coordinate
+  # @return [Object] the value to be stored
+  def validate(x, y, value)
+    raise(TypeError, "Expecting SpecialInputDevice::Color, #{value.class} gavin") if value && !value.is_a?(SpecialInputDevice::Color)
+    value
+  end
+
+  protected(:validate)
+
+  def find_path(image)
+    return nil unless image.width <= width && image.height <= height
+    width_difference    = width - image.width
+    height_difference   = height - image.height
+    smaller_difference  = [width_difference, height_difference].min
+    half_difference     = smaller_difference / 2
+    need_special_handle = smaller_difference.even?
+    if need_special_handle
+      if width_difference < height_difference
+        (height_difference - half_difference).downto(half_difference) do |x0|
+          yield half_difference, x0
+        end
+      elsif width_difference > height_difference
+        (width_difference - half_difference).downto(half_difference) do |x0|
+          yield x0, half_difference
+        end
+      else
+        yield half_difference, half_difference
+      end
+    end
+    (half_difference - (need_special_handle ? 1 : 0)).downto(0) do |x0|
+      left   = x0
+      right  = width_difference - x0
+      top    = x0
+      bottom = height_difference - x0
+      (x0 + 1).upto(bottom) do |x1|
+        yield left, x1
+      end
+      (x0 + 1).upto(right) do |x1|
+        yield x1, bottom
+      end
+      (bottom - 1).downto(top) do |x1|
+        yield right, x1
+      end
+      (right - 1).downto(left) do |x1|
+        yield x1, top
+      end
+    end
+  end
+
+  private(:find_path)
+
+end
+
+require_relative('image/error/image_error')
+require_relative('image/error/damaged_image_error')
+require_relative('image/error/unsupported_image_format_error')
+
+require_relative('image/bmp')

data/lib/special_input_device/image/bmp.rb

@@ -0,0 +1,89 @@
+# <code>SpecialInputDevice::Image::BMP</code> is an image decoder for bmp files.
+module SpecialInputDevice::Image::BMP
+
+  # The header identifiers of bitmap.
+  # This should be the first two bytes in the bitmap file.
+  BITMAP_HEADER_IDENTIFIERS = ['BM', 'BA', 'CI', 'CP', 'IC', 'PT']
+
+  # Load a image from a bmp file.
+  # @param [File] file the file need to load
+  # @return [SpecialInputDevice::Image] the image
+  def self.load(file)
+    filename                 = file.is_a?(File) ? "The path '#{file.path}'" : 'This bitmap file'
+    bitmap_header_identifier = file.read(2)
+    raise(ArgumentError, "#{filename} does not point to a bitmap file.") unless BITMAP_HEADER_IDENTIFIERS.include?(bitmap_header_identifier)
+    system_file_size = file.size if file.is_a?(File)
+    bitmap_file_size = file.read(4).unpack('L<')[0]
+    raise(SpecialInputDevice::DamagedImageError, "The size of the file at '#{path}' should be #{bitmap_file_size} bytes, but the image only has #{system_file_size} bytes.") if file.is_a?(File) && bitmap_file_size != system_file_size
+    file.read(4) # Reserved field
+    image_data_address = file.read(4).unpack('L<')[0]
+    dib_header_size    = file.read(4).unpack('L<')[0]
+    raise(SpecialInputDevice::UnsupportedImageFormatError, "#{filename} is using an unsupported DIB header.") unless dib_header_size == 40
+    width                  = file.read(4).unpack('l<')[0]
+    height                 = file.read(4).unpack('l<')[0]
+    number_of_color_planes = file.read(2).unpack('S<')[0]
+    raise(SpecialInputDevice::DamagedImageError, "#{filename} has been damaged.") unless number_of_color_planes == 1
+    color_depth        = file.read(2).unpack('S<')[0]
+    compression_method = file.read(4).unpack('L<')[0]
+    raise(SpecialInputDevice::UnsupportedImageFormatError, "#{filename} is using an unsupported compression method.") unless compression_method == 0
+    image_size = file.read(4).unpack('L<')[0]
+    file.read(4) # Horizontal resolution
+    file.read(4) # Vertical resolution
+    file.read(4) # Number of colors in the color palette
+    file.read(4) # Number of important colors used
+    file.read(image_data_address - 14 - dib_header_size) # Palette
+    raise(SpecialInputDevice::DamagedImageError, "#{filename} has been damaged.") unless image_size == (color_depth * width.abs + 31) / 32 * 4 * height.abs
+    padding_size = -color_depth * width % 32 / 8
+    image        = SpecialInputDevice::Image.new(width.abs, height.abs)
+    if color_depth == 24 || color_depth == 32
+      byte_size = color_depth / 8
+      (height > 0 ? (height - 1).downto(0) : height.upto(-1)).each do |x0|
+        (width > 0 ? 0.upto(width - 1) : -1.downto(width)).each do |x1|
+          color              = file.read(byte_size).unpack("C#{byte_size}")
+          color[0], color[2] = color[2], color[0]
+          image[x1, x0]      = SpecialInputDevice::Color.new(*color)
+        end
+        file.read(padding_size)
+      end
+    else
+      raise(SpecialInputDevice::UnsupportedImageFormatError, "#{filename} is using an unsupported number of bits per pixel.")
+    end
+    image
+  end
+
+  # Save the image to a bmp file.
+  # @param [SpecialInputDevice::Image] image the file need to load
+  # @param [File] file the file need to load
+  # @return [SpecialInputDevice::Image] the image
+  def self.save(image, file)
+    bmp_header_size  = 14
+    dib_header_size  = 40
+    headers_size     = bmp_header_size + dib_header_size
+    color_depth      = 32
+    width            = image.width
+    height           = image.height
+    row_size         = color_depth / 8 * width
+    image_size       = row_size * height
+    bitmap_file_size = headers_size + image_size
+    pack_format      = "C#{row_size}"
+
+    file.write(BITMAP_HEADER_IDENTIFIERS[0])
+    file.write([bitmap_file_size].pack('L<')) # Bitmap file size
+    file.write([0].pack('L<')) # Reserved field
+    file.write([headers_size].pack('L<')) # Image data address
+    file.write([dib_header_size].pack('L<')) # DIB header size
+    file.write([width].pack('L<')) # Width
+    file.write([height].pack('L<')) # Height
+    file.write([1].pack('S<')) # Number of color planes
+    file.write([color_depth].pack('S<')) # Color depth
+    file.write([0].pack('L<')) # Compression method
+    file.write([image_size].pack('L<')) # Image size
+    file.write([0].pack('L<')) # Horizontal resolution
+    file.write([0].pack('L<')) # Vertical resolution
+    file.write([0].pack('L<')) # Number of colors in the color palette
+    file.write([0].pack('L<')) # Number of important colors used
+    image.each_row.reverse_each { |row| file.write((row.map { |x| [x.blue, x.green, x.red, x.alpha] }.flatten).pack(pack_format)) }
+    file
+  end
+
+end

data/lib/special_input_device/image/error/damaged_image_error.rb

@@ -0,0 +1,4 @@
+# <code>SpecialInputDevice::DamagedImageError</code> occur when loading a image which contain contradiction. For
+# example, the image size from header of BMP file and file system do not match.
+class SpecialInputDevice::DamagedImageError < SpecialInputDevice::ImageError
+end

data/lib/special_input_device/image/error/image_error.rb

@@ -0,0 +1,3 @@
+# <code>SpecialInputDevice::ImageError</code> is the base error class of all image error.
+class SpecialInputDevice::ImageError < RuntimeError
+end

data/lib/special_input_device/image/error/unsupported_image_format_error.rb

@@ -0,0 +1,4 @@
+# <code>SpecialInputDevice::UnsupportedImageFormatError</code> occur when loading a image file and that file's format is
+# not supported yet.
+class SpecialInputDevice::UnsupportedImageFormatError < SpecialInputDevice::ImageError
+end