Refactored Reed-Solomon so it can be used with different GF(256) primitive polynomials

[zxing.git] / core / src / com / google / zxing / qrcode / decoder / Decoder.java

diff --git a/core/src/com/google/zxing/qrcode/decoder/Decoder.java b/core/src/com/google/zxing/qrcode/decoder/Decoder.java
index a37128f..4f73245 100644 (file)
--- a/core/src/com/google/zxing/qrcode/decoder/Decoder.java
+++ b/core/src/com/google/zxing/qrcode/decoder/Decoder.java
@@ -18,18 +18,33 @@ package com.google.zxing.qrcode.decoder;
 \r
 import com.google.zxing.ReaderException;\r
 import com.google.zxing.common.BitMatrix;\r
+import com.google.zxing.common.reedsolomon.GF256;\r
 import com.google.zxing.common.reedsolomon.ReedSolomonDecoder;\r
 import com.google.zxing.common.reedsolomon.ReedSolomonException;\r
 \r
 /**\r
+ * <p>The main class which implements QR Code decoding -- as opposed to locating and extracting\r
+ * the QR Code from an image.</p>\r
+ *\r
  * @author srowen@google.com (Sean Owen)\r
  */\r
 public final class Decoder {\r
 \r
-  private Decoder() {\r
+  private final ReedSolomonDecoder rsDecoder;\r
+\r
+  public Decoder() {\r
+    rsDecoder = new ReedSolomonDecoder(GF256.QR_CODE_FIELD);\r
   }\r
 \r
-  public static String decode(boolean[][] image) throws ReaderException {\r
+  /**\r
+   * <p>Convenience method that can decode a QR Code represented as a 2D array of booleans.\r
+   * "true" is taken to mean a black module.</p>\r
+   *\r
+   * @param image booleans representing white/black QR Code modules\r
+   * @return text encoded within the QR Code\r
+   * @throws ReaderException if the QR Code cannot be decoded\r
+   */\r
+  public String decode(boolean[][] image) throws ReaderException {\r
     int dimension = image.length;\r
     BitMatrix bits = new BitMatrix(dimension);\r
     for (int i = 0; i < dimension; i++) {\r
@@ -42,18 +57,34 @@ public final class Decoder {
     return decode(bits);\r
   }\r
 \r
-  public static String decode(BitMatrix bits) throws ReaderException {\r
+  /**\r
+   * <p>Decodes a QR Code represented as a {@link BitMatrix}. A 1 or "true" is taken to mean a black module.</p>\r
+   *\r
+   * @param bits booleans representing white/black QR Code modules\r
+   * @return text encoded within the QR Code\r
+   * @throws ReaderException if the QR Code cannot be decoded\r
+   */\r
+  public String decode(BitMatrix bits) throws ReaderException {\r
+\r
+    // Construct a parser and read version, error-correction level\r
     BitMatrixParser parser = new BitMatrixParser(bits);\r
     Version version = parser.readVersion();\r
     ErrorCorrectionLevel ecLevel = parser.readFormatInformation().getErrorCorrectionLevel();\r
+\r
+    // Read codewords\r
     byte[] codewords = parser.readCodewords();\r
+    // Separate into data blocks\r
     DataBlock[] dataBlocks = DataBlock.getDataBlocks(codewords, version, ecLevel);\r
+\r
+    // Count total number of data bytes\r
     int totalBytes = 0;\r
     for (int i = 0; i < dataBlocks.length; i++) {\r
       totalBytes += dataBlocks[i].getNumDataCodewords();\r
     }\r
     byte[] resultBytes = new byte[totalBytes];\r
     int resultOffset = 0;\r
+\r
+    // Error-correct and copy data blocks together into a stream of bytes\r
     for (int j = 0; j < dataBlocks.length; j++) {\r
       DataBlock dataBlock = dataBlocks[j];\r
       byte[] codewordBytes = dataBlock.getCodewords();\r
@@ -64,22 +95,33 @@ public final class Decoder {
       }\r
     }\r
 \r
+    // Decode the contents of that stream of bytes\r
     return DecodedBitStreamParser.decode(resultBytes, version);\r
   }\r
 \r
-  private static void correctErrors(byte[] codewordBytes, int numDataCodewords)\r
-      throws ReaderException {\r
+  /**\r
+   * <p>Given data and error-correction codewords received, possibly corrupted by errors, attempts to\r
+   * correct the errors in-place using Reed-Solomon error correction.</p>\r
+   *\r
+   * @param codewordBytes data and error correction codewords\r
+   * @param numDataCodewords number of codewords that are data bytes\r
+   * @throws ReaderException if error correction fails\r
+   */\r
+  private void correctErrors(byte[] codewordBytes, int numDataCodewords) throws ReaderException {\r
     int numCodewords = codewordBytes.length;\r
+    // First read into an array of ints\r
     int[] codewordsInts = new int[numCodewords];\r
     for (int i = 0; i < numCodewords; i++) {\r
       codewordsInts[i] = codewordBytes[i] & 0xFF;\r
     }\r
     int numECCodewords = codewordBytes.length - numDataCodewords;\r
     try {\r
-      ReedSolomonDecoder.decode(codewordsInts, numECCodewords);\r
+      rsDecoder.decode(codewordsInts, numECCodewords);\r
     } catch (ReedSolomonException rse) {\r
       throw new ReaderException(rse.toString());\r
     }\r
+    // Copy back into array of bytes -- only need to worry about the bytes that were data\r
+    // We don't care about errors in the error-correction codewords\r
     for (int i = 0; i < numDataCodewords; i++) {\r
       codewordBytes[i] = (byte) codewordsInts[i];\r
     }\r