目录

textRecognition (OCR)

The optical character recognition (OCR) service provides the capability of converting image information into character information. After printed materials such as bills, cards, tables, newspapers, and books are converted into image information through optical input methods like scanning or taking photos, OCR technologies are used to convert the image information into character information that can be processed by computers. This facilitates the extraction of characters, screen coordinates, and bounding boxes for users.

Currently, this service can recognize simplified Chinese, English, Japanese, Korean, and traditional Chinese. For optimal recognition results, ensure that the images are clear, the text is not obstructed, and the background is simple. This service is not suitable for blurry or severely tilted images.

Since: 4.0.0(10)

Modules to Import

import { textRecognition } from '@kit.CoreVisionKit';

TextRecognitionConfiguration

Describes the OCR configuration, which is used to specify whether text direction detection is supported.

System capability: SystemCapability.AI.OCR.TextRecognition

Model restriction: This API can be used only in the stage model.

Since: 4.0.0(10)

Name Type Read-Only Optional Description
isDirectionDetectionSupported boolean No Yes

Indicates whether text direction detection is supported.

The value true indicates yes, and the value false indicates no.

The default value is true. If you can determine that the current image is correct, you can set this parameter to false to improve performance.

VisionInfo

Visual information to be recognized. Currently, only the visual information about the PixelMap type in color data format RGBA_8888 is supported.

System capability: SystemCapability.AI.OCR.TextRecognition

Model restriction: This API can be used only in the stage model.

Since: 4.0.0(10)

Name Type Read-Only Optional Description
pixelMap image.PixelMap Yes No Image to be recognized. For details about the image requirements, see Constraints.

PixelPoint

Specifies the pixel point position.

System capability: SystemCapability.AI.OCR.TextRecognition

Model restriction: This API can be used only in the stage model.

Since: 4.0.0(10)

Name Type Read-Only Optional Description
x number Yes No Horizontal (X) coordinate of a pixel point.
y number Yes No Vertical (Y) coordinate of a pixel point.

TextWord

Describes the information about a word, including the content and the coordinates of its bounding box.

System capability: SystemCapability.AI.OCR.TextRecognition

Model restriction: This API can be used only in the stage model.

Since: 4.0.0(10)

Name Type Read-Only Optional Description
value string Yes No Text content of a word.
cornerPoints Array<PixelPoint> Yes No List of bounding box points of a word, which is returned clockwise. The first element in the array indicates the upper left corner.

TextLine

Describes a line of text in an image.

System capability: SystemCapability.AI.OCR.TextRecognition

Model restriction: This API can be used only in the stage model.

Since: 4.0.0(10)

Name Type Read-Only Optional Description
value string Yes No Text content of a line.
cornerPoints Array<PixelPoint> Yes No List of bounding box points of a text line, which is returned clockwise. The first element in the array indicates the upper left corner.
words Array<TextWord> Yes No Words contained in a line.

TextBlock

Describes a text block in an image.

System capability: SystemCapability.AI.OCR.TextRecognition

Model restriction: This API can be used only in the stage model.

Since: 4.0.0(10)

Name Type Read-Only Optional Description
value string Yes No Text content of a block.
lines Array<TextLine> Yes No Lines contained in a block.

TextRecognitionResult

Describes the OCR result, including the text content and coordinate information.

System capability: SystemCapability.AI.OCR.TextRecognition

Model restriction: This API can be used only in the stage model.

Since: 4.0.0(10)

Name Type Read-Only Optional Description
value string Yes No Recognized text content.
blocks Array<TextBlock> Yes No Specific block information in the text content.

textRecognition.init

init(): Promise<boolean>

Initializes the OCR service. This API uses a promise to return the result.

System capability: SystemCapability.AI.OCR.TextRecognition

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Returns:

Type Description
Promise<boolean>

Indicates whether the initialization is successful, which is returned through a promise.

The value true indicates yes, and the value false indicates no.

Example:

import { textRecognition } from '@kit.CoreVisionKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

async function initAndReleaseOCR() {
  // Initialize the OCR service.
  const initResult = await textRecognition.init();
  hilog.info(0x0000, 'textRecognitionSample', `OCR service initialization result:${initResult}`);

  if (initResult) {
    hilog.info(0x0000, 'textRecognitionSample', 'OCR service initialized successfully');

    // Add the code for using the OCR service.
    // Example: await textRecognition.recognizeText(...);

    // Release the OCR service after the usage is complete.
    await textRecognition.release();
    hilog.info(0x0000, 'textRecognitionSample', 'OCR service released successfully');
  } else {
    hilog.error(0x0000, 'textRecognitionSample', 'Failed to initialize OCR service');
  }
}

@Entry
@Component
struct Page {

  build() {
    Column(){
      Button('initAndReleaseOCR').onClick(() => {
        // Call the function.
        void initAndReleaseOCR();
      })
    }
  }
}

textRecognition.release

release(): Promise<void>

Releases the OCR service. This API uses a promise to return the result.

System capability: SystemCapability.AI.OCR.TextRecognition

Model restriction: This API can be used only in the stage model.

Since: 5.0.0(12)

Returns:

Type Description
Promise<void> Promise that returns no value.

Example:

import { textRecognition } from '@kit.CoreVisionKit';
import { hilog } from '@kit.PerformanceAnalysisKit';

async function initAndReleaseOCR() {
  // Initialize the OCR service.
  const initResult = await textRecognition.init();
  hilog.info(0x0000, 'textRecognitionSample', `OCR service initialization result:${initResult}`);

  if (initResult) {
    hilog.info(0x0000, 'textRecognitionSample', 'OCR service initialized successfully');

    // Add the code for using the OCR service.
    // Example: await textRecognition.recognizeText(...);

    // Release the OCR service after the usage is complete.
    await textRecognition.release();
    hilog.info(0x0000, 'textRecognitionSample', 'OCR service released successfully');
  } else {
    hilog.error(0x0000, 'textRecognitionSample', 'Failed to initialize OCR service');
  }
}

@Entry
@Component
struct Page {

  build() {
    Column(){
      Button('initAndReleaseOCR').onClick(() => {
        // Call the function.
        void initAndReleaseOCR();
      })
    }
  }
}

textRecognition.recognizeText

recognizeText(visionInfo: VisionInfo, callback: AsyncCallback<TextRecognitionResult>): void

Recognizes text contained in visual information. When the recognition is complete, the callback function is automatically called and the recognition result is returned. This API returns the result asynchronously through a callback.

System capability: SystemCapability.AI.OCR.TextRecognition

Model restriction: This API can be used only in the stage model.

Since: 4.0.0(10)

Parameters:

Parameter Type Mandatory Description
visionInfo VisionInfo Yes Visual information to be recognized.
callback AsyncCallback<TextRecognitionResult> Yes Callback function. When the recognition is successful, err is undefined and the text recognition result is returned. Otherwise, an error object is returned.

Error codes:

For details about the error codes, please refer to Core Vision Kit Error Codes.

ID Error Message
200 Run timed out, please try again later.
401 The parameter check failed.
1001400001 Failed to run OCR, please try again.
1001400002 The OCR service is abnormal.

Example:

import { textRecognition } from '@kit.CoreVisionKit';
import { image } from '@kit.ImageKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { fileIo } from '@kit.CoreFileKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';

async function recognizeTextTest() {
  let imageSource: image.ImageSource | undefined = undefined;
  let chooseImage: PixelMap | undefined = undefined;

  // Select an image from the gallery.
  let photoSelectOptions = new photoAccessHelper.PhotoSelectOptions();
  photoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
  photoSelectOptions.maxSelectNumber = 1;
  let photoPicker: photoAccessHelper.PhotoViewPicker = new photoAccessHelper.PhotoViewPicker();
  let photoSelectResult = await photoPicker.select(photoSelectOptions);
  let uri = photoSelectResult.photoUris[0];
  if (uri === undefined) {
    hilog.error(0x0000, 'OCRDemo', 'Failed to get uri.');
    return;
  }

  // Convert the image into a pixel map.
  let fileSource = await fileIo.open(uri, fileIo.OpenMode.READ_ONLY);
  imageSource = image.createImageSource(fileSource.fd);
  chooseImage = await imageSource.createPixelMap();
  if (!chooseImage) {
    return;
  }

  // Call the text recognition API.
  let visionInfo: textRecognition.VisionInfo = {
    pixelMap: chooseImage
  };
  textRecognition.recognizeText(visionInfo, (error: BusinessError, data: textRecognition.TextRecognitionResult) => {
    if (error.code !== 0) {
      hilog.error(0x0000, 'OCRDemo', `Failed to recognize text. Code: ${error.code}, message: ${error.message}`);
      return;
    }
    // The recognition is successful. Obtain the corresponding result.
    let recognitionString = JSON.stringify(data);
    hilog.info(0x0000, 'OCRDemo', `Succeeded in recognizing text: ${recognitionString}`);

    if (chooseImage && imageSource) {
      void chooseImage.release();
      void imageSource.release();
    }
  });
  if (fileSource) {
    await fileIo.close(fileSource);
  }
}

@Entry
@Component
struct Page {

  build() {
    Column(){
      Button('recognizeTextTest').onClick(() => {
        // Call the function.
        void recognizeTextTest();
      })
    }
  }
}

textRecognition.recognizeText

recognizeText(visionInfo: VisionInfo, configuration ?: TextRecognitionConfiguration): Promise<TextRecognitionResult>

Recognizes text contained in visual information. You can perform more detailed settings by customizing configuration items (for example, whether to support orientation detection). This API uses a promise to return the result.

System capability: SystemCapability.AI.OCR.TextRecognition

Model restriction: This API can be used only in the stage model.

Since: 4.0.0(10)

Parameters:

Parameter Type Mandatory Description
visionInfo VisionInfo Yes Visual information to be recognized.
configuration TextRecognitionConfiguration No Recognition configuration.

Returns:

Type Description
Promise<TextRecognitionResult> OCR result returned through a promise.

Error codes:

For details about the error codes, please refer to Core Vision Kit Error Codes.

ID Error Message
200 Run timed out, please try again later.
401 The parameter check failed.
1001400001 Failed to run OCR, please try again.
1001400002 The OCR service is abnormal.

Example:

import { textRecognition } from '@kit.CoreVisionKit';
import { image } from '@kit.ImageKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { fileIo } from '@kit.CoreFileKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';

async function recognizeTextTest() {
  let imageSource: image.ImageSource | undefined = undefined;
  let chooseImage: PixelMap | undefined = undefined;

  // Select an image from the gallery.
  let photoSelectOptions = new photoAccessHelper.PhotoSelectOptions();
  photoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
  photoSelectOptions.maxSelectNumber = 1;
  let photoPicker: photoAccessHelper.PhotoViewPicker = new photoAccessHelper.PhotoViewPicker();
  let photoSelectResult = await photoPicker.select(photoSelectOptions);
  let uri = photoSelectResult.photoUris[0];
  if (uri === undefined) {
    hilog.error(0x0000, 'OCRDemo', 'Failed to get uri.');
    return;
  }

  // Convert the image into a pixel map.
  let fileSource = await fileIo.open(uri, fileIo.OpenMode.READ_ONLY);
  imageSource = image.createImageSource(fileSource.fd);
  chooseImage = await imageSource.createPixelMap();
  if (!chooseImage) {
    return;
  }

  // Call the text recognition API.
  let visionInfo: textRecognition.VisionInfo = {
    pixelMap: chooseImage
  };
  let recognitionResult = await textRecognition.recognizeText(visionInfo);

  // The recognition is successful. Obtain the corresponding result.
  let recognitionString = JSON.stringify(recognitionResult);
  hilog.info(0x0000, 'OCRDemo', `Succeeded in recognizing text: ${recognitionString}`);

  if (chooseImage && imageSource) {
    void chooseImage.release();
    void imageSource.release();
  }
  if (fileSource) {
    await fileIo.close(fileSource);
  }
}

@Entry
@Component
struct Page {

  build() {
    Column(){
      Button('recognizeTextTest').onClick(() => {
        // Call the function.
        void recognizeTextTest();
      })
    }
  }
}

textRecognition.recognizeText

recognizeText(visionInfo: VisionInfo, configuration: TextRecognitionConfiguration, callback: AsyncCallback<TextRecognitionResult>): void

Recognizes text contained in visual information. You can customize the configuration for more detailed settings. When the recognition is complete, the callback function is automatically called and the recognition result is returned. This API returns the result asynchronously through a callback.

System capability: SystemCapability.AI.OCR.TextRecognition

Model restriction: This API can be used only in the stage model.

Since: 4.0.0(10)

Parameters:

Parameter Type Mandatory Description
visionInfo VisionInfo Yes Visual information to be recognized.
configuration TextRecognitionConfiguration Yes Recognition configuration.
callback AsyncCallback<TextRecognitionResult> Yes Callback function. When the recognition is successful, err is undefined and the text recognition result is returned. Otherwise, an error object is returned.

Error codes:

For details about the error codes, please refer to Core Vision Kit Error Codes.

ID Error Message
200 Run timed out, please try again later.
401 The parameter check failed.
1001400001 Failed to run OCR, please try again.
1001400002 The OCR service is abnormal.

Example:

import { textRecognition } from '@kit.CoreVisionKit';
import { image } from '@kit.ImageKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { fileIo } from '@kit.CoreFileKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';

async function recognizeTextTest() {
  let imageSource: image.ImageSource | undefined = undefined;
  let chooseImage: PixelMap | undefined = undefined;

  // Select an image from the gallery.
  let photoSelectOptions = new photoAccessHelper.PhotoSelectOptions();
  photoSelectOptions.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
  photoSelectOptions.maxSelectNumber = 1;
  let photoPicker: photoAccessHelper.PhotoViewPicker = new photoAccessHelper.PhotoViewPicker();
  let photoSelectResult = await photoPicker.select(photoSelectOptions);
  let uri = photoSelectResult.photoUris[0];
  if (uri === undefined) {
    hilog.error(0x0000, 'OCRDemo', 'Failed to get uri.');
    return;
  }

  // Convert the image into a pixel map.
  let fileSource = await fileIo.open(uri, fileIo.OpenMode.READ_ONLY);
  imageSource = image.createImageSource(fileSource.fd);
  chooseImage = await imageSource.createPixelMap();
  if (!chooseImage) {
    return;
  }

  // Call the text recognition API.
  let visionInfo: textRecognition.VisionInfo = {
    pixelMap: chooseImage
  };
  let textConfiguration: textRecognition.TextRecognitionConfiguration = {
    isDirectionDetectionSupported: false
  };
  textRecognition.recognizeText(
    visionInfo,
    textConfiguration,
    (error: BusinessError, data: textRecognition.TextRecognitionResult) => {
      if (error.code !== 0) {
        hilog.error(0x0000, 'OCRDemo', `Failed to recognize text. Code: ${error.code}, message: ${error.message}`);
        return;
      }
      // The recognition is successful. Obtain the corresponding result.
      let recognitionString = JSON.stringify(data);
      hilog.info(0x0000, 'OCRDemo', `Succeeded in recognizing text: ${recognitionString}`);

      if (chooseImage && imageSource) {
        void chooseImage.release();
        void imageSource.release();
      }
    }
  );
  if (fileSource) {
    await fileIo.close(fileSource);
  }
}

@Entry
@Component
struct Page {

  build() {
    Column(){
      Button('recognizeTextTest').onClick(() => {
        // Call the function.
        void recognizeTextTest();
      })
    }
  }
}

textRecognition.getSupportedLanguages

getSupportedLanguages(): Promise<Array<string>>

Obtains the list of languages supported by OCR. This API uses a promise to return the result.

System capability: SystemCapability.AI.OCR.TextRecognition

Model restriction: This API can be used only in the stage model.

Since: 4.0.0(10)

Returns:

Type Description
Promise<Array<string>> Promise object, which returns the List of Supported Languages

Error codes:

For details about the error codes, please refer to Core Vision Kit Error Codes.

ID Error Message
1001400001 Failed to run OCR, please try again.
1001400002 The OCR service is abnormal.

Example:

import { textRecognition } from '@kit.CoreVisionKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Page {
  @State supportedLanguages: string[] = [];

  aboutToAppear() {
    // Obtain the list of supported languages.
    textRecognition.getSupportedLanguages().then((data: Array<string>) => {
      this.supportedLanguages = data;
      let languageString = data.join(', ');
      hilog.info(0x0000, 'OCRDemo', `Succeeded in obtaining the language: ${languageString}`);
    }, (err: BusinessError) => {
      hilog.error(0x0000, 'OCRDemo', `Failed to obtain the language. Code: ${err.code}, message: ${err.message}`);
    });
  }

  build() {
    Column() {
      Text(this.supportedLanguages.join(', '))
    }
  }
}

textRecognition.getSupportedLanguages

getSupportedLanguages(callback: AsyncCallback<Array<string>>): void

Obtains the list of languages supported by OCR. This API returns the result asynchronously through a callback.

System capability: SystemCapability.AI.OCR.TextRecognition

Model restriction: This API can be used only in the stage model.

Since: 4.0.0(10)

Parameters:

Parameter Type Mandatory Description
callback AsyncCallback<Array<string>> Yes Callback function. If the recognition is successful, err is undefined and the List of Supported Languages is returned. Otherwise, an error object is returned.

Error codes:

For details about the error codes, please refer to Core Vision Kit Error Codes.

ID Error Message
1001400001 Failed to run OCR, please try again.
1001400002 The OCR service is abnormal.

Example:

import { textRecognition } from '@kit.CoreVisionKit';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { BusinessError } from '@kit.BasicServicesKit';

@Entry
@Component
struct Page {
  @State supportedLanguages: string[] = [];

  aboutToAppear() {
    // Obtain the list of supported languages.
    textRecognition.getSupportedLanguages((error: BusinessError, data: Array<string>) => {
      if (!error) {
        this.supportedLanguages = data;
        hilog.info(0x0000, 'OCRDemo', `Succeeded in obtaining the language: ${data}`);
      } else {
        hilog.error(0x0000, 'OCRDemo', `Failed to obtain the language. Code: ${error.code}, message: ${error.message}`);
      }
    });
  }

  build() {
    Column() {
      Text(this.supportedLanguages.join(', '))
    }
  }
}

List of Supported Languages

Language (English) Description
zh-CN Simplified Chinese
en English
ja Japanese
ko Korean
zh-TW Traditional Chinese