visual-qrcode 0.1.2 → 0.1.3

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f61f0ec6cbd27dd795252d141fb7dd3b6b9cfb98efe35e73d19176505d3e1c0e
-  data.tar.gz: 5aeb4d2931b1b574d2824dbcfe8d0c03480e30f3395dcc39ec5b262fa61b27ac
+  metadata.gz: 0ed1452bc8167ca44fd547c65998487c46f259967c28edc10ea7730f3e968b62
+  data.tar.gz: e6f33b6faf3d491657f13db6218260ab68888d15e046286bac339267451f79f8
 SHA512:
-  metadata.gz: 5f3588aa015afac87a8ef7375b25c033d8a3a39071941ed9e4ffe6dd35ba3e7039c8c05ec1fca29c5b7fc43348a39ab7d209273aff9c9a92f949f809a6d4d6fe
-  data.tar.gz: 1af2b54970af438dae3c551cf7e0f5126723dff1873f0ea0ca53e0f298e1b2c6948ad93ec7cb832801ad783bf209a61a503987dd12bd01d6ec2820e3717c8c71
+  metadata.gz: 429de2eb4cfa170258b51f814d452df963a32bf54afa6dc2ce8c3ccaf65fc2c8d0da1e490aa9bb2705881cddaf3c511da975610c6f198ae53930793610d6a99a
+  data.tar.gz: d9b1f0e0e9c16592a44a99cb4272adb605189c6902d8e42cf5ef9c4aa0e11ec4c11b209e39fd54ab3b2a4287ca2cf415929e36af742975f3979e5b24cf30f41e

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/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.
+
+![image](/docs/basic_to_visual_sample.png)
 
 ## Installation
 
@@ -30,10 +36,12 @@ 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(
+    "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
@@ -42,26 +50,66 @@ 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. 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("bonjour by 280", "spec/images/marianne.png", size: 280)
+visual_qr_code = VisualQrcode::Qrcode.new(
+    "eh", 
+    "spec/images/zidane.png", 
+    qr_size: 10
+)
 
-visual_qrcode.as_png.write("./marianne_visual_qrcode_280x280.png")
+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 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 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 **default size**, and then reduced to the expected size to maintain a good background image quality.
+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
 
-> 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.
+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
 

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

@@ -14,6 +14,8 @@ module VisualQrcode
         @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

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, qr_size: nil)
       @content = content
       @size = size
+      @padding_modules = padding_modules || DEFAULT_PADDING_MODULES
+      @qr_size = 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_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_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

data/lib/visual_qrcode/version.rb

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

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: visual-qrcode
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 0.1.3
 platform: ruby
 authors:
 - Caillou
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2024-07-12 00:00:00.000000000 Z
+date: 2024-07-15 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