mudhorn/zxing
1
0
Fork 0
mirror of https://github.com/zxing/zxing.git synced 2025-03-05 20:48:51 -08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Did a bunch of comments cleanup.

Browse source 
git-svn-id: https://zxing.googlecode.com/svn/trunk@701 59b500cc-1b3d-0410-9834-0bbf25fbcc57
This commit is contained in:
dswitkin 2008-11-14 15:40:38 +00:00
parent 002d80eed2
commit 97ffa36734
5 changed files with 115 additions and 122 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

16
core/src/com/google/zxing/qrcode/encoder/Encoder.java
View file

@ -99,10 +99,10 @@ public final class Encoder {
};
// The numbers were generated using the logic found in
// http://www.d-project.com/qrcode/. We use generated numbers instead
// of the logic itself (don't want to copy it). The numbers are
// http://www.d-project.com/qrcode/. We use generated numbers instead
// of the logic itself (don't want to copy it). The numbers are
// supposed to be identical to the ones in the table is from the table
// in Appendix A of JISX0510:2004 (p. 30). However, there are some
// in Appendix A of JISX0510:2004 (p. 30). However, there are some
// cases the spec seems to be wrong.
static final ECPolyInfo kECPolynomials[] = {
{ 7,
@ -274,7 +274,7 @@ public final class Encoder {
private static GF_Poly *g_ec_polynomials[kMaxNumECBytes + 1];
public:
// Encode "bytes" with the error correction level "ec_level". The
// Encode "bytes" with the error correction level "ec_level". The
// encoding mode will be chosen internally by ChooseMode().
// On success, store the result in "qr_code" and return true. On
// error, return false. We recommend you to use QRCode.EC_LEVEL_L
@ -423,7 +423,7 @@ public final class Encoder {
}
// Initialize "qr_code" according to "num_input_bytes", "ec_level",
// and "mode". On success, modify "qr_code" and return true. On
// and "mode". On success, modify "qr_code" and return true. On
// error, return false.
static boolean InitQRCode(int num_input_bytes, int ec_level, int mode, QRCode *qr_code) {
qr_code.set_ec_level(ec_level);
@ -447,7 +447,7 @@ public final class Encoder {
final int num_data_bytes = num_bytes - num_ec_bytes;
// We want to choose the smallest version which can contain data
// of "num_input_bytes" + some extra bits for the header (mode
// info and length info). The header can be three bytes
// info and length info). The header can be three bytes
// (precisely 4 + 16 bits) at most. Hence we do +3 here.
if (num_data_bytes >= num_input_bytes + 3) {
// Yay, we found the proper rs block info!
@ -504,7 +504,7 @@ public final class Encoder {
}
// Get number of data bytes and number of error correction bytes for
// block id "block_id". Store the result in
// block id "block_id". Store the result in
// "num_data_bytes_in_block", and "num_ec_bytes_in_block".
// See table 12 in 8.5.1 of JISX0510:2004 (p.30)
static void GetNumDataBytesAndNumECBytesForBlockID(
@ -807,7 +807,7 @@ public final class Encoder {
}
// Get error correction polynomials. The polynomials are
// defined in Appendix A of JISX0510 2004 (p. 59). In the appendix,
// defined in Appendix A of JISX0510 2004 (p. 59). In the appendix,
// they use exponential notations for the polynomials. We need to
// apply GaloisField.Log() to all coefficients generated by the
// function to compare numbers with the ones in the appendix.

34
core/src/com/google/zxing/qrcode/encoder/MaskUtil.java
View file

@ -22,9 +22,8 @@ package com.google.zxing.qrcode.encoder;
*/
public final class MaskUtil {
// The mask penalty calculation is complicated. See Table 21 of
// JISX0510:2004 (p.45) for details. Basically it applies four
// rules and summate all penalties.
// The mask penalty calculation is complicated. See Table 21 of JISX0510:2004 (p.45) for details.
// Basically it applies four rules and summate all penalties.
public static int CalculateMaskPenalty(final Matrix matrix) {
int penalty = 0;
penalty += ApplyMaskPenaltyRule1(matrix);
@ -34,9 +33,8 @@ public final class MaskUtil {
return penalty;
}
// Apply mask penalty rule 1 and return the penalty.
// Find repetitive cells with the same color and give penalty to
// them. Example: 00000 or 11111.
// Apply mask penalty rule 1 and return the penalty. Find repetitive cells with the same color and
// give penalty to them. Example: 00000 or 11111.
public static int ApplyMaskPenaltyRule1(final Matrix matrix) {
final int penalty = (ApplyMaskPenaltyRule1Internal(matrix, true) +
ApplyMaskPenaltyRule1Internal(matrix, false));
@ -44,8 +42,8 @@ public final class MaskUtil {
return penalty;
}
// Apply mask penalty rule 2 and return the penalty.
// Find 2x2 blocks with the same color and give penalty to them.
// Apply mask penalty rule 2 and return the penalty. Find 2x2 blocks with the same color and give
// penalty to them.
//
// JAVAPORT: Consider using Matrix.getArray() instead.
public static int ApplyMaskPenaltyRule2(final Matrix matrix) {
@ -64,9 +62,8 @@ public final class MaskUtil {
return penalty;
}
// Apply mask penalty rule 3 and return the penalty.
// Find consecutive cells of 00001011101 or 10111010000, and give
// penalty to them. If we find patterns like 000010111010000, we give
// Apply mask penalty rule 3 and return the penalty. Find consecutive cells of 00001011101 or
// 10111010000, and give penalty to them. If we find patterns like 000010111010000, we give
// penalties twice (i.e. 40 * 2).
//
// JAVAPORT: This many calls to Matrix.get() looks expensive. We should profile and consider
@ -122,10 +119,8 @@ public final class MaskUtil {
return penalty;
}
// Apply mask penalty rule 4 and return the penalty.
// Calculate the ratio of dark cells and give penalty if the ratio
// is far from 50%. It gives 10 penalty for 5% distance.
// Examples:
// Apply mask penalty rule 4 and return the penalty. Calculate the ratio of dark cells and give
// penalty if the ratio is far from 50%. It gives 10 penalty for 5% distance. Examples:
// - 0% => 100
// - 40% => 20
// - 45% => 10
@ -149,8 +144,8 @@ public final class MaskUtil {
return penalty;
}
// Return the mask bit for "mask_pattern" at "x" and "y".
// See 8.8 of JISX0510:2004 for mask pattern conditions.
// Return the mask bit for "mask_pattern" at "x" and "y". See 8.8 of JISX0510:2004 for mask
// pattern conditions.
public static int GetDataMaskBit(final int mask_pattern, final int x, final int y) {
Debug.DCHECK(QRCode.IsValidMaskPattern(mask_pattern));
switch (mask_pattern) {
@ -177,9 +172,8 @@ public final class MaskUtil {
return -1;
}
// Helper function for ApplyMaskPenaltyRule1. We need this for doing
// this calculation in both vertical and horizontal orders
// respectively.
// Helper function for ApplyMaskPenaltyRule1. We need this for doing this calculation in both
// vertical and horizontal orders respectively.
private static int ApplyMaskPenaltyRule1Internal(final Matrix matrix, boolean is_horizontal) {
int penalty = 0;
int num_same_bit_cells = 0;

93
core/src/com/google/zxing/qrcode/encoder/MatrixUtil.java
View file

@ -50,8 +50,7 @@ public final class MatrixUtil {
{1, 1, 1, 1, 1},
};
// From Appendix E. Table 1, JIS0510X:2004 (p 71).
// The table was double-checked by komatsu.
// From Appendix E. Table 1, JIS0510X:2004 (p 71). The table was double-checked by komatsu.
private static final int kPositionAdjustmentPatternCoordinateTable[][] = {
{-1, -1, -1, -1, -1, -1, -1}, // Version 1
{ 6, 18, -1, -1, -1, -1, -1}, // Version 2
@ -121,8 +120,7 @@ public final class MatrixUtil {
private static final uint32 kTypeInfoPoly = 0x537;
private static final uint32 kTypeInfoMaskPattern = 0x5412;
// Set all cells to -1. -1 means that the cell is empty (not set
// yet).
// Set all cells to -1. -1 means that the cell is empty (not set yet).
public static void ClearMatrix(Matrix matrix) {
for (int y = 0; y < matrix.height(); ++y) {
for (int x = 0; x < matrix.width(); ++x) {
@ -153,9 +151,8 @@ public final class MatrixUtil {
return result.toString();
}
// Build 2D matrix of QR Code from "data_bits" with "ec_level",
// "version" and "mask_pattern". On success, store the result in
// "matrix" and return true. On error, return false.
// Build 2D matrix of QR Code from "data_bits" with "ec_level", "version" and "mask_pattern". On
// success, store the result in "matrix" and return true. On error, return false.
public static boolean BuildMatrix(final BitVector &data_bits,
int ec_level,
int version,
@ -177,8 +174,8 @@ public final class MatrixUtil {
return EmbedDataBits(data_bits, mask_pattern, matrix);
}
// Embed basic patterns. On success, modify the matrix and return
// true. On error, return false. The basic patterns are:
// Embed basic patterns. On success, modify the matrix and return true. On error, return false.
// The basic patterns are:
// - Position detection patterns
// - Timing patterns
// - Dark dot at the left bottom corner
@ -196,8 +193,7 @@ public final class MatrixUtil {
return true;
}
// Embed type information. On success, modify the matrix and return
// true. On error, return false.
// Embed type information. On success, modify the matrix and return true. On error, return false.
public static boolean EmbedTypeInfo(int ec_level, int mask_pattern, Matrix matrix) {
BitVector type_info_bits;
if (!MakeTypeInfoBits(ec_level, mask_pattern, &type_info_bits)) {
@ -206,12 +202,11 @@ public final class MatrixUtil {
Debug.DCHECK_EQ(15, type_info_bits.size());
for (int i = 0; i < type_info_bits.size(); ++i) {
// Place bits in LSB to MSB order. LSB (least significant bit)
// is the last value in "type_info_bits".
// Place bits in LSB to MSB order. LSB (least significant bit) is the last value in
// "type_info_bits".
final int bit = type_info_bits.at(type_info_bits.size() - 1 - i);
// Type info bits at the left top corner.
// See 8.9 of JISX0510:2004 (p.46).
// Type info bits at the left top corner. See 8.9 of JISX0510:2004 (p.46).
final int x1 = kTypeInfoCoordinates[i][0];
final int y1 = kTypeInfoCoordinates[i][1];
matrix.set(y1, x1, bit);
@ -231,10 +226,9 @@ public final class MatrixUtil {
return true;
}
// Embed version information if need be. On success, modify the
// matrix and return true. On error, return false.
// See 8.10 of JISX0510:2004 (p.47) for how to embed version
// information. Return true on success. Return false otherwise.
// Embed version information if need be. On success, modify the matrix and return true. On error,
// return false. See 8.10 of JISX0510:2004 (p.47) for how to embed version information. Return
// true on success, otherwise return false.
public static boolean MaybeEmbedVersionInfo(int version, Matrix matrix) {
if (version < 7) { // Version info is necessary if version >= 7.
return true; // Don't need version info.
@ -259,9 +253,8 @@ public final class MatrixUtil {
return true;
}
// Embed "data_bits" using "mask_pattern". On success, modify the
// matrix and return true. On error, return false. For debugging
// purpose, it skips masking process if "mask_pattern" is -1.
// Embed "data_bits" using "mask_pattern". On success, modify the matrix and return true. On
// error, return false. For debugging purposes, it skips masking process if "mask_pattern" is -1.
// See 8.7 of JISX0510:2004 (p.38) for how to embed data bits.
public static boolean EmbedDataBits(final BitVector &data_bits, int mask_pattern, Matrix matrix) {
int bit_index = 0;
@ -286,9 +279,8 @@ public final class MatrixUtil {
bit = data_bits.at(bit_index);
++bit_index;
} else {
// Padding bit. If there is no bit left, we'll fill the
// left cells with 0, as described in 8.4.9 of
// JISX0510:2004 (p. 24).
// Padding bit. If there is no bit left, we'll fill the left cells with 0, as described
// in 8.4.9 of JISX0510:2004 (p. 24).
bit = 0;
}
Debug.DCHECK(IsValidValue(bit));
@ -316,10 +308,8 @@ public final class MatrixUtil {
return true;
}
// Return the position of the most significant bit set (to one) in
// the "value". The most significant bit is position 32. If there
// is no bit set, return 0.
// Examples:
// Return the position of the most significant bit set (to one) in the "value". The most
// significant bit is position 32. If there is no bit set, return 0. Examples:
// - FindMSBSet(0) => 0
// - FindMSBSet(1) => 1
// - FindMSBSet(255) => 8
@ -332,9 +322,8 @@ public final class MatrixUtil {
return num_digits;
}
// Calculate BCH (Bose-Chaudhuri-Hocquenghem) code for "value" using
// polynomial "poly". The BCH code is used for encoding type
// information and version information.
// Calculate BCH (Bose-Chaudhuri-Hocquenghem) code for "value" using polynomial "poly". The BCH
// code is used for encoding type information and version information.
// Example: Calculation of version information of 7.
// f(x) is created from 7.
// - 7 = 000111 in 6 bits
@ -356,12 +345,11 @@ public final class MatrixUtil {
// Encode it in binary: 110010010100
// The return value is 0xc94 (1100 1001 0100)
//
// Since all coefficients in the polynomials are 1 or 0, we can do the
// calculation by bit operations. We don't care if cofficients are
// positive or nagative.
// Since all coefficients in the polynomials are 1 or 0, we can do the calculation by bit
// operations. We don't care if cofficients are positive or negative.
public static uint32 CalculateBCHCode(uint32 value, uint32 poly) {
// If poly is "1 1111 0010 0101" (version info poly),
// msb_set_in_poly is 13. We'll subtract 1 from 13 to make it 12.
// If poly is "1 1111 0010 0101" (version info poly), msb_set_in_poly is 13. We'll subtract 1
// from 13 to make it 12.
final int msb_set_in_poly = FindMSBSet(poly);
value <<= msb_set_in_poly - 1;
// Do the division business using exclusive-or operations.
@ -372,9 +360,8 @@ public final class MatrixUtil {
return value;
}
// Make bit vector of type information. On success, store the
// result in "bits" and return true. On error, return false.
// Encode error correction level and mask pattern. See 8.9 of
// Make bit vector of type information. On success, store the result in "bits" and return true.
// On error, return false. Encode error correction level and mask pattern. See 8.9 of
// JISX0510:2004 (p.45) for details.
public static boolean MakeTypeInfoBits(int ec_level, final int mask_pattern, BitVector *bits) {
final int ec_code = QRCode.GetECLevelCode(ec_level);
@ -402,10 +389,8 @@ public final class MatrixUtil {
return true;
}
// Make bit vector of version information. On success, store the
// result in "bits" and return true. On error, return false.
// Encode version information. See 8.10 of JISX0510:2004 (p.45) for
// details.
// Make bit vector of version information. On success, store the result in "bits" and return true.
// On error, return false. See 8.10 of JISX0510:2004 (p.45) for details.
public static boolean MakeVersionInfoBits(int version, BitVector *bits) {
bits.AppendBits(version, 6);
final uint32 bch_code = MatrixUtil.CalculateBCHCode(version,
@ -431,9 +416,8 @@ public final class MatrixUtil {
}
private static void EmbedTimingPatterns(Matrix matrix) {
// -8 is for skipping position detection patterns (size 7), and
// two horizontal/vertical separation patterns (size 1).
// Thus, 8 = 7 + 1.
// -8 is for skipping position detection patterns (size 7), and two horizontal/vertical
// separation patterns (size 1). Thus, 8 = 7 + 1.
for (int i = 8; i < matrix.width() - 8; ++i) {
final int bit = (i + 1) % 2;
// Horizontal line.
@ -449,8 +433,7 @@ public final class MatrixUtil {
}
}
// Embed the lonely dark dot at left bottom corner.
// JISX0510:2004 (p.46)
// Embed the lonely dark dot at left bottom corner. JISX0510:2004 (p.46)
private static void EmbedDarkDotAtLeftBottomCorner(Matrix matrix) {
Debug.DCHECK(matrix.get(matrix.height() - 8, 8) != 0);
matrix.set(matrix.height() - 8, 8, 1);
@ -480,7 +463,7 @@ public final class MatrixUtil {
// Note that we cannot unify the function with EmbedPositionDetectionPattern() despite they are
// almost identical, since we cannot write a function that takes 2D arrays in different sizes in
// C/C++. We should live with the fact.
// C/C++. We should live with the fact.
private static void EmbedPositionAdjustmentPattern(final int x_start, final int y_start,
Matrix matrix) {
// We know the width and height.
@ -507,8 +490,7 @@ public final class MatrixUtil {
}
}
// Embed position detection patterns and surrounding
// vertical/horizontal separators.
// Embed position detection patterns and surrounding vertical/horizontal separators.
private static void EmbedPositionDetectionPatternsAndSeparators(Matrix matrix) {
// Embed three big squares at corners.
final int pdp_width = arraysize(kPositionDetectionPattern[0]);
@ -557,11 +539,10 @@ public final class MatrixUtil {
if (x == -1 || y == -1) {
continue;
}
// If the cell is unset, we embed the position adjustment
// pattern here.
// If the cell is unset, we embed the position adjustment pattern here.
if (IsEmpty(matrix.get(y, x))) {
// -2 is necessary since the x/y coordinates point to the
// center of the pattern, not the left top corner.
// -2 is necessary since the x/y coordinates point to the center of the pattern, not the
// left top corner.
EmbedPositionAdjustmentPattern(x - 2, y - 2, matrix);
}
}

88
core/src/com/google/zxing/qrcode/encoder/QRCode.java
View file

@ -52,7 +52,7 @@ public final class QRCode {
private Matrix matrix_;
// They call encoding "mode". The modes are defined in 8.3 of JISX0510:2004 (p.14). It's unlikely
// They call encoding "mode". The modes are defined in 8.3 of JISX0510:2004 (p.14). It's unlikely
// (probably we will not support complicated modes) but if you add an item to this, please also
// add it to ModeToString(), GetModeCode(), GetNumBitsForLength(), Encoder.AppendBytes(), and
// Encoder.ChooseMode().
@ -121,20 +121,8 @@ public final class QRCode {
// Matrix data of the QR Code.
public final Matrix matrix() { return matrix_; }
// Return the value of the module (cell) pointed by "x" and "y" in
// the matrix of the QR Code. They call cells in the matrix
// "modules". 1 represents a black cell, and 0 represents a white
// cell.
//
// Note that the class internally used Array2D. You should access
// cells in row-major order for cache efficiency. Example:
//
// for (int y = 0; y < qrcode.matrix_width(); ++y) {
// for (int x = 0; x < qrcode.matrix_width(); ++x) {
// DoSomething(qrcode.at(x, y));
// }
// }
//
// Return the value of the module (cell) pointed by "x" and "y" in the matrix of the QR Code. They
// call cells in the matrix "modules". 1 represents a black cell, and 0 represents a white cell.
public int at(int x, int y) {
// The value must be zero or one.
int value = matrix_.get(y, x);
@ -142,7 +130,7 @@ public final class QRCode {
return value;
}
// Checks all the member variables are set properly. Returns true on success. Otherwise, returns
// Checks all the member variables are set properly. Returns true on success. Otherwise, returns
// false.
// JAVAPORT: Do not call EverythingIsBinary(matrix_) here as it is very expensive.
public boolean IsValid() {
@ -204,36 +192,68 @@ public final class QRCode {
return result.toString();
}
public void set_mode(int value) { mode_ = value; }
public void set_ec_level(int value) { ec_level_ = value; }
public void set_version(int value) { version_ = value; }
public void set_matrix_width(int value) { matrix_width_ = value; }
public void set_mask_pattern(int value) { mask_pattern_ = value; }
public void set_num_total_bytes(int value) { num_total_bytes_ = value; }
public void set_num_data_bytes(int value) { num_data_bytes_ = value; }
public void set_num_ec_bytes(int value) { num_ec_bytes_ = value; }
public void set_num_rs_blocks(int value) { num_rs_blocks_ = value; }
public void set_mode(int value) {
mode_ = value;
}
public void set_ec_level(int value) {
ec_level_ = value;
}
public void set_version(int value) {
version_ = value;
}
public void set_matrix_width(int value) {
matrix_width_ = value;
}
public void set_mask_pattern(int value) {
mask_pattern_ = value;
}
public void set_num_total_bytes(int value) {
num_total_bytes_ = value;
}
public void set_num_data_bytes(int value) {
num_data_bytes_ = value;
}
public void set_num_ec_bytes(int value) {
num_ec_bytes_ = value;
}
public void set_num_rs_blocks(int value) {
num_rs_blocks_ = value;
}
// This takes ownership of the 2D array. The 2D array will be
// deleted in the destructor of the class.
public void set_matrix(Matrix value) { matrix_ = value; }
public void set_matrix(Matrix value) {
matrix_ = value;
}
// Check if "version" is valid.
public static boolean IsValidVersion(final int version) {
return version >= kMinVersion && version <= kMaxVersion;
}
// Check if "mask_pattern" is valid.
public static boolean IsValidECLevel(int ec_level) {
return ec_level >= 0 && ec_level < NUM_EC_LEVELS;
}
// Check if "mode" is valid.
public static boolean IsValidMode(final int mode) {
return mode >= 0 && mode < NUM_MODES;
}
// Check if "width" is valid.
public static boolean IsValidMatrixWidth(int width) {
return width >= kMinMatrixWidth && width <= kMaxMatrixWidth;
}
// Check if "mask_pattern" is valid.
public static boolean IsValidMaskPattern(int mask_pattern) {
return mask_pattern >= 0 && mask_pattern < kNumMaskPatterns;
@ -277,9 +297,8 @@ public final class QRCode {
return "UNKNOWN";
}
// Return the code of error correction level. On error, return -1.
// The codes of error correction levels are defined in the table 22
// of JISX0510:2004 (p.45).
// Return the code of error correction level. On error, return -1. The codes of error correction
// levels are defined in the table 22 of JISX0510:2004 (p.45).
public static int GetECLevelCode(final int ec_level) {
switch (ec_level) {
case QRCode.EC_LEVEL_L:
@ -296,9 +315,8 @@ public final class QRCode {
return -1; // Unknown error correction level.
}
// Return the code of mode. On error, return -1.
// The codes of modes are defined in the table 2 of JISX0510:2004
// (p.16).
// Return the code of mode. On error, return -1. The codes of modes are defined in the table 2 of
// JISX0510:2004 (p.16).
public static int GetModeCode(final int mode) {
switch (mode) {
case QRCode.MODE_NUMERIC:
@ -315,8 +333,8 @@ public final class QRCode {
return -1; // Unknown mode.
}
// Return the number of bits needed for representing the length info
// of QR Code with "version" and "mode". On error, return -1.
// Return the number of bits needed for representing the length info of QR Code with "version" and
// "mode". On error, return -1.
public static int GetNumBitsForLength(int version, int mode) {
if (!IsValidVersion(version)) {
Debug.LOG_ERROR("Invalid version: " + version);

6
core/src/com/google/zxing/qrcode/encoder/Renderer.java
View file

@ -31,11 +31,11 @@ public final class Renderer {
// See 7.3.7 of JISX0510:2004 (p. 11).
private static final int kQuietZoneSize = 4;
// Render QR Code as PNG image with "cell_size". On success, store
// Render QR Code as PNG image with "cell_size". On success, store
// the result in "result" and return true. On error, return false.
// The recommended cell size for desktop screens is 3. This
// setting generates 87x87 pixels PNG image for version 1 QR Code
// (21x21). 87 = (21 + 4 + 4) * 3. 4 is for surrounding white
// (21x21). 87 = (21 + 4 + 4) * 3. 4 is for surrounding white
// space (they call it quiet zone).
// Sorry for the long function but libpng's API is a bit complecated.
// See http://www.libpng.org/pub/png/libpng-1.2.5-manual.html for
@ -117,7 +117,7 @@ public final class Renderer {
}
// Similar to RenderAsPNG but it renders QR code from data in
// "bytes" with error correction level "ec_level". This is the
// "bytes" with error correction level "ec_level". This is the
// friendliest function in the QR code library.
public static boolean RenderAsPNGFromData(final StringPiece& bytes, int ec_level, int cell_size,
String *result) {