VisualQrcode

VisualQrcode gives you various tools to generate working QR codes with images in their backgrounds, based on this research.

Example of some VisualQrcode generated by the tests :

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.

Installation

Install the gem and add to the application's Gemfile by executing:

$ bundle add visual-qrcode

If bundler is not being used to manage dependencies, install the gem by executing:

$ gem install visual-qrcode

Dependencies

visual-qrcode depends on two gems :

• rqrcode_core
• mini_magick

Make sur that you have the ImageMagick CLI installed on your computer to use mini_magick. See its requirements

Usage

The basic usage requires a string for the QRCode content and an image_path (or image_url).

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

# 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.

If you choose a size too small, you'll get an error informing you of the minimum size necessary for your content.

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 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.

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.

visual_qr_code = VisualQrcode::Qrcode.new(
    "https://en.wikipedia.org/wiki/Zinedine_Zidane",
    "spec/images/zidane.png", 
    size: 260, 
    padding_modules: 0
)

You can also customize the padding if you want more or less modules than the default value.

QRCode minimum Size

The minimum size of RQRCodeCore 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

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

After checking out the repo, run bin/setup to install dependencies. Then, run rake spec to run the tests. You can also run bin/console for an interactive prompt that will allow you to experiment.

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.

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/JeSuisUnCaillou/visual-qrcode/issues.

License

The gem is available as open source under the terms of the MIT License.