目录

图片区域解码与下采样(ArkTS)

应用在处理大尺寸图片时，直接解码整张图片可能导致内存占用过高和解码耗时较长。通过区域解码和下采样解码功能，可以有效优化这一场景：

适用场景：

场景 推荐方式 说明
图片局部放大查看 区域解码 只解码需要查看的区域。
大图预览（如4K图片在手机屏幕显示） 下采样解码 降低分辨率，减少内存占用。
地图/全景图瓦片加载 组合使用 指定区域并指定输出尺寸。

区域解码

区域解码通过设置解码参数desiredRegion，指定需要解码的矩形区域。解码器仅解码该区域的数据。参数详情请参考Region。

[h2]开发步骤

  1. 参考使用ImageSource完成图片解码创建ImageSource实例。

  2. 设置desiredRegion参数执行区域解码。

    async DecodeRegion(imageSource: image.ImageSource): Promise<image.PixelMap | undefined> {
  let decodingOptions: image.DecodingOptions = {
    desiredRegion: {
      size: { width: 1000, height: 1000 },
      x: 0,
      y: 0
    }
  };

  try {
    let pixelMap = await imageSource.createPixelMap(decodingOptions);
    console.info('Succeeded in decoding region.');
    return pixelMap;
  } catch (error) {
    console.error(`Failed to decode region: ${error}.`);
    return undefined;
  }
}

[h2]使用限制

下采样解码

下采样解码通过设置解码参数desiredSize，指定期望输出的图片尺寸。解码器会根据期望尺寸输出PixelMap，减少最终的内存占用。

解码处理差异：

参数详情请参考DecodingOptions。

[h2]开发步骤

  1. 参考使用ImageSource完成图片解码创建ImageSource实例。

  2. 设置desiredSize参数执行下采样解码。

    async DownsampleDecode(imageSource: image.ImageSource): Promise<image.PixelMap | undefined> {
  let decodingOptions: image.DecodingOptions = {
    desiredSize: { width: 512, height: 512 }
  };

  try {
    let pixelMap = await imageSource.createPixelMap(decodingOptions);
    console.info('Succeeded in downsample decoding.');
    return pixelMap;
  } catch (error) {
    console.error(`Failed to downsample decode: ${error}.`);
    return undefined;
  }
}

区域解码与下采样组合使用

当同时设置desiredRegion和desiredSize时，需要通过cropAndScaleStrategy参数指定裁剪与缩放的先后顺序。

[h2]cropAndScaleStrategy策略

策略 常量值 操作顺序 说明
SCALE_FIRST 1 先缩放，再裁剪。 -
CROP_FIRST 2 先裁剪，再缩放。 推荐使用，可减少解码峰值内存。

推荐使用CROP_FIRST：先裁剪再缩放可精确控制裁剪区域，保证不同格式解码效果一致。

参数详情请参考CropAndScaleStrategy。

[h2]开发步骤

  1. 参考使用ImageSource完成图片解码创建ImageSource实例。

  2. 同时设置desiredRegion、desiredSize和cropAndScaleStrategy参数。

    async CombinedDecode(imageSource: image.ImageSource): Promise<image.PixelMap | undefined> {
  let decodingOptions: image.DecodingOptions = {
    desiredRegion: {
      size: { width: 2000, height: 2000 },
      x: 1000,
      y: 500
    },
    desiredSize: { width: 512, height: 512 },
    cropAndScaleStrategy: image.CropAndScaleStrategy.CROP_FIRST
  };

  try {
    let pixelMap = await imageSource.createPixelMap(decodingOptions);
    console.info('Succeeded in combined decoding.');
    return pixelMap;
  } catch (error) {
    console.error(`Failed to combined decode: ${error}.`);
    return undefined;
  }
}

注意事项