com.microblink.directApi

Class Recognizer

java.lang.Object

com.microblink.directApi.Recognizer

public class Recognizer
extends java.lang.Object

DirectAPI Recognizer 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	Recognizer.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.
Recognizer.State	getCurrentState() Returns the current state of the recognizer.
static Recognizer	getSingletonInstance() Returns the recognizer singleton.
void	initialize(android.content.Context context, RecognitionSettings recognitionSettings, 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	recognizeBitmapWithSettings(android.graphics.Bitmap image, Orientation imageOrientation, Rectangle scanRegion, ScanResultListener resultListener, RecognitionSettings recognitionSettings) Perform recognition of image represented as Android Bitmap.
void	recognizeBitmapWithSettings(android.graphics.Bitmap image, Orientation imageOrientation, ScanResultListener resultListener, RecognitionSettings recognitionSettings) 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	recognizeImageWithSettings(Image image, ScanResultListener resultListener, RecognitionSettings recognitionSettings) Use this method to directly recognize Image object obtained via MetadataListener while recognizer is active.
void	setLicenseKey(android.content.Context context, java.lang.String licenseKey) Sets the license key required for unlocking the library.
void	setLicenseKey(java.lang.String licenseKey, java.lang.String licensee) Sets the license key required for unlocking the library.
void	setMetadataListener(MetadataListener metadataListener, MetadataSettings metadataSettings) Sets the listener that will obtain metadata that is being processed.
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

public static Recognizer getSingletonInstance()
                                       throws FeatureNotSupportedException

Returns the recognizer singleton.

Returns:

the recognizer singleton.

Throws:

FeatureNotSupportedException

getCurrentState

public final Recognizer.State getCurrentState()

Returns the current state of the recognizer.

Returns:

the current state of the recognizer.

setLicenseKey

public final void setLicenseKey(@NonNull
                                android.content.Context context,
                                @NonNull
                                java.lang.String licenseKey)
                         throws InvalidLicenceKeyException

Sets the license key required for unlocking the library.

Parameters:

context - Application context used for license checking.

licenseKey - License key.

Throws:

java.lang.IllegalStateException - if recognizer is not in offline state (use getCurrentState method to obtain the state)

InvalidLicenceKeyException - if licence key is invalid

setLicenseKey

public final void setLicenseKey(@NonNull
                                java.lang.String licenseKey,
                                @NonNull
                                java.lang.String licensee)
                         throws InvalidLicenceKeyException

Sets the license key required for unlocking the library. Use this method when having license key that allows usage of library in multiple different applications (i.e. license key not bound to application's package name).

Parameters:

licenseKey - License key.

licensee - Licensee to which license key is bound.

Throws:

java.lang.IllegalStateException - if recognizer is not in offline state (use getCurrentState method to obtain the state)

InvalidLicenceKeyException - if licence key is invalid

initialize

public final void initialize(@NonNull
                             android.content.Context context,
                             @NonNull
                             RecognitionSettings recognitionSettings,
                             @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 DirectAPI recognizer and RecognizerView. So if both RecognizerView and DirectAPI try to initialize the native library at the same time, the following will happen: - if first initialized from RecognizerView, this method will return false, indicating failure to initialize DirectAPI - if first initialized from here, method will return true, HOWEVER if after that native library is initialized again from RecognizerView, **RecognizerView's settings will be applied**, in that case calling recognize method will use RecognizerView's settings - to prevent that, you must use recognizeWithSettings method All in all, RecognizerView's settings always have priority over DirectAPI's settings.

Parameters:

context - Application context used for loading required resources.

recognitionSettings - Recognition settings 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

recognizeBitmapWithSettings

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

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 RecognizerView was initialized after this Recognizer.

Parameters:

image - Image that needs to be recognized.

imageOrientation - Orientation of the bitmap image.

resultListener - Result listener that will handle recognition done event.

recognitionSettings - Recognition settings 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

recognizeBitmapWithSettings

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

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 RecognizerView was initialized after this Recognizer.

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.

recognitionSettings - Recognition settings 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

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 ImageListener)

resultListener - Listener that will be invoked with recognition result.

recognizeImageWithSettings

@UiThread
public final void recognizeImageWithSettings(@NonNull
                                                       Image image,
                                                       @NonNull
                                                       ScanResultListener resultListener,
                                                       RecognitionSettings recognitionSettings)

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.

recognitionSettings - Recognition settings 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

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.

setMetadataListener

public void setMetadataListener(MetadataListener metadataListener,
                                MetadataSettings metadataSettings)

Sets the listener that will obtain metadata that is being processed.

Parameters:

metadataListener - metadata listener that will be notified about available metadata

metadataSettings - settings defining which metadata should be reported to metadata listener