tesseract  v4.0.0-17-g361f3264
Open Source OCR Engine
ltrresultiterator.h
1 // File: ltrresultiterator.h
3 // Description: Iterator for tesseract results in strict left-to-right
4 // order that avoids using tesseract internal data structures.
5 // Author: Ray Smith
6 // Created: Fri Feb 26 11:01:06 PST 2010
7 //
8 // (C) Copyright 2010, Google Inc.
9 // Licensed under the Apache License, Version 2.0 (the "License");
10 // you may not use this file except in compliance with the License.
11 // You may obtain a copy of the License at
12 // http://www.apache.org/licenses/LICENSE-2.0
13 // Unless required by applicable law or agreed to in writing, software
14 // distributed under the License is distributed on an "AS IS" BASIS,
15 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
16 // See the License for the specific language governing permissions and
17 // limitations under the License.
18 //
20 
21 #ifndef TESSERACT_CCMAIN_LTR_RESULT_ITERATOR_H_
22 #define TESSERACT_CCMAIN_LTR_RESULT_ITERATOR_H_
23 
24 #include "pageiterator.h" // for PageIterator
25 #include "platform.h" // for TESS_API
26 #include "publictypes.h" // for PageIteratorLevel
27 #include "unichar.h" // for StrongScriptDirection
28 
29 class BLOB_CHOICE_IT;
30 class PAGE_RES;
31 class WERD_RES;
32 
33 namespace tesseract {
34 
35 class Tesseract;
36 
37 // Class to iterate over tesseract results, providing access to all levels
38 // of the page hierarchy, without including any tesseract headers or having
39 // to handle any tesseract structures.
40 // WARNING! This class points to data held within the TessBaseAPI class, and
41 // therefore can only be used while the TessBaseAPI class still exists and
42 // has not been subjected to a call of Init, SetImage, Recognize, Clear, End
43 // DetectOS, or anything else that changes the internal PAGE_RES.
44 // See apitypes.h for the definition of PageIteratorLevel.
45 // See also base class PageIterator, which contains the bulk of the interface.
46 // LTRResultIterator adds text-specific methods for access to OCR output.
47 
48 class TESS_API LTRResultIterator : public PageIterator {
49  friend class ChoiceIterator;
50  public:
51  // page_res and tesseract come directly from the BaseAPI.
52  // The rectangle parameters are copied indirectly from the Thresholder,
53  // via the BaseAPI. They represent the coordinates of some rectangle in an
54  // original image (in top-left-origin coordinates) and therefore the top-left
55  // needs to be added to any output boxes in order to specify coordinates
56  // in the original image. See TessBaseAPI::SetRectangle.
57  // The scale and scaled_yres are in case the Thresholder scaled the image
58  // rectangle prior to thresholding. Any coordinates in tesseract's image
59  // must be divided by scale before adding (rect_left, rect_top).
60  // The scaled_yres indicates the effective resolution of the binary image
61  // that tesseract has been given by the Thresholder.
62  // After the constructor, Begin has already been called.
64  int scale, int scaled_yres,
65  int rect_left, int rect_top,
66  int rect_width, int rect_height);
67 
68  virtual ~LTRResultIterator();
69 
70  // LTRResultIterators may be copied! This makes it possible to iterate over
71  // all the objects at a lower level, while maintaining an iterator to
72  // objects at a higher level. These constructors DO NOT CALL Begin, so
73  // iterations will continue from the location of src.
74  // TODO: For now the copy constructor and operator= only need the base class
75  // versions, but if new data members are added, don't forget to add them!
76 
77  // ============= Moving around within the page ============.
78 
79  // See PageIterator.
80 
81  // ============= Accessing data ==============.
82 
83  // Returns the null terminated UTF-8 encoded text string for the current
84  // object at the given level. Use delete [] to free after use.
85  char* GetUTF8Text(PageIteratorLevel level) const;
86 
87  // Set the string inserted at the end of each text line. "\n" by default.
88  void SetLineSeparator(const char *new_line);
89 
90  // Set the string inserted at the end of each paragraph. "\n" by default.
91  void SetParagraphSeparator(const char *new_para);
92 
93  // Returns the mean confidence of the current object at the given level.
94  // The number should be interpreted as a percent probability. (0.0f-100.0f)
95  float Confidence(PageIteratorLevel level) const;
96 
97  // Returns the attributes of the current row.
98  void RowAttributes(float* row_height, float* descenders,
99  float* ascenders) const;
100 
101  // ============= Functions that refer to words only ============.
102 
103  // Returns the font attributes of the current word. If iterating at a higher
104  // level object than words, eg textlines, then this will return the
105  // attributes of the first word in that textline.
106  // The actual return value is a string representing a font name. It points
107  // to an internal table and SHOULD NOT BE DELETED. Lifespan is the same as
108  // the iterator itself, ie rendered invalid by various members of
109  // TessBaseAPI, including Init, SetImage, End or deleting the TessBaseAPI.
110  // Pointsize is returned in printers points (1/72 inch.)
111  const char* WordFontAttributes(bool* is_bold,
112  bool* is_italic,
113  bool* is_underlined,
114  bool* is_monospace,
115  bool* is_serif,
116  bool* is_smallcaps,
117  int* pointsize,
118  int* font_id) const;
119 
120  // Return the name of the language used to recognize this word.
121  // On error, nullptr. Do not delete this pointer.
122  const char* WordRecognitionLanguage() const;
123 
124  // Return the overall directionality of this word.
125  StrongScriptDirection WordDirection() const;
126 
127  // Returns true if the current word was found in a dictionary.
128  bool WordIsFromDictionary() const;
129 
130  // Returns the number of blanks before the current word.
131  int BlanksBeforeWord() const;
132 
133  // Returns true if the current word is numeric.
134  bool WordIsNumeric() const;
135 
136  // Returns true if the word contains blamer information.
137  bool HasBlamerInfo() const;
138 
139  // Returns the pointer to ParamsTrainingBundle stored in the BlamerBundle
140  // of the current word.
141  const void *GetParamsTrainingBundle() const;
142 
143  // Returns a pointer to the string with blamer information for this word.
144  // Assumes that the word's blamer_bundle is not nullptr.
145  const char *GetBlamerDebug() const;
146 
147  // Returns a pointer to the string with misadaption information for this word.
148  // Assumes that the word's blamer_bundle is not nullptr.
149  const char *GetBlamerMisadaptionDebug() const;
150 
151  // Returns true if a truth string was recorded for the current word.
152  bool HasTruthString() const;
153 
154  // Returns true if the given string is equivalent to the truth string for
155  // the current word.
156  bool EquivalentToTruth(const char *str) const;
157 
158  // Returns a null terminated UTF-8 encoded truth string for the current word.
159  // Use delete [] to free after use.
160  char* WordTruthUTF8Text() const;
161 
162  // Returns a null terminated UTF-8 encoded normalized OCR string for the
163  // current word. Use delete [] to free after use.
164  char* WordNormedUTF8Text() const;
165 
166  // Returns a pointer to serialized choice lattice.
167  // Fills lattice_size with the number of bytes in lattice data.
168  const char *WordLattice(int *lattice_size) const;
169 
170  // ============= Functions that refer to symbols only ============.
171 
172  // Returns true if the current symbol is a superscript.
173  // If iterating at a higher level object than symbols, eg words, then
174  // this will return the attributes of the first symbol in that word.
175  bool SymbolIsSuperscript() const;
176  // Returns true if the current symbol is a subscript.
177  // If iterating at a higher level object than symbols, eg words, then
178  // this will return the attributes of the first symbol in that word.
179  bool SymbolIsSubscript() const;
180  // Returns true if the current symbol is a dropcap.
181  // If iterating at a higher level object than symbols, eg words, then
182  // this will return the attributes of the first symbol in that word.
183  bool SymbolIsDropcap() const;
184 
185  protected:
186  const char *line_separator_;
187  const char *paragraph_separator_;
188 };
189 
190 // Class to iterate over the classifier choices for a single RIL_SYMBOL.
192  public:
193  // Construction is from a LTRResultIterator that points to the symbol of
194  // interest. The ChoiceIterator allows a one-shot iteration over the
195  // choices for this symbol and after that is is useless.
196  explicit ChoiceIterator(const LTRResultIterator& result_it);
197  ~ChoiceIterator();
198 
199  // Moves to the next choice for the symbol and returns false if there
200  // are none left.
201  bool Next();
202 
203  // ============= Accessing data ==============.
204 
205  // Returns the null terminated UTF-8 encoded text string for the current
206  // choice.
207  // NOTE: Unlike LTRResultIterator::GetUTF8Text, the return points to an
208  // internal structure and should NOT be delete[]ed to free after use.
209  const char* GetUTF8Text() const;
210 
211  // Returns the confidence of the current choice.
212  // The number should be interpreted as a percent probability. (0.0f-100.0f)
213  float Confidence() const;
214 
215  private:
216  // Pointer to the WERD_RES object owned by the API.
218  // Iterator over the blob choices.
219  BLOB_CHOICE_IT* choice_it_;
220 };
221 
222 } // namespace tesseract.
223 
224 #endif // TESSERACT_CCMAIN_LTR_RESULT_ITERATOR_H_
Definition: baseapi.cpp:94
PageIteratorLevel
Definition: publictypes.h:219
BLOB_CHOICE_IT * choice_it_
Definition: ltrresultiterator.h:219
Definition: ltrresultiterator.h:191
Definition: ltrresultiterator.h:48
Definition: pageres.h:169
Definition: tesseractclass.h:173
Definition: pageres.h:77
const char * line_separator_
Definition: ltrresultiterator.h:186
Definition: pageiterator.h:52
WERD_RES * word_res_
Definition: ltrresultiterator.h:217
const char * paragraph_separator_
Definition: ltrresultiterator.h:187