core/src/com/google/zxing/MonochromeBitmapSource.java

   1 /*
   2  * Copyright 2007 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;
  18
  19 import com.google.zxing.common.BitArray;
  20
  21 /**
  22  * <p>Encapsulates a generic black-and-white bitmap -- a collection of pixels in two dimensions.
  23  * This unifies many possible representations, like AWT's <code>BufferedImage</code>.</p>
  24  *
  25  * @author Sean Owen
  26  * @author dswitkin@google.com (Daniel Switkin)
  27  */
  28 public interface MonochromeBitmapSource {
  29
  30   /**
  31    * @param x horizontal offset, from left, of the pixel
  32    * @param y vertical offset, from top, of the pixel
  33    * @return true iff the pixel at (x,y) is black
  34    */
  35   boolean isBlack(int x, int y);
  36
  37   /**
  38    * <p>Returns an entire row of black/white pixels as an array of bits, where "true" means "black".
  39    * This is a sort of "bulk get" operation intended to enable efficient access in
  40    * certain situations.</p>
  41    *
  42    * @param y vertical offset, from top, of the row of pixels
  43    * @param row if not null, {@link BitArray} to write pixels into. If null, a new {@link BitArray}
  44    * is allocated and returned.
  45    * @param startX horizontal offset, from left, from which to start getting pixels
  46    * @param getWidth number of pixels to get from the row
  47    * @return {@link BitArray} representing the (subset of the) row of pixels. If row parameter
  48    *         was not null, it is returned.
  49    */
  50   BitArray getBlackRow(int y, BitArray row, int startX, int getWidth);
  51
  52   /**
  53    * Entirely analogous to {@link #getBlackRow(int, BitArray, int, int)} but gets a column.
  54    */
  55   BitArray getBlackColumn(int x, BitArray column, int startY, int getHeight);
  56
  57   BitArray getBlackDiagonal(int x, int y, int dx, int dy, BitArray diagonal, int size);
  58
  59   /**
  60    * @return height of underlying image
  61    */
  62   int getHeight();
  63
  64   /**
  65    * @return width of underlying image
  66    */
  67   int getWidth();
  68
  69   /**
  70    * <p>Estimates black point according to the given method, which is optionally parameterized by
  71    * a single int argument. For {@link BlackPointEstimationMethod#ROW_SAMPLING}, this
  72    * specifies the row to sample.</p>
  73    *
  74    * <p>The estimated value will be used in subsequent computations that rely on an estimated black
  75    * point.</p>
  76    *
  77    * @param method black point estimation method
  78    * @param argument method-specific argument
  79    */
  80   void estimateBlackPoint(BlackPointEstimationMethod method, int argument) throws ReaderException;
  81
  82   /**
  83    * @return {@link BlackPointEstimationMethod} representing last sampling method used
  84    */
  85   BlackPointEstimationMethod getLastEstimationMethod();
  86
  87   /**
  88    * <p>Optional operation which returns an implementation based on the same underlying
  89    * image, but which behaves as if the underlying image had been rotated 90 degrees
  90    * counterclockwise. This is useful in the context of 1D barcodes and the
  91    * {@link DecodeHintType#TRY_HARDER} decode hint, and is only intended to be
  92    * used in non-resource-constrained environments. Hence, implementations
  93    * of this class which are only used in resource-constrained mobile environments
  94    * don't have a need to implement this.</p>
  95    *
  96    * @throws IllegalArgumentException if not supported
  97    */
  98   MonochromeBitmapSource rotateCounterClockwise();
  99
 100   /**
 101    * @return true iff rotation is supported
 102    * @see #rotateCounterClockwise()
 103    */
 104   boolean isRotateSupported();
 105
 106   /**
 107    * Retrieves the luminance at the pixel x,y in the bitmap. This method is only used for estimating
 108    * the black point and implementing getBlackRow() - it is not meant for decoding, hence it is not
 109    * part of MonochromeBitmapSource itself, and is protected.
 110    *
 111    * @param x The x coordinate in the image.
 112    * @param y The y coordinate in the image.
 113    * @return The luminance value between 0 and 255.
 114    */
 115   int getLuminance(int x, int y);
 116
 117   /**
 118    * This is the main mechanism for retrieving luminance data. It is dramatically more efficient
 119    * than repeatedly calling getLuminance(). As above, this is not meant for decoders.
 120    *
 121    * @param y The row to fetch
 122    * @param row The array to write luminance values into. It is <b>strongly</b> suggested that you
 123    *            allocate this yourself, making sure row.length >= getWidth(), and reuse the same
 124    *            array on subsequent calls for performance. If you pass null, you will be flogged,
 125    *            but then I will take pity on you and allocate a sufficient array internally.
 126    * @return The array containing the luminance data. This is the same as row if it was usable.
 127    */
 128   int[] getLuminanceRow(int y, int[] row);
 129
 130   /**
 131    * The same as getLuminanceRow(), but for columns.
 132    *
 133    * @param x The column to fetch
 134    * @param column The array to write luminance values into. See above.
 135    * @return The array containing the luminance data.
 136    */
 137   int[] getLuminanceColumn(int x, int[] column);
 138
 139 }