TessBaseAPI (tess-two 1.0.0-SNAPSHOT API)

java.lang.Object
- com.googlecode.tesseract.android.TessBaseAPI

```
public class TessBaseAPI
extends Object
```
Java interface for the Tesseract OCR engine. Does not implement all available JNI methods, but does implement enough to be useful. Comments are adapted from original Tesseract source.

Author:

alanv@google.com (Alan Viverette)

Nested Class Summary

Nested Classes
Modifier and Type	Class and Description
`static class`	`TessBaseAPI.PageIteratorLevel` Elements of the page hierarchy, used in `ResultIterator` to provide functions that operate on each level without having to have 5x as many functions.
`static class`	`TessBaseAPI.PageSegMode`

Field Summary

Fields
Modifier and Type	Field and Description
`static int`	`OEM_CUBE_ONLY` Run Cube only - better accuracy, but slower
`static int`	`OEM_DEFAULT` Default OCR engine mode.
`static int`	`OEM_TESSERACT_CUBE_COMBINED` Run both and combine results - best accuracy
`static int`	`OEM_TESSERACT_ONLY` Run Tesseract only - fastest
`static String`	`VAR_CHAR_BLACKLIST` Blacklist of characters to not recognize.
`static String`	`VAR_CHAR_WHITELIST` Whitelist of characters to recognize.

Constructor Summary

Constructors
Constructor and Description

TessBaseAPI()
Constructs an instance of TessBaseAPI.

Constructors
Constructor and Description
`TessBaseAPI()` Constructs an instance of TessBaseAPI.

Method Summary

Methods
Modifier and Type	Method and Description
`boolean`	`addPageToDocument(Pix imageToProcess, String imageToWrite, TessPdfRenderer tessPdfRenderer)` Appends sandwiched page to opened document (if any).
`boolean`	`beginDocument(TessPdfRenderer tessPdfRenderer)` Starts document creation
`void`	`clear()` Frees up recognition results and any stored image data, without actually freeing any recognition data that would be time-consuming to reload.
`void`	`end()` Closes down tesseract and free up all memory.
`boolean`	`endDocument(TessPdfRenderer tessPdfRenderer)` Ends document creation
`protected void`	`finalize()` Called by the GC to clean up the native data that we set up when we construct the object.
`String`	`getBoxText(int page)` The recognized text is returned as coded in the same format as a UTF8 box file used in training.
`String`	`getHOCRText(int page)` Make a HTML-formatted string with hOCR markup from the internal data structures.
`String`	`getInitLanguagesAsString()` Returns the languages string used in the last valid initialization.
`Pixa`	`getRegions()` Returns the result of page layout analysis as a Pixa, in reading order.
`ResultIterator`	`getResultIterator()`
`Pixa`	`getStrips()` Returns the strips as a Pixa.
`Pixa`	`getTextlines()` Returns the textlines as a Pixa.
`String`	`getUTF8Text()` The recognized text is returned as a String which is coded as UTF8.
`Pixa`	`getWords()` Returns the word bounding boxes as a Pixa, in reading order.
`boolean`	`init(String datapath, String language)` Initializes the Tesseract engine with a specified language model.
`boolean`	`init(String datapath, String language, int ocrEngineMode)` Initializes the Tesseract engine with the specified language model(s).
`int`	`meanConfidence()` Returns the mean confidence of text recognition.
`void`	`ReadConfigFile(String filename)` Read a "config" file containing a set of variable, value pairs.
`void`	`setDebug(boolean enabled)` Sets debug mode.
`void`	`setImage(android.graphics.Bitmap bmp)` Provides an image for Tesseract to recognize.
`void`	`setImage(byte[] imagedata, int width, int height, int bpp, int bpl)` Provides an image for Tesseract to recognize.
`void`	`setImage(File file)` Provides an image for Tesseract to recognize.
`void`	`setImage(Pix image)` Provides a Leptonica pix format image for Tesseract to recognize.
`void`	`setInputName(String name)` Set the name of the input file.
`void`	`setOutputName(String name)` Set the name of the output files.
`void`	`setPageSegMode(int mode)` Sets the page segmentation mode.
`void`	`setRectangle(int left, int top, int width, int height)` Restricts recognition to a sub-rectangle of the image.
`void`	`setRectangle(android.graphics.Rect rect)` Restricts recognition to a sub-rectangle of the image.
`boolean`	`setVariable(String var, String value)` Set the value of an internal "variable" (of either old or new types).
`int[]`	`wordConfidences()` Returns all word confidences (between 0 and 100) in an array.

Methods inherited from class java.lang.Object
clone, equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

- Field Detail
  - VAR_CHAR_WHITELIST
```
public static final String VAR_CHAR_WHITELIST
```
    Whitelist of characters to recognize.
    
    See Also:
    Constant Field Values
  - VAR_CHAR_BLACKLIST
```
public static final String VAR_CHAR_BLACKLIST
```
    Blacklist of characters to not recognize.
    
    See Also:
    Constant Field Values
  - OEM_TESSERACT_ONLY
```
public static final int OEM_TESSERACT_ONLY
```
    Run Tesseract only - fastest
    
    See Also:
    Constant Field Values
  - OEM_CUBE_ONLY
```
public static final int OEM_CUBE_ONLY
```
    Run Cube only - better accuracy, but slower
    
    See Also:
    Constant Field Values
  - OEM_TESSERACT_CUBE_COMBINED
```
public static final int OEM_TESSERACT_CUBE_COMBINED
```
    Run both and combine results - best accuracy
    
    See Also:
    Constant Field Values
  - OEM_DEFAULT
```
public static final int OEM_DEFAULT
```
    Default OCR engine mode.
    
    See Also:
    Constant Field Values
- Constructor Detail
  - TessBaseAPI
```
public TessBaseAPI()
```
    Constructs an instance of TessBaseAPI.
- Method Detail
  - finalize
```
protected void finalize()
                 throws Throwable
```
    Called by the GC to clean up the native data that we set up when we construct the object. Altered from original version to avoid a crash-causing bug in OCR Test application.
    
    Overrides:
    
    finalize in class Object
    
    Throws:
    
    Throwable
  - init
```
public boolean init(String datapath,
           String language)
```
    Initializes the Tesseract engine with a specified language model. Returns true on success.
    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.
    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 null 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 [~][+[~]]* 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.
    
    Parameters:
    datapath - the parent directory of tessdata ending in a forward slash
    language - (optional) an ISO 639-3 string representing the language(s)
    
    Returns:
    true on success
  - init
```
public boolean init(String datapath,
           String language,
           int ocrEngineMode)
```
    Initializes the Tesseract engine with the specified language model(s). Returns true on success.
    
    Parameters:
    datapath - the parent directory of tessdata ending in a forward slash
    language - (optional) an ISO 639-3 string representing the language(s)
    mode - the OCR engine mode to be set
    
    Returns:
    true on success
  - getInitLanguagesAsString
```
public String getInitLanguagesAsString()
```
    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.
    
    Returns:
    the last-used language code
  - clear
```
public void clear()
```
    Frees up recognition results and any stored image data, without actually freeing any recognition data that would be time-consuming to reload. Afterwards, you must call SetImage or SetRectangle before doing any Recognize or Get* operation.
  - end
```
public void end()
```
    Closes down tesseract and free up all memory. End() is equivalent to destructing and reconstructing your TessBaseAPI.
    Once End() has been used, none of the other API functions may be used other than Init and anything declared above it in the class definition.
  - setVariable
```
public boolean setVariable(String var,
                  String value)
```
    Set the value of an internal "variable" (of either old or new types). Supply the name of the variable and the value as a string, just as you would in a config file.
    Example: setVariable(VAR_TESSEDIT_CHAR_BLACKLIST, "xyz"); to ignore x, y and z. * setVariable(VAR_BLN_NUMERICMODE, "1"); to set numeric-only mode. *
    setVariable() may be used before open(), but settings will revert to defaults on close().
    
    Parameters:
    var - name of the variable
    value - value to set
    
    Returns:
    false if the name lookup failed
  - setPageSegMode
```
public void setPageSegMode(int mode)
```
    Sets the page segmentation mode. This controls how much processing the OCR engine will perform before recognizing text.
    
    Parameters:
    mode - the page segmentation mode to set
  - setDebug
```
public void setDebug(boolean enabled)
```
    Sets debug mode. This controls how much information is displayed in the log during recognition.
    
    Parameters:
    enabled - true to enable debugging mode
  - setRectangle
```
public void setRectangle(android.graphics.Rect rect)
```
    Restricts recognition to a sub-rectangle of the image. Call after SetImage. Each SetRectangle clears the recogntion results so multiple rectangles can be recognized with the same image.
    
    Parameters:
    rect - the bounding rectangle
  - setRectangle
```
public void setRectangle(int left,
                int top,
                int width,
                int height)
```
    Restricts recognition to a sub-rectangle of the image. Call after SetImage. Each SetRectangle clears the recogntion results so multiple rectangles can be recognized with the same image.
    
    Parameters:
    left - the left bound
    top - the right bound
    width - the width of the bounding box
    height - the height of the bounding box
  - setImage
```
public void setImage(File file)
```
    Provides an image for Tesseract to recognize.
    
    Parameters:
    file - absolute path to the image file
  - setImage
```
public void setImage(android.graphics.Bitmap bmp)
```
    Provides an image for Tesseract to recognize. Does not copy the image buffer. The source image must persist until after Recognize or GetUTF8Chars is called.
    
    Parameters:
    bmp - bitmap representation of the image
  - setImage
```
public void setImage(Pix image)
```
    Provides a Leptonica pix format image for Tesseract to recognize. Clones the pix object. The source image may be destroyed immediately after SetImage is called, but its contents may not be modified.
    
    Parameters:
    image - Leptonica pix representation of the image
  - setImage
```
public void setImage(byte[] imagedata,
            int width,
            int height,
            int bpp,
            int bpl)
```
    Provides an image for Tesseract to recognize. Copies the image buffer. The source image may be destroyed immediately after SetImage is called. SetImage clears all recognition results, and sets the rectangle to the full image, so it may be followed immediately by a GetUTF8Text, and it will automatically perform recognition.
    
    Parameters:
    imagedata - byte representation of the image
    width - image width
    height - image height
    bpp - bytes per pixel
    bpl - bytes per line
  - getUTF8Text
```
public String getUTF8Text()
```
    The recognized text is returned as a String which is coded as UTF8.
    
    Returns:
    the recognized text
  - meanConfidence
```
public int meanConfidence()
```
    Returns the mean confidence of text recognition.
    
    Returns:
    the mean confidence
  - wordConfidences
```
public int[] wordConfidences()
```
    Returns all word confidences (between 0 and 100) in an array. The number of confidences should correspond to the number of space-delimited words in GetUTF8Text().
    
    Returns:
    an array of word confidences (between 0 and 100) for each space-delimited word returned by GetUTF8Text()
  - getRegions
```
public Pixa getRegions()
```
    Returns the result of page layout analysis as a Pixa, in reading order.
    
    Returns:
    Pixa contaning page layout bounding boxes
  - getTextlines
```
public Pixa getTextlines()
```
    Returns the textlines as a Pixa. Block IDs are not returned.
    
    Returns:
    Pixa containing textlines
  - getStrips
```
public Pixa getStrips()
```
    Returns the strips as a Pixa. Block IDs are not returned.
    
    Returns:
    Pixa containing strips
  - getWords
```
public Pixa getWords()
```
    Returns the word bounding boxes as a Pixa, in reading order.
    
    Returns:
    Pixa containing word bounding boxes
  - getResultIterator
```
public ResultIterator getResultIterator()
```
  - getHOCRText
```
public String getHOCRText(int page)
```
    Make a HTML-formatted string with hOCR markup from the internal data structures.
    
    Parameters:
    page - is 0-based but will appear in the output as 1-based.
    
    Returns:
    HTML-formatted string with hOCR markup
  - setInputName
```
public void setInputName(String name)
```
    Set the name of the input file. Needed only for training and reading a UNLV zone file.
    
    Parameters:
    name - input file name
  - setOutputName
```
public void setOutputName(String name)
```
    Set the name of the output files. Needed only for debugging.
    
    Parameters:
    name - output file name
  - ReadConfigFile
```
public void ReadConfigFile(String filename)
```
    Read a "config" file containing a set of variable, value pairs. Searches the standard places: tessdata/configs, tessdata/tessconfigs.
    
    Parameters:
    filename - the configuration filename, without path
  - getBoxText
```
public String getBoxText(int page)
```
    The recognized text is returned as coded in the same format as a UTF8 box file used in training.
    
    Parameters:
    page - is a 0-based page index that will appear in the box file.
  - beginDocument
```
public boolean beginDocument(TessPdfRenderer tessPdfRenderer)
```
    Starts document creation
    
    Returns:
    true on success. false on failure
  - endDocument
```
public boolean endDocument(TessPdfRenderer tessPdfRenderer)
```
    Ends document creation
    
    Returns:
    true on success. false on failure
  - addPageToDocument
```
public boolean addPageToDocument(Pix imageToProcess,
                        String imageToWrite,
                        TessPdfRenderer tessPdfRenderer)
```
    Appends sandwiched page to opened document (if any).
    
    Parameters:
    imageToProcess - image which will be used for OCR
    imageToWrite - image which will be written into resulting document
    
    Returns:
    true on success. false on failure

Class TessBaseAPI

Nested Class Summary

Field Summary

Constructor Summary

Method Summary

Methods inherited from class java.lang.Object

Field Detail

VAR_CHAR_WHITELIST

VAR_CHAR_BLACKLIST

OEM_TESSERACT_ONLY

OEM_CUBE_ONLY

OEM_TESSERACT_CUBE_COMBINED

OEM_DEFAULT

Constructor Detail

TessBaseAPI

Method Detail

finalize

init

init

getInitLanguagesAsString

clear

end

setVariable

setPageSegMode

setDebug

setRectangle

setRectangle

setImage

setImage

setImage

setImage

getUTF8Text

meanConfidence

wordConfidences

getRegions

getTextlines

getStrips

getWords

getResultIterator

getHOCRText

setInputName

setOutputName

ReadConfigFile

getBoxText

beginDocument

endDocument

addPageToDocument