core/src/com/google/zxing/common/BitMatrix.java

   1 /*\r
   2  * Copyright 2007 ZXing authors\r
   3  *\r
   4  * Licensed under the Apache License, Version 2.0 (the "License");\r
   5  * you may not use this file except in compliance with the License.\r
   6  * You may obtain a copy of the License at\r
   7  *\r
   8  *      http://www.apache.org/licenses/LICENSE-2.0\r
   9  *\r
  10  * Unless required by applicable law or agreed to in writing, software\r
  11  * distributed under the License is distributed on an "AS IS" BASIS,\r
  12  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\r
  13  * See the License for the specific language governing permissions and\r
  14  * limitations under the License.\r
  15  */\r
  16 \r
  17 package com.google.zxing.common;\r
  18 \r
  19 /**\r
  20  * <p>Represents a 2D matrix of bits. In function arguments below, and throughout the common\r
  21  * module, x is the column position, and y is the row position. The ordering is always x, y.\r
  22  * The origin is at the top-left.</p>\r
  23  *\r
  24  * <p>Internally the bits are represented in a 1-D array of 32-bit ints. However, each row begins\r
  25  * with a new int. This is done intentionally so that we can copy out a row into a BitArray very\r
  26  * efficiently.</p>\r
  27  *\r
  28  * <p>The ordering of bits is row-major. Within each int, the least significant bits are used first,\r
  29  * meaning they represent lower x values. This is compatible with BitArray's implementation.</p>\r
  30  *\r
  31  * @author Sean Owen\r
  32  * @author dswitkin@google.com (Daniel Switkin)\r
  33  */\r
  34 public final class BitMatrix {\r
  35 \r
  36   // TODO: Just like BitArray, these need to be public so ProGuard can inline them.\r
  37   public final int width;\r
  38   public final int height;\r
  39   public final int rowSize;\r
  40   public final int[] bits;\r
  41 \r
  42   // A helper to construct a square matrix.\r
  43   public BitMatrix(int dimension) {\r
  44     this(dimension, dimension);\r
  45   }\r
  46 \r
  47   public BitMatrix(int width, int height) {\r
  48     if (width < 1 || height < 1) {\r
  49       throw new IllegalArgumentException("Both dimensions must be greater than 0");\r
  50     }\r
  51     this.width = width;\r
  52     this.height = height;\r
  53     int rowSize = width >> 5;\r
  54     if ((width & 0x1f) != 0) {\r
  55       rowSize++;\r
  56     }\r
  57     this.rowSize = rowSize;\r
  58     bits = new int[rowSize * height];\r
  59   }\r
  60 \r
  61   /**\r
  62    * <p>Gets the requested bit, where true means black.</p>\r
  63    *\r
  64    * @param x The horizontal component (i.e. which column)\r
  65    * @param y The vertical component (i.e. which row)\r
  66    * @return value of given bit in matrix\r
  67    */\r
  68   public boolean get(int x, int y) {\r
  69     int offset = y * rowSize + (x >> 5);\r
  70     return ((bits[offset] >>> (x & 0x1f)) & 1) != 0;\r
  71   }\r
  72 \r
  73   /**\r
  74    * <p>Sets the given bit to true.</p>\r
  75    *\r
  76    * @param x The horizontal component (i.e. which column)\r
  77    * @param y The vertical component (i.e. which row)\r
  78    */\r
  79   public void set(int x, int y) {\r
  80     int offset = y * rowSize + (x >> 5);\r
  81     bits[offset] |= 1 << (x & 0x1f);\r
  82   }\r
  83 \r
  84   /**\r
  85    * <p>Flips the given bit.</p>\r
  86    *\r
  87    * @param x The horizontal component (i.e. which column)\r
  88    * @param y The vertical component (i.e. which row)\r
  89    */\r
  90   public void flip(int x, int y) {\r
  91     int offset = y * rowSize + (x >> 5);\r
  92     bits[offset] ^= 1 << (x & 0x1f);\r
  93   }\r
  94 \r
  95   /**\r
  96    * Clears all bits (sets to false).\r
  97    */\r
  98   public void clear() {\r
  99     int max = bits.length;\r
 100     for (int i = 0; i < max; i++) {\r
 101       bits[i] = 0;\r
 102     }\r
 103   }\r
 104 \r
 105   /**\r
 106    * <p>Sets a square region of the bit matrix to true.</p>\r
 107    *\r
 108    * @param left The horizontal position to begin at (inclusive)\r
 109    * @param top The vertical position to begin at (inclusive)\r
 110    * @param width The width of the region\r
 111    * @param height The height of the region\r
 112    */\r
 113   public void setRegion(int left, int top, int width, int height) {\r
 114     if (top < 0 || left < 0) {\r
 115       throw new IllegalArgumentException("Left and top must be nonnegative");\r
 116     }\r
 117     if (height < 1 || width < 1) {\r
 118       throw new IllegalArgumentException("Height and width must be at least 1");\r
 119     }\r
 120     int right = left + width;\r
 121     int bottom = top + height;\r
 122     if (bottom > this.height || right > this.width) {\r
 123       throw new IllegalArgumentException("The region must fit inside the matrix");\r
 124     }\r
 125     for (int y = top; y < bottom; y++) {\r
 126       int offset = y * rowSize;\r
 127       for (int x = left; x < right; x++) {\r
 128         bits[offset + (x >> 5)] |= 1 << (x & 0x1f);\r
 129       }\r
 130     }\r
 131   }\r
 132 \r
 133   /**\r
 134    * A fast method to retrieve one row of data from the matrix as a BitArray.\r
 135    *\r
 136    * @param y The row to retrieve\r
 137    * @param row An optional caller-allocated BitArray, will be allocated if null or too small\r
 138    * @return The resulting BitArray - this reference should always be used even when passing\r
 139    *         your own row\r
 140    */\r
 141   public BitArray getRow(int y, BitArray row) {\r
 142     if (row == null || row.getSize() < width) {\r
 143       row = new BitArray(width);\r
 144     }\r
 145     int offset = y * rowSize;\r
 146     for (int x = 0; x < rowSize; x++) {\r
 147       row.setBulk(x << 5, bits[offset + x]);\r
 148     }\r
 149     return row;\r
 150   }\r
 151 \r
 152   /**\r
 153    * @return The width of the matrix\r
 154    */\r
 155   public int getWidth() {\r
 156     return width;\r
 157   }\r
 158 \r
 159   /**\r
 160    * @return The height of the matrix\r
 161    */\r
 162   public int getHeight() {\r
 163     return height;\r
 164   }\r
 165 \r
 166   /**\r
 167    * This method is for compatibility with older code. It's only logical to call if the matrix\r
 168    * is square, so I'm throwing if that's not the case.\r
 169    *\r
 170    * @return row/column dimension of this matrix\r
 171    */\r
 172   public int getDimension() {\r
 173     if (width != height) {\r
 174       throw new RuntimeException("Can't call getDimension() on a non-square matrix");\r
 175     }\r
 176     return width;\r
 177   }\r
 178 \r
 179   public String toString() {\r
 180     StringBuffer result = new StringBuffer(height * (width + 1));\r
 181     for (int y = 0; y < height; y++) {\r
 182       for (int x = 0; x < width; x++) {\r
 183         result.append(get(x, y) ? "X " : "  ");\r
 184       }\r
 185       result.append('\n');\r
 186     }\r
 187     return result.toString();\r
 188   }\r
 189 \r
 190 }\r