Debian Codegraph @

vendor/chillerlan/php-qrcode/src/Detector/GridSampler.php

raw
1 <?php
2 /**
3 * Class GridSampler
4 *
5 * @created 17.01.2021
6 * @author ZXing Authors
7 * @author Smiley <[email protected]>
8 * @copyright 2021 Smiley
9 * @license Apache-2.0
10 */
11 declare(strict_types=1);
12
13 namespace chillerlan\QRCode\Detector;
14
15 use chillerlan\QRCode\Data\QRMatrix;
16 use chillerlan\QRCode\Decoder\BitMatrix;
17 use function array_fill, count, intdiv, sprintf;
18
19 /**
20 * Implementations of this class can, given locations of finder patterns for a QR code in an
21 * image, sample the right points in the image to reconstruct the QR code, accounting for
22 * perspective distortion. It is abstracted since it is relatively expensive and should be allowed
23 * to take advantage of platform-specific optimized implementations, like Sun's Java Advanced
24 * Imaging library, but which may not be available in other environments such as J2ME, and vice
25 * versa.
26 *
27 * The implementation used can be controlled by calling #setGridSampler(GridSampler)
28 * with an instance of a class which implements this interface.
29 *
30 * @author Sean Owen
31 */
32 final class GridSampler{
33
34 /** @var float[] */
35 private array $points;
36
37 /**
38 * Checks a set of points that have been transformed to sample points on an image against
39 * the image's dimensions to see if the point are even within the image.
40 *
41 * This method will actually "nudge" the endpoints back onto the image if they are found to be
42 * barely (less than 1 pixel) off the image. This accounts for imperfect detection of finder
43 * patterns in an image where the QR Code runs all the way to the image border.
44 *
45 * For efficiency, the method will check points from either end of the line until one is found
46 * to be within the image. Because the set of points are assumed to be linear, this is valid.
47 *
48 * @param int $dimension matrix width/height
49 *
50 * @throws \chillerlan\QRCode\Detector\QRCodeDetectorException if an endpoint is lies outside the image boundaries
51 */
52 private function checkAndNudgePoints(int $dimension):void{
53 $nudged = true;
54 $max = count($this->points);
55
56 // Check and nudge points from start until we see some that are OK:
57 for($offset = 0; $offset < $max && $nudged; $offset += 2){
58 $x = (int)$this->points[$offset];
59 $y = (int)$this->points[($offset + 1)];
60
61 if($x < -1 || $x > $dimension || $y < -1 || $y > $dimension){
62 throw new QRCodeDetectorException(sprintf('checkAndNudgePoints 1, x: %s, y: %s, d: %s', $x, $y, $dimension));
63 }
64
65 $nudged = false;
66
67 if($x === -1){
68 $this->points[$offset] = 0.0;
69 $nudged = true;
70 }
71 elseif($x === $dimension){
72 $this->points[$offset] = ($dimension - 1);
73 $nudged = true;
74 }
75
76 if($y === -1){
77 $this->points[($offset + 1)] = 0.0;
78 $nudged = true;
79 }
80 elseif($y === $dimension){
81 $this->points[($offset + 1)] = ($dimension - 1);
82 $nudged = true;
83 }
84
85 }
86
87 // Check and nudge points from end:
88 $nudged = true;
89
90 for($offset = ($max - 2); $offset >= 0 && $nudged; $offset -= 2){
91 $x = (int)$this->points[$offset];
92 $y = (int)$this->points[($offset + 1)];
93
94 if($x < -1 || $x > $dimension || $y < -1 || $y > $dimension){
95 throw new QRCodeDetectorException(sprintf('checkAndNudgePoints 2, x: %s, y: %s, d: %s', $x, $y, $dimension));
96 }
97
98 $nudged = false;
99
100 if($x === -1){
101 $this->points[$offset] = 0.0;
102 $nudged = true;
103 }
104 elseif($x === $dimension){
105 $this->points[$offset] = ($dimension - 1);
106 $nudged = true;
107 }
108
109 if($y === -1){
110 $this->points[($offset + 1)] = 0.0;
111 $nudged = true;
112 }
113 elseif($y === $dimension){
114 $this->points[($offset + 1)] = ($dimension - 1);
115 $nudged = true;
116 }
117
118 }
119
120 }
121
122 /**
123 * Samples an image for a rectangular matrix of bits of the given dimension. The sampling
124 * transformation is determined by the coordinates of 4 points, in the original and transformed
125 * image space.
126 *
127 * @return \chillerlan\QRCode\Decoder\BitMatrix representing a grid of points sampled from the image within a region
128 * defined by the "from" parameters
129 * @throws \chillerlan\QRCode\Detector\QRCodeDetectorException if image can't be sampled, for example, if the transformation defined
130 * by the given points is invalid or results in sampling outside the image boundaries
131 */
132 public function sampleGrid(BitMatrix $matrix, int $dimension, PerspectiveTransform $transform):BitMatrix{
133
134 if($dimension <= 0){
135 throw new QRCodeDetectorException('invalid matrix size');
136 }
137
138 $bits = new BitMatrix($dimension);
139 $this->points = array_fill(0, (2 * $dimension), 0.0);
140
141 for($y = 0; $y < $dimension; $y++){
142 $max = count($this->points);
143 $iValue = ($y + 0.5);
144
145 for($x = 0; $x < $max; $x += 2){
146 $this->points[$x] = (($x / 2) + 0.5);
147 $this->points[($x + 1)] = $iValue;
148 }
149 // phpcs:ignore
150 [$this->points, ] = $transform->transformPoints($this->points);
151 // Quick check to see if points transformed to something inside the image;
152 // sufficient to check the endpoints
153 $this->checkAndNudgePoints($matrix->getSize());
154
155 // no need to try/catch as QRMatrix::set() will silently discard out of bounds values
156 # try{
157 for($x = 0; $x < $max; $x += 2){
158 // Black(-ish) pixel
159 $bits->set(
160 intdiv($x, 2),
161 $y,
162 $matrix->check((int)$this->points[$x], (int)$this->points[($x + 1)]),
163 QRMatrix::M_DATA,
164 );
165 }
166 # }
167 # catch(\Throwable $aioobe){//ArrayIndexOutOfBoundsException
168 // This feels wrong, but, sometimes if the finder patterns are misidentified, the resulting
169 // transform gets "twisted" such that it maps a straight line of points to a set of points
170 // whose endpoints are in bounds, but others are not. There is probably some mathematical
171 // way to detect this about the transformation that I don't know yet.
172 // This results in an ugly runtime exception despite our clever checks above -- can't have
173 // that. We could check each point's coordinates but that feels duplicative. We settle for
174 // catching and wrapping ArrayIndexOutOfBoundsException.
175 # throw new QRCodeDetectorException('ArrayIndexOutOfBoundsException');
176 # }
177
178 }
179
180 return $bits;
181 }
182
183 }