com.microblink.blinkinput.directApi

Class RecognizerRunner

java.lang.Object

com.microblink.blinkinput.directApi.RecognizerRunner

public class RecognizerRunner
extends java.lang.Object

RecognizerRunner singleton that can be used to perform recognition of Bitmaps and Images.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	RecognizerRunner.State

Method Summary

Modifier and Type	Method and Description
void	cancel() If there is ongoing recognition process, this method will request cancellation of it and wait for recognition process to complete.
RecognizerRunner.State	getCurrentState() Returns the current state of the recognizer.
static RecognizerRunner	getSingletonInstance() Returns the recognizer singleton.
void	initialize(android.content.Context context, RecognizerBundle recognizerBundle, DirectApiErrorListener errorListener) Initialize native library for recognition and returns true if initialization has been performed.
void	recognizeBitmap(android.graphics.Bitmap image, Orientation imageOrientation, Rectangle scanRegion, ScanResultListener resultListener) Perform recognition of image represented as Android Bitmap.
void	recognizeBitmap(android.graphics.Bitmap image, Orientation imageOrientation, ScanResultListener resultListener) Perform recognition of image represented as Android Bitmap.
void	recognizeBitmapWithRecognizers(android.graphics.Bitmap image, Orientation imageOrientation, Rectangle scanRegion, ScanResultListener resultListener, RecognizerBundle recognizerBundle) Perform recognition of image represented as Android Bitmap.
void	recognizeBitmapWithRecognizers(android.graphics.Bitmap image, Orientation imageOrientation, ScanResultListener resultListener, RecognizerBundle recognizerBundle) Perform recognition of image represented as Android Bitmap.
void	recognizeImage(Image image, ScanResultListener resultListener) Use this method to directly recognize Image object obtained via MetadataListener while recognizer is active.
void	recognizeImageWithRecognizers(Image image, ScanResultListener resultListener, RecognizerBundle recognizerBundle) Use this method to directly recognize Image object obtained via MetadataListener while recognizer is active.
void	recognizeString(java.lang.String stringData, ScanResultListener resultListener) Use this method to directly recognize given string data without performing the OCR, while recognizer is active.
void	recognizeStringWithRecognizers(java.lang.String stringData, ScanResultListener resultListener, RecognizerBundle recognizerBundle) Use this method to directly recognize given string data without performing the OCR, while recognizer is active.
void	resetRecognitionState() Resets the recognition state, i.e.
void	resetRecognitionState(boolean hardReset) Resets the recognition state.
void	setMetadataCallbacks(MetadataCallbacks metadataCallbacks) Sets the metadata callbacks that will obtain metadata during processing.
void	terminate() Terminates the native library.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

getSingletonInstance

@NonNull
public static RecognizerRunner getSingletonInstance()

Returns the recognizer singleton.

Returns:

the recognizer singleton.

getCurrentState

@NonNull
public final RecognizerRunner.State getCurrentState()

Returns the current state of the recognizer.

Returns:

the current state of the recognizer.

initialize

public final void initialize(@NonNull
                             android.content.Context context,
                             @NonNull
                             RecognizerBundle recognizerBundle,
                             @NonNull
                             DirectApiErrorListener errorListener)

Initialize native library for recognition and returns true if initialization has been performed.

Please note that native library is singleton, i.e. it is used from both this RecognizerRunner recognizer and RecognizerRunnerView. So if both RecognizerRunnerView and RecognizerRunner try to initialize the native library at the same time, the following will happen: - if first initialized from RecognizerRunnerView, this method will return false, indicating failure to initialize RecognizerRunner - if first initialized from here, method will return true, HOWEVER if after that native library is initialized again from RecognizerRunnerView, **RecognizerRunnerView's settings will be applied**, in that case calling recognize method will use RecognizerRunnerView's settings - to prevent that, you must use recognizeWithSettings method All in all, RecognizerRunnerView's settings always have priority over RecognizerRunner's settings.

Parameters:

context - Application context used for loading required resources.

recognizerBundle - RecognizerRunner bundle defining a recognition process.

errorListener - Listener that will be notified of any error in native library in background thread.

Throws:

java.lang.IllegalStateException - if recognizer is already initialized

java.lang.NullPointerException - if context, settings array or errorListener is null

recognizeBitmap

public final void recognizeBitmap(@NonNull
                                  android.graphics.Bitmap image,
                                  @NonNull
                                  Orientation imageOrientation,
                                  @NonNull
                                  ScanResultListener resultListener)

Perform recognition of image represented as Android Bitmap.

Parameters:

image - Image that needs to be recognized.

imageOrientation - Orientation of the bitmap image.

resultListener - Result listener that will handle recognition done event.

Throws:

java.lang.IllegalStateException - if recognizer is not initialized or is currently working

java.lang.NullPointerException - if given null scan result listener

recognizeBitmap

public final void recognizeBitmap(@NonNull
                                  android.graphics.Bitmap image,
                                  @NonNull
                                  Orientation imageOrientation,
                                  @NonNull
                                  Rectangle scanRegion,
                                  @NonNull
                                  ScanResultListener resultListener)

Perform recognition of image represented as Android Bitmap.

Parameters:

image - Image that needs to be recognized.

imageOrientation - Orientation of the bitmap image.

scanRegion - Region of image that needs to be recognized. Rectangle is given as percentages of image size - x coordinate and width are percentages of image width and y coordinate and height are percentages of image height. Therefore, rectangle(0.f, 0.f, 1.f, 1.f) represents the whole image, whilst rectangle(0.5f, 0.f, 0.5f, 1.f) represents the right half of the image.

resultListener - Result listener that will handle recognition done event.

Throws:

java.lang.IllegalStateException - if recognizer is not initialized or is currently working

java.lang.NullPointerException - if given null scan result listener

recognizeBitmapWithRecognizers

public final void recognizeBitmapWithRecognizers(@NonNull
                                                 android.graphics.Bitmap image,
                                                 @NonNull
                                                 Orientation imageOrientation,
                                                 @NonNull
                                                 ScanResultListener resultListener,
                                                 @NonNull
                                                 RecognizerBundle recognizerBundle)

Perform recognition of image represented as Android Bitmap.

Unlike method recognize, this method will apply given settings for recognition of current image. This may be much slower than using method recognize, but it is the only option if RecognizerRunnerView was initialized after this RecognizerRunner.

Parameters:

image - Image that needs to be recognized.

imageOrientation - Orientation of the bitmap image.

resultListener - Result listener that will handle recognition done event.

recognizerBundle - Recognizer bundle that will be used to perform this recognition.

Throws:

java.lang.IllegalStateException - if recognizer is not initialized or is currently working

java.lang.NullPointerException - if given null scan result listener

recognizeBitmapWithRecognizers

public final void recognizeBitmapWithRecognizers(@NonNull
                                                 android.graphics.Bitmap image,
                                                 @NonNull
                                                 Orientation imageOrientation,
                                                 @NonNull
                                                 Rectangle scanRegion,
                                                 @NonNull
                                                 ScanResultListener resultListener,
                                                 @NonNull
                                                 RecognizerBundle recognizerBundle)

Perform recognition of image represented as Android Bitmap.

Unlike method recognize, this method will apply given settings for recognition of current image. This may be much slower than using method recognize, but it is the only option if RecognizerRunnerView was initialized after this RecognizerRunner.

Parameters:

image - Image that needs to be recognized.

imageOrientation - Orientation of the bitmap image.

scanRegion - Region of image that needs to be recognized. Rectangle is given as percentages of image size - x coordinate and width are percentages of image width and y coordinate and height are percentages of image height. Therefore, rectangle(0.f, 0.f, 1.f, 1.f) represents the whole image, whilst rectangle(0.5f, 0.f, 0.5f, 1.f) represents the right half of the image.

resultListener - Result listener that will handle recognition done event.

recognizerBundle - Recognizer bundle that will be used to perform this recognition.

Throws:

java.lang.IllegalStateException - if recognizer is not initialized or is currently working

java.lang.NullPointerException - if given null scan result listener

resetRecognitionState

@AnyThread
public final void resetRecognitionState()

Resets the recognition state, i.e. clears the cached data and all scanning results. Recognition starts from the beginning.

resetRecognitionState

@AnyThread
public final void resetRecognitionState(boolean hardReset)

Resets the recognition state. If hard reset is requested, clears the cached data and all scanning results and recognition starts from the beginning. Otherwise, if soft reset is requested and the recognition is consisted of multiple steps, clears the scanning cache and results only for the current step.

Parameters:

hardReset - true to request hard reset, false for the soft reset.

recognizeImage

@UiThread
public final void recognizeImage(@NonNull
                                           Image image,
                                           @NonNull
                                           ScanResultListener resultListener)

Use this method to directly recognize Image object obtained via MetadataListener while recognizer is active.

Recognition will be performed with same settings that were used for initialization of recognizer singleton.

Please note that Image object will be disposed as soon as onMetadataAvailable method ends. You must clone the Image object by calling its clone() method to ensure Image lives long enough to be processed.

Parameters:

image - Image to be processed (usually obtained from DebugImageListener)

resultListener - Listener that will be invoked with recognition result.

recognizeImageWithRecognizers

@UiThread
public final void recognizeImageWithRecognizers(@NonNull
                                                          Image image,
                                                          @NonNull
                                                          ScanResultListener resultListener,
                                                          @NonNull
                                                          RecognizerBundle recognizerBundle)

Use this method to directly recognize Image object obtained via MetadataListener while recognizer is active. Please note that Image object will be disposed as soon as onMetadataAvailable method ends. You must clone the Image object by calling its clone() method to ensure Image lives long enough to be processed. Recognition will be performed with given recognition settings.

If error happens due to illegal settings, onError will be invoked of the DirectApiErrorListener that was set in initialize method.

Parameters:

image - Image to be processed (usually obtained from MetadataListener).

resultListener - Listener that will be invoked with recognition result.

recognizerBundle - Recognizer bundle that will be used to perform this recognition.

Throws:

java.lang.IllegalStateException - if recognizer is not initialized or is currently working or Image object is already disposed

java.lang.NullPointerException - if given null scan result listener

recognizeString

@UiThread
public final void recognizeString(@NonNull
                                            java.lang.String stringData,
                                            @NonNull
                                            ScanResultListener resultListener)

Use this method to directly recognize given string data without performing the OCR, while recognizer is active.

Recognition will be performed with same settings that were used for initialization of recognizer singleton.

Parameters:

stringData - String to be processed.

resultListener - Listener that will be invoked with recognition result.

Throws:

java.lang.IllegalStateException - if recognizer is not initialized or is currently working

java.lang.NullPointerException - if given null scan result listener

recognizeStringWithRecognizers

@UiThread
public final void recognizeStringWithRecognizers(@NonNull
                                                           java.lang.String stringData,
                                                           @NonNull
                                                           ScanResultListener resultListener,
                                                           @NonNull
                                                           RecognizerBundle recognizerBundle)

Use this method to directly recognize given string data without performing the OCR, while recognizer is active. Recognition will be performed with given recognition settings.

If error happens due to illegal settings, onError will be invoked of the DirectApiErrorListener that was set in initialize method.

Parameters:

stringData - String to be processed.

resultListener - Listener that will be invoked with recognition result.

recognizerBundle - Recognizer bundle that will be used to perform this recognition.

Throws:

java.lang.IllegalStateException - if recognizer is not initialized or is currently working

java.lang.NullPointerException - if given null scan result listener

cancel

public void cancel()

If there is ongoing recognition process, this method will request cancellation of it and wait for recognition process to complete. It is not defined whether ScanResultListener given to last recognition requiest will be called with result or not - in some cases it could happen, in some it would not.

terminate

public void terminate()

Terminates the native library.

setMetadataCallbacks

@AnyThread
public void setMetadataCallbacks(@Nullable
                                            MetadataCallbacks metadataCallbacks)

Sets the metadata callbacks that will obtain metadata during processing.

Parameters:

metadataCallbacks - collection of metadata callbacks tha will obtain metadata during processing. If set to null, all callbacks will be disabled.