tesseract  v4.0.0-17-g361f3264
Open Source OCR Engine
tesseract::TessBaseAPI Class Reference

#include <baseapi.h>

Collaboration diagram for tesseract::TessBaseAPI:

Public Member Functions

 TessBaseAPI ()
 
virtual ~TessBaseAPI ()
 
void SetInputName (const char *name)
 
const char * GetInputName ()
 
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)
 
int Init (const char *datapath, const char *language)
 
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)
 
Pix * GetThresholdedImage ()
 
Boxa * GetRegions (Pixa **pixa)
 
Boxa * GetTextlines (const bool raw_image, const int raw_padding, Pixa **pixa, int **blockids, int **paraids)
 
Boxa * GetTextlines (Pixa **pixa, int **blockids)
 
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)
 
Boxa * GetComponentImages (const PageIteratorLevel level, const bool text_only, Pixa **pixa, int **blockids)
 
int GetThresholdedImageScaleFactor () const
 
PageIteratorAnalyseLayout ()
 
PageIteratorAnalyseLayout (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)
 
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)
 
ResultIteratorGetIterator ()
 
MutableIteratorGetMutableIterator ()
 
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 ()
 
int IsValidWord (const char *word)
 
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)
 
void SetFillLatticeFunc (FillLatticeFunc f)
 
BLOCK_LIST * FindLinesCreateBlockList ()
 
void GetFeaturesForBlob (TBLOB *blob, INT_FEATURE_STRUCT *int_features, int *num_features, int *feature_outline_index)
 
void RunAdaptiveClassifier (TBLOB *blob, int num_max_matches, int *unichar_ids, float *ratings, int *num_matches_returned)
 
const char * GetUnichar (int unichar_id)
 
const DawgGetDawg (int i) const
 
int NumDawgs () const
 
Tesseracttesseract () const
 
OcrEngineMode oem () const
 
void InitTruthCallback (TruthCallback *cb)
 
void set_min_orientation_margin (double margin)
 

Static Public Member Functions

static const char * Version ()
 
static size_t getOpenCLDevice (void **device)
 
static void CatchSignals ()
 
static void ClearPersistentCache ()
 
static void DeleteBlockList (BLOCK_LIST *block_list)
 
static ROWMakeTessOCRRow (float baseline, float xheight, float descender, float ascender)
 
static TBLOBMakeTBLOB (Pix *pix)
 
static void NormalizeTBLOB (TBLOB *tblob, ROW *row, bool numeric_mode)
 
static ROWFindRowForBox (BLOCK_LIST *blocks, int left, int top, int right, int bottom)
 

Protected Member Functions

TESS_LOCAL bool InternalSetImage ()
 
virtual TESS_LOCAL bool Threshold (Pix **pix)
 
TESS_LOCAL int FindLines ()
 
void ClearResults ()
 
TESS_LOCAL LTRResultIteratorGetLTRIterator ()
 
TESS_LOCAL int TextLength (int *blob_count)
 
TESS_LOCAL void DetectParagraphs (bool after_text_recognition)
 
TESS_LOCAL void AdaptToCharacter (const char *unichar_repr, int length, float baseline, float xheight, float descender, float ascender)
 
TESS_LOCAL PAGE_RESRecognitionPass1 (BLOCK_LIST *block_list)
 
TESS_LOCAL PAGE_RESRecognitionPass2 (BLOCK_LIST *block_list, PAGE_RES *pass1_result)
 
TESS_LOCAL const PAGE_RESGetPageRes () const
 

Static Protected Member Functions

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

Protected Attributes

Tesseracttesseract_
 The underlying data object. More...
 
Tesseractosd_tesseract_
 For orientation & script detection. More...
 
EquationDetectequ_detect_
 The equation detector. More...
 
FileReader reader_
 Reads files from any filesystem. More...
 
ImageThresholderthresholder_
 Image thresholding module. More...
 
GenericVector< ParagraphModel * > * paragraph_models_
 
BLOCK_LIST * block_list_
 The page layout. More...
 
PAGE_RESpage_res_
 The page-level data. More...
 
STRINGinput_file_
 Name used by training code. More...
 
STRINGoutput_file_
 Name used by debug code. More...
 
STRINGdatapath_
 Current location of tessdata. More...
 
STRINGlanguage_
 Last initialized language. More...
 
OcrEngineMode last_oem_requested_
 Last ocr language mode requested. More...
 
bool recognition_done_
 page_res_ contains recognition data. More...
 
TruthCallbacktruth_cb_
 
int rect_left_
 
int rect_top_
 
int rect_width_
 
int rect_height_
 
int image_width_
 
int image_height_
 

Private Member Functions

bool ProcessPagesFileList (FILE *fp, STRING *buf, const char *retry_config, int timeout_millisec, TessResultRenderer *renderer, int tessedit_page_number)
 
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)
 

Private Attributes

const char * unknown_title_ = ""
 

Detailed Description

Base class for all tesseract APIs. Specific classes can add ability to work on different inputs or produce different outputs. This class is mostly an interface layer on top of the Tesseract instance class to hide the data types so that users of this class don't have to include any other Tesseract headers.

Constructor & Destructor Documentation

◆ TessBaseAPI()

tesseract::TessBaseAPI::TessBaseAPI ( )

◆ ~TessBaseAPI()

tesseract::TessBaseAPI::~TessBaseAPI ( )
virtual

Member Function Documentation

◆ CatchSignals()

void tesseract::TessBaseAPI::CatchSignals ( )
static

Writes the thresholded image to stderr as a PBM file on receipt of a SIGSEGV, SIGFPE, or SIGBUS signal. (Linux/Unix only).

◆ ClearAdaptiveClassifier()

void tesseract::TessBaseAPI::ClearAdaptiveClassifier ( )

Call between pages or documents etc to free up memory and forget adaptive data.

◆ ClearResults()

void tesseract::TessBaseAPI::ClearResults ( )
protected

Delete the pageres and block list ready for a new page.

Delete the pageres and clear the block list ready for a new page.

◆ DetectParagraphs()

void tesseract::TessBaseAPI::DetectParagraphs ( bool  after_text_recognition)
protected

◆ FindLines()

int tesseract::TessBaseAPI::FindLines ( )
protected

Find lines from the image making the BLOCK_LIST.

Returns
0 on success.

Find lines from the image making the BLOCK_LIST.

◆ GetAvailableLanguagesAsVector()

void tesseract::TessBaseAPI::GetAvailableLanguagesAsVector ( GenericVector< STRING > *  langs) const

Returns the available languages in the sorted vector of STRINGs.

◆ GetBoolVariable()

bool tesseract::TessBaseAPI::GetBoolVariable ( const char *  name,
bool *  value 
) const

◆ GetDatapath()

const char * tesseract::TessBaseAPI::GetDatapath ( )

◆ GetDoubleVariable()

bool tesseract::TessBaseAPI::GetDoubleVariable ( const char *  name,
double *  value 
) const

◆ GetInitLanguagesAsString()

const char * tesseract::TessBaseAPI::GetInitLanguagesAsString ( ) const

Returns the languages string used in the last valid initialization. If the last initialization specified "deu+hin" then that will be returned. If hin loaded eng automatically as well, then that will not be included in this list. To find the languages actually loaded use GetLoadedLanguagesAsVector. The returned string should NOT be deleted.

◆ GetInputImage()

Pix * tesseract::TessBaseAPI::GetInputImage ( )

◆ GetInputName()

const char * tesseract::TessBaseAPI::GetInputName ( )

These functions are required for searchable PDF output. We need our hands on the input file so that we can include it in the PDF without transcoding. If that is not possible, we need the original image. Finally, resolution metadata is stored in the PDF so we need that as well.

◆ GetIntVariable()

bool tesseract::TessBaseAPI::GetIntVariable ( const char *  name,
int *  value 
) const

Returns true if the parameter was found among Tesseract parameters. Fills in value with the value of the parameter.

◆ GetLoadedLanguagesAsVector()

void tesseract::TessBaseAPI::GetLoadedLanguagesAsVector ( GenericVector< STRING > *  langs) const

Returns the loaded languages in the vector of STRINGs. Includes all languages loaded by the last Init, including those loaded as dependencies of other loaded languages.

◆ GetLTRIterator()

LTRResultIterator * tesseract::TessBaseAPI::GetLTRIterator ( )
protected

Return an LTR Result Iterator – used only for training, as we really want to ignore all BiDi smarts at that point. delete once you're done with it.

Get a left-to-right iterator to the results of LayoutAnalysis and/or Recognize. The returned iterator must be deleted after use.

◆ getOpenCLDevice()

size_t tesseract::TessBaseAPI::getOpenCLDevice ( void **  data)
static

If compiled with OpenCL AND an available OpenCL device is deemed faster than serial code, then "device" is populated with the cl_device_id and returns sizeof(cl_device_id) otherwise *device=nullptr and returns 0.

◆ GetPageSegMode()

PageSegMode tesseract::TessBaseAPI::GetPageSegMode ( ) const

Return the current page segmentation mode.

◆ GetSourceYResolution()

int tesseract::TessBaseAPI::GetSourceYResolution ( )

◆ GetStringVariable()

const char * tesseract::TessBaseAPI::GetStringVariable ( const char *  name) const

Returns the pointer to the string that represents the value of the parameter if it was found among Tesseract parameters.

◆ GetVariableAsString()

bool tesseract::TessBaseAPI::GetVariableAsString ( const char *  name,
STRING val 
)

Get value of named variable as a string, if it exists.

◆ Init() [1/4]

int tesseract::TessBaseAPI::Init ( const char *  datapath,
const char *  language,
OcrEngineMode  oem,
char **  configs,
int  configs_size,
const GenericVector< STRING > *  vars_vec,
const GenericVector< STRING > *  vars_values,
bool  set_only_non_debug_params 
)

Instances are now mostly thread-safe and totally independent, but some global parameters remain. Basically it is safe to use multiple TessBaseAPIs in different threads in parallel, UNLESS: you use SetVariable on some of the Params in classify and textord. If you do, then the effect will be to change it for all your instances.

Start tesseract. Returns zero on success and -1 on failure. NOTE that the only members that may be called before Init are those listed above here in the class definition.

The datapath must be the name of the parent directory of tessdata and must end in / . Any name after the last / will be stripped. The language is (usually) an ISO 639-3 string or nullptr will default to eng. It is entirely safe (and eventually will be efficient too) to call Init multiple times on the same instance to change language, or just to reset the classifier. The language may be a string of the form [~]<lang>[+[~]<lang>]* indicating that multiple languages are to be loaded. Eg hin+eng will load Hindi and English. Languages may specify internally that they want to be loaded with one or more other languages, so the ~ sign is available to override that. Eg if hin were set to load eng by default, then hin+~eng would force loading only hin. The number of loaded languages is limited only by memory, with the caveat that loading additional languages will impact both speed and accuracy, as there is more work to do to decide on the applicable language, and there is more chance of hallucinating incorrect words. WARNING: On changing languages, all Tesseract parameters are reset back to their default values. (Which may vary between languages.) If you have a rare need to set a Variable that controls initialization for a second call to Init you should explicitly call End() and then use SetVariable before Init. This is only a very rare use case, since there are very few uses that require any parameters to be set before Init.

If set_only_non_debug_params is true, only params that do not contain "debug" in the name will be set.

The datapath must be the name of the data directory (no ending /) or some other file in which the data directory resides (for instance argv[0].) The language is (usually) an ISO 639-3 string or nullptr will default to eng. If numeric_mode is true, then only digits and Roman numerals will be returned.

Returns
: 0 on success and -1 on initialization failure.

◆ Init() [2/4]

int tesseract::TessBaseAPI::Init ( const char *  datapath,
const char *  language,
OcrEngineMode  oem 
)
inline

◆ Init() [3/4]

int tesseract::TessBaseAPI::Init ( const char *  datapath,
const char *  language 
)
inline

◆ Init() [4/4]

int tesseract::TessBaseAPI::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 
)

◆ InitForAnalysePage()

void tesseract::TessBaseAPI::InitForAnalysePage ( )

Init only for page layout analysis. Use only for calls to SetImage and AnalysePage. Calls that attempt recognition will generate an error.

◆ InitLangMod()

int tesseract::TessBaseAPI::InitLangMod ( const char *  datapath,
const char *  language 
)

Init only the lang model component of Tesseract. The only functions that work after this init are SetVariable and IsValidWord. WARNING: temporary! This function will be removed from here and placed in a separate API at some future time.

◆ InternalSetImage()

bool tesseract::TessBaseAPI::InternalSetImage ( )
protected

Common code for setting the image. Returns true if Init has been called.

Common code for setting the image.

◆ PrintVariables()

void tesseract::TessBaseAPI::PrintVariables ( FILE *  fp) const

Print Tesseract parameters to the given file.

◆ ProcessPagesFileList()

bool tesseract::TessBaseAPI::ProcessPagesFileList ( FILE *  fp,
STRING buf,
const char *  retry_config,
int  timeout_millisec,
TessResultRenderer renderer,
int  tessedit_page_number 
)
private

◆ ProcessPagesMultipageTiff()

bool tesseract::TessBaseAPI::ProcessPagesMultipageTiff ( const unsigned char *  data,
size_t  size,
const char *  filename,
const char *  retry_config,
int  timeout_millisec,
TessResultRenderer renderer,
int  tessedit_page_number 
)
private

◆ ReadConfigFile()

void tesseract::TessBaseAPI::ReadConfigFile ( const char *  filename)

Read a "config" file containing a set of param, value pairs. Searches the standard places: tessdata/configs, tessdata/tessconfigs and also accepts a relative or absolute path name. Note: only non-init params will be set (init params are set by Init()).

Read a "config" file containing a set of parameter name, value pairs. Searches the standard places: tessdata/configs, tessdata/tessconfigs and also accepts a relative or absolute path name.

◆ ReadDebugConfigFile()

void tesseract::TessBaseAPI::ReadDebugConfigFile ( const char *  filename)

Same as above, but only set debug params from the given config file.

◆ SetDebugVariable()

bool tesseract::TessBaseAPI::SetDebugVariable ( const char *  name,
const char *  value 
)

◆ SetInputImage()

void tesseract::TessBaseAPI::SetInputImage ( Pix *  pix)

◆ SetInputName()

void tesseract::TessBaseAPI::SetInputName ( const char *  name)

Set the name of the input file. Needed for training and reading a UNLV zone file, and for searchable PDF output.

Set the name of the input file. Needed only for training and loading a UNLV zone file.

◆ SetOutputName()

void tesseract::TessBaseAPI::SetOutputName ( const char *  name)

Set the name of the bonus output files. Needed only for debugging.

Set the name of the output files. Needed only for debugging.

◆ SetPageSegMode()

void tesseract::TessBaseAPI::SetPageSegMode ( PageSegMode  mode)

Set the current page segmentation mode. Defaults to PSM_SINGLE_BLOCK. The mode is stored as an IntParam so it can also be modified by ReadConfigFile or SetVariable("tessedit_pageseg_mode", mode as string).

Set the current page segmentation mode. Defaults to PSM_AUTO. The mode is stored as an IntParam so it can also be modified by ReadConfigFile or SetVariable("tessedit_pageseg_mode", mode as string).

◆ SetVariable()

bool tesseract::TessBaseAPI::SetVariable ( const char *  name,
const char *  value 
)

Set the value of an internal "parameter." Supply the name of the parameter and the value as a string, just as you would in a config file. Returns false if the name lookup failed. Eg SetVariable("tessedit_char_blacklist", "xyz"); to ignore x, y and z. Or SetVariable("classify_bln_numeric_mode", "1"); to set numeric-only mode. SetVariable may be used before Init, but settings will revert to defaults on End().

Note: Must be called after Init(). Only works for non-init variables (init variables should be passed to Init()).

◆ TesseractRect()

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

Recognize a rectangle from an image and return the result as a string. May be called many times for a single Init. Currently has no error checking. Greyscale of 8 and color of 24 or 32 bits per pixel may be given. Palette color images will not work properly and must be converted to 24 bit. Binary images of 1 bit per pixel may also be given but they must be byte packed with the MSB of the first byte being the first pixel, and a 1 represents WHITE. For binary images set bytes_per_pixel=0. The recognized text is returned as a char* which is coded as UTF8 and must be freed with the delete [] operator.

Note that TesseractRect is the simplified convenience interface. For advanced uses, use SetImage, (optionally) SetRectangle, Recognize, and one or more of the Get*Text functions below.

Recognize a rectangle from an image and return the result as a string. May be called many times for a single Init. Currently has no error checking. Greyscale of 8 and color of 24 or 32 bits per pixel may be given. Palette color images will not work properly and must be converted to 24 bit. Binary images of 1 bit per pixel may also be given but they must be byte packed with the MSB of the first byte being the first pixel, and a one pixel is WHITE. For binary images set bytes_per_pixel=0. The recognized text is returned as a char* which is coded as UTF8 and must be freed with the delete [] operator.

◆ TextLength()

int tesseract::TessBaseAPI::TextLength ( int *  blob_count)
protected

Return the length of the output text string, as UTF8, assuming one newline per line and one per block, with a terminator, and assuming a single character reject marker for each rejected character. Also return the number of recognized blobs in blob_count.

Return the length of the output text string, as UTF8, assuming liberally two spacing marks after each word (as paragraphs end with two newlines), and assuming a single character reject marker for each rejected character. Also return the number of recognized blobs in blob_count.

◆ Threshold()

bool tesseract::TessBaseAPI::Threshold ( Pix **  pix)
protectedvirtual

Run the thresholder to make the thresholded image. If pix is not nullptr, the source is thresholded to pix instead of the internal IMAGE.

Run the thresholder to make the thresholded image, returned in pix, which must not be nullptr. *pix must be initialized to nullptr, or point to an existing pixDestroyable Pix. The usual argument to Threshold is Tesseract::mutable_pix_binary().

◆ Version()

const char * tesseract::TessBaseAPI::Version ( )
static

Returns the version identifier as a static string. Do not delete.

Member Data Documentation

◆ block_list_

BLOCK_LIST* tesseract::TessBaseAPI::block_list_
protected

The page layout.

◆ datapath_

STRING* tesseract::TessBaseAPI::datapath_
protected

Current location of tessdata.

◆ equ_detect_

EquationDetect* tesseract::TessBaseAPI::equ_detect_
protected

The equation detector.

◆ input_file_

STRING* tesseract::TessBaseAPI::input_file_
protected

Name used by training code.

◆ language_

STRING* tesseract::TessBaseAPI::language_
protected

Last initialized language.

◆ last_oem_requested_

OcrEngineMode tesseract::TessBaseAPI::last_oem_requested_
protected

Last ocr language mode requested.

◆ osd_tesseract_

Tesseract* tesseract::TessBaseAPI::osd_tesseract_
protected

For orientation & script detection.

◆ output_file_

STRING* tesseract::TessBaseAPI::output_file_
protected

Name used by debug code.

◆ page_res_

PAGE_RES* tesseract::TessBaseAPI::page_res_
protected

The page-level data.

◆ paragraph_models_

GenericVector<ParagraphModel *>* tesseract::TessBaseAPI::paragraph_models_
protected

◆ reader_

FileReader tesseract::TessBaseAPI::reader_
protected

Reads files from any filesystem.

◆ recognition_done_

bool tesseract::TessBaseAPI::recognition_done_
protected

page_res_ contains recognition data.

◆ tesseract_

Tesseract* tesseract::TessBaseAPI::tesseract_
protected

The underlying data object.

◆ thresholder_

ImageThresholder* tesseract::TessBaseAPI::thresholder_
protected

Image thresholding module.

◆ truth_cb_

TruthCallback* tesseract::TessBaseAPI::truth_cb_
protected

◆ unknown_title_

const char* tesseract::TessBaseAPI::unknown_title_ = ""
private

The documentation for this class was generated from the following files: