• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1# Camera Metadata (ArkTS)
2<!--Kit: Camera Kit-->
3<!--Subsystem: Multimedia-->
4<!--Owner: @qano-->
5<!--SE: @leo_ysl-->
6<!--TSE: @xchaosioda-->
7
8Before developing a camera application, request permissions by following the instructions provided in [Camera Development Preparations](camera-preparation.md).
9
10Metadata is the description and context of image information returned by the camera application. It provides detailed data for the image information, such as the coordinates of a viewfinder frame for identifying a portrait in a photo or video.
11
12Metadata uses a tag (key) to find the corresponding data during parameter transfers and configurations, reducing memory copy operations.
13
14## How to Develop
15
16Read [Module Description](../../reference/apis-camera-kit/arkts-apis-camera.md) for the API reference.
17
181. Import the modules.
19   ```ts
20   import { camera } from '@kit.CameraKit';
21   import { BusinessError } from '@kit.BasicServicesKit';
22   ```
23
242. Obtain the metadata types supported by the current device from **supportedMetadataObjectTypes** in the [CameraOutputCapability](../../reference/apis-camera-kit/arkts-apis-camera-i.md#cameraoutputcapability) class, and then use [createMetadataOutput](../../reference/apis-camera-kit/arkts-apis-camera-CameraManager.md#createmetadataoutput) to create a metadata output stream.
25
26   ```ts
27   function getMetadataOutput(cameraManager: camera.CameraManager, cameraOutputCapability: camera.CameraOutputCapability): camera.MetadataOutput | undefined {
28     let metadataObjectTypes: Array<camera.MetadataObjectType> = cameraOutputCapability.supportedMetadataObjectTypes;
29     let metadataOutput: camera.MetadataOutput | undefined = undefined;
30     try {
31       metadataOutput = cameraManager.createMetadataOutput(metadataObjectTypes);
32     } catch (error) {
33       let err = error as BusinessError;
34       console.error(`Failed to createMetadataOutput, error code: ${err.code}`);
35     }
36     return metadataOutput;
37   }
38   ```
39
403. Call [Session.start](../../reference/apis-camera-kit/arkts-apis-camera-Session.md#start11) to start outputting metadata, and obtain the data through subscription to the **'metadataObjectsAvailable'** event. If the call fails, an error code is returned. For details, see [CameraErrorCode](../../reference/apis-camera-kit/arkts-apis-camera-e.md#cameraerrorcode).
41
42   For details about how to obtain preview output, see [Camera Preview (ArkTS)](camera-preview.md).
43
44   ```ts
45   async function startMetadataOutput(previewOutput: camera.PreviewOutput, metadataOutput: camera.MetadataOutput, cameraManager: camera.CameraManager): Promise<void> {
46     let cameraArray: Array<camera.CameraDevice> = [];
47     cameraArray = cameraManager.getSupportedCameras();
48     if (cameraArray.length == 0) {
49       console.error('no camera.');
50       return;
51     }
52     // Obtain the supported modes.
53     let sceneModes: Array<camera.SceneMode> = cameraManager.getSupportedSceneModes(cameraArray[0]);
54     let isSupportPhotoMode: boolean = sceneModes.indexOf(camera.SceneMode.NORMAL_PHOTO) >= 0;
55     if (!isSupportPhotoMode) {
56       console.error('photo mode not support');
57       return;
58     }
59     let cameraInput: camera.CameraInput | undefined = undefined;
60     cameraInput = cameraManager.createCameraInput(cameraArray[0]);
61     if (cameraInput === undefined) {
62       console.error('cameraInput is undefined');
63       return;
64     }
65     // Open the camera.
66     await cameraInput.open();
67     let session: camera.PhotoSession = cameraManager.createSession(camera.SceneMode.NORMAL_PHOTO) as camera.PhotoSession;
68     session.beginConfig();
69     session.addInput(cameraInput);
70     session.addOutput(previewOutput);
71     session.addOutput(metadataOutput);
72     await session.commitConfig();
73     await session.start();
74   }
75   ```
76
774. Call [Session.stop](../../reference/apis-camera-kit/arkts-apis-camera-Session.md#stop11) to stop outputting metadata. If the call fails, an error code is returned. For details, see [CameraErrorCode](../../reference/apis-camera-kit/arkts-apis-camera-e.md#cameraerrorcode).
78
79   ```ts
80   function stopMetadataOutput(session: camera.Session): void {
81     session.stop().then(() => {
82       console.info('Callback returned with session stopped.');
83     }).catch((err: BusinessError) => {
84       console.error(`Failed to session stop, error code: ${err.code}`);
85     });
86   }
87   ```
88
89## Status Listening
90
91During camera application development, you can listen for the status of metadata objects and output stream.
92
93- Register the **'metadataObjectsAvailable'** event to listen for metadata objects that are available. When a valid metadata object is detected, the callback function returns the metadata. This event can be registered when a MetadataOutput object is created.
94
95  ```ts
96  function onMetadataObjectsAvailable(metadataOutput: camera.MetadataOutput): void {
97    metadataOutput.on('metadataObjectsAvailable', (err: BusinessError, metadataObjectArr: Array<camera.MetadataObject>) => {
98      if (err !== undefined && err.code !== 0) {
99        return;
100      }
101      console.info('metadata output metadataObjectsAvailable');
102    });
103  }
104  ```
105
106  > **NOTE**
107  >
108  > Currently, only **FACE_DETECTION** is available for the metadata type. The metadata object is the rectangle of the recognized face, including the x-axis coordinate and y-axis coordinate of the upper left corner of the rectangle as well as the width and height of the rectangle.
109
110- Register the **'error'** event to listen for metadata stream errors. The callback function returns an error code when an API is incorrectly used. For details about the error code types, see [CameraErrorCode](../../reference/apis-camera-kit/arkts-apis-camera-e.md#cameraerrorcode).
111
112  ```ts
113  function onMetadataError(metadataOutput: camera.MetadataOutput): void {
114    metadataOutput.on('error', (metadataOutputError: BusinessError) => {
115      console.error(`Metadata output error code: ${metadataOutputError.code}`);
116    });
117  }
118  ```
119