Generating QR Codes in Linux

Creating and Reading QR Codes

By

With the right tools, you can create your own QR code squares with information you want to share on a business card, in a letter, or on your website.

Read errors of unreliable, one-dimensional bar codes often caused interruptions in industrial production, prompting companies like Toyota and its subsidiary Denso Wave to develop as early as 1994 a new code for acquiring stock data. The new matrix bar code was designed to store more information than the traditional bar code and to stay legible, even if the label was dirty, wrinkled, or partially destroyed.

The quick response code, or QR code, comprises a matrix of square dots instead of the usual lines. Measuring up to 177 by 177 dots, the QR code encodes up to 4,296 characters, compared with a bar code that encodes just 13.

Thanks to numerous free reader apps for smartphones, QR codes have gained in popularity in recent years. Posters, catalogs, magazines, business cards, and even television screens display the small squares, offering additional information or URLs for microsites.

Data Grabber

If you want to encode your address into a QR code for a business card, you could try one of the many services on the Internet. However, restrictions typically apply. For example, some services allow only QR codes in a certain size or in limited quantities. Also, you never know for sure, what the services do with your data. For example, some sites explicitly allow sharing and selling the data to third parties in their terms of use, more or less pre-programming an increase in junk mail in the future. Fortunately, several QR code tools can help you avoid these problems in Linux.

On My Mark!

The quickest way to create a QR code is with the Qrencode command-line utility. Any major distribution can install Qrencode via the package manager. The following command then creates a QR code containing the text “Hello World!” (Figure 1):

$ qrencode -o qrcode.png 'Hello World!'
Figure 1: Qrencode encoding the string “Hello World!” as a QR code and storing it in the qrcode.png file.

The generated QR code ends up in the qrcode.png file. If the file already exists, it’s overwritten without prompting. If you have at least version 3.3.0 (qrencode -V), Qrencode can generate an EPS graphic,

$ qrencode -t EPS -o qrcode.eps 'Hello World!'

or ASCII output (Figure 2).

Figure 2: Outputting QR codes in ASCII characters just for fun. Each # corresponds to a dot.

In the QR code image, the software creates a white border the width of one dot. This facilitates the process of deciphering the code for programs or the smartphone later on. If desirable, you can increase or decrease the edge with the -m parameter; in the following example the border width would be 10 code pixels:

$ qrencode -m 10 -o qrcode.png 'Hello World!'

If you are saving the QR code in PNG format, the -s parameter specifies the height of a black QR code pixel. By default, Qrencode draws every black dot three by three pixels. The program creates a slightly smaller QR code with quite a wide margin with the following command:

$ qrencode -s 2 -m 10 -o qrcode.png 'Hello World!'

A white border appears around the QR code that is exactly 20 screen pixels wide (10 QR code dots in width, with each dot two pixels). If you are creating EPS images, the only parameter available is -m; -s moves the entire QR code out of the image in this case. To control the resolution of PNGs further, use the -d parameter to define the dpi.

Tolerance

Besides the specified data, the QR code contains additional error correction information. If a portion of the image is damaged, it allows you to reconstruct the missing or illegible data. The more additional information the QR code contains, the more heavily damaged it can be without becoming useless.

Increasing the error tolerance increases the size of the image because you need more black dots (Figure 3).

Figure 3: Both QR codes contain the text Hello World!; the one on the left uses the highest error correction level, H, and therefore is more robust – but also larger.

The QR code standard thus uses four levels of error correction: H level allows you to read all data if 30 percent of the QR code is destroyed, Q level if 25 percent is unreadable, and M level if just 15 percent is unintelligible. At the lowest level, L, only 7 percent of the data can be faulty. In Qrencode, the -l parameter selects the error correction level. The possible values are pretty much what you would expect: L, M, Q, and H.

The level you choose depends on the proposed use. If you expect the QR code to be exposed to external influences (e.g., wind, weather, graffiti) or if you are planning to manipulate the image deliberately (see the “Intruders” box), you will want the highest level, H. On a business card, the lowest level, L, is sufficient. If in doubt, simply omit the -l parameter. The program then uses level L by default.

Variety

Qrencode lets you encode any text, including URLs. You only need to use single quotes if blanks and non-standard characters appear in the text:

$ qrencode -o lpm.png http://www.linuxpromagazine.com

All modern QR code readers recognize that this is a web address and will offer to open it in the browser.

Getting an QR-encoded address automatically to enter a smartphone owner’s address book is more difficult. In this case, you need to enter your address and some additional, cryptic information:

$ qrencode -o address.png 'BEGIN:VCARD VERSION:4.0 FN: N:Schuermann;Tim;;; ADR:;;Putzbrunner Str. 71;Munich;;81739; END:VCARD'

Typing this is not exactly easy, so to make life easier, you might prefer a QR code generator with a graphical user interface, such as QtQR.

QtQR

As the name suggests, QtQR is based on Qt. The tool relies on Python and the python-qrtools library. You can simply install the program via the package manager on Ubuntu. For other distributions, you will find the source code and RPM and DEB packages on the project’s download page.

The main window in QtQR is quite simple: Top left in the selection you can set what data you want to store in the QR code. For an address, choose Contact Information (PhoneBook). Depending on the type of information, QtQR displays appropriate fields (Figure 4).

Figure 4: QtQR can also decode QR codes. Here, the software is reading a QR code saved as a file with the information shown in the left panel of the window.

As you fill out the fields, the program creates the corresponding QR code on the right. You can resize the code at top right. Pixel Size lets you set the number of pixels per square dot the QR code uses, whereas Margin Size lets you specify the size of the margin. Error Correction lets you define the correction level. Once you have set all parameters, save the code as a PNG file by clicking the Save QRCode button.

Portable QR-Code Generator

If QtQR’s capabilities do not meet your needs, you can try Portable QR-Code Generator. It also encodes geographical coordinates and WiFi access data, which can be useful if you want to offer guests quick access to WiFi as a hotel or coffee shop operator, for example.

Because Portable QR-Code Generator is written in Java, you must first install a Java run-time environment via the package manager. On Ubuntu, launch the Software Center and find the OpenJDK Java 7 runtime; on openSUSE 12.3, the matching package goes by the name java-1_7_0-openjdk.

The ZIP archive of the portable QR code generator is available from the project’s Downloads page (to download, click on the Herunterladen link under the .zip entry). Unzip the file on your hard drive, open a terminal window, change to the directory with the extracted files, and run the command:

$ java -jar QRCodeGen.jar

The main window appears, and a small preview window (Figure 5) shows you the QR code.

Figure 5: Portable QR-Code Generator offers numerous functions but also uses plenty of space on the screen – scrollbars are not included.

In the main window, look at the top edge first. Depending on the data you want to store in the code, click on the appropriate tab; that is, to save a URL, open the URL tab, and for an address, use VCard v4.

In the selected tab, the program displays appropriate fields. For an address, you will see more tabs that group the information, but you only need to fill out the required fields. If you do not want to specify a phone number, simply ignore the Telephone tab. If the address is already in a vCard file, you can import it by clicking Read VCard.

Once you have entered the data to encode, click on Generate. The results appear in the preview window. Plain text (in the Text tab) and geographic coordinates (in the Geo URI tab) are exceptions; the preview shows the code during entry.

You can define the size of the QR codes, as well as the error correction level at the bottom left under QR Code options section. In contrast to the previously featured tools, the Portable QR code generator allows you to specify the dimensions for the final image.

If you set Requested size (pixel) to 400, the resulting QR code image is 400 screen pixels wide. However, if you want to specify the size of each dot in the code, set Mode to Module size, then in Module size (pixel) define the number of pixels to form a dot. Additionally, you can select a specific Character encoding (see the “Character Encoding” box).

To the right, in the QR Code details panel, you will see some statistics that reveal, among other things, how many bytes of payload (Data byes) the QR code currently displayed contains. To check the text that the Portable QR code generator actually dumped into the QR code, look at the bottom of the window; the details are in the Data field.

You can copy the generated QR code to the clipboard (Edit | Copy QR Code to clipboard) or save a PNG format image file with File | Save As.

KDE Applications

KDE users have an easy way to convert text into QR code: Copy some text to the clipboard, click the Klipper tool (the scissors) in the system section of the control bar at the bottom, and select Show Barcode. Unfortunately, the interface does not let you save the QR code shown on the left side (Figure 6) or copy it to the clipboard. Your only workaround is to grab a screenshot with KSnapshot. For a single QR code this will still be faster than installing one of the other tools.

Figure 6: The KDE Klipper tool, which manages the Clipboard, can produce QR code on the fly.

A possible alternative is the slightly older KBarcode4-light. To use it, first install PyQt via the package manager. On openSUSE 12.3 and Ubuntu, it resides in the python-qt4 package. Next, unpack the KBarcode4-light archive, which you downloaded off the web. In the src subdirectory, run the python kbarcode.py command.

In the window that now appears (Figure 7), select the QR Code item in the Encoding drop-down, then type the text to encode in Value, and press Generate. The resulting QR code appears at the bottom. Pressing Save as PDF lets you save the code in a text file.

Figure 7: KBarcode4-light offers less functionality than Qrencode.

Theoretically, it’s possible to export the QR code as an image file, but clicking Save on modern distributions only leads to an error message in the terminal. Another alternative is to click Copy and then paste the Clipboard contents into another program. The options offered in the Basic Options and Extra Options tabs are useless for QR codes.

Bookworms

Although dozens of apps are out there for reading QR codes with smartphones, only a few fairly rudimentary programs exist for Linux. If you have QtQR installed, press Decode in the bottom right corner of the main window. The program either accepts the QR code as an image file (Decode from File), or reads it via a webcam (Decode from Webcam).

However, QtQR is quite picky: For example, it does not interpret QR codes for dots of exactly one pixel. Additionally, the program stubbornly insists that the text contains ISO-8859-1 character encoding. If you have a QR code image file, one option is to use the Libdecodeqr-simpletest program, which is actually only intended as an example program for programmers on how to read codes in their own programs with the Libdecodeqr library. However, it is excellent for reading codes at the command line.

On Ubuntu, you can install the reader from the libdecodeqr-examples package with:

sudo apt-get install libdecodeqr-examples

Owners of other distros first need to install a C++ compiler, make, and developer files from OpenCV (on openSUSE, in the opencv-devel package). Then, use the archive of the current version from the Latest Stable Source Code section. Extract it on your hard drive, and in the resulting src subdirectory, enter the following three commands: ./configure, make and sudo make install.

As soon as the program exists on your hard drive, you can decipher QR code in the qrcode.png file with the following command:

$ libdecodeqr-simpletest qrcode.png

… at least in theory; the practical results will be disappointing in many cases. In my tests, libdecodeqr-simpletest simply refused to see any data in the QR codes (Figure 8).

Figure 8: libdecodeqr-simpletest identifies the QR code but does not return the text.

Touch the Bar!

A much better alternative is ZBar. This program reads QR codes from files or via a connected webcam. Ubuntu includes the small tool in the zbar-tools package. On other distributions, you first need to run the package manager to install the developer packages for Qt4, PyGTK and ImageMagick. On openSUSE 12.3, they are named libqt4-devel, python-gtk-devel, and ImageMagick-devel.

If you want to read the QR code with the webcam, you additionally need the kernel header files; on openSUSE 12.3, they are located in the kernel-devel package. If you want to do without this function, you must use the --disable-video configuration parameter to disable it explicitly. After unpacking the source code, you can install the software with ./configure && make && sudo make install. To decode a PNG file with a QR code in ZBar, use:

zbarimg -d <file>.png

The -d parameter ensures that a window with the QR code appears (Figure 9) in addition to the decoded information in the terminal window.

Figure 9: ZBar delivers all stored address data and even detects the vCard format used; unfortunately, it does not fully understand UTF-8.

If you want to read a QR code with a camera, you need to launch zbarcam. This pops up a preview window with the image from the webcam. Now hold up the QR code to the camera. Once the program has detected the code, it draws a green border around the QR code and prints the data in the terminal window (see the Big and Colorful” box).

You can disable the preview with the --nodisplay switch; raw delivers the raw data, and xml packages the data in an XML format. The above three parameters help if you want to integrate the tool into a script. The parameters --raw and --xml can also be used with zbarimg.

Conclusions

Of the tested programs, Portable QR-Code Generator offers the greatest functionality. Data entry is also convenient in a variety of tabs. Qrencode creates QR codes more quickly, and it is easy to scripted so you generate QR codes in batches. KBarcode4-light is deprecated, but it is the only program that can generate PDF files; the EPS images created by Qrencode offer similar output.

QtQR is especially recommended for decoding QR codes in PNG format. ZBar is a candidate for the command line that is also excellently suited for use in shell scripts. Along with a webcam, you could use it to create a small terminal for reading QR codes. libdecodeqr-simpletest is hardly usable in production and basically not worth installing.

Info

[1] ISO 8859: http://en.wikipedia.org/wiki/ISO-8859
[2] Character encoding: http://en.wikipedia.org/wiki/Character_encoding

The Author

Tim Schürmann is a freelance computer scientist and author. Besides books, Tim has published various articles in magazines and on websites.

Related content

  • QR Code Generators

    With the right tools, you can create your own QR code squares with information you want to share, for example, on a business card, in a letter, or on your website.

  • Barcode

    Machine-readable codes aren’t just for big companies anymore. With the right programs and some low-cost hardware, you can create and read the most important codes.

  • Converting Images to Text

    If you need to display an image in the terminal or as plain HTML, a variety of smart tools can help with the conversion.

comments powered by Disqus
Subscribe to our Linux Newsletters
Find Linux and Open Source Jobs
Subscribe to our ADMIN Newsletters

Support Our Work

Linux Magazine content is made possible with support from readers like you. Please consider contributing when you’ve found an article to be beneficial.

Learn More

News