baseapi.h

Go to the documentation of this file.

// File:        baseapi.h
// Description: Simple API for calling tesseract.
// Author:      Ray Smith
// Created:     Fri Oct 06 15:35:01 PDT 2006
//
// (C) Copyright 2006, Google Inc.
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
// http://www.apache.org/licenses/LICENSE-2.0
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.
//

#ifndef TESSERACT_API_BASEAPI_H__
#define TESSERACT_API_BASEAPI_H__

#include <stdio.h>
// To avoid collision with other typenames include the ABSOLUTE MINIMUM
// complexity of includes here. Use forward declarations wherever possible
// and hide includes of complex types in baseapi.cpp.
#include "platform.h"
#include "apitypes.h"
#include "thresholder.h"
#include "unichar.h"
#include "tesscallback.h"
#include "publictypes.h"
#include "pageiterator.h"
#include "resultiterator.h"

template <typename T> class GenericVector;
class PAGE_RES;
class PAGE_RES_IT;
class ParagraphModel;
class BlamerBundle;
class BLOCK_LIST;
class DENORM;
class IMAGE;
class MATRIX;
class PBLOB;
class ROW;
class STRING;
class WERD;
struct Pix;
struct Box;
struct Pixa;
struct Boxa;
class ETEXT_DESC;
struct OSResults;
class TBOX;
class UNICHARSET;

// From oldlist.h
// TODO(antonova): remove when oldlist is deprecated.
struct list_rec;
typedef list_rec *LIST;

#define MAX_NUM_INT_FEATURES 512
struct INT_FEATURE_STRUCT;
typedef INT_FEATURE_STRUCT *INT_FEATURE;
typedef INT_FEATURE_STRUCT INT_FEATURE_ARRAY[MAX_NUM_INT_FEATURES];
struct TBLOB;

namespace tesseract {

class CubeRecoContext;
class Dawg;
class Dict;
class EquationDetect;
class LTRResultIterator;
class MutableIterator;
class Tesseract;
class Trie;
class Wordrec;

typedef int (Dict::*DictFunc)(void* void_dawg_args,
                              UNICHAR_ID unichar_id, bool word_end) const;
typedef double (Dict::*ProbabilityInContextFunc)(const char* lang,
                                                 const char* context,
                                                 int context_bytes,
                                                 const char* character,
                                                 int character_bytes);
typedef void (Wordrec::*FillLatticeFunc)(const MATRIX &ratings,
                                         const LIST &best_choices,
                                         const UNICHARSET &unicharset,
                                         BlamerBundle *blamer_bundle);
typedef TessCallback3<const UNICHARSET &, int, PAGE_RES *> TruthCallback;

class TESS_API TessBaseAPI {
 public:
  TessBaseAPI();
  virtual ~TessBaseAPI();

  static const char* Version();

  void SetInputName(const char* name);

  void SetOutputName(const char* name);

  bool SetVariable(const char* name, const char* value);
  bool SetDebugVariable(const char* name, const char* value);

  bool GetIntVariable(const char *name, int *value) const;
  bool GetBoolVariable(const char *name, bool *value) const;
  bool GetDoubleVariable(const char *name, double *value) const;

  const char *GetStringVariable(const char *name) const;

  void PrintVariables(FILE *fp) const;

  bool GetVariableAsString(const char *name, STRING *val);

  int Init(const char* datapath, const char* language, OcrEngineMode mode,
           char **configs, int configs_size,
           const GenericVector<STRING> *vars_vec,
           const GenericVector<STRING> *vars_values,
           bool set_only_non_debug_params);
  int Init(const char* datapath, const char* language, OcrEngineMode oem) {
    return Init(datapath, language, oem, NULL, 0, NULL, NULL, false);
  }
  int Init(const char* datapath, const char* language) {
    return Init(datapath, language, OEM_DEFAULT, NULL, 0, NULL, NULL, false);
  }

  const char* GetInitLanguagesAsString() const;

  void GetLoadedLanguagesAsVector(GenericVector<STRING>* langs) const;

  void GetAvailableLanguagesAsVector(GenericVector<STRING>* langs) const;

  int InitLangMod(const char* datapath, const char* language);

  void InitForAnalysePage();

  void ReadConfigFile(const char* filename);
  void ReadDebugConfigFile(const char* filename);

  void SetPageSegMode(PageSegMode mode);

  PageSegMode GetPageSegMode() const;

  char* TesseractRect(const unsigned char* imagedata,
                      int bytes_per_pixel, int bytes_per_line,
                      int left, int top, int width, int height);

  void ClearAdaptiveClassifier();

   /* @{ */

  void SetImage(const unsigned char* imagedata, int width, int height,
                int bytes_per_pixel, int bytes_per_line);

  void SetImage(const Pix* pix);

  void SetSourceResolution(int ppi);

  void SetRectangle(int left, int top, int width, int height);

  void SetThresholder(ImageThresholder* thresholder) {
    if (thresholder_ != NULL)
      delete thresholder_;
    thresholder_ = thresholder;
    ClearResults();
  }

  Pix* GetThresholdedImage();

  Boxa* GetRegions(Pixa** pixa);

  Boxa* GetTextlines(Pixa** pixa, int** blockids);

  Boxa* GetStrips(Pixa** pixa, int** blockids);

  Boxa* GetWords(Pixa** pixa);

  Boxa* GetConnectedComponents(Pixa** cc);

  Boxa* GetComponentImages(PageIteratorLevel level,
                           bool text_only,
                           Pixa** pixa, int** blockids);

  int GetThresholdedImageScaleFactor() const;

  void DumpPGM(const char* filename);

  PageIterator* AnalyseLayout();

  int Recognize(ETEXT_DESC* monitor);

  int RecognizeForChopTest(ETEXT_DESC* monitor);

  bool ProcessPages(const char* filename,
                    const char* retry_config, int timeout_millisec,
                    STRING* text_out);

  bool ProcessPage(Pix* pix, int page_index, const char* filename,
                   const char* retry_config, int timeout_millisec,
                   STRING* text_out);

  ResultIterator* GetIterator();

  MutableIterator* GetMutableIterator();

  char* GetUTF8Text();

  char* GetHOCRText(int page_number);
  char* GetBoxText(int page_number);
  char* GetUNLVText();
  int MeanTextConf();
  int* AllWordConfidences();

  bool AdaptToWordStr(PageSegMode mode, const char* wordstr);

  void Clear();

  void End();

  int IsValidWord(const char *word);

  bool GetTextDirection(int* out_offset, float* out_slope);

  void SetDictFunc(DictFunc f);

  void SetProbabilityInContextFunc(ProbabilityInContextFunc f);

  void SetFillLatticeFunc(FillLatticeFunc f);

  bool DetectOS(OSResults*);

  void GetFeaturesForBlob(TBLOB* blob, const DENORM& denorm,
                          INT_FEATURE_ARRAY int_features,
                          int* num_features, int* FeatureOutlineIndex);

  static ROW* FindRowForBox(BLOCK_LIST* blocks, int left, int top,
                            int right, int bottom);

  void RunAdaptiveClassifier(TBLOB* blob, const DENORM& denorm,
                             int num_max_matches,
                             int* unichar_ids,
                             float* ratings,
                             int* num_matches_returned);

  const char* GetUnichar(int unichar_id);

  const Dawg *GetDawg(int i) const;

  int NumDawgs() const;

  static ROW *MakeTessOCRRow(float baseline, float xheight,
                             float descender, float ascender);

  static TBLOB *MakeTBLOB(Pix *pix);

  static void NormalizeTBLOB(TBLOB *tblob, ROW *row,
                             bool numeric_mode, DENORM *denorm);

  Tesseract* const tesseract() const {
    return tesseract_;
  }
  
  OcrEngineMode const oem() const {
    return last_oem_requested_;
  }

  void InitTruthCallback(TruthCallback *cb) { truth_cb_ = cb; }

  CubeRecoContext *GetCubeRecoContext() const;

  void set_min_orientation_margin(double margin);

  void GetBlockTextOrientations(int** block_orientation,
                                bool** vertical_writing);

  BLOCK_LIST* FindLinesCreateBlockList();

  static void DeleteBlockList(BLOCK_LIST* block_list);
 /* @} */

 protected:

  TESS_LOCAL bool InternalSetImage();

  TESS_LOCAL virtual void Threshold(Pix** pix);

  TESS_LOCAL int FindLines();

  TESS_LOCAL void ClearResults();

  TESS_LOCAL LTRResultIterator* GetLTRIterator();

  TESS_LOCAL int TextLength(int* blob_count);

  /* @{ */

  TESS_LOCAL void AdaptToCharacter(const char *unichar_repr,
                                   int length,
                                   float baseline,
                                   float xheight,
                                   float descender,
                                   float ascender);

  TESS_LOCAL PAGE_RES* RecognitionPass1(BLOCK_LIST* block_list);
  TESS_LOCAL PAGE_RES* RecognitionPass2(BLOCK_LIST* block_list, PAGE_RES* pass1_result);

  TESS_LOCAL void DetectParagraphs(bool after_text_recognition);

  TESS_LOCAL static int TesseractExtractResult(char** text,
                                    int** lengths,
                                    float** costs,
                                    int** x0,
                                    int** y0,
                                    int** x1,
                                    int** y1,
                                    PAGE_RES* page_res);

  TESS_LOCAL const PAGE_RES* GetPageRes() const {
    return page_res_;
  };
  /* @} */

 protected:
  Tesseract*        tesseract_;       
  Tesseract*        osd_tesseract_;   
  EquationDetect*   equ_detect_;      
  ImageThresholder* thresholder_;     
  GenericVector<ParagraphModel *>* paragraph_models_;
  BLOCK_LIST*       block_list_;      
  PAGE_RES*         page_res_;        
  STRING*           input_file_;      
  STRING*           output_file_;     
  STRING*           datapath_;        
  STRING*           language_;        
  OcrEngineMode last_oem_requested_;  
  bool          recognition_done_;   
  TruthCallback *truth_cb_;           

  /* @{ */
  int rect_left_;
  int rect_top_;
  int rect_width_;
  int rect_height_;
  int image_width_;
  int image_height_;
  /* @} */

};

}  // namespace tesseract.

#endif  // TESSERACT_API_BASEAPI_H__