com.googlecode.tesseract.android

Class TessBaseAPI

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.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static interface	TessBaseAPI.OcrEngineMode
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 Page segmentation mode.
static interface	TessBaseAPI.ProgressNotifier Interface that may be implemented by calling object in order to receive progress callbacks during OCR.
class	TessBaseAPI.ProgressValues Represents values indicating recognition progress and status.

Field Summary

Fields

Modifier and Type	Field and Description
static int	OEM_CUBE_ONLY Deprecated.
static int	OEM_DEFAULT Default OCR engine mode.
static int	OEM_TESSERACT_CUBE_COMBINED Deprecated.
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.
static String	VAR_FALSE String value used to assign a boolean variable to false.
static String	VAR_SAVE_BLOB_CHOICES Save blob choices allowing us to get alternative results.
static String	VAR_TRUE String value used to assign a boolean variable to true.

Constructor Summary

Constructors

Constructor and Description
TessBaseAPI() Constructs an instance of TessBaseAPI.
TessBaseAPI(TessBaseAPI.ProgressNotifier progressNotifier) Constructs an instance of TessBaseAPI with a callback method for receiving progress updates during OCR.

Method Summary

Modifier and Type	Method and Description
boolean	addPageToDocument(Pix imageToProcess, String imageToWrite, TessPdfRenderer tessPdfRenderer) Adds the given data to the opened document (if any).
boolean	beginDocument(TessPdfRenderer tessPdfRenderer) Starts a new document with no title.
boolean	beginDocument(TessPdfRenderer tessPdfRenderer, String title) Starts a new document.
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) Finishes the document and finalizes the output data.
String	getBoxText(int page) The recognized text is returned as coded in the same format as a UTF8 box file used in training.
Pixa	getConnectedComponents() Gets the individual connected (text) components (created after pages segmentation step, but before recognition) as a Pixa, in reading order.
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.
int	getPageSegMode() Return the current page segmentation mode.
Pixa	getRegions() Returns the result of page layout analysis as a Pixa, in reading order.
ResultIterator	getResultIterator() Get a reading-order iterator to the results of LayoutAnalysis and/or Recognize.
Pixa	getStrips() Get textlines and strips of image regions as a Pixa, in reading order.
Pixa	getTextlines() Returns the textlines as a Pixa.
Pix	getThresholdedImage() Get a copy of the internal thresholded image from Tesseract.
String	getUTF8Text() The recognized text is returned as a String which is coded as UTF8.
String	getVersion() Returns the version identifier as a string.
Pixa	getWords() Get the words 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 (average) confidence value between 0 and 100.
protected void	onProgressValues(int percent, int left, int right, int top, int bottom, int textLeft, int textRight, int textTop, int textBottom) Called from native code to update progress of ongoing recognition passes.
void	readConfigFile(String filename) Read a "config" file containing a set of variable, value pairs.
void	setDebug(boolean enabled) Sets debug mode.
void	setImage(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 bonus 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(Rect rect) Restricts recognition to a sub-rectangle of the image.
boolean	setVariable(String var, String value) Set the value of an internal "parameter."
void	stop() Cancel recognition started by getHOCRText(int).
int[]	wordConfidences() Returns all word confidences (between 0 and 100) in an array.

Methods inherited from class java.lang.Object

clone, equals, finalize, 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

VAR_SAVE_BLOB_CHOICES

public static final String VAR_SAVE_BLOB_CHOICES

Save blob choices allowing us to get alternative results.

See Also:

Constant Field Values

VAR_TRUE

public static final String VAR_TRUE

String value used to assign a boolean variable to true.

See Also:

Constant Field Values

VAR_FALSE

public static final String VAR_FALSE

String value used to assign a boolean variable to false.

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

@Deprecated
public static final int OEM_CUBE_ONLY

Deprecated.

Run Cube only - better accuracy, but slower

See Also:

Constant Field Values

OEM_TESSERACT_CUBE_COMBINED

@Deprecated
public static final int OEM_TESSERACT_CUBE_COMBINED

Deprecated.

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.

When the instance of TessBaseAPI is no longer needed, its end() method must be invoked to dispose of it.

TessBaseAPI

public TessBaseAPI(TessBaseAPI.ProgressNotifier progressNotifier)

Constructs an instance of TessBaseAPI with a callback method for receiving progress updates during OCR.

When the instance of TessBaseAPI is no longer needed, its end() method must be invoked to dispose of it.

Parameters:

progressNotifier - Callback to receive progress notifications

Method Detail

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 [~]<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.

Parameters:

datapath - the parent directory of tessdata ending in a forward slash

language - 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 - an ISO 639-3 string representing the language(s)

ocrEngineMode - the OCR engine mode to be set

Returns:

true on success

See Also:

init(String, String)

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.

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 "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.

Parameters:

var - name of the variable

value - value to set

Returns:

false if the name lookup failed

getPageSegMode

public int getPageSegMode()

Return the current page segmentation mode.

Returns:

value of the current page segmentation mode

setPageSegMode

public void setPageSegMode(int mode)

Sets the page segmentation mode. Defaults to TessBaseAPI.PageSegMode.PSM_SINGLE_BLOCK. This controls how much processing the OCR engine will perform before recognizing text.

The mode can also be modified by readConfigFile or setVariable("tessedit_pageseg_mode", mode as string).

Parameters:

mode - the TessBaseAPI.PageSegMode 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(Rect rect)

Restricts recognition to a sub-rectangle of the image. Call after SetImage. Each SetRectangle clears the recognition 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 recognition 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. 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:

file - absolute path to the image file

setImage

public void setImage(Bitmap bmp)

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:

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. This is a blocking operation that will not work with stop(). Call getHOCRText(int) before calling this function to interrupt a recognition task with stop()

Returns:

the recognized text

meanConfidence

public int meanConfidence()

Returns the (average) confidence value between 0 and 100.

Returns:

confidence value

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

getThresholdedImage

public Pix getThresholdedImage()

Get a copy of the internal thresholded image from Tesseract.

Caller takes ownership of the Pix and must recycle() it. May be called any time after setImage.

Returns:

Pix containing the thresholded image

getRegions

public Pixa getRegions()

Returns the result of page layout analysis as a Pixa, in reading order.

Can be called before or after Recognize.

Returns:

Pixa contaning page layout bounding boxes

getTextlines

public Pixa getTextlines()

Returns the textlines as a Pixa. Textlines are extracted from the thresholded image.

Can be called before or after Recognize. Block IDs are not returned. Paragraph IDs are not returned.

Returns:

Pixa containing textlines

getStrips

public Pixa getStrips()

Get textlines and strips of image regions as a Pixa, in reading order.

Enables downstream handling of non-rectangular regions. Can be called before or after Recognize. Block IDs are not returned.

Returns:

Pixa containing strips

getWords

public Pixa getWords()

Get the words as a Pixa, in reading order.

Can be called before or after Recognize.

Returns:

Pixa containing word bounding boxes

getConnectedComponents

public Pixa getConnectedComponents()

Gets the individual connected (text) components (created after pages segmentation step, but before recognition) as a Pixa, in reading order.

Can be called before or after Recognize. Note: the caller is responsible for calling recycle() on the returned Pixa.

Returns:

Pixa containing connected components bounding boxes

getResultIterator

public ResultIterator getResultIterator()

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

Returns:

iterator to the results of LayoutAnalysis and/or Recognize

getHOCRText

public String getHOCRText(int page)

Make a HTML-formatted string with hOCR markup from the internal data structures. Interruptible by stop().

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 for training and reading a UNLV zone file.

Parameters:

name - input file name

setOutputName

public void setOutputName(String name)

Set the name of the bonus 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. Note: only non-init params will be set.

Parameters:

filename - the configuration filename, without the 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.

Constructs coordinates in the original image - not just the rectangle.

Parameters:

page - a 0-based page index that will appear in the box file.

Returns:

the recognized text

getVersion

public String getVersion()

Returns the version identifier as a string.

Returns:

the version identifier

stop

public void stop()

Cancel recognition started by getHOCRText(int).

onProgressValues

protected void onProgressValues(int percent,
                                int left,
                                int right,
                                int top,
                                int bottom,
                                int textLeft,
                                int textRight,
                                int textTop,
                                int textBottom)

Called from native code to update progress of ongoing recognition passes.

Parameters:

percent - Percent complete

left - Left bound of word bounding box

right - Right bound of word bounding box

top - Top bound of word bounding box

bottom - Bottom bound of word bounding box

textLeft - Left bound of text bounding box

textRight - Right bound of text bounding box

textTop - Top bound of text bounding box

textBottom - Bottom bound of text bounding box

beginDocument

public boolean beginDocument(TessPdfRenderer tessPdfRenderer,
                             String title)

Starts a new document. This clears the contents of the output data. Caller is responsible for escaping the provided title.

Parameters:

tessPdfRenderer - the renderer instance to use

title - a title to be used in the document metadata

Returns:

true on success. false on failure

beginDocument

public boolean beginDocument(TessPdfRenderer tessPdfRenderer)

Starts a new document with no title.

Parameters:

tessPdfRenderer - the renderer instance to use

Returns:

true on success. false on failure

See Also:

beginDocument(TessPdfRenderer, String)

endDocument

public boolean endDocument(TessPdfRenderer tessPdfRenderer)

Finishes the document and finalizes the output data. Invalid if beginDocument not yet called.

Parameters:

tessPdfRenderer - the renderer instance to use

Returns:

true on success. false on failure

addPageToDocument

public boolean addPageToDocument(Pix imageToProcess,
                                 String imageToWrite,
                                 TessPdfRenderer tessPdfRenderer)

Adds the given data to the opened document (if any).

Parameters:

imageToProcess - image to be used for OCR

imageToWrite - path to image to be written into resulting document

tessPdfRenderer - the renderer instance to use

Returns:

true on success. false on failure