Limax Project

7.15 QR Code

Limax provides QR Code codec support (except Micro QR Code) with reference to ISO/IEC 18004-2006.

All language versions are implemented in a single file, without any dependencies except for the language standard library for easy reference.

7.15.1 Encoder

Prototype

Java	QrCode limax.codec.QrCode.encode(byte[] data, int ecl)
C#	QrCode limax.codec.QrCode.encode(byte[] data, int ecl)
C99	QrCode qr_encode(void *data, int size, int ecl)
Javascript	QrCode encode(data, ecl)

1. Parameter

1.1. data, byte array, in particular, for Javascript, the method QrCode.toUTF8 is provided, which can convert the string input in the browser into a UTF8 byte array. (Please refer to qrcode.html in the javascript directory)

1.2. ecl, the constants ECL_L, ECL_M, ECL_Q, and ECL_H defined by each language determine the error correction level.

2. Return value

2.1. QrCode object, the input data is too long to be represented by the QR Code of VERSION 40, and returns null. In particular, for C99, the QrCode object needs to be released by qrcode->release(qrcode).

2.2. All QrCode objects provide the method toSvgXML, return the SvgXML string, and output to the file, which is convenient for the browser to display directly.

2.3. The QrCode object of Java and C# provides the method getModules(), returns the boolean array representing the QrCode module, and the length of the array is squared to obtain the size. The C99 directly accesses the QrCode member modules and size. It is easy to generate other forms of representation through the module array, such as images (refer to the implementation of limax.executable.QrCodeTool.java).

The compatibility of ISO/IEC 18004-2006

1. Only single digital mode, alphanumeric mode, byte mode encoding are supported, and without mixed mode. If all the input data conform to the digital mode, the digital mode is selected. If all the input data conform to the alphanumeric mode, the alphanumeric mode is selected, otherwise the byte mode is used.

2. ECI, FNC1, KANJI, and Structured Append are not supported.

Application discussion

1. Usually input data should be considered using UTF8 encoding.

2. To exchange data through QR Code, if it is required to generate a QR Code as small as possible, it is most effective to use pure numbers. The digital mode generates short codes; adds uppercase letters; and alphanumeric mode generates shorter codes. Avoid using lowercase letters.

3. If it needs to embed images in the QR Code, a higher error correction level is chosen, such as ECL_Q, ECL_H.

7.15.2 Decoder (decode a QR Code in a black and white picture)

Prototype

Java	QrCode.Info limax.codec.QrCode.decode(byte[] image_1bit, int width, int height, int sample_granularity);
C99	QrCodeInfo qr_decode(char *image_1bit, int width, int height, int sample_granularity);

1. Parameter

1.1. image_1bit, the input should be a 1bit black and white picture, one byte for one pixel and 0 for black.

1.2. width, image width.

1.3. height, image height.

1.4. sample_granularity, sample granularity, 1 is point-by-point sampling. Larger pictures can choose better sampling granularity for better performance, but may result in decoding failure.

2. Return value

2.1. Whether the decoding succeeds or not, it returns QrCode.Info, or QrCodeInfo object. The return object info in C99 should be released by info->release(info). Either success or failure is indicated by the status field. The object fields in C99 can be accessed directly, and it is obtained by the get methods in Java.

2.2. status, status field. enum QrCode.Info.Status in Java, enum scan_status in C99. There are multiple return status values.

2.2.1. SCAN_OK, if the scan is successful, the correct decoded data can be obtained.

2.2.2. ERR_POSITIONING, positioning the QR Code in the image fails.

2.2.3. ERR_VERSION_INFO, failed to get version information.

2.2.4. ERR_ALIGNMENTS, failed to locate ALIGNMENT PATTERNS in QR Code.

2.2.5. ERR_FORMAT_INFO, failed to get format information (error correction level and mask).

2.2.6. ERR_UNRECOVERABLE_CODEWORDS, the number of codeword errors exceeds the error correction capacity.

2.2.7 UNSUPPORTED_ENCODE_MODE, an unsupported encoding mode. In this case, the data obtained from Info is the undecoded data of the error correction completion, and the application should decode itself if it has the ability.

2.3. data, length, the byte array representation of the returned data, which cannot be interpreted as a NULL termination string in C99.

2.4. reverse, whether the image is inverted.

2.5. mirror, whether the image is mirrored.

2.6. version, version.

2.7. ecl, error correction level.

2.8. mask, mask number.

The compatibility of ISO/IEC 18004-2006

1. Not support Micro QR Code decoding.

2. Support QR Code reversal and mirroring

3. Supports mixed mode, digital mode, alphanumeric mode, byte mode, KANJI mode (KANJI mode encoded Japanese characters are converted to UTF8 output)

4. Supports ECI mode, two FNC1 modes, which are output using the symbol identification method specified by ISO/IEC 15424. (Whether ECI, FNC1 can be interlaced, and how to interlace, are not mentioned by neither standard. It is implemented to allow random interleaving)

5. Structured Append mode is not supported

7.15.3 Sample tool
- Javascript version
  
  The qrcode.html in the javascript directory can generate a QR Code with an error correction level of H based on the input string.
- Java version
```
java -jar limax.jar qrcode encode <filename> <(L|M|Q|H)> <text>
```
  Generate a QR Code for the text string and output it to the file specified by filename. The file content is determined by the file name suffix. If it is svg, SvgXML is generated. In addition, the graphic file is generated, and the file name suffix must be the file format supported by the ImageIO.write method.
```
java -jar limax.jar qrcode decode <filename> [sample_granularity=1] [bwthreshold=64] [meanfilter=2]
```
  To decode a picture, a picture containing a QR Code is used to perform decoding.
  
  sample_granularity is the sampling granularity, bwthreshold is the threshold for further conversion to black and white after the image is converted to grayscale (there is a strange problem, the grayscale conversion result of jdk does not meet the conversion formula of Y = 0.299R + 0.587G + 0.114B, which is obviously dark, and choose bwthreshold=64 here), meanfilter determines the mean filter size, uses the surrounding (N*2+1)^2 pixels to participate in the central pixel mean calculation. The mean filter filters the image noise which may affect decoding.
  
  The default parameters are more suitable for decoding photos. If the screenshot is needs to be decoded, this parameter selection may lead to failure.
```
java –jar limax.jar qrcode decode capture.jpg 1 128 0
```
  Maybe it is the right choice. The screen resolution is usually much smaller than the photo and meanfilter=2 may destroy the QR Code module in the screenshot. In addition, the screenshot usually has no noise problems, and 0 is a more appropriate choice.

7.15.4 Advanced topic
- Decoding performance
  
  1. Obviously, the smaller the picture, the higher the decoding performance is. The smaller the picture, the less the detail is, which may be problem to decode the high version QR Code. It is an engineering method to zoom out the original image or intercept part of the original image, and no discussion is focused.
  
  2. The decoding operation is memory intensive. The performance of the java version is not comparable to the C99 version. The application that requires performance is recommended to use the C99 version.
  
  3. The preprocessing process from color image to black and white image is more expensive than the decoding operation itself. An image processing library that can fully utilize GPU capabilities can be considered to use. Opencv is used in the demo. Actual measurement on pc can be more than 10 times higher than the java version.
  
  4. If all of the above methods are used and the requirements are not met, a larger sample_granularity decoding parameter can be chosen.
  
  5. For more extreme requirements, the decoder can be optimized in parallel. The parallel optimization of the running environment is too relevant. It is not provided here. The scanFinder method in the source code is the biggest performance bottleneck and can be considered.
- Image Quality
  
  1. Image quality is a prerequisite for successful decoding and is affected by various factors.
  
  2. ISO/IEC 18004-2006 has clear guidelines for the specification of QR Code images and printing rules. In reality, there are a lot of non-compliant QR Codes. For example, Border explicitly requires at least 4 times width of the module, but there are many QR Codes that print text in the Border range.
  
  3. QR Code uses the RS error correction algorithm and has some resistance to image contamination in the QR Code, but it cannot solve the FinderPattern pollution at the three corners. In addition, the three FinderPatterns are not enough for perspective correction. The current implementation determines the bottom right corner of the QR Code by scanning the bottom and right edges, so there is a certain requirement for the bottom blank and the right blank, and there is no good resistance ability to the contamination in the scan range.
  
  4. The higher the version of the QR Code, the higher the focus requirements are. The poor focus, the edge ratio of the blurred QR Code image filtering, and the ratio of the width of the black module to the white module will be significantly deviated. The FinderPattern can not be determined, and directly leads to decoding failure.
  
  5. Insufficient illumination will cause the camera to choose a higher sensitivity, resulting in more image noise, and image filtering can solve certain problems. How to choose a better filtering solution can only be measured according to the specific application environment.
  
  6. Multiple QR Code on the same image is not supported, and multiple QR Code may cause FinderPattern selection errors. Some selected Radio Button on the PC screen has obvious FinderPattern characteristic, and such interruption may also exist in the actual environment. In terms of current implementation, three FinderPattern are selected according to the largest area, and no variance filtering is performed (the bigger perspective distortion makes the far-end FinderPattern significantly smaller, and the variance filtering may filter such FinderPattern). The largest area standard determines the larger the QR Code area in the picture, the higher the decoding success rate is. Scaning the significantly small QR Code may require image cutting or partial magnification.
  
  7. It is impossible to fully support the non-standard creative QR Code. Some creative QR Code is designed to fit the parameter conditions of a particular decoder. It is not very meaningful to measure parameters for such QR Code unless the compatibility of such QR Code is design goal.
- Demo
  
  1. The demo/qrdecode directory provides two versions of the demo for pc and android. To compile these versions, it needs to download the opencv library and configure it accordingly.
  
  2. The pc version has the same function as the java version, and is used to decode the QR Code in the photo, which has a great performance improvement.
  
  3. The pc version is identical to the android version of the key code, which can assist in the design of android applications in specific scenarios, experiment and select image filtering algorithms and parameters.
  
  4. The android version uses a camera to directly implement a generic real-time decoder that displays QR Code information.
  
  5. http://www.limax-project.org/download/QR-Demo.apk provides download

Prev Next

7.15 QR Code

7.15.1 Encoder

7.15.2 Decoder (decode a QR Code in a black and white picture)

7.15.3 Sample tool

7.15.4 Advanced topic