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__

#define TESSERACT_VERSION_STR "3.05.02"
#define TESSERACT_VERSION 0x030502
#define MAKE_VERSION(major, minor, patch) (((major) << 16) | ((minor) << 8) | \
                                            (patch))

#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;
struct BlamerBundle;
class BLOCK_LIST;
class DENORM;
class MATRIX;
class ROW;
class STRING;
class WERD;
struct Pix;
struct Box;
struct Pixa;
struct Boxa;
class ETEXT_DESC;
struct OSResults;
class TBOX;
class UNICHARSET;
class WERD_CHOICE_LIST;

struct INT_FEATURE_STRUCT;
typedef INT_FEATURE_STRUCT *INT_FEATURE;
struct TBLOB;

namespace tesseract {

#ifndef NO_CUBE_BUILD
class CubeRecoContext;
#endif  // NO_CUBE_BUILD
class Dawg;
class Dict;
class EquationDetect;
class PageIterator;
class LTRResultIterator;
class ResultIterator;
class MutableIterator;
class TessResultRenderer;
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 float (Dict::*ParamsModelClassifyFunc)(
    const char *lang, void *path);
typedef void (Wordrec::*FillLatticeFunc)(const MATRIX &ratings,
                                         const WERD_CHOICE_LIST &best_choices,
                                         const UNICHARSET &unicharset,
                                         BlamerBundle *blamer_bundle);
typedef TessCallback4<const UNICHARSET &, int, PageIterator *, Pix *>
    TruthCallback;

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

  static const char* Version();

  static size_t getOpenCLDevice(void **device);

  static void CatchSignals();

  void SetInputName(const char* name);
  const char* GetInputName();
  // Takes ownership of the input pix.
  void SetInputImage(Pix *pix);
  Pix* GetInputImage();
  int GetSourceYResolution();
  const char* GetDatapath();

  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(Pix* pix);

  void SetSourceResolution(int ppi);

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

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

  Pix* GetThresholdedImage();

  Boxa* GetRegions(Pixa** pixa);

  Boxa* GetTextlines(const bool raw_image, const int raw_padding,
                     Pixa** pixa, int** blockids, int** paraids);
  /*
     Helper method to extract from the thresholded image. (most common usage)
  */
  Boxa* GetTextlines(Pixa** pixa, int** blockids) {
    return GetTextlines(false, 0, pixa, blockids, NULL);
  }

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

  Boxa* GetWords(Pixa** pixa);

  Boxa* GetConnectedComponents(Pixa** cc);

  Boxa* GetComponentImages(const PageIteratorLevel level,
                           const bool text_only, const bool raw_image,
                           const int raw_padding,
                           Pixa** pixa, int** blockids, int** paraids);
  // Helper function to get binary images with no padding (most common usage).
  Boxa* GetComponentImages(const PageIteratorLevel level,
                           const bool text_only,
                           Pixa** pixa, int** blockids) {
    return GetComponentImages(level, text_only, false, 0, pixa, blockids, NULL);
  }

  int GetThresholdedImageScaleFactor() const;

  void DumpPGM(const char* filename);

  PageIterator* AnalyseLayout();
  PageIterator* AnalyseLayout(bool merge_similar_words);

  int Recognize(ETEXT_DESC* monitor);

  int RecognizeForChopTest(ETEXT_DESC* monitor);

  bool ProcessPages(const char* filename, const char* retry_config,
                    int timeout_millisec, TessResultRenderer* renderer);
  // Does the real work of ProcessPages.
  bool ProcessPagesInternal(const char* filename, const char* retry_config,
                            int timeout_millisec, TessResultRenderer* renderer);

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

  ResultIterator* GetIterator();

  MutableIterator* GetMutableIterator();

  char* GetUTF8Text();

  char* GetHOCRText(ETEXT_DESC* monitor, int page_number);

  char* GetHOCRText(int page_number);

  char* GetTSVText(int page_number);

  char* GetBoxText(int page_number);

  char* GetUNLVText();

  bool DetectOrientationScript(int* orient_deg, float* orient_conf, const char** script_name, float* script_conf);

  char* GetOsdText(int page_number);

  int MeanTextConf();
  int* AllWordConfidences();

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

  void Clear();

  void End();

  static void ClearPersistentCache();

  int IsValidWord(const char *word);
  // Returns true if utf8_character is defined in the UniCharset.
  bool IsValidCharacter(const char *utf8_character);


  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, INT_FEATURE_STRUCT* int_features,
                          int* num_features, int* feature_outline_index);

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

  void RunAdaptiveClassifier(TBLOB* blob,
                             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);

  Tesseract* tesseract() const { return tesseract_; }

  OcrEngineMode oem() const { return last_oem_requested_; }

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

#ifndef NO_CUBE_BUILD

  CubeRecoContext *GetCubeRecoContext() const;
#endif  // NO_CUBE_BUILD

  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();

  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_;
  /* @} */

 private:
  // A list of image filenames gets special consideration
  bool ProcessPagesFileList(FILE *fp,
                            STRING *buf,
                            const char* retry_config, int timeout_millisec,
                            TessResultRenderer* renderer,
                            int tessedit_page_number);
  // TIFF supports multipage so gets special consideration.
  bool ProcessPagesMultipageTiff(const unsigned char *data,
                                 size_t size,
                                 const char* filename,
                                 const char* retry_config,
                                 int timeout_millisec,
                                 TessResultRenderer* renderer,
                                 int tessedit_page_number);
  // There's currently no way to pass a document title from the
  // Tesseract command line, and we have multiple places that choose
  // to set the title to an empty string. Using a single named
  // variable will hopefully reduce confusion if the situation changes
  // in the future.
  const char *unknown_title_;
};  // class TessBaseAPI.

STRING HOcrEscape(const char* text);
}  // namespace tesseract.

#endif  // TESSERACT_API_BASEAPI_H__