Skip to main content

Text Data Scanner | iOS Document Scanner

Text Data Scanner

ScanbotSdk.UI.startTextDataScanner(configuration: TextDataScannerConfiguration): Promise

Opens a Scanning UI to perform OCR and detect text data.

alt text

The Text Data Scanner is based on the OCR feature and thus requires the proper installation of the corresponding OCR language files (e.g. for English please add the file eng.traineddata). For more details on how to set up OCR language files please refer to the OCR section.

Use the API method ScanbotSdk.UI.startTextDataScanner(configuration: TextDataScannerConfiguration): Promise to start the Text Data Scanner UI.

Result:

The promise resolves to a result object with the following properties:

  • status - 'OK' If any text was detected; 'CANCELED' if the user canceled the operation (tapped on the "cancel" button).
  • result
    • text - the recognized text
    • confidence - confidence in the accuracy of the detection (0 - 100)

Options:

In order to start the Text Data Scanner, it is required to pass textDataScannerStep to the component's configuration.

A Text Data Scanner Step is defined through the interface TextDataScannerStep

export interface TextDataScannerStep {
/** User guidance hint text. */
guidanceText: string;

/** Validation pattern to automatically validate recognized text. '?' = any character, '#' - any digit, all other characters represent themselves. An empty string or nil value will disable the validation pattern. */
pattern: string;

/** If set to TRUE pattern validation also validates successfully if only a part of the whole recognized text matches the the validation pattern. If set to FALSE, the whole text must match the validation pattern. Applies to pattern validation only. Defaults to FALSE. */
shouldMatchSubstring: boolean;

/** The cameras zoom level preferred for this step. The actual zoom might be different from the preferred one to avoid clipping of finder area and maintain its aspect ratio and height */
preferredZoom: number;

/** The preferred finder aspect ratio. **/
aspectRatio: FinderAspectRatio;

/** The preferred height of the finder for zoom scale 1.0 (unzoomed). The actual finder height might change to maintain aspect ratio and to not clip the screen. Defaults to 40 points. */
unzoomedFinderHeight: number;

/** A string (list) of accepted characters during text recognition. If empty or nil, all characters are accepted. Defaults to nil. */
allowedSymbols: string;

/** Recognition strategy for the text. */
textFilterStrategy: TextFilterStrategy;

/** Threshold used to pause the detection after significant movement occurred. -1 is default value. Default = 0 for textFilterStrategy='DOCUMENT' and 1000 for textFilterStrategy='LCD_DOT_MATRIX_DISPLAY' */
significantShakeDelay: number;
}

All other configuration options are optional.

export interface TextDataScannerConfiguration {
/**
* Required configuration for the scanned item
*/
textDataScannerStep: TextDataScannerStep;
/**
* A string (list) of accepted characters during text recognition.
* If empty or nil, all characters are accepted.
* Defaults to nil.
*/
allowedSymbols?: string[];
/**
* The aspect ratio for the workflow steps region of interest and, equally, for the finder view.
* Defaults to 5:1.
*/
aspectRatio?: FinderAspectRatio;
/**
* The preferred camera module (default: BACK)
*/
cameraModule?: CameraModule;
/**
* Background color of the detection overlay.
*/
cameraOverlayColor?: string;
/**
* Whether the cancel button is hidden or not.
*/
cancelButtonHidden?: boolean;
/**
* String being displayed on the cancel button.
*/
cancelButtonTitle?: string;
/**
* Foreground color of the detection overlay.
*/
finderLineColor?: string;
/**
* Width of finder frame border. Default is 2.
*/
finderLineWidth?: number;
/**
* Foreground color of the description label.
*/
finderTextHintColor?: string;
/**
* Foreground color of the flash button when flash is off.
*/
flashButtonInactiveColor?: string;
/**
* Whether flash is toggled on or off.
*/
flashEnabled?: boolean;
/**
* A user guidance hint for this workflow step.
* The guidance hint is displayed while the workflow step is active.
*/
guidanceText?: string;
/**
* UI Interface orientation lock mode (PORTRAIT, LANDSCAPE, ALL)
*/
interfaceOrientation?: InterfaceOrientation;
/**
* The maximum number of accumulated video frames before the current recognition result is returned.
*/
maximumNumberOfAccumulatedFrames?: any;
/**
* The minimum equal results in accumulated video frames to count as valid.
*/
minimumNumberOfRequiredFramesWithEqualRecognitionResult?: any;
/**
* Maximum image side length (height or width) for OCR processing.
* If the initial image has longer side - it will be downscaled to the limit.
* Setting to 0 means no limit. Default is 0.
* Using this parameter might be useful for slower devices or to reduce processing load.
*/
ocrResolutionLimit?: any;
/**
* Sets a validation pattern to validate to automatically validate recognized text.
* ‘?’ = any character
* ‘#’ - any digit
* All other characters represent themselves.
*/
pattern?: string;
/**
* The cameras zoom level preferred for this step. The actual zoom might be different from the preferred one
* to avoid clipping of finder area and maintain its aspect ratio and height;
*/
preferredZoom?: number;
/**
* Enables or disables the recognition.
*/
recognitionEnabled?: boolean;
/**
* If set to true pattern validation also validates successfully if only a part of the whole recognized text matches
* the the validation pattern.
* If set to false, the whole text must match the validation pattern.
* Applies to pattern validation only. Defaults to false.
*/
shouldMatchSubstring?: boolean;
/**
* ! EXPERIMENTAL !
* Callback to clean a recognized text prior to validation. Filter out unwanted phrases and textual noise here.
* Default is nil.
* eg.
*
* (text) => {
* let out = text.toUpperCase();
* if (out[0] === 'X') {
* out = out.replace('X', '');
* }
* return out;
* }
*
* Notes:
* • Use JSStringToStringTextFunctionBuilder! Do not set this manually;
* • Do not reference any external library or any variable that is declared outside of the
* scope of the function
*/
stringSanitizerBlock?: JSStringToStringTextFunction;
/**
* 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.
*/
supportedLanguages?: string;
/**
* The title of the step.
* By default it is an empty.
*/
title?: string;
/**
* Recognition strategy for the text. Default is 'Document'.
*/
textFilterStrategy?: TextFilterStrategy;
/**
* Background color of the top bar.
*/
topBarBackgroundColor?: string;
/**
* Foreground color of the cancel button and when flash button is on.
*/
topBarButtonsColor?: string;
/**
* The preferred height of the finder for zoom scale 1.0 (unzoomed).
* The actual finder height might change to maintain aspect ratio and to not clip the screen.
* Defaults to 40 points.
*/
unzoomedFinderHeight?: number;
/**
* ! EXPERIMENTAL !
* Callback block for recognized text validation. If pattern validation is not powerful enough, you can
* specify your own validation block here. Defaults to nil.
* eg.
*
* (text) => {
* let firstLetter = text[0].toUpperCase();
* let length = text.length;
* return firstLetter === 'A' && length >= 4 && length < 20;
* }
*
* Notes:
* • Use JSStringToBoolTextFunctionBuilder! Do not set this manually;
* • Do not reference any external library or any variable that is declared outside of the
* scope of the function
*/
validationBlock?: JSStringToBoolTextFunction;
/**
* The color of the word boxes. It is recommended to use colors with alpha &lt; 0.5.
*/
wordBoxHighlightColor?: string;
/**
* Whether the word boxes should be shown.
*/
wordBoxHighlightEnabled?: boolean;
}

Want to scan longer than one minute?

Generate your free "no-strings-attached" Trial License and properly test the Scanbot SDK.

Get your free Trial License

What do you think of this documentation?


On this page

Scroll to top