baseapi.h

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// 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_
 
#ifdef HAVE_CONFIG_H
#  include "config_auto.h" // DISABLED_LEGACY_ENGINE
#endif
 
#include "export.h"
#include "pageiterator.h"
#include "publictypes.h"
#include "resultiterator.h"
#include "unichar.h"
 
#include <tesseract/version.h>
 
#include <cstdio>
#include <vector> // for std::vector
 
struct Pix;
struct Pixa;
struct Boxa;
 
namespace tesseract {
 
class PAGE_RES;
class ParagraphModel;
class BLOCK_LIST;
class ETEXT_DESC;
struct OSResults;
class UNICHARSET;
 
class Dawg;
class Dict;
class EquationDetect;
class PageIterator;
class ImageThresholder;
class LTRResultIterator;
class ResultIterator;
class MutableIterator;
class TessResultRenderer;
class Tesseract;
 
// Function to read a std::vector<char> from a whole file.
// Returns false on failure.
using FileReader = bool (*)(const char *filename, std::vector<char> *data);
 
using DictFunc = int (Dict::*)(void *, const UNICHARSET &, UNICHAR_ID,
                               bool) const;
using ProbabilityInContextFunc = double (Dict::*)(const char *, const char *,
                                                  int, const char *, int);
 
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;
 
#ifndef DISABLED_LEGACY_ENGINE
 
  void PrintFontsTable(FILE *fp) const;
 
#endif
 
  void PrintVariables(FILE *fp) const;
 
  bool GetVariableAsString(const char *name, std::string *val) const;
 
  int Init(const char *datapath, const char *language, OcrEngineMode mode,
           char **configs, int configs_size,
           const std::vector<std::string> *vars_vec,
           const std::vector<std::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 std::vector<std::string> *vars_vec,
           const std::vector<std::string> *vars_values,
           bool set_only_non_debug_params, FileReader reader);
 
  const char *GetInitLanguagesAsString() const;
 
  void GetLoadedLanguagesAsVector(std::vector<std::string> *langs) const;
 
  void GetAvailableLanguagesAsVector(std::vector<std::string> *langs) const;
 
  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);
 
  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);
 
  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) const;
  // Returns true if utf8_character is defined in the UniCharset.
  bool IsValidCharacter(const char *utf8_character) const;
 
  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);
 
  const char *GetUnichar(int unichar_id) const;
 
  const Dawg *GetDawg(int i) const;
 
  int NumDawgs() const;
 
  Tesseract *tesseract() const {
    return tesseract_;
  }
 
  OcrEngineMode oem() const {
    return last_oem_requested_;
  }
 
  void set_min_orientation_margin(double margin);
  /* @} */
 
protected:
  bool InternalSetImage();
 
  virtual bool Threshold(Pix **pix);
 
  int FindLines();
 
  void ClearResults();
 
  LTRResultIterator *GetLTRIterator();
 
  int TextLength(int *blob_count) const;
 
  void DetectParagraphs(bool after_text_recognition);
 
  const PAGE_RES *GetPageRes() const {
    return page_res_;
  }
 
protected:
  Tesseract *tesseract_;          
  Tesseract *osd_tesseract_;      
  EquationDetect *equ_detect_;    
  FileReader reader_;             
  ImageThresholder *thresholder_; 
  std::vector<ParagraphModel *> *paragraph_models_;
  BLOCK_LIST *block_list_;           
  PAGE_RES *page_res_;               
  std::string input_file_;           
  std::string output_file_;          
  std::string datapath_;             
  std::string language_;             
  OcrEngineMode last_oem_requested_; 
  bool recognition_done_;            
 
  /* @{ */
  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, std::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.
 
std::string HOcrEscape(const char *text);
 
} // namespace tesseract
 
#endif // TESSERACT_API_BASEAPI_H_