tesseract
3.03
|
00001 00002 // File: detlinefit.h 00003 // Description: Deterministic least upper-quartile squares line fitting. 00004 // Author: Ray Smith 00005 // Created: Thu Feb 28 14:35:01 PDT 2008 00006 // 00007 // (C) Copyright 2008, Google Inc. 00008 // Licensed under the Apache License, Version 2.0 (the "License"); 00009 // you may not use this file except in compliance with the License. 00010 // You may obtain a copy of the License at 00011 // http://www.apache.org/licenses/LICENSE-2.0 00012 // Unless required by applicable law or agreed to in writing, software 00013 // distributed under the License is distributed on an "AS IS" BASIS, 00014 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 00015 // See the License for the specific language governing permissions and 00016 // limitations under the License. 00017 // 00019 00020 #ifndef TESSERACT_CCSTRUCT_DETLINEFIT_H_ 00021 #define TESSERACT_CCSTRUCT_DETLINEFIT_H_ 00022 00023 #include "genericvector.h" 00024 #include "kdpair.h" 00025 #include "points.h" 00026 00027 namespace tesseract { 00028 00029 // This class fits a line to a set of ICOORD points. 00030 // There is no restriction on the direction of the line, as it 00031 // uses a vector method, ie no concern over infinite gradients. 00032 // The fitted line has the least upper quartile of squares of perpendicular 00033 // distances of all source points from the line, subject to the constraint 00034 // that the line is made from one of the pairs of [{p1,p2,p3},{pn-2, pn-1, pn}] 00035 // i.e. the 9 combinations of one of the first 3 and last 3 points. 00036 // A fundamental assumption of this algorithm is that one of the first 3 and 00037 // one of the last 3 points are near the best line fit. 00038 // The points must be Added in line order for the algorithm to work properly. 00039 // No floating point calculations are needed* to make an accurate fit, 00040 // and no random numbers are needed** so the algorithm is deterministic, 00041 // architecture-stable, and compiler-stable as well as stable to minor 00042 // changes in the input. 00043 // *A single floating point division is used to compute each line's distance. 00044 // This is unlikely to result in choice of a different line, but if it does, 00045 // it would be easy to replace with a 64 bit integer calculation. 00046 // **Random numbers are used in the nth_item function, but the worst 00047 // non-determinism that can result is picking a different result among equals, 00048 // and that wouldn't make any difference to the end-result distance, so the 00049 // randomness does not affect the determinism of the algorithm. The random 00050 // numbers are only there to guarantee average linear time. 00051 // Fitting time is linear, but with a high constant, as it tries 9 different 00052 // lines and computes the distance of all points each time. 00053 // This class is aimed at replacing the LLSQ (linear least squares) and 00054 // LMS (least median of squares) classes that are currently used for most 00055 // of the line fitting in Tesseract. 00056 class DetLineFit { 00057 public: 00058 DetLineFit(); 00059 ~DetLineFit(); 00060 00061 // Delete all Added points. 00062 void Clear(); 00063 00064 // Adds a new point. Takes a copy - the pt doesn't need to stay in scope. 00065 // Add must be called on points in sequence along the line. 00066 void Add(const ICOORD& pt); 00067 // Associates a half-width with the given point if a point overlaps the 00068 // previous point by more than half the width, and its distance is further 00069 // than the previous point, then the more distant point is ignored in the 00070 // distance calculation. Useful for ignoring i dots and other diacritics. 00071 void Add(const ICOORD& pt, int halfwidth); 00072 00073 // Fits a line to the points, returning the fitted line as a pair of 00074 // points, and the upper quartile error. 00075 double Fit(ICOORD* pt1, ICOORD* pt2) { 00076 return Fit(0, 0, pt1, pt2); 00077 } 00078 // Fits a line to the points, ignoring the skip_first initial points and the 00079 // skip_last final points, returning the fitted line as a pair of points, 00080 // and the upper quartile error. 00081 double Fit(int skip_first, int skip_last, ICOORD* pt1, ICOORD* pt2); 00082 00083 // Constrained fit with a supplied direction vector. Finds the best line_pt, 00084 // that is one of the supplied points having the median cross product with 00085 // direction, ignoring points that have a cross product outside of the range 00086 // [min_dist, max_dist]. Returns the resulting error metric using the same 00087 // reduced set of points. 00088 // *Makes use of floating point arithmetic* 00089 double ConstrainedFit(const FCOORD& direction, 00090 double min_dist, double max_dist, 00091 bool debug, ICOORD* line_pt); 00092 00093 // Returns true if there were enough points at the last call to Fit or 00094 // ConstrainedFit for the fitted points to be used on a badly fitted line. 00095 bool SufficientPointsForIndependentFit() const; 00096 00097 // Backwards compatible fit returning a gradient and constant. 00098 // Deprecated. Prefer Fit(ICOORD*, ICOORD*) where possible, but use this 00099 // function in preference to the LMS class. 00100 double Fit(float* m, float* c); 00101 00102 // Backwards compatible constrained fit with a supplied gradient. 00103 // Deprecated. Use ConstrainedFit(const FCOORD& direction) where possible 00104 // to avoid potential difficulties with infinite gradients. 00105 double ConstrainedFit(double m, float* c); 00106 00107 private: 00108 // Simple struct to hold an ICOORD point and a halfwidth representing half 00109 // the "width" (supposedly approximately parallel to the direction of the 00110 // line) of each point, such that distant points can be discarded when they 00111 // overlap nearer points. (Think i dot and other diacritics or noise.) 00112 struct PointWidth { 00113 PointWidth() : pt(ICOORD(0, 0)), halfwidth(0) {} 00114 PointWidth(const ICOORD& pt0, int halfwidth0) 00115 : pt(pt0), halfwidth(halfwidth0) {} 00116 00117 ICOORD pt; 00118 int halfwidth; 00119 }; 00120 // Type holds the distance of each point from the fitted line and the point 00121 // itself. Use of double allows integer distances from ICOORDs to be stored 00122 // exactly, and also the floating point results from ConstrainedFit. 00123 typedef KDPairInc<double, ICOORD> DistPointPair; 00124 00125 // Computes and returns the squared evaluation metric for a line fit. 00126 double EvaluateLineFit(); 00127 00128 // Computes the absolute values of the precomputed distances_, 00129 // and returns the squared upper-quartile error distance. 00130 double ComputeUpperQuartileError(); 00131 00132 // Returns the number of sample points that have an error more than threshold. 00133 int NumberOfMisfittedPoints(double threshold) const; 00134 00135 // Computes all the cross product distances of the points from the line, 00136 // storing the actual (signed) cross products in distances_. 00137 // Ignores distances of points that are further away than the previous point, 00138 // and overlaps the previous point by at least half. 00139 void ComputeDistances(const ICOORD& start, const ICOORD& end); 00140 00141 // Computes all the cross product distances of the points perpendicular to 00142 // the given direction, ignoring distances outside of the give distance range, 00143 // storing the actual (signed) cross products in distances_. 00144 void ComputeConstrainedDistances(const FCOORD& direction, 00145 double min_dist, double max_dist); 00146 00147 // Stores all the source points in the order they were given and their 00148 // halfwidths, if any. 00149 GenericVector<PointWidth> pts_; 00150 // Stores the computed perpendicular distances of (some of) the pts_ from a 00151 // given vector (assuming it goes through the origin, making it a line). 00152 // Since the distances may be a subset of the input points, and get 00153 // re-ordered by the nth_item function, the original point is stored 00154 // along side the distance. 00155 GenericVector<DistPointPair> distances_; // Distances of points. 00156 // The squared length of the vector used to compute distances_. 00157 double square_length_; 00158 }; 00159 00160 } // namespace tesseract. 00161 00162 #endif // TESSERACT_CCSTRUCT_DETLINEFIT_H_ 00163 00164