2 * Copyright 2009 ZXing authors
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
8 * http://www.apache.org/licenses/LICENSE-2.0
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
17 package com.google.zxing.common;
19 import com.google.zxing.Binarizer;
20 import com.google.zxing.LuminanceSource;
21 import com.google.zxing.NotFoundException;
24 * This class implements a local thresholding algorithm, which while slower than the
25 * GlobalHistogramBinarizer, is fairly efficient for what it does. It is designed for
26 * high frequency images of barcodes with black data on white backgrounds. For this application,
27 * it does a much better job than a global blackpoint with severe shadows and gradients.
28 * However it tends to produce artifacts on lower frequency images and is therefore not
29 * a good general purpose binarizer for uses outside ZXing.
31 * This class extends GlobalHistogramBinarizer, using the older histogram approach for 1D readers,
32 * and the newer local approach for 2D readers. 1D decoding using a per-row histogram is already
33 * inherently local, and only fails for horizontal gradients. We can revisit that problem later,
34 * but for now it was not a win to use local blocks for 1D.
36 * This Binarizer is the default for the unit tests and the recommended class for library users.
38 * @author dswitkin@google.com (Daniel Switkin)
40 public final class HybridBinarizer extends GlobalHistogramBinarizer {
42 // This class uses 5x5 blocks to compute local luminance, where each block is 8x8 pixels.
43 // So this is the smallest dimension in each axis we can accept.
44 private static final int MINIMUM_DIMENSION = 40;
46 private BitMatrix matrix = null;
48 public HybridBinarizer(LuminanceSource source) {
52 public BitMatrix getBlackMatrix() throws NotFoundException {
53 binarizeEntireImage();
57 public Binarizer createBinarizer(LuminanceSource source) {
58 return new HybridBinarizer(source);
61 // Calculates the final BitMatrix once for all requests. This could be called once from the
62 // constructor instead, but there are some advantages to doing it lazily, such as making
63 // profiling easier, and not doing heavy lifting when callers don't expect it.
64 private void binarizeEntireImage() throws NotFoundException {
66 LuminanceSource source = getLuminanceSource();
67 if (source.getWidth() >= MINIMUM_DIMENSION && source.getHeight() >= MINIMUM_DIMENSION) {
68 byte[] luminances = source.getMatrix();
69 int width = source.getWidth();
70 int height = source.getHeight();
71 int subWidth = width >> 3;
72 if ((width & 0x07) != 0) {
75 int subHeight = height >> 3;
76 if ((height & 0x07) != 0) {
79 int[][] blackPoints = calculateBlackPoints(luminances, subWidth, subHeight, width, height);
81 matrix = new BitMatrix(width, height);
82 calculateThresholdForBlock(luminances, subWidth, subHeight, width, height, blackPoints, matrix);
84 // If the image is too small, fall back to the global histogram approach.
85 matrix = super.getBlackMatrix();
90 // For each 8x8 block in the image, calculate the average black point using a 5x5 grid
91 // of the blocks around it. Also handles the corner cases (fractional blocks are computed based
92 // on the last 8 pixels in the row/column which are also used in the previous block).
93 private static void calculateThresholdForBlock(byte[] luminances, int subWidth, int subHeight,
94 int width, int height, int[][] blackPoints, BitMatrix matrix) {
95 for (int y = 0; y < subHeight; y++) {
97 if ((yoffset + 8) >= height) {
100 for (int x = 0; x < subWidth; x++) {
101 int xoffset = x << 3;
102 if ((xoffset + 8) >= width) {
105 int left = (x > 1) ? x : 2;
106 left = (left < subWidth - 2) ? left : subWidth - 3;
107 int top = (y > 1) ? y : 2;
108 top = (top < subHeight - 2) ? top : subHeight - 3;
110 for (int z = -2; z <= 2; z++) {
111 int[] blackRow = blackPoints[top + z];
112 sum += blackRow[left - 2];
113 sum += blackRow[left - 1];
114 sum += blackRow[left];
115 sum += blackRow[left + 1];
116 sum += blackRow[left + 2];
118 int average = sum / 25;
119 threshold8x8Block(luminances, xoffset, yoffset, average, width, matrix);
124 // Applies a single threshold to an 8x8 block of pixels.
125 private static void threshold8x8Block(byte[] luminances, int xoffset, int yoffset, int threshold,
126 int stride, BitMatrix matrix) {
127 for (int y = 0; y < 8; y++) {
128 int offset = (yoffset + y) * stride + xoffset;
129 for (int x = 0; x < 8; x++) {
130 int pixel = luminances[offset + x] & 0xff;
131 if (pixel < threshold) {
132 matrix.set(xoffset + x, yoffset + y);
138 // Calculates a single black point for each 8x8 block of pixels and saves it away.
139 private static int[][] calculateBlackPoints(byte[] luminances, int subWidth, int subHeight,
140 int width, int height) {
141 int[][] blackPoints = new int[subHeight][subWidth];
142 for (int y = 0; y < subHeight; y++) {
143 int yoffset = y << 3;
144 if ((yoffset + 8) >= height) {
145 yoffset = height - 8;
147 for (int x = 0; x < subWidth; x++) {
148 int xoffset = x << 3;
149 if ((xoffset + 8) >= width) {
155 for (int yy = 0; yy < 8; yy++) {
156 int offset = (yoffset + yy) * width + xoffset;
157 for (int xx = 0; xx < 8; xx++) {
158 int pixel = luminances[offset + xx] & 0xff;
169 // If the contrast is inadequate, use half the minimum, so that this block will be
170 // treated as part of the white background, but won't drag down neighboring blocks
173 if (max - min > 24) {
176 // When min == max == 0, let average be 1 so all is black
177 average = max == 0 ? 1 : min >> 1;
179 blackPoints[y][x] = average;