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.