baseapi.h

Go to the documentation of this file.

// File:        baseapi.h
// Description: Simple API for calling tesseract.
// Author:      Ray Smith
//
// (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 <cstdio>
#include <functional>  // for std::function
 
// 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 <tesseract/version.h>
 
#include "apitypes.h"
#include "pageiterator.h"
#include "platform.h"
#include "publictypes.h"
#include "resultiterator.h"
#include "serialis.h"
#include "thresholder.h"
#include "unichar.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;
using INT_FEATURE = INT_FEATURE_STRUCT*;
struct TBLOB;
 
namespace tesseract {
 
class Dawg;
class Dict;
class EquationDetect;
class PageIterator;
class LTRResultIterator;
class ResultIterator;
class MutableIterator;
class TessResultRenderer;
class Tesseract;
class Trie;
class Wordrec;
 
using DictFunc = int (Dict::*)(void*, const UNICHARSET&, UNICHAR_ID,
                               bool) const;
using ProbabilityInContextFunc = double (Dict::*)(const char*, const char*, int,
                                                  const char*, int);
using ParamsModelClassifyFunc = float (Dict::*)(const char*, void*);
using FillLatticeFunc = void (Wordrec::*)(const MATRIX&,
                                          const WERD_CHOICE_LIST&,
                                          const UNICHARSET&, BlamerBundle*);
using TruthCallback =
    std::function<void(const UNICHARSET&, int, PageIterator*, Pix*)>;
 
class TESS_API TessBaseAPI {
 public:
  TessBaseAPI();
  virtual ~TessBaseAPI();
  // Copy constructor and assignment operator are currently unsupported.
  TessBaseAPI(TessBaseAPI const&) = delete;
  TessBaseAPI& operator=(TessBaseAPI const&) = delete;
 
  static const char* Version();
 
  static size_t getOpenCLDevice(void** device);
 
  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, nullptr, 0, nullptr, nullptr, false);
  }
  int Init(const char* datapath, const char* language) {
    return Init(datapath, language, OEM_DEFAULT, nullptr, 0, nullptr, nullptr,
                false);
  }
  // In-memory version reads the traineddata file directly from the given
  // data[data_size] array, and/or reads data via a FileReader.
  int Init(const char* data, int data_size, 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, FileReader reader);
 
  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(bool raw_image, 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, nullptr);
  }
 
  Boxa* GetStrips(Pixa** pixa, int** blockids);
 
  Boxa* GetWords(Pixa** pixa);
 
  Boxa* GetConnectedComponents(Pixa** cc);
 
  Boxa* GetComponentImages(PageIteratorLevel level, bool text_only,
                           bool raw_image, 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,
                              nullptr);
  }
 
  int GetThresholdedImageScaleFactor() const;
 
  PageIterator* AnalyseLayout();
  PageIterator* AnalyseLayout(bool merge_similar_words);
 
  int Recognize(ETEXT_DESC* monitor);
 
#ifndef DISABLED_LEGACY_ENGINE
 
  int RecognizeForChopTest(ETEXT_DESC* monitor);
#endif
 
  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* GetAltoText(ETEXT_DESC* monitor, int page_number);
 
  char* GetAltoText(int page_number);
 
  char* GetTSVText(int page_number);
 
  char* GetLSTMBoxText(int page_number);
 
  char* GetBoxText(int page_number);
 
  char* GetWordStrBoxText(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();
 
#ifndef DISABLED_LEGACY_ENGINE
 
  bool AdaptToWordStr(PageSegMode mode, const char* wordstr);
#endif  //  ndef DISABLED_LEGACY_ENGINE
 
  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);
 
  bool DetectOS(OSResults*);
 
  void GetBlockTextOrientations(int** block_orientation,
                                bool** vertical_writing);
 
#ifndef DISABLED_LEGACY_ENGINE
 
  void SetFillLatticeFunc(FillLatticeFunc f);
 
  BLOCK_LIST* FindLinesCreateBlockList();
 
  static void DeleteBlockList(BLOCK_LIST* block_list);
 
  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);
 
  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);
#endif  // ndef DISABLED_LEGACY_ENGINE
 
  const char* GetUnichar(int unichar_id);
 
  const Dawg* GetDawg(int i) const;
 
  int NumDawgs() const;
 
  Tesseract* tesseract() const {
    return tesseract_;
  }
 
  OcrEngineMode oem() const {
    return last_oem_requested_;
  }
 
  void InitTruthCallback(TruthCallback cb) {
    truth_cb_ = cb;
  }
 
  void set_min_orientation_margin(double margin);
  /* @} */
 
 protected:
  TESS_LOCAL bool InternalSetImage();
 
  TESS_LOCAL virtual bool Threshold(Pix** pix);
 
  TESS_LOCAL int FindLines();
 
  void ClearResults();
 
  TESS_LOCAL LTRResultIterator* GetLTRIterator();
 
  TESS_LOCAL int TextLength(int* blob_count);
 
  TESS_LOCAL void DetectParagraphs(bool after_text_recognition);
 
#ifndef DISABLED_LEGACY_ENGINE
 
  /* @{ */
 
  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 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_;
  }
  /* @} */
#endif  // ndef DISABLED_LEGACY_ENGINE
 
 protected:
  Tesseract* tesseract_;           
  Tesseract* osd_tesseract_;       
  EquationDetect* equ_detect_;     
  FileReader reader_;              
  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);
};  // class TessBaseAPI.
 
STRING HOcrEscape(const char* text);
}  // namespace tesseract.
 
#endif  // TESSERACT_API_BASEAPI_H_