Package com.microblink.directApi
Class RecognizerRunner
- java.lang.Object
-
- com.microblink.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 Description static class
RecognizerRunner.State
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method 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, boolean treatAsVideoFrame, ScanResultListener resultListener)
Use this method to directly recognize Image object obtained via MetadataListener while recognizer is active.void
recognizeImageWithRecognizers(Image image, boolean treatAsVideoFrame, 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.
-
-
-
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 initializedjava.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 workingjava.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 workingjava.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 workingjava.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 workingjava.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, boolean treatAsVideoFrame, @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)treatAsVideoFrame
- If set to true, image will be processed as part of video stream. This means that recognition will be optimized for speed and will rely on time-redundancy between consecutive video frames in order to yield best possible recognition result. If set to false, recognition will be optimized for processing single image - the processing may be slower but will not rely on time-redundant information between consecutive video frames.resultListener
- Listener that will be invoked with recognition result.
-
recognizeImageWithRecognizers
@UiThread public final void recognizeImageWithRecognizers(@NonNull Image image, boolean treatAsVideoFrame, @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.treatAsVideoFrame
- If set to true, image will be processed as part of video stream. This means that recognition will be optimized for speed and will rely on time-redundancy between consecutive video frames in order to yield best possible recognition result. If set to false, recognition will be optimized for processing single image - the processing may be slower but will not rely on time-redundant information between consecutive video frames.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 disposedjava.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 workingjava.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 workingjava.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 whetherScanResultListener
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.
-
-