|
| 1 | +# Reading QR Codes |
| 2 | + |
| 3 | +## Basic usage |
| 4 | + |
| 5 | +The QR Code reader can be called either from a `QRCode` instance or invoked directly via the `Decoder` class with a `QROptions` (`QRCodeReaderOptionsTrait`) instance. |
| 6 | + |
| 7 | +```php |
| 8 | +$options = new QROptions |
| 9 | + |
| 10 | +$options->readerUseImagickIfAvailable = true; |
| 11 | +$options->readerIncreaseContrast = true; |
| 12 | +$options->readerGrayscale = true; |
| 13 | +$options->readerInvertColors = false; |
| 14 | +``` |
| 15 | + |
| 16 | +The option `QROptions::$readerUseImagickIfAvailable` is exclusive to the `QRCode` instance in order to decide which `LuminanceSourceInterface` to use. |
| 17 | +The `QRCode` instance has 3 convenience methods related to the reader: |
| 18 | +```php |
| 19 | +$qrcode = new QRCode($options) |
| 20 | + |
| 21 | +$result = $qrcode->readFromFile('path/to/qrcode.png'); |
| 22 | +$result = $qrcode->readFromBlob($imagedata); |
| 23 | + |
| 24 | +// from a luminance source instance |
| 25 | +$source = IMagickLuminanceSource::fromBlob($imagedata, $options); |
| 26 | +$result = $qrcode->readFromSource($source); |
| 27 | +``` |
| 28 | + |
| 29 | +## The `LuminanceSourceInterface` |
| 30 | + |
| 31 | +The method `QRCode::readFromSource()` takes a `LuminanceSourceInterface` instance as parameter and is mainly for internal use, as you can invoke and call the decoder directly with it. |
| 32 | +Each `LuminanceSourceInterface` has the static convenience methods `fromFile()` and `fromBlob()` that will invoke the instance with the respective parameters, alternatively the instance(s) can be invoked manually: |
| 33 | + |
| 34 | +from an `Imagick` instance: |
| 35 | +```php |
| 36 | +$imagick = new Imagick; |
| 37 | +$imagick->readImageBlob($imagedata); |
| 38 | + |
| 39 | +$source = new IMagickLuminanceSource($imagick, $options); |
| 40 | +``` |
| 41 | + |
| 42 | +from a `GdImage` instance: |
| 43 | + |
| 44 | +```php |
| 45 | +$gdimage = imagecreatefromstring($imagedata); |
| 46 | + |
| 47 | +$source = new GDLuminanceSource($gdimage, $options); |
| 48 | +``` |
| 49 | + |
| 50 | +## The `Decoder` |
| 51 | + |
| 52 | +The `Decoder` takes a `QROptions` instance as parameter, which currently has no use - it is only handed over for possible future uses. |
| 53 | + |
| 54 | +```php |
| 55 | +$result = (new Decoder($options))->decode($source); |
| 56 | +``` |
| 57 | + |
| 58 | +That is all! The decoder will either return a `DecoderResult` instance or throw an exception. |
| 59 | +It is generally a good practice to wrap the reading in a try/catch block: |
| 60 | + |
| 61 | +```php |
| 62 | +try{ |
| 63 | + $result = $qrcode->readFromFile('path/to/file.png'); // -> DecoderResult |
| 64 | + |
| 65 | + // ... do stuff with the result |
| 66 | +} |
| 67 | +catch(QRCodeDecoderException){ |
| 68 | + // ... adjust input image (position, contrast, invert, sharpen) and repeat the process |
| 69 | +} |
| 70 | +``` |
| 71 | + |
| 72 | +You can now use the result instance: |
| 73 | + |
| 74 | +```php |
| 75 | +$content = $result->data; |
| 76 | +// ...or simply cast it to string: |
| 77 | +$content = (string)$result; |
| 78 | +``` |
| 79 | + |
| 80 | +The result instance also holds `Version`, `EccLevel`, `MaskPattern` and `BitBuffer` instances, as well as an array of `FinderPattern` instances, |
| 81 | +it also offers a method that returns a `QRMatrix` instance populated with the detected settings: |
| 82 | + |
| 83 | +```php |
| 84 | +$matrix = $result->getQRMatrix(); |
| 85 | + |
| 86 | +// ...matrix modification... |
| 87 | + |
| 88 | +$output = (new QRCode($options))->renderMatrix($matrix); |
| 89 | + |
| 90 | +// ...dump output |
| 91 | +``` |
| 92 | + |
| 93 | + |
| 94 | +## General considerations |
| 95 | + |
| 96 | +The QR Code reader reads the given QR symbol in a single pass, unlike e.g. a reader app on a mobile device with a camera, which repeats the reading process for a sequence of frames from the video input and takes the "best" result. |
| 97 | +It means that this reader may fail to properly decode a symbol that reads perfectly fine on a mobile - you'd need to emulate the same process of sequential reading while adjusting the input image to get a similar result. |
| 98 | + |
| 99 | +Further it seems ([per observation](https://github.com/chillerlan/php-qrcode/blob/92346420a5a88aeeb8dc16f731ef1f93331635d3/tests/QRCodeReaderTestAbstract.php#L168-L172)) that the reader favors smaller module sizes (1-2 pixel side length) from version 20 onwards. |
| 100 | +The test data set seemed to randomly produce errors depending on the given module scale, independent of the luminance source. |
| 101 | +However, scaling down to get a smaller module size isn't the best solution as it may produce additional challenges due to filter artifacts. |
0 commit comments