Tesseract  3.02
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
cube_object.h
Go to the documentation of this file.
1 /**********************************************************************
2  * File: cube_object.h
3  * Description: Declaration of the Cube Object Class
4  * Author: Ahmad Abdulkader
5  * Created: 2007
6  *
7  * (C) Copyright 2008, 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  *
18  **********************************************************************/
19 
20 // The CubeObject class is the main class used to perform recognition of
21 // a specific char_samp as a single word.
22 // To recognize a word, a CubeObject is constructed for this word.
23 // A Call to RecognizeWord is then issued specifying the language model that
24 // will be used during recognition. If none is specified, the default language
25 // model in the CubeRecoContext is used. The CubeRecoContext is passed at
26 // construction time
27 //
28 // The typical usage pattern for Cube is shown below:
29 //
30 // // Create and initialize Tesseract object and get its
31 // // CubeRecoContext object (note that Tesseract object owns it,
32 // // so it will be freed when the Tesseract object is freed).
33 // tesseract::Tesseract *tess_obj = new tesseract::Tesseract();
34 // tess_obj->init_tesseract(data_path, lang, tesseract::OEM_CUBE_ONLY);
35 // CubeRecoContext *cntxt = tess_obj->GetCubeRecoContext();
36 // CHECK(cntxt != NULL) << "Unable to create a Cube reco context";
37 // .
38 // .
39 // .
40 // // Do this to recognize a word in pix whose co-ordinates are
41 // // (left,top,width,height)
42 // tesseract::CubeObject *cube_obj;
43 // cube_obj = new tesseract::CubeObject(cntxt, pix,
44 // left, top, width, height);
45 //
46 // // Get back Cube's list of answers
47 // tesseract::WordAltList *alt_list = cube_obj->RecognizeWord();
48 // CHECK(alt_list != NULL && alt_list->AltCount() > 0);
49 //
50 // // Get the string and cost of every alternate
51 // for (int alt = 0; alt < alt_list->AltCount(); alt++) {
52 // // Return the result as a UTF-32 string
53 // string_32 res_str32 = alt_list->Alt(alt);
54 // // Convert to UTF8 if need-be
55 // string res_str;
56 // CubeUtils::UTF32ToUTF8(res_str32.c_str(), &res_str);
57 // // Get the string cost. This should get bigger as you go deeper
58 // // in the list
59 // int cost = alt_list->AltCost(alt);
60 // }
61 //
62 // // Call this once you are done recognizing this word
63 // delete cube_obj;
64 //
65 // // Call this once you are done recognizing all words with
66 // // for the current language
67 // delete tess_obj;
68 //
69 // Note that if the language supports "Italics" (see the CubeRecoContext), the
70 // RecognizeWord function attempts to de-slant the word.
71 
72 #ifndef CUBE_OBJECT_H
73 #define CUBE_OBJECT_H
74 
75 #include "img.h"
76 #include "char_samp.h"
77 #include "word_altlist.h"
78 #include "beam_search.h"
79 #include "cube_search_object.h"
80 #include "tess_lang_model.h"
81 #include "cube_reco_context.h"
82 
83 namespace tesseract {
84 
85 // minimum aspect ratio needed to normalize a char_samp before recognition
86 static const float kMinNormalizationAspectRatio = 3.5;
87 // minimum probability a top alt choice must meet before having
88 // deslanted processing applied to it
89 static const float kMinProbSkipDeslanted = 0.25;
90 
91 class CubeObject {
92  public:
93  // Different flavors of constructor. They just differ in the way the
94  // word image is specified
95  CubeObject(CubeRecoContext *cntxt, CharSamp *char_samp);
96  CubeObject(CubeRecoContext *cntxt, IMAGE *img,
97  int left, int top, int wid, int hgt);
98  CubeObject(CubeRecoContext *cntxt, Pix *pix,
99  int left, int top, int wid, int hgt);
100  ~CubeObject();
101 
102  // Perform the word recognition using the specified language mode. If none
103  // is specified, the default language model in the CubeRecoContext is used.
104  // Returns the sorted list of alternate word answers
105  WordAltList *RecognizeWord(LangModel *lang_mod = NULL);
106  // Same as RecognizeWord but recognizes as a phrase
108  // Computes the cost of a specific string. This is done by performing
109  // recognition of a language model that allows only the specified word.
110  // The alternate list(s) will be permanently modified.
111  int WordCost(const char *str);
112  // Recognizes a single character and returns the list of results.
114 
115  // Returns the BeamSearch object that resulted from the last call to
116  // RecognizeWord
117  inline BeamSearch *BeamObj() const {
118  return (deslanted_ == true ? deslanted_beam_obj_ : beam_obj_);
119  }
120  // Returns the WordAltList object that resulted from the last call to
121  // RecognizeWord
122  inline WordAltList *AlternateList() const {
123  return (deslanted_ == true ? deslanted_alt_list_ : alt_list_);
124  }
125  // Returns the CubeSearchObject object that resulted from the last call to
126  // RecognizeWord
127  inline CubeSearchObject *SrchObj() const {
128  return (deslanted_ == true ? deslanted_srch_obj_ : srch_obj_);
129  }
130  // Returns the CharSamp object that resulted from the last call to
131  // RecognizeWord. Note that this object is not necessarily identical to the
132  // one passed at construction time as normalization might have occurred
133  inline CharSamp *CharSample() const {
134  return (deslanted_ == true ? deslanted_char_samp_ : char_samp_);
135  }
136 
137  // Set the ownership of the CharSamp
138  inline void SetCharSampOwnership(bool own_char_samp) {
139  own_char_samp_ = own_char_samp;
140  }
141 
142  protected:
143  // Normalize the CharSamp if its aspect ratio exceeds the below constant.
144  bool Normalize();
145 
146  private:
147  // minimum segment count needed to normalize a char_samp before recognition
148  static const int kMinNormalizationSegmentCnt = 4;
149 
150  // Data member initialization function
151  void Init();
152  // Free alternate lists.
153  void Cleanup();
154  // Perform the actual recognition using the specified language mode. If none
155  // is specified, the default language model in the CubeRecoContext is used.
156  // Returns the sorted list of alternate answers. Called by both
157  // RecognizerWord (word_mode is true) or RecognizePhrase (word mode is false)
158  WordAltList *Recognize(LangModel *lang_mod, bool word_mode);
159 
160  CubeRecoContext *cntxt_;
161  BeamSearch *beam_obj_;
162  BeamSearch *deslanted_beam_obj_;
163  bool offline_mode_;
164  bool own_char_samp_;
165  bool deslanted_;
166  CharSamp *char_samp_;
167  CharSamp *deslanted_char_samp_;
168  CubeSearchObject *srch_obj_;
169  CubeSearchObject *deslanted_srch_obj_;
170  WordAltList *alt_list_;
171  WordAltList *deslanted_alt_list_;
172 };
173 }
174 
175 #endif // CUBE_OBJECT_H