visual-qrcode 0.1.1 → 0.1.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ff65d953dd617026b54fb67139962d89a0447ed0d0e7366ed73a3a8a6d9834d
-  data.tar.gz: 8df829a7254d9ce0b60aac4aee8193f9d71a516386ef829ce32ea423b1fcbb87
+  metadata.gz: f61f0ec6cbd27dd795252d141fb7dd3b6b9cfb98efe35e73d19176505d3e1c0e
+  data.tar.gz: 5aeb4d2931b1b574d2824dbcfe8d0c03480e30f3395dcc39ec5b262fa61b27ac
 SHA512:
-  metadata.gz: fdbaf267baf3d51d34871ce631ee7be59b728307e839db6d9bb65d045fa9b83fed6c38d225ddf6a4613e757ca7d90bac285af369161bf94f18a28d3b8e8f5e74
-  data.tar.gz: ae5b2a40c7c9d1d6165f3c7e22255ff019b6a7a4d7b1f5fbb3eddffcd6dd4af0c38c8d6b9976d8cf7807b66ec65cbb821baea950aaf9b1f5a8204ff7737d74c5
+  metadata.gz: 5f3588aa015afac87a8ef7375b25c033d8a3a39071941ed9e4ffe6dd35ba3e7039c8c05ec1fca29c5b7fc43348a39ab7d209273aff9c9a92f949f809a6d4d6fe
+  data.tar.gz: 1af2b54970af438dae3c551cf7e0f5126723dff1873f0ea0ca53e0f298e1b2c6948ad93ec7cb832801ad783bf209a61a503987dd12bd01d6ec2820e3717c8c71

data/.rubocop.yml

@@ -14,3 +14,6 @@ Style/StringLiteralsInInterpolation:
 
 Style/Documentation:
   Enabled: false
+
+Rspec/MultipleMemoizedHelpers:
+  Enabled: false

data/Guardfile

@@ -0,0 +1,33 @@
+# frozen_string_literal: true
+
+# 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(lib spec) \
+#  .select{|d| Dir.exist?(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"
+
+# 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
+  watch(%r{^spec/.+_spec\.rb$})
+  watch(%r{^lib/(.+)\.rb$})     { |m| "spec/#{m[1]}_spec.rb" }
+  watch("spec/spec_helper.rb")  { "spec" }
+end

data/README.md

@@ -1,24 +1,67 @@
 # Visual::Qrcode
 
-TODO: Delete this and the text below, and describe your gem
+`Visual::Qrcode` gives you various tools to generate working QRCodes with images in their backgrounds, based on [this research](https://cgv.cs.nthu.edu.tw/Projects/Recreational_Graphics/Halftone_QRCodes/).
 
-Welcome to your new gem! In this directory, you'll find the files you need to be able to package up your Ruby library into a gem. Put your Ruby code in the file `lib/visual_qrcode`. To experiment with that code, run `bin/console` for an interactive prompt.
+Example of the marianne Visual QRCode generated by the tests :
 
-## Installation
+![image](/spec/images/marianne_visual_qrcode.png)
 
-TODO: Replace `UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG` with your gem name right after releasing it to RubyGems.org. Please do not do it earlier due to security reasons. Alternatively, replace this section with instructions to install your gem from git if you don't plan to release to RubyGems.org.
+## Installation
 
 Install the gem and add to the application's Gemfile by executing:
 
-    $ bundle add UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+    $ bundle add visual-qrcode
 
 If bundler is not being used to manage dependencies, install the gem by executing:
 
-    $ gem install UPDATE_WITH_YOUR_GEM_NAME_IMMEDIATELY_AFTER_RELEASE_TO_RUBYGEMS_ORG
+    $ gem install visual-qrcode
+
+
+## Dependencies
+
+`visual-qrcode` depends on two gems :
+
+- [rqrcode_core](https://github.com/whomwah/rqrcode_core)
+- [mini_magick](https://github.com/minimagick/minimagick)
+
+> Make sur that you have the `ImageMagick` CLI installed on your computer to use `mini_magick`. See its [requirements](https://github.com/minimagick/minimagick?tab=readme-ov-file#requirements)
+
 
 ## Usage
 
-TODO: Write usage instructions here
+The basic usage requires a string for the QRCode content and an `image_path` (or `image_url`).
+**Default size** : 3x the basic QRCode size generated with a high level of error correction.
+
+```ruby
+visual_qr_code = VisualQrcode::Qrcode.new("bonjour", "spec/images/marianne.png")
+
+# Returns a MiniMagick::Image
+image = visual_qr_code.as_png
+
+# MiniMagick::Image has a write method to create an image file
+image.write("./marianne_visual_qrcode.png")
+```
+
+You can also add a size parameter, in pixels. This size can't be smaller than the **default  size**.
+
+```ruby
+visual_qr_code = VisualQrcode::Qrcode.new("bonjour by 280", "spec/images/marianne.png", size: 280)
+
+visual_qrcode.as_png.write("./marianne_visual_qrcode_280x280.png")
+```
+
+## Design choices
+
+### Padding
+
+In order to have a nice visual, a padding is added on the image to keep it inside of the QRCode guide patterns. Also it helps to reckognize that the image _is_ a scannable QRCode and not just some random image.
+
+### Resize method
+
+The Visual QRCode will be generated at a mutiple of the **default size**, and then reduced to the expected size to maintain a good background image quality.
+
+> For example, if the Default size is 140px, and you want a 230px image, it will generate a 280px Visual QRCode and then reduce it to 230px.
+
 
 ## Development
 
@@ -26,9 +69,15 @@ After checking out the repo, run `bin/setup` to install dependencies. Then, run
 
 To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
 
+### Testing
+
+Run `bundle exec rake` to run tests and lint. This is what runs in the CI.
+
+You can also use `bundle exec guard` to run gard and listen to modified files to run the test
+
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/visual-qrcode.
+Bug reports and pull requests are welcome on GitHub at https://github.com/JeSuisUnCaillou/visual-qrcode/issues.
 
 ## License
 

data/lib/visual_qrcode/export.rb

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require "mini_magick"
+require_relative "pixel_tools"
+require_relative "pixels_handler"
+
+module VisualQrcode
+  class Export
+    include PixelTools
+
+    def initialize(pixels)
+      @pixels_handler = PixelsHandler.new(pixels: pixels)
+    end
+
+    def as_png(size: nil, margin: 6)
+      @pixels_handler.add_margin(margin, color: :white)
+      image = MiniMagick::Image.get_image_from_pixels(pixels, dimensions, "RGBA", PIXEL_DEPTH, "png")
+
+      image.resize "#{size}x#{size}" if size
+
+      image
+    end
+
+    def as_text(dark: "x", light: " ")
+      pixels.map do |row|
+        row.map do |pixel|
+          is_light = pixel.nil? || pixel.sum < max_depth * 3
+          is_light ? light : dark
+        end.join
+      end.join("\n")
+    end
+
+    def pixels
+      @pixels_handler.pixels
+    end
+
+    def dimensions
+      @pixels_handler.dimensions
+    end
+  end
+end

data/lib/visual_qrcode/module_filler.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+module ModuleFiller
+  PIXELS_PER_MODULE = 3
+
+  def fill_vqr_module(x_index, y_index)
+    if @common_patterns[x_index][y_index].nil?
+      fill_vqr_module_with_image(x_index, y_index)
+      fill_vqr_module_with_basic_qrcode(x_index, y_index)
+    else
+      fill_vqr_module_with_pattern(x_index, y_index)
+    end
+  end
+
+  protected
+
+  def fill_vqr_module_with_basic_qrcode(x_index, y_index)
+    multiplied_range_each(x_index, y_index) do |new_x, new_y, x_offset, y_offset|
+      if central_pixel?(x_offset, y_offset) || @image_handler.pixels[new_x][new_y][3].zero?
+        value = @basic_qrcode.modules[x_index][y_index]
+        @vqr_pixels[new_x][new_y] = pixel_of(value)
+      end
+    end
+  end
+
+  def fill_vqr_module_with_image(x_index, y_index)
+    multiplied_range_each(x_index, y_index) do |new_x, new_y, x_offset, y_offset|
+      next if central_pixel?(x_offset, y_offset)
+
+      pixel = @image_handler.pixels[new_x][new_y]
+      @vqr_pixels[new_x][new_y] = pixel
+    end
+  end
+
+  def fill_vqr_module_with_pattern(x_index, y_index)
+    multiplied_range_each(x_index, y_index) do |new_x, new_y|
+      value = @common_patterns[x_index][y_index]
+      @vqr_pixels[new_x][new_y] = pixel_of(value)
+    end
+  end
+
+  def multiplied_range_each(x_index, y_index, &block)
+    module_range.each do |x_offset|
+      module_range.each do |y_offset|
+        new_x = (PIXELS_PER_MODULE * x_index * size_multiplier) + x_offset
+        new_y = (PIXELS_PER_MODULE * y_index * size_multiplier) + y_offset
+        block.call(new_x, new_y, x_offset, y_offset)
+      end
+    end
+  end
+
+  def module_size
+    @module_size ||= PIXELS_PER_MODULE * size_multiplier
+  end
+
+  # [0, 1, 2] : all pixels of a module
+  def module_range
+    @module_range ||= 0..(module_size - 1)
+  end
+
+  # 1 : the central pixels of a module
+  def central_range
+    @central_range ||= begin
+      third_of_range = module_range.max / 3
+      (third_of_range + 1)..((third_of_range * 2) + 1)
+    end
+  end
+
+  def central_pixel?(x_offset, y_offset)
+    central_range.include?(x_offset) && central_range.include?(y_offset)
+  end
+end

data/lib/visual_qrcode/pixel_tools.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module PixelTools
+  PIXEL_DEPTH = 8
+
+  def max_depth
+    @max_depth ||= (2**PIXEL_DEPTH) - 1
+  end
+
+  def pixel_of(value)
+    pixel_value = value ? 0 : max_depth
+    [pixel_value, pixel_value, pixel_value, max_depth]
+  end
+
+  def transparent_pixel
+    @transparent_pixel ||= [0] * 4
+  end
+
+  def white_pixel
+    @white_pixel ||= [255] * 4
+  end
+
+  def pixel_of_color(color)
+    send(:"#{color}_pixel")
+  end
+end

data/lib/visual_qrcode/pixels_handler.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require "mini_magick"
+require_relative "pixel_tools"
+
+module VisualQrcode
+  class PixelsHandler
+    include PixelTools
+
+    attr_accessor :pixels
+
+    def initialize(pixels: nil, image_path: nil)
+      if pixels
+        @pixels = pixels
+      else
+        @image = MiniMagick::Image.open(image_path)
+        set_pixels_from_image
+      end
+    end
+
+    def size
+      @pixels.length
+    end
+
+    def dimensions
+      [size] * 2
+    end
+
+    def resize_with_padding(new_size, padding)
+      padded_size = new_size - (2 * padding)
+      resize(padded_size)
+      add_margin(padding)
+    end
+
+    def resize(new_size)
+      image.resize "#{new_size}x#{new_size}"
+      set_pixels_from_image
+    end
+
+    def add_margin(margin, color: :transparent)
+      pixel = pixel_of_color(color)
+      row_margin = [pixel] * margin
+      col_margin = [Array.new(size + (2 * margin), pixel)] * margin
+
+      margined_rows = @pixels.map do |row|
+        row_margin + row + row_margin
+      end
+
+      @pixels = col_margin + margined_rows + col_margin
+    end
+
+    private
+
+    def set_pixels_from_image
+      @pixels = @image.get_pixels("RGBA")
+    end
+
+    def image
+      @image ||= MiniMagick::Image.get_image_from_pixels(@pixels, [size, size], "RGBA", PIXEL_DEPTH, "png")
+    end
+  end
+end

data/lib/visual_qrcode/qrcode.rb

@@ -0,0 +1,83 @@
+# frozen_string_literal: true
+
+require "rqrcode_core"
+require_relative "pixels_handler"
+require_relative "export"
+require_relative "pixel_tools"
+require_relative "module_filler"
+
+module VisualQrcode
+  class Qrcode
+    include PixelTools
+    include ModuleFiller
+
+    PADDING_MODULES = 7
+
+    attr_reader :content, :basic_qrcode, :image_handler, :vqr_pixels
+
+    def initialize(content, image_path, size: nil)
+      @content = content
+      @size = size
+
+      @basic_qrcode = RQRCodeCore::QRCode.new(content, level: :h)
+      @image_handler = VisualQrcode::PixelsHandler.new(image_path: image_path)
+      @common_patterns = @basic_qrcode.instance_variable_get(:@common_patterns)
+    end
+
+    def as_png(margin: default_margin)
+      make
+      VisualQrcode::Export.new(@vqr_pixels).as_png(size: @size, margin: margin)
+    end
+
+    def basic_qrcode_as_png(margin: default_margin)
+      make
+      basic_qrcode_pixels = @basic_qrcode.modules.map do |module_row|
+        pixels_row = module_row.map { |value| [pixel_of(value)] * PIXELS_PER_MODULE }.flatten
+        ([pixels_row] * PIXELS_PER_MODULE)
+      end.flatten(1)
+
+      VisualQrcode::Export.new(basic_qrcode_pixels).as_png(size: @size, margin: margin)
+    end
+
+    def make
+      intit_vqr_pixels
+      resize_image
+      fill_vqr_pixels
+    end
+
+    def intit_vqr_pixels
+      @vqr_length = min_length * size_multiplier
+      @vqr_pixels = Array.new(@vqr_length) { Array.new(@vqr_length) }
+    end
+
+    def resize_image
+      padding_size = PADDING_MODULES * module_size
+      @image_handler.resize_with_padding(@vqr_length, padding_size)
+    end
+
+    def fill_vqr_pixels
+      @basic_qrcode.modules.each_with_index do |module_row, x_index|
+        module_row.each_index do |y_index|
+          fill_vqr_module(x_index, y_index)
+        end
+      end
+    end
+
+    private
+
+    def default_margin
+      module_size * 2
+    end
+
+    def size_multiplier
+      return 1 if @size.nil?
+      raise "Minimum size for your content is #{min_length}px" if @size < min_length
+
+      @size_multiplier ||= 1 + (@size / min_length)
+    end
+
+    def min_length
+      @min_length ||= @basic_qrcode.modules.length * PIXELS_PER_MODULE
+    end
+  end
+end

data/lib/visual_qrcode/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module VisualQrcode
-  VERSION = "0.1.1"
+  VERSION = "0.1.2"
 end

data/lib/visual_qrcode.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "visual_qrcode/version"
-require_relative "visual_qrcode/test"
+require_relative "visual_qrcode/qrcode"
 
 module VisualQrcode
   class Error < StandardError; end

metadata

@@ -1,15 +1,43 @@
 --- !ruby/object:Gem::Specification
 name: visual-qrcode
 version: !ruby/object:Gem::Version
-  version: 0.1.1
+  version: 0.1.2
 platform: ruby
 authors:
 - Caillou
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-07-11 00:00:00.000000000 Z
-dependencies: []
+date: 2024-07-12 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: mini_magick
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5'
+- !ruby/object:Gem::Dependency
+  name: rqrcode_core
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.2'
 description: A gem to generate working QRCodes with images in their background
 email:
 - 6117264+JeSuisUnCaillou@users.noreply.github.com
@@ -21,11 +49,16 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
 - lib/visual_qrcode.rb
-- lib/visual_qrcode/test.rb
+- lib/visual_qrcode/export.rb
+- lib/visual_qrcode/module_filler.rb
+- lib/visual_qrcode/pixel_tools.rb
+- lib/visual_qrcode/pixels_handler.rb
+- lib/visual_qrcode/qrcode.rb
 - lib/visual_qrcode/version.rb
 - sig/visual_qrcode.rbs
 homepage: https://github.com/JeSuisUnCaillou/visual-qrcode

data/lib/visual_qrcode/test.rb

@@ -1,11 +0,0 @@
-# frozen_string_literal: true
-
-module VisualQrcode
-  class Test
-    attr_accessor :input
-
-    def initialize(input)
-      @input = input
-    end
-  end
-end