Pileus Git - ~andy/freeotp/blob - src/com/google/zxing/common/HybridBinarizer.java

   1 /*
   2  * Copyright 2009 ZXing authors
   3  *
   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
   7  *
   8  *      http://www.apache.org/licenses/LICENSE-2.0
   9  *
  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.
  15  */
  16
  17 package com.google.zxing.common;
  18
  19 import com.google.zxing.Binarizer;
  20 import com.google.zxing.LuminanceSource;
  21 import com.google.zxing.NotFoundException;
  22
  23 /**
  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.
  30  *
  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.
  35  *
  36  * This Binarizer is the default for the unit tests and the recommended class for library users.
  37  *
  38  * @author dswitkin@google.com (Daniel Switkin)
  39  */
  40 public final class HybridBinarizer extends GlobalHistogramBinarizer {
  41
  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 BLOCK_SIZE_POWER = 3;
  45   private static final int BLOCK_SIZE = 1 << BLOCK_SIZE_POWER; // ...0100...00
  46   private static final int BLOCK_SIZE_MASK = BLOCK_SIZE - 1;   // ...0011...11
  47   private static final int MINIMUM_DIMENSION = BLOCK_SIZE * 5;
  48   private static final int MIN_DYNAMIC_RANGE = 24;
  49
  50   private BitMatrix matrix;
  51
  52   public HybridBinarizer(LuminanceSource source) {
  53     super(source);
  54   }
  55
  56   /**
  57    * Calculates the final BitMatrix once for all requests. This could be called once from the
  58    * constructor instead, but there are some advantages to doing it lazily, such as making
  59    * profiling easier, and not doing heavy lifting when callers don't expect it.
  60    */
  61   @Override
  62   public BitMatrix getBlackMatrix() throws NotFoundException {
  63     if (matrix != null) {
  64       return matrix;
  65     }
  66     LuminanceSource source = getLuminanceSource();
  67     int width = source.getWidth();
  68     int height = source.getHeight();
  69     if (width >= MINIMUM_DIMENSION && height >= MINIMUM_DIMENSION) {
  70       byte[] luminances = source.getMatrix();
  71       int subWidth = width >> BLOCK_SIZE_POWER;
  72       if ((width & BLOCK_SIZE_MASK) != 0) {
  73         subWidth++;
  74       }
  75       int subHeight = height >> BLOCK_SIZE_POWER;
  76       if ((height & BLOCK_SIZE_MASK) != 0) {
  77         subHeight++;
  78       }
  79       int[][] blackPoints = calculateBlackPoints(luminances, subWidth, subHeight, width, height);
  80
  81       BitMatrix newMatrix = new BitMatrix(width, height);
  82       calculateThresholdForBlock(luminances, subWidth, subHeight, width, height, blackPoints, newMatrix);
  83       matrix = newMatrix;
  84     } else {
  85       // If the image is too small, fall back to the global histogram approach.
  86       matrix = super.getBlackMatrix();
  87     }
  88     return matrix;
  89   }
  90
  91   @Override
  92   public Binarizer createBinarizer(LuminanceSource source) {
  93     return new HybridBinarizer(source);
  94   }
  95
  96   /**
  97    * For each block in the image, calculate the average black point using a 5x5 grid
  98    * of the blocks around it. Also handles the corner cases (fractional blocks are computed based
  99    * on the last pixels in the row/column which are also used in the previous block).
 100    */
 101   private static void calculateThresholdForBlock(byte[] luminances,
 102                                                  int subWidth,
 103                                                  int subHeight,
 104                                                  int width,
 105                                                  int height,
 106                                                  int[][] blackPoints,
 107                                                  BitMatrix matrix) {
 108     for (int y = 0; y < subHeight; y++) {
 109       int yoffset = y << BLOCK_SIZE_POWER;
 110       int maxYOffset = height - BLOCK_SIZE;
 111       if (yoffset > maxYOffset) {
 112         yoffset = maxYOffset;
 113       }
 114       for (int x = 0; x < subWidth; x++) {
 115         int xoffset = x << BLOCK_SIZE_POWER;
 116         int maxXOffset = width - BLOCK_SIZE;
 117         if (xoffset > maxXOffset) {
 118           xoffset = maxXOffset;
 119         }
 120         int left = cap(x, 2, subWidth - 3);
 121         int top = cap(y, 2, subHeight - 3);
 122         int sum = 0;
 123         for (int z = -2; z <= 2; z++) {
 124           int[] blackRow = blackPoints[top + z];
 125           sum += blackRow[left - 2] + blackRow[left - 1] + blackRow[left] + blackRow[left + 1] + blackRow[left + 2];
 126         }
 127         int average = sum / 25;
 128         thresholdBlock(luminances, xoffset, yoffset, average, width, matrix);
 129       }
 130     }
 131   }
 132
 133   private static int cap(int value, int min, int max) {
 134     return value < min ? min : value > max ? max : value;
 135   }
 136
 137   /**
 138    * Applies a single threshold to a block of pixels.
 139    */
 140   private static void thresholdBlock(byte[] luminances,
 141                                      int xoffset,
 142                                      int yoffset,
 143                                      int threshold,
 144                                      int stride,
 145                                      BitMatrix matrix) {
 146     for (int y = 0, offset = yoffset * stride + xoffset; y < BLOCK_SIZE; y++, offset += stride) {
 147       for (int x = 0; x < BLOCK_SIZE; x++) {
 148         // Comparison needs to be <= so that black == 0 pixels are black even if the threshold is 0.
 149         if ((luminances[offset + x] & 0xFF) <= threshold) {
 150           matrix.set(xoffset + x, yoffset + y);
 151         }
 152       }
 153     }
 154   }
 155
 156   /**
 157    * Calculates a single black point for each block of pixels and saves it away.
 158    * See the following thread for a discussion of this algorithm:
 159    *  http://groups.google.com/group/zxing/browse_thread/thread/d06efa2c35a7ddc0
 160    */
 161   private static int[][] calculateBlackPoints(byte[] luminances,
 162                                               int subWidth,
 163                                               int subHeight,
 164                                               int width,
 165                                               int height) {
 166     int[][] blackPoints = new int[subHeight][subWidth];
 167     for (int y = 0; y < subHeight; y++) {
 168       int yoffset = y << BLOCK_SIZE_POWER;
 169       int maxYOffset = height - BLOCK_SIZE;
 170       if (yoffset > maxYOffset) {
 171         yoffset = maxYOffset;
 172       }
 173       for (int x = 0; x < subWidth; x++) {
 174         int xoffset = x << BLOCK_SIZE_POWER;
 175         int maxXOffset = width - BLOCK_SIZE;
 176         if (xoffset > maxXOffset) {
 177           xoffset = maxXOffset;
 178         }
 179         int sum = 0;
 180         int min = 0xFF;
 181         int max = 0;
 182         for (int yy = 0, offset = yoffset * width + xoffset; yy < BLOCK_SIZE; yy++, offset += width) {
 183           for (int xx = 0; xx < BLOCK_SIZE; xx++) {
 184             int pixel = luminances[offset + xx] & 0xFF;
 185             sum += pixel;
 186             // still looking for good contrast
 187             if (pixel < min) {
 188               min = pixel;
 189             }
 190             if (pixel > max) {
 191               max = pixel;
 192             }
 193           }
 194           // short-circuit min/max tests once dynamic range is met
 195           if (max - min > MIN_DYNAMIC_RANGE) {
 196             // finish the rest of the rows quickly
 197             for (yy++, offset += width; yy < BLOCK_SIZE; yy++, offset += width) {
 198               for (int xx = 0; xx < BLOCK_SIZE; xx++) {
 199                 sum += luminances[offset + xx] & 0xFF;
 200               }
 201             }
 202           }
 203         }
 204
 205         // The default estimate is the average of the values in the block.
 206         int average = sum >> (BLOCK_SIZE_POWER * 2);
 207         if (max - min <= MIN_DYNAMIC_RANGE) {
 208           // If variation within the block is low, assume this is a block with only light or only
 209           // dark pixels. In that case we do not want to use the average, as it would divide this
 210           // low contrast area into black and white pixels, essentially creating data out of noise.
 211           //
 212           // The default assumption is that the block is light/background. Since no estimate for
 213           // the level of dark pixels exists locally, use half the min for the block.
 214           average = min >> 1;
 215
 216           if (y > 0 && x > 0) {
 217             // Correct the "white background" assumption for blocks that have neighbors by comparing
 218             // the pixels in this block to the previously calculated black points. This is based on
 219             // the fact that dark barcode symbology is always surrounded by some amount of light
 220             // background for which reasonable black point estimates were made. The bp estimated at
 221             // the boundaries is used for the interior.
 222
 223             // The (min < bp) is arbitrary but works better than other heuristics that were tried.
 224             int averageNeighborBlackPoint = (blackPoints[y - 1][x] + (2 * blackPoints[y][x - 1]) +
 225                 blackPoints[y - 1][x - 1]) >> 2;
 226             if (min < averageNeighborBlackPoint) {
 227               average = averageNeighborBlackPoint;
 228             }
 229           }
 230         }
 231         blackPoints[y][x] = average;
 232       }
 233     }
 234     return blackPoints;
 235   }
 236
 237 }