Dissecting HarmonyOS 7 Core Vision Kit Image Super-Resolution API: Full Data Flow Guide

Introduction

This article continues from a previous overview of HarmonyOS 7 image super-resolution capabilities and dives into the actual API usage. It explains how an image travels from a PixelMap input to a super-resolution result via the Core Vision Kit.

Core API Objects

The image super-resolution capability resides in Core Vision Kit and involves five key objects: PixelMap – actual input and output pixel data. visionBase.ImageData – wraps PixelMap into a format the vision capability recognizes. visionBase.Request – the request object submitted to the Analyzer. ImageSRAnalyzer – creates, processes, and releases the image super-resolution capability. ISPResponse – carries the super-resolution processing result.

An analogy: PixelMap is the picture, ImageData is the packaging box, Request is the shipping label, ImageSRAnalyzer handles processing, and ISPResponse delivers the result back.

Prerequisites (as of 2026-08-15)

API version: 26.0.0 (Beta)

Project model: Stage

System capability: SystemCapability.AI.Vision.VisionBase Supported devices: Phone, Tablet, PC/2-in-1

One request processes a single image only

Core Vision Kit does not support emulator verification

Runtime check with canIUse('SystemCapability.AI.Vision.VisionBase') is required. Capability declaration, runtime detection, and PhotoViewPicker solve three separate problems and cannot replace each other.

Module Imports

import { imageSuperResolution, visionBase } from '@kit.CoreVisionKit';
import { image } from '@kit.ImageKit';
import { fileIo } from '@kit.CoreFileKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { BusinessError } from '@kit.BasicServicesKit';

Each kit serves a distinct purpose: CoreVisionKit for Analyzer/Request/Response, ImageKit for decoding to PixelMap, CoreFileKit for opening files by URI, MediaLibraryKit for launching the system picker, and BasicServicesKit for error handling.

Complete Data Flow Chain

The end-to-end type chain is:

Gallery URI
  ↓ CoreFileKit open file
FileDescriptor
  ↓ ImageKit decode
PixelMap
  ↓ Core Vision Kit wrap
ImageData
  ↓ put into inputData
Request
  ↓ ImageSRAnalyzer.process()
ISPResponse.pixelMap

Each object belongs to a different Kit and has a distinct lifecycle. A detailed breakdown:

URI (MediaLibraryKit) – locates user-selected resource; released when page no longer needs the selection.

File (CoreFileKit) – enables reading the URI file; close after creating ImageSource and decoding.

ImageSource (ImageKit) – parses image format and creates PixelMap; release after decoding.

PixelMap (ImageKit) – represents pixel data for system processing or UI display; release on image swap, result replacement, or page exit.

ImageData (Core Vision Kit) – wraps vision data into unified input; lives for the current request.

Request (Core Vision Kit) – describes one capability invocation; lives for the current request.

ISPResponse (imageSuperResolution) – carries the super-resolution result; release after extracting and taking ownership of its pixelMap.

This chain aids debugging: when encountering parameter errors, blank images, or memory growth, investigate each link rather than assuming the super-resolution integration failed.

Step-by-Step Implementation

1. Get URI from Gallery

const options = new photoAccessHelper.PhotoSelectOptions();
options.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
options.maxSelectNumber = 1;
const picker = new photoAccessHelper.PhotoViewPicker();
const result = await picker.select(options);
const uri = result.photoUris[0];

maxSelectNumber

is set to 1 because the API processes one image per request. Batch processing should be queued serially at the application layer.

2. Decode URI to PixelMap

const file = await fileIo.open(uri, fileIo.OpenMode.READ_ONLY);
const imageSource = image.createImageSource(file.fd);
const sourceSize = imageSource.getImageInfoSync().size;
const pixelMap = await imageSource.createPixelMap({
  desiredSize,
  desiredPixelFormat: image.PixelMapFormat.RGBA_8888
});

Control image dimensions at decode time. The example caps the longest edge at 1280 pixels for stable on-device demos (not a fixed API limit). Close the file handle in a finally block.

3. Wrap PixelMap into ImageData

const imageData: visionBase.ImageData = {
  pixelMap: inputPixelMap
};

ImageData.pixelMap

is the actual image input. Do not pass PixelMap directly to process() or guess field names.

4. Construct Request

const request: visionBase.Request = {
  inputData: imageData
};

Common errors triggering 401 parameter check failed:

// Wrong: process does not accept PixelMap directly
await analyzer.process(inputPixelMap);
// Wrong: inputData cannot hold PixelMap directly
const request = { inputData: inputPixelMap };
// Wrong: do not invent field names
const request = { image: inputPixelMap };

Debugging hierarchy for 401 errors:

Verify PixelMap decoded successfully ( getImageInfoSync()).

Check ImageData.pixelMap is valid.

Ensure Request.inputData is an ImageData instance (avoid as visionBase.Request to bypass type checks).

Confirm only one image per request.

Validate image size, format, device capability, OS version, real device (not emulator), canIUse returns true, supported region, and no concurrent same-feature request.

5. Call process and Retrieve Result

const response: imageSuperResolution.ISPResponse = await analyzer.process(request);
const outputPixelMap = response.pixelMap;
const outputSize = outputPixelMap.getImageInfoSync().size;

Input and output are separate PixelMap instances. When replacing the previous result, release the old PixelMap first:

this.outputImage?.release();
this.outputImage = response.pixelMap;

ImageSRAnalyzer Lifecycle

Three primary methods:

const analyzer = await imageSuperResolution.ImageSRAnalyzer.create();
const response = await analyzer.process(request);
await analyzer.destroy();

Official guidance places create() in aboutToAppear() and destroy() in aboutToDisappear(). Reuse a single Analyzer per page and process images serially; avoid recreating on every button click.

private analyzer: imageSuperResolution.ImageSRAnalyzer | undefined;

async aboutToAppear(): Promise<void> {
  if (canIUse('SystemCapability.AI.Vision.VisionBase')) {
    this.analyzer = await imageSuperResolution.ImageSRAnalyzer.create();
  }
}

async aboutToDisappear(): Promise<void> {
  if (this.analyzer) {
    await this.analyzer.destroy();
    this.analyzer = undefined;
  }
}

Guard Against Stale Async Results

process()

is asynchronous. If the user navigates away before completion, the returning result should not update UI. Use a page-active flag:

private pageActive: boolean = false;

async aboutToAppear(): Promise<void> {
  this.pageActive = true;
  this.analyzer = await imageSuperResolution.ImageSRAnalyzer.create();
}

async aboutToDisappear(): Promise<void> {
  this.pageActive = false;
  const analyzer = this.analyzer;
  this.analyzer = undefined;
  await analyzer?.destroy();
}

After obtaining the result, check the flag before updating state. Even if the page is inactive, the returned response.pixelMap must still be released to avoid leaks.

const response = await analyzer.process(request);
if (!this.pageActive) {
  response.pixelMap.release();
  return;
}
this.outputImage?.release();
this.outputImage = response.pixelMap;

Single-Image and Concurrency Limits

Core Vision Kit documentation states: the same user cannot concurrently invoke the same feature. Within one process, simultaneous calls may return "system busy"; across processes, only one processes at a time while others queue. Best practices:

One Analyzer per page.

Process one image at a time.

Queue batch tasks serially at the application layer.

Release unneeded objects after each image.

Never fire concurrent super-resolution for all images in a list.

Error Handling

Error objects may lack a code property. Directly interpolating error.code can yield "undefined". Safer pattern:

function describeError(error: BusinessError): string {
  if (typeof error.code === 'number') {
    return `处理失败（错误码 ${error.code}）：${error.message ?? '未知原因'}`;
  }
  if (error.message) {
    return `处理失败：${error.message}`;
  }
  return '图像超分处理失败，请更换图片后重试';
}

The API documents error 1018700001 Service exception. On service exceptions, log and restore page interactivity.

Complete Call Example

async function processImage(
  analyzer: imageSuperResolution.ImageSRAnalyzer,
  inputPixelMap: PixelMap
): Promise<PixelMap> {
  const imageData: visionBase.ImageData = {
    pixelMap: inputPixelMap
  };
  const request: visionBase.Request = {
    inputData: imageData
  };
  const response = await analyzer.process(request);
  return response.pixelMap;
}

The code is concise but assumes prior capability detection, image decoding, state management, and resource release are correctly handled.

Conclusion

Obtain image URI via system Picker.

Decode to PixelMap using Image Kit.

Wrap PixelMap into visionBase.ImageData.

Place ImageData into visionBase.Request.inputData.

Call ImageSRAnalyzer.process() and retrieve result from ISPResponse.pixelMap.

Additionally: reuse the Analyzer within the page lifecycle for serial processing; promptly release PixelMap, ImageSource, and other resources after use. In short: get the type chain right, then verify size, format, and device capability – debugging becomes much faster.

References

Huawei Developer Alliance: Image Super-Resolution Development Guide

Huawei Developer Alliance: imageSuperResolution API Reference

Huawei Developer Alliance: Core Vision Kit Overview and Constraints