tesseract  5.0.0-alpha-619-ge9db
ltrresultiterator.h
Go to the documentation of this file.
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 //
7 // (C) Copyright 2010, Google Inc.
8 // Licensed under the Apache License, Version 2.0 (the "License");
9 // you may not use this file except in compliance with the License.
10 // You may obtain a copy of the License at
11 // http://www.apache.org/licenses/LICENSE-2.0
12 // Unless required by applicable law or agreed to in writing, software
13 // distributed under the License is distributed on an "AS IS" BASIS,
14 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
15 // See the License for the specific language governing permissions and
16 // limitations under the License.
17 //
19 
20 #ifndef TESSERACT_CCMAIN_LTR_RESULT_ITERATOR_H_
21 #define TESSERACT_CCMAIN_LTR_RESULT_ITERATOR_H_
22 
23 #include "pageiterator.h" // for PageIterator
24 #include "platform.h" // for TESS_API
25 #include "publictypes.h" // for PageIteratorLevel
26 #include "unichar.h" // for StrongScriptDirection
27 
28 class BLOB_CHOICE_IT;
29 class PAGE_RES;
30 class WERD_RES;
31 
32 namespace tesseract {
33 
34 class Tesseract;
35 
36 // Class to iterate over tesseract results, providing access to all levels
37 // of the page hierarchy, without including any tesseract headers or having
38 // to handle any tesseract structures.
39 // WARNING! This class points to data held within the TessBaseAPI class, and
40 // therefore can only be used while the TessBaseAPI class still exists and
41 // has not been subjected to a call of Init, SetImage, Recognize, Clear, End
42 // DetectOS, or anything else that changes the internal PAGE_RES.
43 // See apitypes.h for the definition of PageIteratorLevel.
44 // See also base class PageIterator, which contains the bulk of the interface.
45 // LTRResultIterator adds text-specific methods for access to OCR output.
46 
48  friend class ChoiceIterator;
49 
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.
63  LTRResultIterator(PAGE_RES* page_res, Tesseract* tesseract, int scale,
64  int scaled_yres, int rect_left, int rect_top,
65  int rect_width, int rect_height);
66 
67  ~LTRResultIterator() override;
68 
69  // LTRResultIterators may be copied! This makes it possible to iterate over
70  // all the objects at a lower level, while maintaining an iterator to
71  // objects at a higher level. These constructors DO NOT CALL Begin, so
72  // iterations will continue from the location of src.
73  // TODO: For now the copy constructor and operator= only need the base class
74  // versions, but if new data members are added, don't forget to add them!
75 
76  // ============= Moving around within the page ============.
77 
78  // See PageIterator.
79 
80  // ============= Accessing data ==============.
81 
82  // Returns the null terminated UTF-8 encoded text string for the current
83  // object at the given level. Use delete [] to free after use.
84  char* GetUTF8Text(PageIteratorLevel level) const;
85 
86  // Set the string inserted at the end of each text line. "\n" by default.
87  void SetLineSeparator(const char* new_line);
88 
89  // Set the string inserted at the end of each paragraph. "\n" by default.
90  void SetParagraphSeparator(const char* new_para);
91 
92  // Returns the mean confidence of the current object at the given level.
93  // The number should be interpreted as a percent probability. (0.0f-100.0f)
94  float Confidence(PageIteratorLevel level) const;
95 
96  // Returns the attributes of the current row.
97  void RowAttributes(float* row_height, float* descenders,
98  float* ascenders) const;
99 
100  // ============= Functions that refer to words only ============.
101 
102  // Returns the font attributes of the current word. If iterating at a higher
103  // level object than words, eg textlines, then this will return the
104  // attributes of the first word in that textline.
105  // The actual return value is a string representing a font name. It points
106  // to an internal table and SHOULD NOT BE DELETED. Lifespan is the same as
107  // the iterator itself, ie rendered invalid by various members of
108  // TessBaseAPI, including Init, SetImage, End or deleting the TessBaseAPI.
109  // Pointsize is returned in printers points (1/72 inch.)
110  const char* WordFontAttributes(bool* is_bold, bool* is_italic,
111  bool* is_underlined, bool* is_monospace,
112  bool* is_serif, bool* is_smallcaps,
113  int* pointsize, int* font_id) const;
114 
115  // Return the name of the language used to recognize this word.
116  // On error, nullptr. Do not delete this pointer.
117  const char* WordRecognitionLanguage() const;
118 
119  // Return the overall directionality of this word.
120  StrongScriptDirection WordDirection() const;
121 
122  // Returns true if the current word was found in a dictionary.
123  bool WordIsFromDictionary() const;
124 
125  // Returns the number of blanks before the current word.
126  int BlanksBeforeWord() const;
127 
128  // Returns true if the current word is numeric.
129  bool WordIsNumeric() const;
130 
131  // Returns true if the word contains blamer information.
132  bool HasBlamerInfo() const;
133 
134  // Returns the pointer to ParamsTrainingBundle stored in the BlamerBundle
135  // of the current word.
136  const void* GetParamsTrainingBundle() const;
137 
138  // Returns a pointer to the string with blamer information for this word.
139  // Assumes that the word's blamer_bundle is not nullptr.
140  const char* GetBlamerDebug() const;
141 
142  // Returns a pointer to the string with misadaption information for this word.
143  // Assumes that the word's blamer_bundle is not nullptr.
144  const char* GetBlamerMisadaptionDebug() const;
145 
146  // Returns true if a truth string was recorded for the current word.
147  bool HasTruthString() const;
148 
149  // Returns true if the given string is equivalent to the truth string for
150  // the current word.
151  bool EquivalentToTruth(const char* str) const;
152 
153  // Returns a null terminated UTF-8 encoded truth string for the current word.
154  // Use delete [] to free after use.
155  char* WordTruthUTF8Text() const;
156 
157  // Returns a null terminated UTF-8 encoded normalized OCR string for the
158  // current word. Use delete [] to free after use.
159  char* WordNormedUTF8Text() const;
160 
161  // Returns a pointer to serialized choice lattice.
162  // Fills lattice_size with the number of bytes in lattice data.
163  const char* WordLattice(int* lattice_size) const;
164 
165  // ============= Functions that refer to symbols only ============.
166 
167  // Returns true if the current symbol is a superscript.
168  // If iterating at a higher level object than symbols, eg words, then
169  // this will return the attributes of the first symbol in that word.
170  bool SymbolIsSuperscript() const;
171  // Returns true if the current symbol is a subscript.
172  // If iterating at a higher level object than symbols, eg words, then
173  // this will return the attributes of the first symbol in that word.
174  bool SymbolIsSubscript() const;
175  // Returns true if the current symbol is a dropcap.
176  // If iterating at a higher level object than symbols, eg words, then
177  // this will return the attributes of the first symbol in that word.
178  bool SymbolIsDropcap() const;
179 
180  protected:
181  const char* line_separator_;
182  const char* paragraph_separator_;
183 };
184 
185 // Class to iterate over the classifier choices for a single RIL_SYMBOL.
187  public:
188  // Construction is from a LTRResultIterator that points to the symbol of
189  // interest. The ChoiceIterator allows a one-shot iteration over the
190  // choices for this symbol and after that is is useless.
191  explicit ChoiceIterator(const LTRResultIterator& result_it);
192  ~ChoiceIterator();
193 
194  // Moves to the next choice for the symbol and returns false if there
195  // are none left.
196  bool Next();
197 
198  // ============= Accessing data ==============.
199 
200  // Returns the null terminated UTF-8 encoded text string for the current
201  // choice.
202  // NOTE: Unlike LTRResultIterator::GetUTF8Text, the return points to an
203  // internal structure and should NOT be delete[]ed to free after use.
204  const char* GetUTF8Text() const;
205 
206  // Returns the confidence of the current choice depending on the used language
207  // data. If only LSTM traineddata is used the value range is 0.0f - 1.0f. All
208  // choices for one symbol should roughly add up to 1.0f.
209  // If only traineddata of the legacy engine is used, the number should be
210  // interpreted as a percent probability. (0.0f-100.0f) In this case
211  // probabilities won't add up to 100. Each one stands on its own.
212  float Confidence() const;
213 
214  // Returns a vector containing all timesteps, which belong to the currently
215  // selected symbol. A timestep is a vector containing pairs of symbols and
216  // floating point numbers. The number states the probability for the
217  // corresponding symbol.
218  std::vector<std::vector<std::pair<const char*, float>>>* Timesteps() const;
219 
220  private:
221  // clears the remaining spaces out of the results and adapt the probabilities
222  void filterSpaces();
223  // Pointer to the WERD_RES object owned by the API.
224  WERD_RES* word_res_;
225  // Iterator over the blob choices.
226  BLOB_CHOICE_IT* choice_it_;
227  std::vector<std::pair<const char*, float>>* LSTM_choices_ = nullptr;
228  std::vector<std::pair<const char*, float>>::iterator LSTM_choice_it_;
229 
230  const int* tstep_index_;
231  // regulates the rating granularity
232  double rating_coefficient_;
233  // leading blanks
234  int blanks_before_word_;
235  // true when there is lstm engine related trained data
236  bool oemLSTM_;
237 };
238 
239 } // namespace tesseract.
240 
241 #endif // TESSERACT_CCMAIN_LTR_RESULT_ITERATOR_H_
tesseract::ChoiceIterator
Definition: ltrresultiterator.h:186
tesseract::Tesseract
Definition: tesseractclass.h:172
tesseract::ChoiceIterator::Timesteps
std::vector< std::vector< std::pair< const char *, float > > > * Timesteps() const
Definition: ltrresultiterator.cpp:470
tesseract::PageIterator
Definition: pageiterator.h:52
StrongScriptDirection
StrongScriptDirection
Definition: unichar.h:43
platform.h
WERD_RES
Definition: pageres.h:160
tesseract::ChoiceIterator::~ChoiceIterator
~ChoiceIterator()
Definition: ltrresultiterator.cpp:412
tesseract::LTRResultIterator::line_separator_
const char * line_separator_
Definition: ltrresultiterator.h:181
tesseract::LTRResultIterator
Definition: ltrresultiterator.h:47
tesseract::LTRResultIterator::paragraph_separator_
const char * paragraph_separator_
Definition: ltrresultiterator.h:182
tesseract::ChoiceIterator::Confidence
float Confidence() const
Definition: ltrresultiterator.cpp:455
publictypes.h
tesseract::PageIteratorLevel
PageIteratorLevel
Definition: publictypes.h:216
pageiterator.h
tesseract
Definition: baseapi.h:65
PAGE_RES
Definition: pageres.h:73
tesseract::ChoiceIterator::GetUTF8Text
const char * GetUTF8Text() const
Definition: ltrresultiterator.cpp:437
unichar.h
TESS_API
#define TESS_API
Definition: platform.h:54
tesseract::ChoiceIterator::Next
bool Next()
Definition: ltrresultiterator.cpp:418
tesseract::ChoiceIterator::ChoiceIterator
ChoiceIterator(const LTRResultIterator &result_it)
Definition: ltrresultiterator.cpp:376