visual-qrcode 0.1.1 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1ff65d953dd617026b54fb67139962d89a0447ed0d0e7366ed73a3a8a6d9834d
-  data.tar.gz: 8df829a7254d9ce0b60aac4aee8193f9d71a516386ef829ce32ea423b1fcbb87
+  metadata.gz: 0ed1452bc8167ca44fd547c65998487c46f259967c28edc10ea7730f3e968b62
+  data.tar.gz: e6f33b6faf3d491657f13db6218260ab68888d15e046286bac339267451f79f8
 SHA512:
-  metadata.gz: fdbaf267baf3d51d34871ce631ee7be59b728307e839db6d9bb65d045fa9b83fed6c38d225ddf6a4613e757ca7d90bac285af369161bf94f18a28d3b8e8f5e74
-  data.tar.gz: ae5b2a40c7c9d1d6165f3c7e22255ff019b6a7a4d7b1f5fbb3eddffcd6dd4af0c38c8d6b9976d8cf7807b66ec65cbb821baea950aaf9b1f5a8204ff7737d74c5
+  metadata.gz: 429de2eb4cfa170258b51f814d452df963a32bf54afa6dc2ce8c3ccaf65fc2c8d0da1e490aa9bb2705881cddaf3c511da975610c6f198ae53930793610d6a99a
+  data.tar.gz: d9b1f0e0e9c16592a44a99cb4272adb605189c6902d8e42cf5ef9c4aa0e11ec4c11b209e39fd54ab3b2a4287ca2cf415929e36af742975f3979e5b24cf30f41e

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,115 @@
-# Visual::Qrcode
+# VisualQrcode
 
-TODO: Delete this and the text below, and describe your gem
+`VisualQrcode` gives you various tools to generate working QR codes 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 some `VisualQrcode` generated by the tests :
 
-## Installation
+![image](/spec/images/marianne_visual_qrcode.png)
+![image](/spec/images/zidane_visual_qrcode.png)
+![image](/spec/images/leaf_visual_qrcode.png)
+
+Basically, each QR Code module is transformed into 9 pixels. The central pixel is the QR Code data, and the 8 other pixels around are used to display the background image.
 
-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.
+![image](/docs/basic_to_visual_sample.png)
+
+## 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`).
+
+```ruby
+visual_qr_code = VisualQrcode::Qrcode.new(
+    "Taataaaa Yoyoyooooo ! Qu'est-ce que tu caches sous ton grand chapeauuuuuu !",
+    "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")
+```
+
+**Default size** : Because we need 9 pixels in each QR Code module, the **minimum size** is **3x the minimum basic QRCode size**  with a high level of error correction. It varies with the amount of content you want to encode in the QR Code.
+
+You can also add a size parameter, in pixels. This size can't be smaller than the **minimum  size**.
+
+```ruby
+visual_qr_code = VisualQrcode::Qrcode.new(
+    "This is a leaf. Yeah. Big surprise, isn't it ?", 
+    "spec/images/leaf.png", 
+    size: 280
+)
+
+visual_qrcode.as_png.write("./leaf_visual_qrcode_280x280.png")
+```
+
+If you choose a size too small, you'll get an error informing you of the minimum size necessary for your content.
+
+If your content is small and produces a QR Code of small size (big patterns, few modules), you can increase the amount of modules with the `qr_size` parameter. It corresponds to the [size option of RQRCodeCore](https://github.com/whomwah/rqrcode_core/tree/master?tab=readme-ov-file#options)
+
+```ruby
+visual_qr_code = VisualQrcode::Qrcode.new(
+    "eh", 
+    "spec/images/zidane.png", 
+    qr_size: 10
+)
+
+visual_qrcode.as_png.write("./zidane_visual_qrcode_size_10.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 line patterns on top and on the left. Also it helps to reckognize that the image _is_ a scannable QRCode and not just some random image.
+
+**By default, the padding is equal to 7 modules.**
+
+If your image has enough transparency to dodge the QRCode lines, you can remove the padding with the `padding_modules: 0` option.
+
+```ruby
+visual_qr_code = VisualQrcode::Qrcode.new(
+    "My leaf don't need no padding, it's a strong and independant leaf",
+    "spec/images/leaf.png", 
+    size: 280, 
+    padding_modules: 0
+)
+```
+
+You can also customize the padding if you want more or less modules than the default value.
+
+### Resize method
+
+The Visual QRCode will be generated at a mutiple of the **minimum size**, and then reduced to the expected size to maintain a good background image quality.
+
+> For example, if the minimum size is 140px, and you want a 230px image, it will generate a 280px Visual QRCode and then reduce it to 230px.
+
+### QRCode minimum Size
+
+The minimum [size of RQRCodeCore](https://github.com/whomwah/rqrcode_core/tree/master?tab=readme-ov-file#options) used is 6 by default, to get enough space for the image to be visible inside the Visual QRCode.
+
+But you can force it to a lower value if you want, with the `qr_size` option.
 
 ## Development
 
@@ -26,9 +117,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) || @pixels_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 = @pixels_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,64 @@
+# 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)
+        raise "Image should be a square" if @image.width != @image.height
+
+        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,84 @@
+# 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
+
+    DEFAULT_PADDING_MODULES = 7
+
+    attr_reader :content, :basic_qrcode, :pixels_handler, :vqr_pixels
+
+    def initialize(content, image_path, size: nil, padding_modules: nil, qr_size: nil)
+      @content = content
+      @size = size
+      @padding_modules = padding_modules || DEFAULT_PADDING_MODULES
+      @qr_size = qr_size || 6
+
+      initialize_basic_qr_code_and_qr_size(content)
+      @pixels_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 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
+      @pixels_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 initialize_basic_qr_code_and_qr_size(content)
+      @basic_qrcode = RQRCodeCore::QRCode.new(content, level: :h, size: @qr_size)
+    rescue RQRCodeCore::QRCodeRunTimeError => e
+      raise e unless e.message =~ /^code length overflow./
+
+      @qr_size += 1
+      initialize_basic_qr_code_and_qr_size(content)
+    end
+
+    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.3"
 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.3
 platform: ruby
 authors:
 - Caillou
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-07-11 00:00:00.000000000 Z
-dependencies: []
+date: 2024-07-15 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,17 @@ files:
 - ".rubocop.yml"
 - ".ruby-version"
 - CHANGELOG.md
+- Guardfile
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/basic_to_visual_sample.png
 - 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