import java.util.Vector;\r
\r
/**\r
+ * <p>This class attempts to find finder patterns in a QR Code. Finder patterns are the square\r
+ * markers at three corners of a QR Code.</p>\r
+ *\r
* <p>This class is not thread-safe and should not be reused.</p>\r
*\r
* @author srowen@google.com (Sean Owen)\r
private final Vector possibleCenters;\r
private boolean hasSkipped;\r
\r
+ /**\r
+ * <p>Creates a finder that will search the image for three finder patterns.</p>\r
+ *\r
+ * @param image image to search\r
+ */\r
FinderPatternFinder(MonochromeBitmapSource image) {\r
this.image = image;\r
this.possibleCenters = new Vector(5);\r
FinderPatternInfo find() throws ReaderException {\r
int maxI = image.getHeight();\r
int maxJ = image.getWidth();\r
- int[] stateCount = new int[5]; // looking for 1 1 3 1 1\r
+ // We are looking for black/white/black/white/black modules in\r
+ // 1:1:3:1:1 ratio; this tracks the number of such modules seen so far\r
+ int[] stateCount = new int[5];\r
boolean done = false;\r
// We can afford to examine every few lines until we've started finding\r
// the patterns\r
int iSkip = BIG_SKIP;\r
for (int i = iSkip - 1; i < maxI && !done; i += iSkip) {\r
- BitArray luminanceRow = image.getBlackRow(i, null, 0, maxJ);\r
+ // Get a row of black/white values\r
+ BitArray blackRow = image.getBlackRow(i, null, 0, maxJ);\r
stateCount[0] = 0;\r
stateCount[1] = 0;\r
stateCount[2] = 0;\r
stateCount[4] = 0;\r
int currentState = 0;\r
for (int j = 0; j < maxJ; j++) {\r
- if (luminanceRow.get(j)) {\r
+ if (blackRow.get(j)) {\r
// Black pixel\r
if ((currentState & 1) == 1) { // Counting white pixels\r
currentState++;\r
if ((currentState & 1) == 0) { // Counting black pixels\r
if (currentState == 4) { // A winner?\r
if (foundPatternCross(stateCount)) { // Yes\r
- boolean confirmed =\r
- handlePossibleCenter(stateCount, i, j);\r
+ boolean confirmed = handlePossibleCenter(stateCount, i, j);\r
if (confirmed) {\r
iSkip = 1; // Go back to examining each line\r
if (hasSkipped) {\r
// Advance to next black pixel\r
do {\r
j++;\r
- } while (j < maxJ && !luminanceRow.get(j));\r
+ } while (j < maxJ && !blackRow.get(j));\r
j--; // back up to that last white pixel\r
}\r
// Clear state to start looking again\r
totalModuleSize += patternInfo[i].getEstimatedModuleSize();\r
}\r
\r
- return new FinderPatternInfo(totalModuleSize / (float) patternInfo.length,\r
- patternInfo);\r
+ return new FinderPatternInfo(totalModuleSize / (float) patternInfo.length, patternInfo);\r
}\r
\r
+ /**\r
+ * Given a count of black/white/black/white/black pixels just seen and an end position,\r
+ * figures the location of the center of this run.\r
+ */\r
private static float centerFromEnd(int[] stateCount, int end) {\r
return (float) (end - stateCount[4] - stateCount[3]) - stateCount[2] / 2.0f;\r
}\r
\r
+ /**\r
+ * @param stateCount count of black/white/black/white/black pixels just read\r
+ * @return true iff the proportions of the counts is close enough to the 1/13/1/1 ratios\r
+ * used by finder patterns to be considered a match\r
+ */\r
private static boolean foundPatternCross(int[] stateCount) {\r
int totalModuleSize = 0;\r
for (int i = 0; i < 5; i++) {\r
}\r
int moduleSize = totalModuleSize / 7;\r
// Allow less than 50% deviance from 1-1-3-1-1 pattern\r
- return\r
- Math.abs(moduleSize - stateCount[0]) << 1 <= moduleSize &&\r
+ return Math.abs(moduleSize - stateCount[0]) << 1 <= moduleSize &&\r
Math.abs(moduleSize - stateCount[1]) << 1 <= moduleSize &&\r
Math.abs(3 * moduleSize - stateCount[2]) << 1 <= 3 * moduleSize &&\r
Math.abs(moduleSize - stateCount[3]) << 1 <= moduleSize &&\r
Math.abs(moduleSize - stateCount[4]) << 1 <= moduleSize;\r
}\r
\r
+ /**\r
+ * <p>After a horizontal scan finds a potential finder pattern, this method\r
+ * "cross-checks" by scanning down vertically through the center of the possible\r
+ * finder pattern to see if the same proportion is detected.</p>\r
+ *\r
+ * @param startI row where a finder pattern was detected\r
+ * @param centerJ center of the section that appears to cross a finder pattern\r
+ * @param maxCount maximum reasonable number of modules that should be\r
+ * observed in any reading state, based on the results of the horizontal scan\r
+ * @return vertical center of finder pattern, or {@link Float#NaN} if not found\r
+ */\r
private float crossCheckVertical(int startI, int centerJ, int maxCount) {\r
MonochromeBitmapSource image = this.image;\r
\r
int maxI = image.getHeight();\r
int[] stateCount = new int[5];\r
\r
+ // Start counting up from center\r
int i = startI;\r
while (i >= 0 && image.isBlack(centerJ, i)) {\r
stateCount[2]++;\r
return Float.NaN;\r
}\r
\r
+ // Now also count down from center\r
i = startI + 1;\r
while (i < maxI && image.isBlack(centerJ, i)) {\r
stateCount[2]++;\r
return foundPatternCross(stateCount) ? centerFromEnd(stateCount, i) : Float.NaN;\r
}\r
\r
+ /**\r
+ * <p>Like {@link #crossCheckVertical(int, int, int)}, and in fact is basically identical,\r
+ * except it reads horizontally instead of vertically. This is used to cross-cross\r
+ * check a vertical cross check and locate the real center of the alignment pattern.</p>\r
+ */\r
private float crossCheckHorizontal(int startJ, int centerI, int maxCount) {\r
MonochromeBitmapSource image = this.image;\r
\r
stateCount[1]++;\r
j--;\r
}\r
- // If already too many modules in this state or ran off the edge:\r
if (j < 0 || stateCount[1] > maxCount) {\r
return Float.NaN;\r
}\r
return foundPatternCross(stateCount) ? centerFromEnd(stateCount, j) : Float.NaN;\r
}\r
\r
+ /**\r
+ * <p>This is called when a horizontal scan finds a possible alignment pattern. It will\r
+ * cross check with a vertical scan, and if successful, will, ah, cross-cross-check\r
+ * with another horizontal scan. This is needed primarily to locate the real horizontal\r
+ * center of the pattern in cases of extreme skew.</p>\r
+ *\r
+ * <p>If that succeeds the finder pattern location is added to a list that tracks\r
+ * the number of times each location has been nearly-matched as a finder pattern.\r
+ * Each additional find is more evidence that the location is in fact a finder\r
+ * pattern center\r
+ *\r
+ * @param stateCount reading state module counts from horizontal scan\r
+ * @param i row where finder pattern may be found\r
+ * @param j end of possible finder pattern in row\r
+ * @return true if a finder pattern candidate was found this time\r
+ */\r
private boolean handlePossibleCenter(int[] stateCount,\r
int i,\r
int j) {\r
// Re-cross check\r
centerJ = crossCheckHorizontal((int) centerJ, (int) centerI, stateCount[2]);\r
if (!Float.isNaN(centerJ)) {\r
- float estimatedModuleSize = (float) (stateCount[0] +\r
- stateCount[1] +\r
- stateCount[2] +\r
- stateCount[3] +\r
- stateCount[4]) / 7.0f;\r
+ float estimatedModuleSize =\r
+ (float) (stateCount[0] + stateCount[1] + stateCount[2] + stateCount[3] + stateCount[4]) / 7.0f;\r
boolean found = false;\r
int max = possibleCenters.size();\r
for (int index = 0; index < max; index++) {\r
}\r
}\r
if (!found) {\r
- possibleCenters.addElement(\r
- new FinderPattern(centerJ, centerI, estimatedModuleSize));\r
+ possibleCenters.addElement(new FinderPattern(centerJ, centerI, estimatedModuleSize));\r
}\r
return true;\r
}\r
return false;\r
}\r
\r
+ /**\r
+ * @return number of rows we could safely skip during scanning, based on the first\r
+ * two finder patterns that have been located. In some cases their position will\r
+ * allow us to infer that the third pattern must lie below a certain point farther\r
+ * down in the image.\r
+ */\r
private int findRowSkip() {\r
int max = possibleCenters.size();\r
if (max <= 1) {\r
return 0;\r
}\r
\r
+ /**\r
+ * @return true iff we have found at least 3 finder patterns that have been detected\r
+ * at least {@link #CENTER_QUORUM} times each\r
+ */\r
private boolean haveMulitplyConfirmedCenters() {\r
int count = 0;\r
int max = possibleCenters.size();\r
return false;\r
}\r
\r
+ /**\r
+ * @return the 3 best {@link FinderPattern}s from our list of candidates. The "best" are\r
+ * those that have been detected at least {@link #CENTER_QUORUM} times, and whose module\r
+ * size differs from the average among those patterns the least\r
+ * @throws ReaderException if 3 such finder patterns do not exist\r
+ */\r
private FinderPattern[] selectBestPatterns() throws ReaderException {\r
Collections.insertionSort(possibleCenters, new CenterComparator());\r
int size = 0;\r
}\r
averageModuleSize /= (float) size;\r
\r
- Collections.insertionSort(\r
- possibleCenters,\r
- new ClosestToAverageComparator(averageModuleSize));\r
+ // We don't have java.util.Collections in J2ME\r
+ Collections.insertionSort(possibleCenters, new ClosestToAverageComparator(averageModuleSize));\r
\r
- //return confirmedCenters.subList(0, 3).toArray(new FinderPattern[3]);\r
FinderPattern[] result = new FinderPattern[3];\r
for (int i = 0; i < 3; i++) {\r
result[i] = (FinderPattern) possibleCenters.elementAt(i);\r
return result;\r
}\r
\r
+ /**\r
+ * <p>Having found three "best" finder patterns we need to decide which is the top-left, top-right,\r
+ * bottom-left. We assume that the one closest to the other two is the top-left one; this is not\r
+ * strictly true (imagine extreme perspective distortion) but for the moment is a serviceable assumption.\r
+ * Lastly we sort top-right from bottom-left by figuring out orientation from vector cross products.</p>\r
+ *\r
+ * @param patterns three best {@link FinderPattern}s\r
+ * @return same {@link FinderPattern}s ordered bottom-left, top-left, top-right\r
+ */\r
private static FinderPattern[] orderBestPatterns(FinderPattern[] patterns) {\r
\r
// Find distances between pattern centers\r
FinderPattern topLeft;\r
FinderPattern topRight;\r
FinderPattern bottomLeft;\r
- // Assume one closest to other two is top left\r
+ // Assume one closest to other two is top left;\r
+ // topRight and bottomLeft will just be guesses below at first\r
if (bcDistance >= abDistance && bcDistance >= acDistance) {\r
topLeft = patterns[0];\r
- topRight = patterns[1]; // These two are guesses at the moment\r
+ topRight = patterns[1];\r
bottomLeft = patterns[2];\r
} else if (acDistance >= bcDistance && acDistance >= abDistance) {\r
topLeft = patterns[1];\r
return new FinderPattern[]{bottomLeft, topLeft, topRight};\r
}\r
\r
+ /**\r
+ * @return distance between two points\r
+ */\r
static float distance(ResultPoint pattern1, ResultPoint pattern2) {\r
float xDiff = pattern1.getX() - pattern2.getX();\r
float yDiff = pattern1.getY() - pattern2.getY();\r
return (float) Math.sqrt((double) (xDiff * xDiff + yDiff * yDiff));\r
}\r
\r
+ /**\r
+ * <p>Orders by {@link FinderPattern#getCount()}, descending.</p>\r
+ */\r
private static class CenterComparator implements Comparator {\r
public int compare(Object center1, Object center2) {\r
return ((FinderPattern) center2).getCount() - ((FinderPattern) center1).getCount();\r
}\r
}\r
\r
+ /**\r
+ * <p>Orders by variance from average module size, ascending.</p>\r
+ */\r
private static class ClosestToAverageComparator implements Comparator {\r
private float averageModuleSize;\r
\r
projects / zxing.git / blobdiff