SBSDKOpticalTextRecognizer
@interface SBSDKOpticalTextRecognizer : NSObject
A factory class to enqueue and execute optical character recognition operations: the heart of the Scanbot SDK OCR module. It performs OCR operations on either a single image or a collection of images, see SBSDKImageStoring. Additionally it can perform a standalone page analysis on a single image. All of the operations are dispatched to a single serial queue to ensure low memory footprint and optimum CPU load.
Any text recognition operation will fail with an error if all of the specified languages are missing as language files. If the specified languages are partially available a warning will be logged, but the operation executes without using the missing languages. Please see the section “Optical Character Recognition” of the main SDK documentation for more details about the OCR language files.
The number of languages passed to OCR operations have a significant impact on the performance: the more languages, the slower the recognition process.
-
Returns a list of the two-letter ISO 639-1 language codes that are retrieved from the current NSLocale and the users preferred languages. Note: This is not a list of installed languages but of languages with training data available.
Declaration
Objective-C
+ (nonnull NSArray<NSString *> *)userPreferredLanguages;
Swift
class func userPreferredLanguages() -> [String]
Return Value
NSArray of NSString objects, each being a two-letter ISO 639-1 language code.
-
Returns a list of all installed two-letter ISO 639-1 language codes.
Declaration
Objective-C
+ (nonnull NSArray<NSString *> *)installedLanguages;
Swift
class func installedLanguages() -> [String]
Return Value
NSArray of NSString objects, each being a two-letter ISO 639-1 language code.
-
Asynchronously recognizes text on a set of images with the specified languages and calls the completion handler upon completion. If pdfOutputURL is a valid file URL a searchable PDF is created and written to the specified URL. A searchable PDF contains selectable and searchable text.
- SBSDKResultInfoImageStorageKey: the image storage as SBSDKImageStoring
- SBSDKResultInfoOCRResultsKey: the OCR results as SBSDKOCRResult
SBSDKResultInfoDestinationFileURLKey: the file URL of the output PDF
Declaration
Objective-C
+ (nullable SBSDKProgress *)recognizeText:(nonnull id<SBSDKImageStoring>)storage copyImageStorage:(BOOL)copyStorage indexSet:(nullable NSIndexSet *)indices languageString:(nullable NSString *)languageString pdfOutputURL:(nullable NSURL *)pdfOutputURL completion:(nullable SBSDKCompletionHandler) completionHandler;
Swift
class func recognizeText(_ storage: SBSDKImageStoring, copyImageStorage copyStorage: Bool, indexSet indices: IndexSet?, languageString: String?, pdfOutputURL: URL?, completion completionHandler: SBSDKCompletionHandler? = nil) -> SBSDKProgress?
Parameters
storage
The image storage containing the images to be recognized. Must not be nil, & contains at least 1 image
copyStorage
Whether the receiver should make a physical copy of the image storage for the operation or not. If set to NO, you must make sure that the image storage is not mutated while the operation is running. Setting YES makes a physical copy of the files in the storage, using up disk memory, but protecting it against mutation.
indices
An NSIndexSet specifying the indices of the images in the image storage that you want to recognize. Pass nil if you want to select all images. Invalid indices are ignored.
languageString
A string of two-letter ISO 639-1 language codes, separated by ‘+’, the OCR engine should use for recognition. E.g. “de+en” (german and english) “ar+he+ja” (arabic, hebrew and japanese). If the string is invalid or nil the user preferred languages are used. Ignores white spaces, invalid languages and invalid characters.
pdfOutputURL
If not nil and a valid file URL a searchable PDF is rendered and saved to this URL.
completionHandler
The completionHandler that is being called upon completion of the operation. Called on main thread. The result info dictionary contains values for the following keys:
Return Value
An SBSDKProgress object that can be used to observe the operations progress and to cancel the operation.
-
Asynchronously recognizes text on a set of images with the specified languages and calls the completion handler upon completion. If pdfOutputURL is a valid file URL a searchable PDF is created and written to the specified URL. A searchable PDF contains selectable and searchable text.
- SBSDKResultInfoImageStorageKey: the image storage as SBSDKImageStoring
- SBSDKResultInfoOCRResultsKey: the OCR results as SBSDKOCRResult
SBSDKResultInfoDestinationFileURLKey: the file URL of the output PDF
Declaration
Objective-C
+ (nullable SBSDKProgress *) recognizeText:(nonnull id<SBSDKImageStoring>)storage copyImageStorage:(BOOL)copyStorage indexSet:(nullable NSIndexSet *)indices languageString:(nullable NSString *)languageString encrypter:(nullable id<SBSDKStorageCrypting>)encrypter pdfOutputURL:(nullable NSURL *)pdfOutputURL completion:(nullable SBSDKCompletionHandler)completionHandler;
Swift
class func recognizeText(_ storage: SBSDKImageStoring, copyImageStorage copyStorage: Bool, indexSet indices: IndexSet?, languageString: String?, encrypter: SBSDKStorageCrypting?, pdfOutputURL: URL?, completion completionHandler: SBSDKCompletionHandler? = nil) -> SBSDKProgress?
Parameters
storage
The image storage containing the images to be recognized. Must not be nil, & contains at least 1 image
copyStorage
Whether the receiver should make a physical copy of the image storage for the operation or not. If set to NO, you must make sure that the image storage is not mutated while the operation is running. Setting YES makes a physical copy of the files in the storage, using up disk memory, but protecting it against mutation.
indices
An NSIndexSet specifying the indices of the images in the image storage that you want to recognize. Pass nil if you want to select all images. Invalid indices are ignored.
languageString
A string of two-letter ISO 639-1 language codes, separated by ‘+’, the OCR engine should use for recognition. E.g. “de+en” (german and english) “ar+he+ja” (arabic, hebrew and japanese). If the string is invalid or nil the user preferred languages are used. Ignores white spaces, invalid languages and invalid characters.
encrypter
The encrypter used to encrypt the PDF file. If nil, no encryption is used.
pdfOutputURL
If not nil and a valid file URL a searchable PDF is rendered and saved to this URL.
completionHandler
The completionHandler that is being called upon completion of the operation. Called on main thread. The result info dictionary contains values for the following keys:
Return Value
An SBSDKProgress object that can be used to observe the operations progress and to cancel the operation.
-
Synchronously recognizes text on a set of images with the specified languages and calls the completion handler upon completion. If pdfOutputURL is a valid file URL a searchable PDF is created and written to the specified URL. A searchable PDF contains selectable and searchable text.
Declaration
Objective-C
+ (nullable SBSDKOCRResult *) recognizeText:(nonnull id<SBSDKImageStoring>)storage indexSet:(nullable NSIndexSet *)indices languageString:(nullable NSString *)languageString pdfOutputURL:(nullable NSURL *)pdfOutputURL error:(NSError *_Nullable *_Nullable)outError;
Swift
class func recognizeText(_ storage: SBSDKImageStoring, indexSet indices: IndexSet?, languageString: String?, pdfOutputURL: URL?) throws -> SBSDKOCRResult
Parameters
storage
The image storage containing the images to be recognized. Must not be nil, & contains at least 1 image
indices
An NSIndexSet specifying the indices of the images in the image storage that you want to recognize. Pass nil if you want to select all images. Invalid indices are ignored.
languageString
A string of two-letter ISO 639-1 language codes, separated by ‘+’, the OCR engine should use for recognition. E.g. “de+en” (german and english) “ar+he+ja” (arabic, hebrew and japanese). If the string is invalid or nil the user preferred languages are used. Ignores white spaces, invalid languages and invalid characters.
pdfOutputURL
If not nil and a valid file URL a searchable PDF is rendered and saved to this URL.
outError
A pointer to an NSError object.
Return Value
An SBSDKOCRResult containing the result of the text recognition. Nil if an error occurred.
-
Synchronously recognizes text on a set of images with the specified languages and calls the completion handler upon completion. If pdfOutputURL is a valid file URL a searchable PDF is created and written to the specified URL. A searchable PDF contains selectable and searchable text.
Declaration
Objective-C
+ (nullable SBSDKOCRResult *) recognizeText:(nonnull id<SBSDKImageStoring>)storage indexSet:(nullable NSIndexSet *)indices languageString:(nullable NSString *)languageString encrypter:(nullable id<SBSDKStorageCrypting>)encrypter pdfOutputURL:(nullable NSURL *)pdfOutputURL error:(NSError *_Nullable *_Nullable)outError;
Swift
class func recognizeText(_ storage: SBSDKImageStoring, indexSet indices: IndexSet?, languageString: String?, encrypter: SBSDKStorageCrypting?, pdfOutputURL: URL?) throws -> SBSDKOCRResult
Parameters
storage
The image storage containing the images to be recognized. Must not be nil, & contains at least 1 image
indices
An NSIndexSet specifying the indices of the images in the image storage that you want to recognize. Pass nil if you want to select all images. Invalid indices are ignored.
languageString
A string of two-letter ISO 639-1 language codes, separated by ‘+’, the OCR engine should use for recognition. E.g. “de+en” (german and english) “ar+he+ja” (arabic, hebrew and japanese). If the string is invalid or nil the user preferred languages are used. Ignores white spaces, invalid languages and invalid characters.
encrypter
The encrypter used to encrypt the PDF file. If nil, no encryption is used.
pdfOutputURL
If not nil and a valid file URL a searchable PDF is rendered and saved to this URL.
outError
A pointer to an NSError object.
Return Value
An SBSDKOCRResult containing the result of the text recognition. Nil if an error occurred.
-
Recognizes text within a specified area on a single image with the specified languages and calls the completion handler upon completion.
- SBSDKResultInfoSourceFileURLKey: the file URL of the input image as NSURL
SBSDKResultInfoOCRResultsKey: the OCR results as SBSDKOCRResult
Declaration
Objective-C
+ (nullable SBSDKProgress *)recognizeText:(nonnull NSURL *)imageURL rectangle:(CGRect)rectangle languageString:(nullable NSString *)languageString completion:(nullable SBSDKCompletionHandler) completionHandler;
Swift
class func recognizeText(_ imageURL: URL, rectangle: CGRect, languageString: String?, completion completionHandler: SBSDKCompletionHandler? = nil) -> SBSDKProgress?
Parameters
imageURL
The file URL at which the image is located. Must not be nil.
rectangle
A rectangle defining the boundaries of where to recognize text. Pass CGRectZero to recognize the whole image.
languageString
A string of two-letter ISO 639-1 language codes, separated by ‘+’, the OCR engine should use for recognition. E.g. “de+en” (german and english) “ar+he+ja” (arabic, hebrew and japanese). If the string is invalid or nil the user preferred languages are used. Ignores white spaces, invalid languages and invalid characters.
completionHandler
The completionHandler that is being called upon completion of the operation. Called on main thread. The result info dictionary contains values for the following keys:
Return Value
An SBSDKProgress object that can be used to observe the operations progress and to cancel the operation.
-
Runs a basic page layout analysis asynchronously on the given image and calls the completion handler upon completion. The result contains information about general text orientation, writing direction, textline order and an angle to deskew the image.
- SBSDKResultInfoSourceFileURLKey: the file URL of the input image as NSURL
SBSDKResultInfoPageAnalyzerResultsKey: the page analysis result as SBSDKPageAnalyzerResult.
Declaration
Objective-C
+ (nullable SBSDKProgress *) analyseImagePageLayout:(nonnull NSURL *)imageURL completion:(nullable SBSDKCompletionHandler)completionHandler;
Swift
class func analyseImagePageLayout(_ imageURL: URL, completion completionHandler: SBSDKCompletionHandler? = nil) -> SBSDKProgress?
Parameters
imageURL
The file URL at which the image is located. Must not be nil.
completionHandler
The completionHandler that is being called upon completion of the operation. Called on main thread. The result info dictionary contains values for the following keys:
Return Value
An SBSDKProgress object that can be used to observe the operations progress and to cancel the operation.