Package com.microblink.directApi

Class RecognizerRunner

  • public class RecognizerRunner
extends java.lang.Object
    RecognizerRunner singleton that can be used to perform recognition of Bitmaps and Images.

    • 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,
                                 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 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.