Package com.microblink.blinkid.directApi

Class RecognizerRunner

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

  • Method Details

    • 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:
      IllegalStateException - if recognizer is already initialized
      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 still image represented as Android Bitmap. Mainly for the use cases when you need to recognize a single or more pre loaded Bitmaps, for example, from the gallery. If you want to recognize more consecutive images that come from the camera video stream, use #recognizeVideoImage(Image, ScanResultListener) instead.
      Parameters:
      image - Image that needs to be recognized.
      imageOrientation - Orientation of the bitmap image.
      resultListener - Result listener that will handle recognition done event.
      Throws:
      IllegalStateException - if recognizer is not initialized or is currently working
      NullPointerException - if given scan result listener is null

    • recognizeBitmap

      public final void recognizeBitmap(@NonNull android.graphics.Bitmap image, @NonNull Orientation imageOrientation, @NonNull Rectangle scanRegion, @NonNull ScanResultListener resultListener)
      Perform recognition of still image represented as Android Bitmap. Mainly for the use cases when you need to recognize a single or more pre loaded Bitmaps, for example, from the gallery. If you want to recognize more consecutive images that come from the camera video stream, use #recognizeVideoImage(Image, ScanResultListener) instead.
      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:
      IllegalStateException - if recognizer is not initialized or is currently working
      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 still image represented as Android Bitmap. Mainly for the use cases when you need to recognize a single or more pre loaded Bitmaps, for example, from the gallery. If you want to recognize more consecutive images that come from the camera video stream, use #recognizeVideoImageWithRecognizers(Image, ScanResultListener, RecognizerBundle) instead.

      Unlike method recognizeBitmap, this method will apply given settings for recognition of current image. This may be much slower than using method recognizeBitmap, 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:
      IllegalStateException - if recognizer is not initialized or is currently working
      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 still image represented as Android Bitmap. Mainly for the use cases when you need to recognize a single or more pre loaded Bitmaps, for example, from the gallery. If you want to recognize more consecutive images that come from the camera video stream, use #recognizeVideoImageWithRecognizers(Image, ScanResultListener, RecognizerBundle) instead.

      Unlike method recognizeBitmap, this method will apply given settings for recognition of current image. This may be much slower than using method recognizeBitmap, 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:
      IllegalStateException - if recognizer is not initialized or is currently working
      NullPointerException - if given null scan result listener

    • recognizeVideoBitmap

      public final void recognizeVideoBitmap(@NonNull android.graphics.Bitmap image, @NonNull Orientation imageOrientation, @NonNull ScanResultListener resultListener)
      Use this method to directly recognize Image from the video stream which are represented as an Android Bitmap. Mainly for the use cases when you need to recognize multiple consecutive frames that originally came from the camera video stream, for example, when a recording of scanning session needs to be processed.

      Recognition will be optimized for speed and will rely on time-redundancy between consecutive video frames in order to yield best possible recognition result.

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

      Parameters:
      image - Image that needs to be recognized.
      imageOrientation - Orientation of the bitmap image.
      resultListener - Result listener that will handle recognition done event.
      Throws:
      IllegalStateException - if recognizer is not initialized or is currently working
      NullPointerException - if given scan result listener is null

    • recognizeVideoBitmap

      public final void recognizeVideoBitmap(@NonNull android.graphics.Bitmap image, @NonNull Orientation imageOrientation, @NonNull Rectangle scanRegion, @NonNull ScanResultListener resultListener)
      Use this method to directly recognize Image from the video stream which are represented as an Android Bitmap. Mainly for the use cases when you need to recognize multiple consecutive frames that originally came from the camera video stream, for example, when a recording of scanning session needs to be processed.

      Recognition will be optimized for speed and will rely on time-redundancy between consecutive video frames in order to yield best possible recognition result.

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

      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:
      IllegalStateException - if recognizer is not initialized or is currently working
      NullPointerException - if given null scan result listener

    • recognizeVideoBitmapWithRecognizers

      public final void recognizeVideoBitmapWithRecognizers(@NonNull android.graphics.Bitmap image, @NonNull Orientation imageOrientation, @NonNull ScanResultListener resultListener, @NonNull RecognizerBundle recognizerBundle)
      Use this method to directly recognize Image from the video stream which are represented as an Android Bitmap. Mainly for the use cases when you need to recognize multiple consecutive frames that originally came from the camera video stream, for example, when a recording of scanning session needs to be processed.

      Recognition will be optimized for speed and will rely on time-redundancy between consecutive video frames in order to yield best possible recognition result.

      Unlike the method recognizeVideoBitmap, this method will apply given settings for recognition of current image. This may be much slower than using method recognizeVideoBitmap, 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:
      IllegalStateException - if recognizer is not initialized or is currently working
      NullPointerException - if given null scan result listener

    • recognizeVideoBitmapWithRecognizers

      public final void recognizeVideoBitmapWithRecognizers(@NonNull android.graphics.Bitmap image, @NonNull Orientation imageOrientation, @NonNull Rectangle scanRegion, @NonNull ScanResultListener resultListener, @NonNull RecognizerBundle recognizerBundle)
      Use this method to directly recognize Image from the video stream which are represented as an Android Bitmap. Mainly for the use cases when you need to recognize multiple consecutive frames that originally came from the camera video stream, for example, when a recording of scanning session needs to be processed.

      Recognition will be optimized for speed and will rely on time-redundancy between consecutive video frames in order to yield best possible recognition result.

      Unlike the method recognizeVideoBitmap, this method will apply given settings for recognition of current image. This may be much slower than using method recognizeVideoBitmap, 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:
      IllegalStateException - if recognizer is not initialized or is currently working
      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.

    • recognizeVideoImage

      @UiThread public final void recognizeVideoImage(@NonNull InputImage image, @NonNull ScanResultListener resultListener)
      Use this method to directly recognize Image from the video stream. Mainly for the use cases when you need to recognize multiple consecutive frames that come from the camera video stream, for example, when you use your own or third party camera management. You should use ImageBuilder methods to create Image from the raw camera frame.

      Recognition will be optimized for speed and will rely on time-redundancy between consecutive video frames in order to yield best possible recognition result.

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

      Please note that, in cases when you are not the owner of the Image object, 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.

    • recognizeVideoImageWithRecognizers

      @UiThread public final void recognizeVideoImageWithRecognizers(@NonNull InputImage image, @NonNull ScanResultListener resultListener, @NonNull RecognizerBundle recognizerBundle)
      Use this method to directly recognize Image from the video stream, with given recognition settings. Mainly for the use cases when you need to recognize multiple consecutive frames that come from the camera video stream, for example, when you use your own or third party camera management. You should use ImageBuilder methods to create Image from the raw camera frame.

      Recognition will be optimized for speed and will rely on time-redundancy between consecutive video frames in order to yield best possible recognition result.

      Please note that, in cases when you are not the owner of the Image object, you must clone the Image object by calling its clone() method to ensure Image lives long enough to be processed.

      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:
      IllegalStateException - if recognizer is not initialized or is currently working or Image object is already disposed
      NullPointerException - if given null scan result listener

    • recognizeStillImage

      @UiThread public final void recognizeStillImage(@NonNull InputImage image, @NonNull ScanResultListener resultListener)
      Use this method to directly recognize still Image. Mainly for the use cases when you need thorough scanning of single or few images which are not part of the video stream and you want to get best possible results from the single image.

      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.

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

      Please note that, in cases when you are not the owner of the Image object, 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.

    • recognizeStillImageWithRecognizers

      @UiThread public final void recognizeStillImageWithRecognizers(@NonNull InputImage image, @NonNull ScanResultListener resultListener, @NonNull RecognizerBundle recognizerBundle)
      Use this method to directly recognize still Image, with given recognition settings. Mainly for the use cases when you need thorough scanning of single or few images which are not part of the video stream and you want to get best possible results from the single image.

      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.

      Please note that, in cases when you are not the owner of the Image object, 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 MetadataListener).
      resultListener - Listener that will be invoked with recognition result.
      recognizerBundle - Recognizer bundle that will be used to perform this recognition.
      Throws:
      IllegalStateException - if recognizer is not initialized or is currently working or Image object is already disposed
      NullPointerException - if given null scan result listener

    • recognizeString

      @UiThread public final void recognizeString(@NonNull 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:
      IllegalStateException - if recognizer is not initialized or is currently working
      NullPointerException - if given null scan result listener

    • recognizeStringWithRecognizers

      @UiThread public final void recognizeStringWithRecognizers(@NonNull 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:
      IllegalStateException - if recognizer is not initialized or is currently working
      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.