visual-qrcode 0.1.2 → 1.O.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f61f0ec6cbd27dd795252d141fb7dd3b6b9cfb98efe35e73d19176505d3e1c0e
-  data.tar.gz: 5aeb4d2931b1b574d2824dbcfe8d0c03480e30f3395dcc39ec5b262fa61b27ac
+  metadata.gz: e1d5268c5f404484b75afcee3fa4dc74fe7d6f709a9cfc2405608ac37ce6ca5e
+  data.tar.gz: 5a17c764d5369a18de46ac7fa8b22e7b873eca29912a20dbcc76b27352883d71
 SHA512:
-  metadata.gz: 5f3588aa015afac87a8ef7375b25c033d8a3a39071941ed9e4ffe6dd35ba3e7039c8c05ec1fca29c5b7fc43348a39ab7d209273aff9c9a92f949f809a6d4d6fe
-  data.tar.gz: 1af2b54970af438dae3c551cf7e0f5126723dff1873f0ea0ca53e0f298e1b2c6948ad93ec7cb832801ad783bf209a61a503987dd12bd01d6ec2820e3717c8c71
+  metadata.gz: 839b3876084aa3528b23ca0bd31aded4783ac835c1b4bd76adae190a8c34f987a6aa0746a97f9f233d8a9cdeed141c27880f128d583dd8f98d7f1807175cfa18
+  data.tar.gz: 0ccc5234545ed305ca8a23587da3d7a49200d253c526039dbabccd585bf89e5413fa348966bc09cd112077c2f73f4a21461809ab4481aea71ec480056f9c5a47

data/README.md

@@ -1,10 +1,16 @@
-# Visual::Qrcode
+# VisualQrcode
 
-`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/).
+`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/).
 
-Example of the marianne Visual QRCode generated by the tests :
+Example of some `VisualQrcode` generated by the tests :
 
+![image](/spec/images/ruby_visual_qrcode.png)
 ![image](/spec/images/marianne_visual_qrcode.png)
+![image](/spec/images/zidane_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.
+
+![image](/docs/basic_to_visual_sample.png)
 
 ## Installation
 
@@ -30,10 +36,13 @@ If bundler is not being used to manage dependencies, install the gem by executin
 ## Usage
 
 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")
+visual_qr_code = VisualQrcode::Qrcode.new(
+    "This is the sentence that will read in the QR Code",
+    "spec/images/marianne.png",
+    size: 260
+)
 
 # Returns a MiniMagick::Image
 image = visual_qr_code.as_png
@@ -42,26 +51,56 @@ image = visual_qr_code.as_png
 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**.
+> **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](https://github.com/whomwah/rqrcode_core/tree/master?tab=readme-ov-file#options)). It varies with the amount of content you want to encode in the QR Code.
+> 
+> If you choose a size too small, you'll get an error informing you of the minimum size necessary for your content.
 
-```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
 
+### 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.
+
+Because of that, it is recommended to provide an image bigger than the expected size, to not be made blurry by the resize. You can't go wrong with an image twice as big as the size of the wanted result.
+
 ### 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.
+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 by keeping some of the well-known patterns of the QR Code in the padding.
 
-### Resize method
+**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(
+    "https://en.wikipedia.org/wiki/Zinedine_Zidane",
+    "spec/images/zidane.png", 
+    size: 260, 
+    padding_modules: 0
+)
+```
 
-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.
+You can also customize the padding if you want more or less modules than the default value.
 
-> 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.
+### 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.
+
+You can increase the amount of modules with the `minimum_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(
+    "small content", 
+    "spec/images/zidane.png", 
+    size: 260,
+    minimum_qr_size: 15
+)
+```
 
+You can also force it to a lower value if you want. But it will always be incremented until finding a suitable value for your content size.
 
 ## Development
 

data/lib/visual_qrcode/module_filler.rb

@@ -16,7 +16,7 @@ module ModuleFiller
 
   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?
+      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
@@ -27,7 +27,7 @@ module ModuleFiller
     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]
+      pixel = @pixels_handler.pixels[new_x][new_y]
       @vqr_pixels[new_x][new_y] = pixel
     end
   end

data/lib/visual_qrcode/pixels_handler.rb

@@ -35,6 +35,7 @@ module VisualQrcode
     def resize(new_size)
       image.resize "#{new_size}x#{new_size}"
       set_pixels_from_image
+      make_square
     end
 
     def add_margin(margin, color: :transparent)
@@ -49,8 +50,42 @@ module VisualQrcode
       @pixels = col_margin + margined_rows + col_margin
     end
 
+    def make_square
+      max_size = [@pixels.length, @pixels.first.length].max
+
+      if @pixels.length < max_size
+        add_transparent_columns_to_size(max_size)
+      elsif @pixels.first.length < max_size
+        add_transparent_rows_to_size(max_size)
+      end
+    end
+
     private
 
+    def add_transparent_columns_to_size(max_size)
+      size_difference = max_size - @pixels.length
+      margin = size_difference / 2
+      rest_of_margin = size_difference % 2
+
+      left_col_margin = [Array.new(max_size, transparent_pixel)] * margin
+      right_col_margin = [Array.new(max_size, transparent_pixel)] * (margin + rest_of_margin)
+
+      @pixels = left_col_margin + @pixels + right_col_margin
+    end
+
+    def add_transparent_rows_to_size(max_size)
+      size_difference = max_size - @pixels.first.length
+      margin = size_difference / 2
+      rest_of_margin = size_difference % 2
+
+      left_row_margin = [transparent_pixel] * margin
+      right_row_margin = [transparent_pixel] * (margin + rest_of_margin)
+
+      @pixels = @pixels.map do |row|
+        left_row_margin + row + right_row_margin
+      end
+    end
+
     def set_pixels_from_image
       @pixels = @image.get_pixels("RGBA")
     end

data/lib/visual_qrcode/qrcode.rb

@@ -11,16 +11,18 @@ module VisualQrcode
     include PixelTools
     include ModuleFiller
 
-    PADDING_MODULES = 7
+    DEFAULT_PADDING_MODULES = 7
 
-    attr_reader :content, :basic_qrcode, :image_handler, :vqr_pixels
+    attr_reader :content, :basic_qrcode, :pixels_handler, :vqr_pixels
 
-    def initialize(content, image_path, size: nil)
+    def initialize(content, image_path, size: nil, padding_modules: nil, minimum_qr_size: nil)
       @content = content
       @size = size
+      @padding_modules = padding_modules || DEFAULT_PADDING_MODULES
+      @minimum_qr_size = minimum_qr_size || 6
 
-      @basic_qrcode = RQRCodeCore::QRCode.new(content, level: :h)
-      @image_handler = VisualQrcode::PixelsHandler.new(image_path: image_path)
+      initialize_basic_qr_code_and_minimum_qr_size(content)
+      @pixels_handler = VisualQrcode::PixelsHandler.new(image_path: image_path)
       @common_patterns = @basic_qrcode.instance_variable_get(:@common_patterns)
     end
 
@@ -29,16 +31,6 @@ module VisualQrcode
       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
@@ -51,8 +43,8 @@ module VisualQrcode
     end
 
     def resize_image
-      padding_size = PADDING_MODULES * module_size
-      @image_handler.resize_with_padding(@vqr_length, padding_size)
+      padding_size = @padding_modules * module_size
+      @pixels_handler.resize_with_padding(@vqr_length, padding_size)
     end
 
     def fill_vqr_pixels
@@ -65,6 +57,15 @@ module VisualQrcode
 
     private
 
+    def initialize_basic_qr_code_and_minimum_qr_size(content)
+      @basic_qrcode = RQRCodeCore::QRCode.new(content, level: :h, size: @minimum_qr_size)
+    rescue RQRCodeCore::QRCodeRunTimeError => e
+      raise e unless e.message =~ /^code length overflow./
+
+      @minimum_qr_size += 1
+      initialize_basic_qr_code_and_minimum_qr_size(content)
+    end
+
     def default_margin
       module_size * 2
     end

data/lib/visual_qrcode/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: visual-qrcode
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 1.O.0
 platform: ruby
 authors:
 - Caillou
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-07-12 00:00:00.000000000 Z
+date: 2024-07-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: mini_magick
@@ -53,6 +53,7 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
+- docs/basic_to_visual_sample.png
 - lib/visual_qrcode.rb
 - lib/visual_qrcode/export.rb
 - lib/visual_qrcode/module_filler.rb