tesseract  3.03
/usr/local/google/home/jbreiden/tesseract-ocr-read-only/ccstruct/detlinefit.h
Go to the documentation of this file.
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 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines