Advanced usage QR Code raw data export

1. What is the "raw data"-export
2. When to use raw data export?
3. Byte Structure of the raw data (file format)
4. How to export raw data
5. How to import raw data

---

1. What is the "raw data"-export

The raw data export is a functionalty of the QRCoder lib which enables exporting raw QRCode data in a small, optionally compressed, logical format which can be imported for later renders.

To do this,

1. Instantiate QRCodeGenerator-class
2. Call the CreateQrCode-method of QRCodeGenerator and pass in your text-to-be-encoded (=payload) and parameters. This will return a QRCodeData-object
3. Pass the QRCodeData-object, which contains the information, to one of the renderer classes (e.g. QRCode)
4. Call GetGraphic-method and get back a Bitmap-object QR Code image

In code, these four steps look like:

//Step 1
QRCodeGenerator qrGenerator = new QRCodeGenerator();
//Step 2
QRCodeData qrCodeData = qrGenerator.CreateQrCode("Text to be encoded.", QRCodeGenerator.ECCLevel.Q);
//Step 3 & 4
QRCode qrCode = new QRCode(qrCodeData);
Bitmap qrCodeImage = qrCode.GetGraphic(20);

The QRCodeGenerator does all the hard calculation work. QRCodeData is data, in a standardized format, so each rendering class can expect the same input.

raw data-export is a functionalty of the QRCodeData-class. It allows exporting calculated QR codes to a files in a logical format.

2. When to use raw data export?

The raw data export comes into play when needing to...
a) calculate/generate QR codes in QRCoder, but render them in another software
b) pre-calculate QR codes, store them in a standard format and render them later
c) store the data using small amounts of disk space

The raw export allows sharing pre-calculated QR codes easily with other programs/software.

3. Byte Structure of the raw data (file format)

Reading the data into other programs without QR Coder requires knowledge of the file's bytes.

Note about compression: When exporting files, a choice to optionally compress the raw data with either Deflate or GZip is present. In that case, the complete raw file will be compressed. The file will need to be uncompressed before it can be recognized as a QR Code file. Keep this in mind if exporting compressed data.

Byte Indices	Description
0-3	Signature {'Q', 'R', 'R', '\0'}
4	QR Code Side Length
5-n	Blob Data

Bytes[0-3]:
The first three bytes of each raw export file contain the bytes 0x51, 0x52 and 0x52. The byte-values are equivalent to the Ascii chars "QRR". They are the file's signature. Use them to check if a file to be read is really a QRCoder raw file, which can easily be identified by opening one with any text editor (unless it is Gzipped). The third byte has the value 0x00 - always. It's used as terminator between the signature and the header.

Byte[4]: The fourth byte, the only byte of the header, contains the side length of a QR Code which is saved in the data blob. For example, look at the following image.

There are 8 white "border blocks" (=quietZone) + 21 QR code modules per row. In this case the fourth byte had a value of 29.

Bytes[5-n]: The bytes from index 5 to the end of file contains the modules. Each byte contains 8 modules - one per bit, colloquially bit-packed data. A one indicates module is black and a 0 is white.

To read the QR code data, process the bits of the bytes by looping over all bytes and converting them into the data needed. For example, an array of 8 * side_length bytes - one per module, an array of 3 * (8 * side_length) bytes - one RGB color per module, etc.

Displays one sample byte of encoded raw data. 91 == 01011011, which is interpreted as above.

4. How to export raw data

Two functions of QRCodeData-class export QR files.

The simplest case would look as follows:

//Create QR data
QRCodeGenerator qrGenerator = new QRCodeGenerator();
QRCodeData qrCodeData = qrGenerator.CreateQrCode("Text to be encoded.", QRCodeGenerator.ECCLevel.Q);

//Export raw data
qrCodeData.SaveRawData("C:\\mypath\\my-raw-file.qrr");

This code exports the raw data, in an uncompressed, logical format, into a file called "my-raw-file.qrr".

Note about file-extentions: When exporting raw data uncompressed, use the proper file-extention.

Export mode	File-extention
Uncompressed	xyz.qrr
Deflate	xyz.zz
Gzip	xyz.gz

One export function returns raw data as a byte[] array, but the other saves the raw data as file. (Note: The file-writing method isn't available in PCL version of the QRCoder.)

Return Type	Calling Name	Parameters
byte[]	GetRawData(QRCodeData.Compression)	Uncompressed, Deflate, GZip
void	SaveRawData(String, QRCodeData.Compression)	String path to export file	Uncompressed, Deflate, GZip

5. How to import raw data

To import a raw data file, use one of the optional overloads of the QRCodeData-class constructor.

Overload	Calling Name	Parameters
1	(String, QRCodeData.Compression)	String path to exported file	Uncompressed, Deflate, GZip
2	(byte[], QRCodeDate.Compression)	Raw data as byte[] array,	Uncompressed, Deflate, GZip

Example:

//Import raw-data
QRCodeData qrCodeData = new QRCodeData("C:\\path-to\\raw-data.qrr", QRCodeData.Compression.Uncompressed);

//Render QR code as usual
QRCode qrCode = new QRCode(qrCodeData);
Bitmap qrCodeImage = qrCode.GetGraphic(20);