Advanced usage QR Code raw data export
- What is the "raw data"-export
- When to use raw data export?
- Structure of the raw data (file format)
- How to export raw data
- How to import raw data
The raw data export is a functionalty of the QRCoder lib which enables you to export the raw QRCode data. To understand what this raw data contains, let's have a look at process when creating QR codes with QRCoder. It contains three simple steps.
- Instantiate QRCodeGenerator-class.
- Call CreateQrCode-method of the generator and pass your text-to-be-encoded (=payload) and parameters to it. It will return a QRCodeData-object.
- Pass the QRCodeData-object, which contains the information about all modules (=black and white dots of the QR code), to one of the renderer classes (e.g. QRCode), call GetGraphic-method and get back a QR code image.
In code this three steps look like:
//Step 1
QRCodeGenerator qrGenerator = new QRCodeGenerator();
//Step 2
QRCodeData qrCodeData = qrGenerator.CreateQrCode("Text to be encoded.", QRCodeGenerator.ECCLevel.Q);
//Step 3
QRCode qrCode = new QRCode(qrCodeData);
Bitmap qrCodeImage = qrCode.GetGraphic(20);
So the QRCodeGenerator does all the hard calculation work for us. QRCodeData is the almost ready QR code in a standardized format, so that every rendering class can expect the same input.
So now let's clarify what's behind the raw data-export. It's a functionalty of the QRCodeData-class. It allows you to export the calculated QR code to a file in it's normalized form.
Now that we know what the raw data is, let's have a look what we can do with it. The raw data export comes into play, when you... a) want to calculate/generate QR codes in QRCoder, but render them in another software. b) want to pre-calculate QR codes, store them in a standard format and render them later.
The raw export allows you to easily share pre-calculated QR codes with other programns/software. Just do step 1 and 2 of the above show example, then export the data and pass it to another program/process/person.
If you want to read the exported raw data with another application, you should know the file structure. So let's have a quick dive into this topic.
| Byte index | Description |
|---|---|
| 0-2 | Signature (QRR) |
| 3 | Signature terminator (0x00/NUL) |
| 4 | QR code side length |
| 5-n | Payload |
The raw data format was wilfully kept as small and simple as possible. (For one thing to keep its size small and for another thing to make it easily usable.)
Bytes[0-2]: 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. You can use them to check, if the file you read is really an QRCoder raw file and in addition to that, you can easily identify raw data files by open them with any text editor.
Byte[3]: The third byte has the value 0x00 - always. It's used as terminator between the signature and the rest of the file's content.
Byte[4]: The fourth byte contains the side length of the QR code which is saved in the raw data file. For example have a look at the following image. It consists out of 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 up to the end of file contains the modules. Each byte contains 8 modules - one per bit. Whereby a one means that the module is black and a 0 means that a module is white.
To read the QR code data simply read the bytes from the 5th byte to the end, bit-wise and print them from left to right. Every X (X = sidelength = 4th byte of raw file) bit, begin a new row while plotting the modules. To get a better understanding let's have a look onto the following picture:
Note about compression: When you export a file (see next paragraph) you can (optionally) compress the raw data with either Deflate or GZip. In this case the complete raw file as described above will be compressed. So if you open a compressed raw file, you can't read the file signature before decompressing the file. Keep this in mind - if you exported compressed, then the first step before parsing the file is decompression!
To export raw data you can use two different functions of the QRCodeData-class which will be described below. 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 would export the raw data in an uncompressed manner into a file called "my-raw-file.qrr".
Note about file-extentions: When you export raw data uncompressed, you should use the file-extentions .qrr., when using deflate compression .zz and when using gzip compression .gz.
| Export mode | File-extention |
|---|---|
| Uncompressed | .qrr |
| Deflate | .zz |
| Gzip | .gz |
Now let's have a look onto the both export functions and their parameters. One returns the raw data as byte[] the other saves the raw data as file. (Note: The file-writing method isn't available in PCL version of the QRCoder.)
GetRawData (Return type: byte[])
| Parameter name | Type | Description |
|---|---|---|
| compressMode | QRCodeDate.Compression | The type of compression. Possible values: Uncompressed,Deflate,GZip |
SaveRawData (Return type: void)
| Parameter name | Type | Description |
|---|---|---|
| filePath | string | Path and filename (=fullpath) where the export shall by saved |
| compressMode | QRCodeDate.Compression | The type of compression. Possible values: Uncompressed,Deflate,GZip |
If you want to import raw data into the QRCoder, then you can just use one of two optional overloads of QRCodeData-class' constructor.
Overload 1 (Return type: void)
| Parameter name | Type | Description |
|---|---|---|
| pathToRawData | string | Path and filename (=fullpath) to the raw file to be imported |
| compressMode | QRCodeDate.Compression | The type of used compression. Possible values: Uncompressed,Deflate,GZip |
Overload 2 (Return type: void)
| Parameter name | Type | Description |
|---|---|---|
| rawData | byte[] | Raw data as byte-array. |
| compressMode | QRCodeDate.Compression | The type of used compression. Possible values: 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);
If you want to import the raw data into another application, just read the paragraph about the file format and implement a "read-raw-data"-function in your application.