b4415e2d创建于 2025年12月20日历史提交

Using ImageSource to Decode Pictures

Image decoding refers to the process of decoding an image in a supported format (JPEG and HEIF currently) into a picture.

How to Develop

Read the API reference for APIs related to image decoding.

Import the image module.

// Import the required modules.
import { image } from '@kit.ImageKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { common } from '@kit.AbilityKit';
import { fileIo as fs } from '@kit.CoreFileKit';
import { resourceManager } from '@kit.LocalizationKit';

DecodingPicture.ets

Obtain an image.

Method 1: Directly obtain the image through the sandbox path. This method applies only to images in the application sandbox path. For details about how to obtain the sandbox path, see Obtaining Application File Paths. For details about the application sandbox and how to push files to the application sandbox directory, see File Management.
```
function getFilePath(context: Context, fileName: string): string {
  const filePath: string = context.cacheDir + '/' + fileName;
  return filePath;
}
```
CodecUtility.ets

Method 2: Obtain the file descriptor of the image through the sandbox path. For details, see file.fs API Reference. To use this method, you must import the @kit.CoreFileKit module first.

function getFileFd(context: Context, fileName: string): number | undefined {
  const filePath: string = context.cacheDir + '/' + fileName;
  const file: fs.File = fs.openSync(filePath, fs.OpenMode.READ_ONLY);
  const fd: number = file?.fd;
  return fd;
}

CodecUtility.ets

Method 3: Obtain the array buffer of the resource file through the resource manager. For details, see ResourceManager API Reference. To use this method, you must import the @kit.LocalizationKit module first.

async function getFileBuffer(context: Context, fileName: string): Promise<ArrayBuffer | undefined> {
  try {
    const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
    // Obtain the resource file content. The Uint8Array is returned.
    const fileData: Uint8Array = await resourceMgr.getRawFileContent(fileName);
    console.info('Successfully get the RawFileContent.');
    // Convert the array to an ArrayBuffer and return the ArrayBuffer.
    const buffer: ArrayBuffer = fileData.buffer.slice(0);
    return buffer;
  } catch (error) {
    console.error(`Failed to get the RawFileContent with error: ${error}.`);
    return undefined;
  }
}

CodecUtility.ets

Method 4: Obtain the raw file descriptor of the resource file through the resource manager. For details, see ResourceManager API Reference. To use this method, you must import the @kit.LocalizationKit module first.

async function getRawFd(context: Context, fileName: string): Promise<resourceManager.RawFileDescriptor | undefined> {
  try {
    const resourceMgr: resourceManager.ResourceManager = context.resourceManager;
    const rawFileDescriptor: resourceManager.RawFileDescriptor = await resourceMgr.getRawFd(fileName);
    console.info('Successfully get the RawFileDescriptor.');
    return rawFileDescriptor;
  } catch (error) {
    console.error(`Failed to get the RawFileDescriptor with error: ${error}.`);
    return undefined;
  }
}

CodecUtility.ets

Create an ImageSource instance.
- Method 1: Create an ImageSource instance using the sandbox path. The sandbox path can be obtained by using method 1 in step 2.
```
// path indicates the obtained sandbox path.
const imageSource : image.ImageSource = image.createImageSource(filePath);
```
  CodecUtility.ets
- Method 2: Create an ImageSource instance using the file descriptor. The file descriptor can be obtained by using method 2 in step 2.
```
// fd is the obtained file descriptor.
const imageSource: image.ImageSource = image.createImageSource(fd);
```
  CodecUtility.ets
- Method 3: Create an ImageSource instance using an array buffer. The array buffer can be obtained by using method 3 in step 2.
```
const imageSource: image.ImageSource = image.createImageSource(buffer);
```
  CodecUtility.ets
- Method 4: Create an ImageSource instance using the raw file descriptor of the resource file. The raw file descriptor can be obtained by using method 4 in step 2.
```
const imageSource: image.ImageSource = image.createImageSource(rawFileDescriptor);
```
  CodecUtility.ets

Set DecodingOptions and decode the image to obtain a picture. Manipulate the picture, for example, obtaining an auxiliary picture. For details about how to manipulate a picture and auxiliary picture, see Image API.

Carry out decoding after the setting.

async createPicture(imageSource : image.ImageSource | undefined, isReturnAux: Boolean)
  : Promise<image.PixelMap | undefined | image.Picture> {
  // Set the decoding options.
  let options: image.DecodingOptionsForPicture = {
    desiredAuxiliaryPictures: [image.AuxiliaryPictureType.GAINMAP] // GAINMAP indicates the type of the auxiliary picture to be decoded.
  };
  let returnPixelMap: image.PixelMap | undefined = undefined;
  // Create a Picture instance.
  try {
    let picture = await imageSource?.createPicture(options);
    if (picture) {
      // Return the auxiliary picture obtained after decoding.
      if (isReturnAux) {
        // type is the type of the auxiliary picture contained in the decoding options.
        let type: image.AuxiliaryPictureType = image.AuxiliaryPictureType.GAINMAP;
        let auxPicture: image.AuxiliaryPicture | null = picture.getAuxiliaryPicture(type);
        // Obtain the information of the auxiliary picture.
        if (auxPicture != null) {
          let auxInfo: image.AuxiliaryPictureInfo = auxPicture.getAuxiliaryPictureInfo();
          console.info('GetAuxiliaryPictureInfo type: ' + auxInfo.auxiliaryPictureType +
            ' height: ' + auxInfo.size.height + ' width: ' + auxInfo.size.width +
            ' rowStride: ' + auxInfo.rowStride + ' pixelFormat: ' + auxInfo.pixelFormat +
            ' colorSpace: ' + auxInfo.colorSpace);
          // Read data of the auxiliary picture and write the data to an ArrayBuffer.
          try {
            let pixelsBuffer = await auxPicture.readPixelsToBuffer();
            let opts: image.InitializationOptions = { size: auxInfo.size };
            try {
              returnPixelMap = image.createPixelMapSync(pixelsBuffer, opts) as image.PixelMap;
              console.info(`Create PixelMap with buffer successfully.`);
            } catch (error) {
              console.error(`Create PixelMap failed with ${error}.`);
            }
          } catch (error) {
            console.error(`Read pixels to buffer failed, error.code: ${error.code},
              error.message: ${error.message}`);
          }
          auxPicture.release();
        }
        return returnPixelMap;
      } else {
        return picture; // Return the decoded Picture instance.
      }
    }
    return returnPixelMap;
  } catch (error) {
    console.error(`Create picture failed: ${error}.`);
  }
  return returnPixelMap;
}

CodecUtility.ets

Release the Picture instance.

Ensure that the asynchronous operations of the Picture instance have finished executing. After these variables are no longer needed, you can manually call the APIs below to release it.
```
async release(picture: image.Picture) {
  picture?.release();
}
```
CodecUtility.ets