Introduction to QR Code, a Matrix Barcode

QR Code is a two-dimensional barcode developed by Denso-Wave in Japan. It is very popular in Japan and is getting more popular in the USA. For example, bit.ly offers a QR Code for each shortened link. Many smartphones (Android, iPhone, Nokia etc) have applications to quickly navigate to a website, dial a number or add a contact, all simply by taking a photo of a QR Code. QR is the abbreviation for Quick Response, as the creator intended the code to be decoded at high speed.

Try it out. The resulting QR Code is shown to the right.
Input:	Note: You need to login first before you can generate a QR Code; if you do not have a TWiki.org account you can use "TWikiGuest" with password "guest" (both are case sensitive).
Output:	http://maps.google.com/maps?z=12&ll=40.2997%2c-111.6737 (Orem, Utah, United States)
Note:	This interactive QR Code generator is powered by the TWiki QRCodePlugin. The geolocation is provided by the GeoLookupPlugin.

It would be very useful to have a higher application level standard on encoding so that applications can more easily be integrated. For example, you can point your smartphone to a QR Code to import a vCard, but at this time there is no real standard to do that.

ZXing (pronounced "zebra crossing") is a Java based open-source, multi-format barcode image processing library for mobile devices. They list a rough guide to standard encoding of information in barcodes.

SPARQCode provides a service to generate and scan QR Code on the fly. They defined a higher application level standard to encode URLs, phone numbers, SMS, geolocation, contact (vCard) and calendar event (vCal). Unfortunately they do not publish the encoding. Rhetoric question: Can you call an API an API when the API is not published?

On their API discussion forum I recommended this: "Make SPARQCode a leader in the field by publishing the spec of the encodings. Other orgs will pick it up quickly, thus it will become a standard. You can benefit from increased brand recognition, and you win by offering ease of use & convenience. Submit an RFC to make it an official standard! My 2c." Their response was a non-committal "we definitely see the potential value".

If not SPARQCode, maybe Google, Apple or another major smartphone provider can drive the higher level standardization effort? I'd love to see an RFC for an application level encoding for QR Code.

Now on to some technical details. The following factors make up a QR Code:

• Text to encode. This can be a URL, a phone number, or any other text input.
• ECC (Error Correction Capability) level. This compensates for dirt, damage or fuzziness of the barcode. Valid values are "L" (low ECC), "M", "Q", "H" (highest ECC). A high ECC level adds more redundancy at the cost of using more space.
• Symbol version of QR Code, or size of matrix. The name is a bit misleading, it is not the version of the spec, rather the size of the matrix. Valid values are "1" ... "40". Some implementations can set the symbol version automatically based on text size, text type and ECC level.
• Module size, e.g. the number of pixels that make a block (a bit) of the matrix barcode.

A damaged barcode can be restored based on the ECC level:

• level "L" - about 7%
• level "M" - about 15%
• level "Q" - about 25%
• level "H" - about 30%

Each symbol version holds a number of modules as depicted to the right. Version 1 holds 21 × 21 modules, version 2 holds 25 x 25, version 3 holds 29 x 29, up to version 40 with 177 x 177 modules.

The symbol version required to encode some text is a bit complicated, depending on the length of the text, the type of text and the ECC Level. Text is encoded differently depending on the content being numeric, alfanumeric, binary or Kanji. Here is an overview on the maximum number of bytes a symbol version can hold for the commonly used ECC level "M":

Version Modules Max. bytes 1 21x21 14 2 25x25 26 3 29x29 42 4 33x33 62 5 37x37 84 6 41x41 106 7 45x45 122 8 49x49 152 9 53x53 180 10 57x57 213

Version Modules Max. bytes 11 61x61 251 12 65x65 287 13 69x69 331 14 73x73 362 15 77x77 412 16 81x81 450 17 85x85 504 18 89x89 560 19 93x93 624 20 97x97 666

Version Modules Max. bytes 21 101x101 711 22 105x105 779 23 109x109 857 24 113x113 911 25 117x117 997 26 121x121 1059 27 125x125 1125 28 129x129 1190 29 133x133 1264 30 137x137 1370

Version Modules Max. bytes 31 141x141 1452 32 145x145 1538 33 149x149 1628 34 153x153 1722 35 157x157 1809 36 161x161 1911 37 165x165 1989 38 169x169 2099 39 173x173 2213 40 177x177 2331

The module size is the number of pixels that make a block of the matrix barcode. Here is an example of URL http://twiki.org/ encoded with different module sizes, all with symbol version 2:

Module size:	1	2	3	4	5
QR Code:

The actual pixel size of the generated image depends on the symbol version and the module size. A mandatory whitespace of 4 modules is added. For example, a symbol version 2 (with 25 modules) and module size 3 results in an image of ((25 + 2x4) x 3) x ((25 + 2x4) x 3) pixels = 99x99 pixels.

The Denso Wave Incorporated website has more details on QR Code system configuration and other specifications.

I hope this introduction was helpful in understanding QR Code. I am looking forward to feedback and comments on this topic.

References:

• Wikipedia:QR_Code - QR Code article on Wikipedia
• http://code.google.com/p/zxing/wiki/BarcodeContents - rough guide to standard encoding of information in barcodes by ZXing
• http://www.sparqcode.com/static/QRGenAPI - unpublished application level API by SPARQCode
• http://www.denso-wave.com/qrcode/qrgene1-e.html - QR Code system configuration by Denso Wave
• QRCodePlugin - TWiki's QR Code generator plugin

Comments

For the geeks among us: The implementation of the QRCodePlugin was very simple thanks to a CPAN:GD::Barcode::QRcode Perl module that does all the work. It only requires a few lines of code to do the guts:

    use GD::Barcode::QRcode;
    my $image = GD::Barcode::QRcode->new( $text, {ECC => $pEcc, Version => $pVer, ModuleSize => $pSize} )->plot->png;

    my( $dir, $fileName ) = _makeFilename( $theWeb, $theTopic, "$text-$pEcc-$pVer-$pSize" );
    open( PNG, "> $dir/$fileName" ) or return "QRCode Plugin Error: Can't write image file $fileName.";
    binmode( PNG );
    print PNG $image;
    close( PNG );

    my $attachDir = TWiki::Func::getPubUrlPath() . "/$theWeb/$theTopic/$fileName";
    my $html = "<img src='$attachDir' alt='' />";
    return $html;

First we generate the png image using GD::Barcode::QRcode->new() and place it into a $image variable. Then we save the image as a file in the page's attachment directory using a name like _QRCodePlugin_45bfdc4c87f4084e309bb39650020da4.png. To ensure unique image names (in case there are multiple QR Codes in a page), we build a hexadecimal string that is an MD5 hash of the CR Code text, ECC version, symbol version and module size. This is done in the _makeFilename() function:

    use Digest::MD5  qw(md5_hex);
    my $md5 = md5_hex( $string );

Finally we create the html <img ... /> tag and return that to the browser. Interested folks can download the plugin to study the code.

I invite you to get involved with the TWiki community. As a contributor you can influence the direction of the project. Your words become part of the conversation that steers the TWiki project.

-- Peter Thoeny - 2011-02-14

Special scanners are available to decode a QR Code. There are also web based decoders where you can upload an image or specify the URL of an image, such as:

• http://zxing.org/w/decode.jspx - decoder at ZXing
• http://www.onlinebarcodereader.com/ - decoder at onlinebarcodereader.com

-- Peter Thoeny - 2011-02-23

Thanks for this excellent contribution to the possibilities of developing for QR codes. Its important to follow the ISO standard, yet equally valuable to provide a unique service for encoding. Do you feel that the new corporate structure of Twiki allows start ups to develop solutions collaboratively yet still maintain value to investors?

-- Ishak Kang - 2011-03-07

Thanks Ishak. TWiki.org is and remains an open source driven project. We'd love to get you involved to grow our community as a contributor and/or a TWiki consultant. As a company (Twiki Inc) we love to work with ISVs that provide value added solutions, especially now with the new Twiki OnDemand hosting solution.

-- Peter Thoeny - 2011-03-08

.