【听见课堂 HarmonyOS NEXT 实战系列 34】ImageSource→PixelMap→Core Vision：OCR 资源生命周期全流程

m0_74969023

105人浏览 · 2026-09-03 09:40:00

m0_74969023 · 2026-09-03 09:40:00 发布

【听见课堂 HarmonyOS NEXT 实战系列 34】ImageSource→PixelMap→Core Vision：OCR 资源生命周期全流程

OCR 经常被简化成“传一张图，返回一段字”。在 HarmonyOS 真正运行时，URI 要先创建 ImageSource，再解码成 PixelMap，Core Vision OCR 还要初始化、识别并释放。任何一步抛异常，如果资源释放只写在成功分支，长课堂和连续扫描就可能累积内存与系统能力句柄。

听见课堂把整条资源链路集中在 ScanCaptureService.recognizeText()，并用嵌套 finally 保证释放顺序。本文逐段拆解当前实现，同时指出大图缩放、页面取消和压力测试尚未形成完整证据。

URI 到 ImageSource、PixelMap、Core Vision 与文本结果的生命周期

一、OCR 输入为什么是 URI

系统 CameraPicker 和 PhotoViewPicker 都返回 URI。页面不复制原图到数据库，也不把二进制长期保存在状态中，而是把 URI 传给能力层：

const recognizedText: string = await this.scanService.recognizeText(uri);

URI 是当前处理链路的输入句柄，不是业务记录的永久主键。

二、第一步创建 ImageSource

const imageSource: image.ImageSource = image.createImageSource(uri);

ImageSource 负责解析图片来源和后续解码。创建阶段可能因 URI 不可访问、格式不支持或资源失效而失败，因此调用方必须把它归类为图片读取问题，而不是 OCR 模型空结果。

三、第二步解码 PixelMap

let pixelMap: image.PixelMap | undefined = undefined;
pixelMap = await imageSource.createPixelMap();

Core Vision 接收的是视觉信息中的 PixelMap。原图越大，解码后的像素内存越高；一张压缩 JPEG 只有几 MB，不代表展开后的 PixelMap 也只有几 MB。

四、为什么 PixelMap 初始值是 undefined

如果 createPixelMap() 自身失败，变量仍为 undefined。释放时先判断：

if (pixelMap !== undefined) {
  await pixelMap.release();
}

这避免对不存在的资源调用 release()，也让异常路径保持可读。

五、第三步初始化 Core Vision OCR

let ocrInitialized: boolean = false;
ocrInitialized = await textRecognition.init();
if (!ocrInitialized) {
  throw new Error('Core Vision OCR initialization failed.');
}

初始化返回布尔值，不能默认成功。只有 true 才进入识别，并在释放阶段调用 textRecognition.release()。

六、第四步构造 VisionInfo

当前实现直接传入：

{ pixelMap: pixelMap }

官方 Core Vision 文本识别指南同样以 VisionInfo.pixelMap 作为 OCR 输入。页面层不需要知道模型配置，只消费最终文本或错误状态。

七、方向检测为何开启

{ isDirectionDetectionSupported: true }

课堂板书和课件照片可能横拍、竖拍或带轻微旋转。方向检测可帮助识别链路处理非正向文字，但它不是无限纠偏：大角度透视、模糊、反光和遮挡仍需拍摄提示与人工复核。

八、第五步只接收非空文本

const result = await textRecognition.recognizeText(visionInfo, config);
const recognizedText: string = result.value.trim();
if (recognizedText.length === 0) {
  throw new Error('Core Vision OCR returned empty text.');
}
return recognizedText;

先 trim() 可以过滤只包含空白字符的伪结果。空文本进入失败恢复，不显示“识别成功 0 字”。

成功、解码失败、初始化失败、空结果下的资源释放矩阵

九、最外层 finally 一定执行

recognizeText() 把识别主体放在 try 中，资源释放放在 finally。无论初始化失败、识别异常还是空文本主动抛错，都会进入释放阶段。

这比在每个 catch 里复制三段释放代码更不容易遗漏。

十、为什么释放顺序是 OCR→PixelMap→ImageSource

OCR 可能仍持有 PixelMap 相关能力，PixelMap 又由 ImageSource 解码而来。项目按依赖反向释放：先 textRecognition.release()，再 pixelMap.release()，最后 imageSource.release()。

这是一条清晰的所有权栈：后创建、上层依赖的资源先退出。

十一、嵌套 finally 防止释放中断

finally {
  try {
    if (ocrInitialized) await textRecognition.release();
  } finally {
    try {
      if (pixelMap !== undefined) await pixelMap.release();
    } finally {
      await imageSource.release();
    }
  }
}