👋 你好,欢迎来到我的博客!我是【菜鸟学鸿蒙】
   我是一名在路上的移动端开发者,正从传统“小码农”转向鸿蒙原生开发的进阶之旅。为了把学习过的知识沉淀下来,也为了和更多同路人互相启发,我决定把探索 HarmonyOS 的过程都记录在这里。
  
  🛠️ 主要方向:ArkTS 语言基础、HarmonyOS 原生应用(Stage 模型、UIAbility/ServiceAbility)、分布式能力与软总线、元服务/卡片、应用签名与上架、性能与内存优化、项目实战,以及 Android → 鸿蒙的迁移踩坑与复盘。
  🧭 内容节奏:从基础到实战——小示例拆解框架认知、专项优化手记、实战项目拆包、面试题思考与复盘,让每篇都有可落地的代码与方法论。
  💡 我相信:写作是把知识内化的过程,分享是让生态更繁荣的方式。
  
   如果你也想拥抱鸿蒙、热爱成长,欢迎关注我,一起交流进步!🚀

前言

做图片浏览类或内容展示类应用时,经常会遇到一种情况:原始图片本身分辨率偏低,或者为了节省带宽使用了缩略图,放大显示后明显发虚。普通的双线性插值或 Lanczos 缩放只是在原有像素基础上做数学填充,对清晰度没有实质改善。HarmonyOS 的 VideoProcessingEngine Kit 提供了基于 AI 算法的图片超分能力,可以对低分辨率 PixelMap 进行增强处理,得到一张分辨率更高、细节更清晰的输出图。

这篇文章从能力约束检查开始,完整走一遍图片超分的接入流程,包括图片加载、超分调用和资源释放,并在最后整理几个容易出问题的地方。

一、普通放大为什么容易模糊

在 ArkUI 中,Image 组件对图片做放大显示本质上是 GPU 采样,常见的双线性插值算法在像素信息不足时,会用周围像素的加权平均值来"猜"新像素的颜色,结果边缘发虚、高频细节丢失。

这不是 ArkUI 的缺陷,而是所有基于几何变换的插值方法的上限。要真正提升图片清晰度,需要让模型"理解"图像内容,推断出更合理的高频纹理——这正是 AI 超分要做的事。

二、官方能力边界先确认清楚

VideoProcessingEngine Kit 的图片超分能力从 API Version 13 开始支持,对应 HarmonyOS 5.0.0(12) 及以上版本。

有几条约束必须提前清楚:

  • 设备限制:目前仅支持手机设备(Phone),不支持平板、折叠屏展开态、2in1 等其他形态。
  • 能力支持检查:并非所有手机型号都开放了该算力入口,调用前必须通过 isImageSuperResolutionSupported() 检查当前设备是否具备超分能力,检查结果为 false 时不应继续调用。
  • 输入格式:接受 image.PixelMap,需要在调用前完成图片解码。
  • 无需额外权限声明:图片超分本身不需要在 module.json5 中声明特殊权限,但读取沙箱外文件时仍需关注文件访问权限。

import 路径确认:

import { imageSuperResolution } from '@kit.VideoProcessingEngineKit';
import { image } from '@kit.ImageKit';

这两个包都属于系统 Kit,无需在 oh-package.json5 里手动添加三方依赖,直接 import 即可。

三、最小实践场景设计

目标是:把一张放在 rawfile 里的低分辨率 JPEG 图片,经过 AI 超分处理后,在同一个页面上与原图并排显示,直观对比清晰度差异。

涉及步骤:

  1. 检查设备能力
  2. 用 ResourceManager 读取 rawfile 图片,解码为 PixelMap
  3. 创建 ImageSuperResolution 实例
  4. 调用 process() 得到超分结果
  5. 分别绑定到两个 Image 组件
  6. 使用完毕后调用 destroy() 释放实例

四、核心代码实现

4.1 能力检查

这一步在页面加载时最先执行,如果设备不支持就不进入后续流程。

import { videoProcessingEngine, imageSuperResolution } from '@kit.VideoProcessingEngineKit';
import { image } from '@kit.ImageKit';

// 检查当前设备是否支持图片超分
const supported: boolean = videoProcessingEngine.isImageSuperResolutionSupported();
if (!supported) {
  console.error('当前设备不支持图片超分能力');
  // 根据业务逻辑决定是否降级展示原图
}

isImageSuperResolutionSupported() 是同步接口,直接取返回值即可,不需要 await。

4.2 读取原始图片,解码为 PixelMap

从 rawfile 读取图片文件,使用 image.createImageSource + createPixelMap 完成解码。

import { resourceManager } from '@ohos.resourceManager';

async function loadRawfilePixelMap(context: Context, rawfileName: string): Promise<image.PixelMap> {
  // 通过 ResourceManager 获取 rawfile 文件描述符
  const rm: resourceManager.ResourceManager = context.resourceManager;
  const rawFd = rm.getRawFdSync(rawfileName);

  // 创建 ImageSource
  const imageSource = image.createImageSource(rawFd.fd, {
    offset: rawFd.offset,
    length: rawFd.length
  });

  // 解码为 PixelMap,RGBA_8888 格式
  const pixelMap = await imageSource.createPixelMap({
    editable: false,
    desiredPixelFormat: image.PixelMapFormat.RGBA_8888
  });

  imageSource.release();
  return pixelMap;
}

getRawFdSync 返回的是文件描述符信息(包含 fd、offset、length),createImageSource 需要这三个字段才能正确定位 HAP 包内资源,直接传 fd 而不带 offset/length 在打包后可能取到错误数据。

4.3 创建超分实例并处理图片

ImageSuperResolution.create() 是异步接口,返回 Promise<ImageSuperResolution>。

async function runSuperResolution(
  context: Context,
  inputPixelMap: image.PixelMap
): Promise<image.PixelMap | null> {
  // 创建 ImageSuperResolution 实例
  let srInstance: imageSuperResolution.ImageSuperResolution | null = null;
  try {
    srInstance = await imageSuperResolution.ImageSuperResolution.create(context);

    // 执行超分处理,process() 接收 PixelMap 并返回增强后的 PixelMap
    const outputPixelMap = await srInstance.process(inputPixelMap);
    return outputPixelMap;
  } catch (err) {
    console.error(`图片超分失败: ${JSON.stringify(err)}`);
    return null;
  } finally {
    // 无论成功与否都要释放实例
    if (srInstance !== null) {
      srInstance.destroy();
    }
  }
}

4.4 页面展示:原图与超分结果并排对比

@Entry
@Component
struct ImageSuperResPage {
  @State originalPixelMap: image.PixelMap | null = null;
  @State enhancedPixelMap: image.PixelMap | null = null;
  @State isProcessing: boolean = false;
  @State isSupported: boolean = false;

  aboutToAppear(): void {
    // 检查能力
    this.isSupported = videoProcessingEngine.isImageSuperResolutionSupported();
  }

  async handleProcess(): Promise<void> {
    if (!this.isSupported) {
      return;
    }
    this.isProcessing = true;

    // 加载原始低分辨率图片
    const inputPixelMap = await loadRawfilePixelMap(getContext(this), 'low_res_sample.jpg');
    this.originalPixelMap = inputPixelMap;

    // 执行超分
    const result = await runSuperResolution(getContext(this), inputPixelMap);
    if (result !== null) {
      this.enhancedPixelMap = result;
    }

    this.isProcessing = false;
  }

  build() {
    Column({ space: 16 }) {
      Text('图片超分对比').fontSize(18).fontWeight(FontWeight.Bold)

      if (!this.isSupported) {
        Text('当前设备不支持图片超分').fontColor(Color.Red)
      }

      Row({ space: 12 }) {
        Column() {
          Text('原图').fontSize(14)
          if (this.originalPixelMap !== null) {
            Image(this.originalPixelMap)
              .width(160)
              .height(160)
              .objectFit(ImageFit.Contain)
          } else {
            Blank().width(160).height(160).backgroundColor('#F0F0F0')
          }
        }

        Column() {
          Text('超分结果').fontSize(14)
          if (this.enhancedPixelMap !== null) {
            Image(this.enhancedPixelMap)
              .width(160)
              .height(160)
              .objectFit(ImageFit.Contain)
          } else {
            Blank().width(160).height(160).backgroundColor('#F0F0F0')
          }
        }
      }

      if (this.isProcessing) {
        LoadingProgress().width(40).height(40)
        Text('处理中…').fontSize(13)
      } else {
        Button('开始超分处理')
          .enabled(this.isSupported)
          .onClick(() => {
            this.handleProcess();
          })
      }
    }
    .width('100%')
    .padding(20)
    .alignItems(HorizontalAlign.Center)
  }
}

两个 Image 组件分别绑定原始 PixelMap 和超分后的 PixelMap,用 width/height 控制显示尺寸,objectFit(ImageFit.Contain) 保持比例,方便观察清晰度差异。

五、几个关键点拆开看

process() 的输入尺寸限制

根据官方文档描述,process() 接受的输入 PixelMap 有分辨率范围要求。输入图片过大(超过超分模型的输入上限)或者格式不符(非 RGBA_8888)都可能导致处理失败。在解码阶段指定 desiredPixelFormat: image.PixelMapFormat.RGBA_8888 是比较安全的做法,官方示例中也采用此格式。

create() 每次调用都有开销

ImageSuperResolution.create(context) 内部会初始化 AI 模型,这个过程有一定耗时,不适合在列表滑动中对每张图重复创建。如果有批量超分需求,建议在页面 aboutToAppear 时创建一个实例,在 aboutToDisappear 时统一 destroy,而不是每次处理都重建。

destroy() 不能遗漏

ImageSuperResolution 实例绑定了底层 AI 推理资源,如果不调用 destroy(),资源不会被 GC 自动回收(Native 侧资源不在 JS 堆内),长期运行会造成资源泄漏。建议用 try/finally 结构确保 destroy 一定被执行,不管 process() 成功与否。

isImageSuperResolutionSupported() 是运行时检查,不是编译时保证

即使应用的 compileSdkVersion 满足 API 13,也必须在运行时调用这个函数再次确认。不同硬件平台的算力情况不同,返回 false 是正常情况,应该有对应的降级逻辑而不是直接崩溃。

六、容易踩坑的地方

问题一:rawfile 文件描述符处理不完整

直接用 getRawFdSync(name).fd 传给 createImageSource(fd),在真机打包后因为 rawfile 内偏移量不为 0,导致解码失败或解出错误图片。正确方式是同时传入 offset 和 length,如上面代码所示。

问题二:在非 Phone 设备上调用直接返回错误

ImageSuperResolution 文档明确写明"目前仅支持手机设备",如果应用需要支持平板或 2in1,必须在非 Phone 形态下完全绕过超分逻辑,否则 create() 或 process() 会抛出错误。isImageSuperResolutionSupported() 在这些设备上会返回 false,可以作为统一的判断入口。

问题三:process() 结果没有被持久引用就调用了 destroy()

如果 srInstance.destroy() 在 process() 返回的 PixelMap 赋值给 State 之前就执行,不会影响 PixelMap 本身(PixelMap 是独立对象),但写代码时要确保 outputPixelMap 引用已经安全保存后再走到 finally 里的 destroy,避免逻辑顺序混乱。

问题四:超分后直接用原始尺寸的 Image 组件展示

超分后 PixelMap 的分辨率比输入更高,如果 Image 组件的显示尺寸和原图一致,视觉上可能看不出区别。建议让超分结果的显示区域略大于原图,或者直接用 width: '100%' 铺满容器,才能观察到清晰度提升的效果。

七、出问题时的排查顺序

  1. 先查 API Version:确认 compileSdkVersion 和 targetSdkVersion 都 ≥ 13,否则 import 编译都过不去。
  2. 再查设备类型:只有 Phone 支持,先打印 deviceInfo.deviceType 确认运行环境。
  3. 再查 isImageSuperResolutionSupported() 返回值:返回 false 时不应继续往下调用,先确认这一步。
  4. 再查 PixelMap 格式:确认解码时指定了 RGBA_8888,不要用默认格式或 BGRA。
  5. 再查 rawfile 读取方式:确认 createImageSource 传入了完整的 fd + offset + length。
  6. 最后看 process() 的 catch 里的错误码:结合官方错误码文档定位具体原因。

开发经验总结

  • VideoProcessingEngine Kit 的图片超分从 API Version 13 起支持,仅限 Phone 设备,接入前必须做运行时能力检查。
  • ImageSuperResolution.create(context) 初始化开销不可忽视,批量场景下复用实例比每次重建更合理。
  • destroy() 是释放 Native 侧资源的唯一出口,try/finally 是最稳妥的写法。
  • rawfile 图片读取需要同时传 fd、offset、length,少了后两个在打包后会出问题。
  • 超分结果在 UI 上要给足够的显示空间才能直观感受到清晰度的变化,等比压缩回原始尺寸会掩盖超分效果。

如果你的应用里有类似"列表缩略图放大预览"的场景,可以对比一下:直接把缩略图放大和先过超分再展示,在边缘细节和文字清晰度上差异通常比较明显——这也是判断超分收益是否值得引入的最简单验证方式。

📝 写在最后

如果你觉得这篇文章对你有帮助,或者有任何想法、建议,欢迎在评论区留言交流!你的每一个点赞 👍、收藏 ⭐、关注 ❤️,都是我持续更新的最大动力!

我是一个在代码世界里不断摸索的小码农,愿我们都能在成长的路上越走越远,越学越强!

感谢你的阅读,我们下篇文章再见~👋

✍️ 作者:菜鸟不学编程
🧵 本文原创,转载请注明出处。

Logo

作为“人工智能6S店”的官方数字引擎,为AI开发者与企业提供一个覆盖软硬件全栈、一站式门户。

更多推荐