Passed
Push — gh-pages ( 20c441...dd59e5 )
by
unknown
02:54 queued 01:00
created

Binarizer::getBlackMatrix()   A

Complexity

Conditions 5
Paths 5

Size

Total Lines 22
Code Lines 11

Duplication

Lines 0
Ratio 0 %

Importance

Changes 1
Bugs 0 Features 0
Metric Value
cc 5
eloc 11
c 1
b 0
f 0
nc 5
nop 0
dl 0
loc 22
rs 9.6111
1
<?php
2
/**
3
 * Class Binarizer
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
12
namespace chillerlan\QRCode\Decoder;
13
14
use RuntimeException;
15
use function array_fill, count, max;
16
17
/**
18
 * This class implements a local thresholding algorithm, which while slower than the
19
 * GlobalHistogramBinarizer, is fairly efficient for what it does. It is designed for
20
 * high frequency images of barcodes with black data on white backgrounds. For this application,
21
 * it does a much better job than a global blackpoint with severe shadows and gradients.
22
 * However it tends to produce artifacts on lower frequency images and is therefore not
23
 * a good general purpose binarizer for uses outside ZXing.
24
 *
25
 * This class extends GlobalHistogramBinarizer, using the older histogram approach for 1D readers,
26
 * and the newer local approach for 2D readers. 1D decoding using a per-row histogram is already
27
 * inherently local, and only fails for horizontal gradients. We can revisit that problem later,
28
 * but for now it was not a win to use local blocks for 1D.
29
 *
30
 * This Binarizer is the default for the unit tests and the recommended class for library users.
31
 *
32
 * @author [email protected] (Daniel Switkin)
33
 */
34
final class Binarizer{
35
36
	// This class uses 5x5 blocks to compute local luminance, where each block is 8x8 pixels.
37
	// So this is the smallest dimension in each axis we can accept.
38
	private const BLOCK_SIZE_POWER  = 3;
39
	private const BLOCK_SIZE        = 8;  // ...0100...00
40
	private const BLOCK_SIZE_MASK   = 7;  // ...0011...11
41
	private const MINIMUM_DIMENSION = 40;
42
	private const MIN_DYNAMIC_RANGE = 24;
43
44
#	private const LUMINANCE_BITS    = 5;
45
	private const LUMINANCE_SHIFT   = 3;
46
	private const LUMINANCE_BUCKETS = 32;
47
48
	private LuminanceSource $source;
49
50
	/**
51
	 *
52
	 */
53
	public function __construct(LuminanceSource $source){
54
		$this->source = $source;
55
	}
56
57
	/**
58
	 * @throws \RuntimeException
59
	 */
60
	private function estimateBlackPoint(array $buckets):int{
61
		// Find the tallest peak in the histogram.
62
		$numBuckets     = count($buckets);
63
		$maxBucketCount = 0;
64
		$firstPeak      = 0;
65
		$firstPeakSize  = 0;
66
67
		for($x = 0; $x < $numBuckets; $x++){
68
69
			if($buckets[$x] > $firstPeakSize){
70
				$firstPeak     = $x;
71
				$firstPeakSize = $buckets[$x];
72
			}
73
74
			if($buckets[$x] > $maxBucketCount){
75
				$maxBucketCount = $buckets[$x];
76
			}
77
		}
78
79
		// Find the second-tallest peak which is somewhat far from the tallest peak.
80
		$secondPeak      = 0;
81
		$secondPeakScore = 0;
82
83
		for($x = 0; $x < $numBuckets; $x++){
84
			$distanceToBiggest = $x - $firstPeak;
85
			// Encourage more distant second peaks by multiplying by square of distance.
86
			$score = $buckets[$x] * $distanceToBiggest * $distanceToBiggest;
87
88
			if($score > $secondPeakScore){
89
				$secondPeak      = $x;
90
				$secondPeakScore = $score;
91
			}
92
		}
93
94
		// Make sure firstPeak corresponds to the black peak.
95
		if($firstPeak > $secondPeak){
96
			$temp       = $firstPeak;
97
			$firstPeak  = $secondPeak;
98
			$secondPeak = $temp;
99
		}
100
101
		// If there is too little contrast in the image to pick a meaningful black point, throw rather
102
		// than waste time trying to decode the image, and risk false positives.
103
		if($secondPeak - $firstPeak <= $numBuckets / 16){
104
			throw new RuntimeException('no meaningful dark point found');
105
		}
106
107
		// Find a valley between them that is low and closer to the white peak.
108
		$bestValley      = $secondPeak - 1;
109
		$bestValleyScore = -1;
110
111
		for($x = $secondPeak - 1; $x > $firstPeak; $x--){
112
			$fromFirst = $x - $firstPeak;
113
			$score     = $fromFirst * $fromFirst * ($secondPeak - $x) * ($maxBucketCount - $buckets[$x]);
114
115
			if($score > $bestValleyScore){
116
				$bestValley      = $x;
117
				$bestValleyScore = $score;
118
			}
119
		}
120
121
		return $bestValley << self::LUMINANCE_SHIFT;
122
	}
123
124
	/**
125
	 * Calculates the final BitMatrix once for all requests. This could be called once from the
126
	 * constructor instead, but there are some advantages to doing it lazily, such as making
127
	 * profiling easier, and not doing heavy lifting when callers don't expect it.
128
	 *
129
	 * Converts a 2D array of luminance data to 1 bit data. As above, assume this method is expensive
130
	 * and do not call it repeatedly. This method is intended for decoding 2D barcodes and may or
131
	 * may not apply sharpening. Therefore, a row from this matrix may not be identical to one
132
	 * fetched using getBlackRow(), so don't mix and match between them.
133
	 *
134
	 * @return \chillerlan\QRCode\Decoder\BitMatrix The 2D array of bits for the image (true means black).
135
	 */
136
	public function getBlackMatrix():BitMatrix{
137
		$width  = $this->source->getWidth();
138
		$height = $this->source->getHeight();
139
140
		if($width >= self::MINIMUM_DIMENSION && $height >= self::MINIMUM_DIMENSION){
141
			$subWidth = $width >> self::BLOCK_SIZE_POWER;
142
143
			if(($width & self::BLOCK_SIZE_MASK) !== 0){
144
				$subWidth++;
145
			}
146
147
			$subHeight = $height >> self::BLOCK_SIZE_POWER;
148
149
			if(($height & self::BLOCK_SIZE_MASK) !== 0){
150
				$subHeight++;
151
			}
152
153
			return $this->calculateThresholdForBlock($subWidth, $subHeight, $width, $height);
154
		}
155
156
		// If the image is too small, fall back to the global histogram approach.
157
		return $this->getHistogramBlackMatrix($width, $height);
158
	}
159
160
	/**
161
	 *
162
	 */
163
	public function getHistogramBlackMatrix(int $width, int $height):BitMatrix{
164
		$matrix = new BitMatrix(max($width, $height));
165
166
		// Quickly calculates the histogram by sampling four rows from the image. This proved to be
167
		// more robust on the blackbox tests than sampling a diagonal as we used to do.
168
		$buckets = array_fill(0, self::LUMINANCE_BUCKETS, 0);
169
170
		for($y = 1; $y < 5; $y++){
171
			$row             = (int)($height * $y / 5);
172
			$localLuminances = $this->source->getRow($row);
173
			$right           = (int)(($width * 4) / 5);
174
175
			for($x = (int)($width / 5); $x < $right; $x++){
176
				$pixel = $localLuminances[(int)$x] & 0xff;
177
				$buckets[$pixel >> self::LUMINANCE_SHIFT]++;
178
			}
179
		}
180
181
		$blackPoint = $this->estimateBlackPoint($buckets);
182
183
		// We delay reading the entire image luminance until the black point estimation succeeds.
184
		// Although we end up reading four rows twice, it is consistent with our motto of
185
		// "fail quickly" which is necessary for continuous scanning.
186
		$localLuminances = $this->source->getMatrix();
187
188
		for($y = 0; $y < $height; $y++){
189
			$offset = $y * $width;
190
191
			for($x = 0; $x < $width; $x++){
192
				$pixel = (int)($localLuminances[$offset + $x] & 0xff);
193
194
				if($pixel < $blackPoint){
195
					$matrix->set($x, $y);
196
				}
197
			}
198
		}
199
200
		return $matrix;
201
	}
202
203
	/**
204
	 * Calculates a single black point for each block of pixels and saves it away.
205
	 * See the following thread for a discussion of this algorithm:
206
	 *
207
	 * @see http://groups.google.com/group/zxing/browse_thread/thread/d06efa2c35a7ddc0
208
	 */
209
	private function calculateBlackPoints(array $luminances, int $subWidth, int $subHeight, int $width, int $height):array{
210
		$blackPoints = array_fill(0, $subHeight, 0);
211
212
		foreach($blackPoints as $key => $point){
213
			$blackPoints[$key] = array_fill(0, $subWidth, 0);
214
		}
215
216
		for($y = 0; $y < $subHeight; $y++){
217
			$yoffset    = ($y << self::BLOCK_SIZE_POWER);
218
			$maxYOffset = $height - self::BLOCK_SIZE;
219
220
			if($yoffset > $maxYOffset){
221
				$yoffset = $maxYOffset;
222
			}
223
224
			for($x = 0; $x < $subWidth; $x++){
225
				$xoffset    = ($x << self::BLOCK_SIZE_POWER);
226
				$maxXOffset = $width - self::BLOCK_SIZE;
227
228
				if($xoffset > $maxXOffset){
229
					$xoffset = $maxXOffset;
230
				}
231
232
				$sum = 0;
233
				$min = 255;
234
				$max = 0;
235
236
				for($yy = 0, $offset = $yoffset * $width + $xoffset; $yy < self::BLOCK_SIZE; $yy++, $offset += $width){
237
238
					for($xx = 0; $xx < self::BLOCK_SIZE; $xx++){
239
						$pixel = (int)($luminances[(int)($offset + $xx)]) & 0xff;
240
						$sum   += $pixel;
241
						// still looking for good contrast
242
						if($pixel < $min){
243
							$min = $pixel;
244
						}
245
246
						if($pixel > $max){
247
							$max = $pixel;
248
						}
249
					}
250
251
					// short-circuit min/max tests once dynamic range is met
252
					if($max - $min > self::MIN_DYNAMIC_RANGE){
253
						// finish the rest of the rows quickly
254
						for($yy++, $offset += $width; $yy < self::BLOCK_SIZE; $yy++, $offset += $width){
255
							for($xx = 0; $xx < self::BLOCK_SIZE; $xx++){
256
								$sum += $luminances[$offset + $xx] & 0xff;
257
							}
258
						}
259
					}
260
				}
261
262
				// The default estimate is the average of the values in the block.
263
				$average = $sum >> (self::BLOCK_SIZE_POWER * 2);
264
265
				if($max - $min <= self::MIN_DYNAMIC_RANGE){
266
					// If variation within the block is low, assume this is a block with only light or only
267
					// dark pixels. In that case we do not want to use the average, as it would divide this
268
					// low contrast area into black and white pixels, essentially creating data out of noise.
269
					//
270
					// The default assumption is that the block is light/background. Since no estimate for
271
					// the level of dark pixels exists locally, use half the min for the block.
272
					$average = (int)($min / 2);
273
274
					if($y > 0 && $x > 0){
275
						// Correct the "white background" assumption for blocks that have neighbors by comparing
276
						// the pixels in this block to the previously calculated black points. This is based on
277
						// the fact that dark barcode symbology is always surrounded by some amount of light
278
						// background for which reasonable black point estimates were made. The bp estimated at
279
						// the boundaries is used for the interior.
280
281
						// The (min < bp) is arbitrary but works better than other heuristics that were tried.
282
						$averageNeighborBlackPoint = (int)(($blackPoints[$y - 1][$x] + (2 * $blackPoints[$y][$x - 1]) + $blackPoints[$y - 1][$x - 1]) / 4);
283
284
						if($min < $averageNeighborBlackPoint){
285
							$average = $averageNeighborBlackPoint;
286
						}
287
					}
288
				}
289
290
				$blackPoints[$y][$x] = (int)($average);
291
			}
292
		}
293
294
		return $blackPoints;
295
	}
296
297
	/**
298
	 * For each block in the image, calculate the average black point using a 5x5 grid
299
	 * of the blocks around it. Also handles the corner cases (fractional blocks are computed based
300
	 * on the last pixels in the row/column which are also used in the previous block).
301
	 */
302
	private function calculateThresholdForBlock(
303
		int $subWidth,
304
		int $subHeight,
305
		int $width,
306
		int $height
307
	):BitMatrix{
308
		$matrix      = new BitMatrix(max($width, $height));
309
		$luminances  = $this->source->getMatrix();
310
		$blackPoints = $this->calculateBlackPoints($luminances, $subWidth, $subHeight, $width, $height);
311
312
		for($y = 0; $y < $subHeight; $y++){
313
			$yoffset    = ($y << self::BLOCK_SIZE_POWER);
314
			$maxYOffset = $height - self::BLOCK_SIZE;
315
316
			if($yoffset > $maxYOffset){
317
				$yoffset = $maxYOffset;
318
			}
319
320
			for($x = 0; $x < $subWidth; $x++){
321
				$xoffset    = ($x << self::BLOCK_SIZE_POWER);
322
				$maxXOffset = $width - self::BLOCK_SIZE;
323
324
				if($xoffset > $maxXOffset){
325
					$xoffset = $maxXOffset;
326
				}
327
328
				$left = $this->cap($x, 2, $subWidth - 3);
329
				$top  = $this->cap($y, 2, $subHeight - 3);
330
				$sum  = 0;
331
332
				for($z = -2; $z <= 2; $z++){
333
					$blackRow = $blackPoints[$top + $z];
334
					$sum      += $blackRow[$left - 2] + $blackRow[$left - 1] + $blackRow[$left] + $blackRow[$left + 1] + $blackRow[$left + 2];
335
				}
336
337
				$average = (int)($sum / 25);
338
339
				// Applies a single threshold to a block of pixels.
340
				for($j = 0, $o = $yoffset * $width + $xoffset; $j < self::BLOCK_SIZE; $j++, $o += $width){
341
					for($i = 0; $i < self::BLOCK_SIZE; $i++){
342
						// Comparison needs to be <= so that black == 0 pixels are black even if the threshold is 0.
343
						if(($luminances[$o + $i] & 0xff) <= $average){
344
							$matrix->set($xoffset + $i, $yoffset + $j);
345
						}
346
					}
347
				}
348
			}
349
		}
350
351
		return $matrix;
352
	}
353
354
	private function cap(int $value, int $min, int $max):int{
355
356
		if($value < $min){
357
			return $min;
358
		}
359
360
		if($value > $max){
361
			return $max;
362
		}
363
364
		return $value;
365
	}
366
367
}
368