《图片抠图》一、subjectSegmentation使用指南-深圳市維司達科技有限公司

HarmonyOS 主体分割（subjectSegmentation）完全使用指南：端侧AI抠图从入门到精通

关键词：HarmonyOS、ArkTS、Core Vision Kit、subjectSegmentation、主体分割、AI抠图
适用版本：HarmonyOS 6.1+ / SDK 6.1.0(23)+

效果

一、前言：端侧AI，触手可及

在过去，想要在App中实现"抠图"功能，通常需要依赖云端AI服务——上传用户图片到服务器、等待处理、再下载结果。这不仅带来网络延迟，还涉及用户隐私安全问题。

HarmonyOS NEXT彻底改变了这一局面。华为通过Core Vision Kit（基础视觉服务）将AI能力下沉到系统层面，开发者只需几行代码，即可在端侧实现高精度、低延时的智能抠图功能。

什么是主体分割？

主体分割（Subject Segmentation）是 Core Vision Kit 提供的核心视觉能力之一。它能够：

🔍 自动识别图片中的显著主体（人物、动物、商品等）
✂️ 将主体从背景中精准分离
🖼️ 输出透明背景的前景图（PixelMap）
📐 提供每个主体的位置矩形框信息

典型应用场景

场景	说明
证件照制作	抠出人像，替换纯色背景
电商商品图	自动提取商品主体，生成白底图
创意贴纸	从照片中提取人物/宠物，制作个性贴纸
背景替换	分离主体后，合成新的创意背景
图片编辑	对主体单独进行美化、滤镜等处理

二、环境准备

2.1 开发环境要求

项目	要求
DevEco Studio	6.1.0 Release 及以上
HarmonyOS SDK	6.1.0(23) 及以上
编译SDK版本	`compatibleSdkVersion: "6.1.0(23)"`
运行设备	仅支持真机（不支持模拟器）

⚠️重要提示：主体分割能力依赖设备端侧NPU进行AI推理，模拟器无法运行。开发调试时请务必使用真实的HarmonyOS设备。

2.2 项目配置

在项目的build-profile.json5中确认SDK版本：

{ "app": { "products": [ { "compatibleSdkVersion": "6.1.0(23)", "targetSdkVersion": "6.1.0(23)", "runtimeOS": "HarmonyOS" } ] } }

2.3 模块引入

主体分割能力来自@kit.CoreVisionKit，无需额外安装依赖，系统SDK已内置。只需在代码中引入：

import{subjectSegmentation}from'@kit.CoreVisionKit';import{image}from'@kit.ImageKit';

三、API 全景解析

3.1 核心接口一览

subjectSegmentation命名空间提供了三个核心方法：

// 1. 初始化分割服务（加载AI模型）subjectSegmentation.init():Promise<void>// 2. 执行主体分割subjectSegmentation.doSegmentation(visionInfo:VisionInfo,config:SegmentationConfig):Promise<SegmentationResult>// 3. 释放资源subjectSegmentation.release():Promise<void>

标准调用流程：init()→doSegmentation()→release()

3.2 VisionInfo — 输入参数

VisionInfo是分割接口的输入数据结构，核心字段为pixelMap：

interfaceVisionInfo{pixelMap:image.PixelMap;// 待分割的图片（必填）}

图片要求：

参数	限制
图片格式	支持 JPG、PNG 等常见格式
尺寸范围	宽/高在 20px ~ 9000px 之间
高宽比	建议 < 3:1（过于细长的图片可能识别失败）
主体占比	不小于原图面积的 5‰
输入格式	必须为`PixelMap`，不能直接传 URI

3.3 SegmentationConfig — 配置项

控制分割行为的关键配置：

interfaceSegmentationConfig{maxCount:number;// 最大分割主体数量enableSubjectDetails:boolean;// 是否返回每个主体的详细信息enableSubjectForegroundImage:boolean;// 是否返回抠图后的前景图}

参数	说明	建议值
`maxCount`	限制最多识别多少个主体	1~20，根据业务需求
`enableSubjectDetails`	设为`true`后返回每个主体的位置矩形框	`true`
`enableSubjectForegroundImage`	核心参数，设为`true`才会返回抠好的透明前景图	`true`（抠图必须）

3.4 SegmentationResult — 返回结果

分割完成后的结果数据结构：

interfaceSegmentationResult{subjectCount:number;// 实际识别到的主体数量fullSubject:FullSubject;// 整体主体信息（所有主体合并）subjectDetails?:SubjectDetail[];// 各主体详情数组}interfaceFullSubject{subjectRectangle:Rectangle;// 整体主体的边界矩形foregroundImage?:image.PixelMap;// 合并后的前景图}interfaceSubjectDetail{subjectRectangle:Rectangle;// 单个主体的边界矩形foregroundImage?:image.PixelMap;// 单个主体的前景图}interfaceRectangle{left:number;// 左上角 X 坐标top:number;// 左上角 Y 坐标width:number;// 宽度height:number;// 高度}

结果数据说明：

subjectCount：实际识别到的主体数，可能小于maxCount
fullSubject.foregroundImage：所有主体合并到一张透明背景图上
subjectDetails[i].foregroundImage：第i个主体单独的透明背景图
subjectRectangle：主体在原图中的位置信息，可用于绘制标注框

四、最小可运行示例

下面是一个完整的、可直接在真机上运行的单页面抠图示例。

4.1 完整代码

import{subjectSegmentation}from'@kit.CoreVisionKit';import{image}from'@kit.ImageKit';import{photoAccessHelper}from'@kit.MediaLibraryKit';import{fileIo}from'@kit.CoreFileKit';import{hilog}from'@kit.PerformanceAnalysisKit';import{BusinessError}from'@kit.BasicServicesKit';constTAG='SegDemo';@Entry@Componentstruct SimpleSegDemo{@StateoriginalImage:image.PixelMap|undefined=undefined;@StateresultImage:image.PixelMap|undefined=undefined;@StateinfoText:string='点击按钮选择图片';@StateisLoading:boolean=false;// 页面出现时初始化服务asyncaboutToAppear():Promise<void>{awaitsubjectSegmentation.init();hilog.info(0x0000,TAG,'Segmentation service initialized');}// 页面消失时释放资源asyncaboutToDisappear():Promise<void>{awaitsubjectSegmentation.release();hilog.info(0x0000,TAG,'Segmentation service released');}build(){Column({space:16}){// 原图展示Text('原始图片').fontSize(14).fontColor('#666')Image(this.originalImage).objectFit(ImageFit.Contain).height(200).width('90%').backgroundColor('#f5f5f5').borderRadius(8)// 抠图结果Text('抠图结果').fontSize(14).fontColor('#666')Image(this.resultImage).objectFit(ImageFit.Contain).height(200).width('90%').backgroundColor('#f5f5f5').borderRadius(8)// 信息文本Text(this.infoText).fontSize(12).fontColor('#999').padding(8)// 操作按钮Button('选择图片并抠图').type(ButtonType.Capsule).width('80%').height(48).backgroundColor('#6366f1').fontColor(Color.White).onClick(()=>this.pickAndSegment())}.width('100%').height('100%').justifyContent(FlexAlign.Center).padding(20)}/** 选择图片并执行分割 */privateasyncpickAndSegment():Promise<void>{try{// 第一步：从相册选择图片constoptions=newphotoAccessHelper.PhotoSelectOptions();options.MIMEType=photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;options.maxSelectNumber=1;constpicker=newphotoAccessHelper.PhotoViewPicker();constresult=awaitpicker.select(options);consturi=result.photoUris[0];if(!uri){this.infoText='未选择图片';return;}// 第二步：将图片转为 PixelMapconstfile=awaitfileIo.open(uri,fileIo.OpenMode.READ_ONLY);constimageSource=image.createImageSource(file.fd);this.originalImage=awaitimageSource.createPixelMap();this.resultImage=undefined;// 第三步：配置参数并调用分割this.isLoading=true;this.infoText='正在分析中...';constvisionInfo:subjectSegmentation.VisionInfo={pixelMap:this.originalImage};constconfig:subjectSegmentation.SegmentationConfig={maxCount:5,enableSubjectDetails:true,enableSubjectForegroundImage:true};// 第四步：执行分割constsegResult=awaitsubjectSegmentation.doSegmentation(visionInfo,config);// 第五步：处理结果this.resultImage=segResult.fullSubject?.foregroundImage;this.infoText=`识别到${segResult.subjectCount}个主体`;}catch(err){conste=errasBusinessError;this.infoText=`失败:${e.message}`;hilog.error(0x0000,TAG,`Error: code=${e.code}, message=${e.message}`);}finally{this.isLoading=false;}}}

4.2 关键代码逐行解析

① 生命周期管理 — init 与 release

asyncaboutToAppear():Promise<void>{awaitsubjectSegmentation.init();// 页面加载时初始化，加载AI模型}asyncaboutToDisappear():Promise<void>{awaitsubjectSegmentation.release();// 页面销毁时释放，防止内存泄漏}

💡init()会加载端侧AI模型到内存，是一个异步操作。建议在页面aboutToAppear时调用，在aboutToDisappear时调用release()释放资源。

② 构建 VisionInfo 入参

constvisionInfo:subjectSegmentation.VisionInfo={pixelMap:this.originalImage// 必须是 PixelMap 格式};

⚠️ 入参只接受PixelMap，不能直接传图片 URI。需要先通过image.createImageSource()进行转换。

③ 配置 SegmentationConfig

constconfig:subjectSegmentation.SegmentationConfig={maxCount:5,// 最多识别5个主体enableSubjectDetails:true,// 返回每个主体的位置信息enableSubjectForegroundImage:true// 返回前景图（抠图必须开启）};

🔑enableSubjectForegroundImage是抠图的核心开关。如果设为false，只能得到主体的位置信息，无法获得抠好的透明图。

④ 处理分割结果

constsegResult=awaitsubjectSegmentation.doSegmentation(visionInfo,config);// 获取合并前景图（所有主体在一张图上）constfullForeground=segResult.fullSubject?.foregroundImage;// 获取单个主体的前景图if(segResult.subjectDetails){for(leti=0;i<segResult.subjectDetails.length;i++){constsingleSubject=segResult.subjectDetails[i].foregroundImage;// 可单独使用每个主体的抠图结果}}

五、进阶用法

5.1 多主体分割

当maxCount > 1时，可以识别并分离多个主体：

constconfig:subjectSegmentation.SegmentationConfig={maxCount:10,// 最多识别10个主体enableSubjectDetails:true,enableSubjectForegroundImage:true};constresult=awaitsubjectSegmentation.doSegmentation(visionInfo,config);// 收集所有主体的前景图constsubjects:image.PixelMap[]=[];if(result.subjectDetails){for(leti=0;i<result.subjectDetails.length;i++){constdetail=result.subjectDetails[i];if(detail.foregroundImage){subjects.push(detail.foregroundImage);}}}

5.2 主体位置标注

利用subjectRectangle在原图上绘制边框，标注识别到的主体位置：

// 在原图上绘制主体边框（示例逻辑）if(result.subjectDetails){for(leti=0;i<result.subjectDetails.length;i++){constrect=result.subjectDetails[i].subjectRectangle;// rect.left, rect.top: 左上角坐标// rect.width, rect.height: 主体尺寸// 可使用 Canvas 或 Stack + Position 在原图上绘制矩形}}

5.3 错误处理最佳实践

try{awaitsubjectSegmentation.init();constresult=awaitsubjectSegmentation.doSegmentation(visionInfo,config);if(result.subjectCount===0){// 未识别到主体（可能是纯背景图或主体太小）console.info('未识别到主体，请更换图片');}}catch(err){conste=errasBusinessError;switch(e.code){case1002100001:console.error('初始化失败，设备可能不支持');break;case1002100002:console.error('推理失败，请检查图片格式');break;default:console.error(`未知错误: code=${e.code}, message=${e.message}`);}}finally{awaitsubjectSegmentation.release();}

5.4 throw 语句的 ArkTS 限制

ArkTS 编译器有一条严格规则：throw语句只能抛出Error或其子类的实例（规则码arkts-limited-throw）。在catch块中重新抛出异常时，不能直接throw err，因为err的类型是unknown：

// ❌ 错误：ArkTS 编译器报错 arkts-limited-throwtry{awaitsubjectSegmentation.init();}catch(err){throwerr;// 编译错误！err 类型为 unknown}// ✅ 正确：构造新的 Error 对象再抛出try{awaitsubjectSegmentation.init();}catch(err){conste=errasBusinessError;thrownewError(`Init failed: code=${e.code}, message=${e.message}`);}// ✅ 也可以：不重新抛出，直接在 catch 中处理try{awaitsubjectSegmentation.init();}catch(err){conste=errasBusinessError;hilog.error(0x0000,TAG,`Init failed:${e.message}`);// 返回默认值或空结果，而不是重新抛出}

六、性能优化与注意事项

6.1 生命周期管理

✅ 推荐做法 ❌ 不推荐做法 ───────────────────────────── ───────────────────────────── aboutToAppear 中 init() 每次分割都调用 init() aboutToDisappear 中 release() 不释放资源 一个页面周期内多次 doSegmentation 多个页面同时 init

6.2 PixelMap 内存管理

PixelMap是内存密集型对象，一张 4K 图片的 PixelMap 可能占用数十MB内存：

// 不再使用的 PixelMap 应及时释放if(this.oldPixelMap){this.oldPixelMap.release();// 显式释放内存this.oldPixelMap=undefined;}

6.3 图片预处理建议

对于超大图片（如 4K 以上），建议在分割前进行适当缩放：

// 创建缩放后的 PixelMapconstdecodingOptions:image.DecodingOptions={desiredSize:{width:1080,height:0}// 宽度缩放到1080，高度自适应};constpixelMap=awaitimageSource.createPixelMap(decodingOptions);

6.4 异步操作的用户体验

分割操作是耗时的（通常 1~3 秒），务必：

使用async/await或Promise异步调用
在 UI 上显示 Loading 状态
分割过程中禁用按钮防止重复点击

七、常见问题 FAQ

Q1: 模拟器上运行报错 “service not available”？

A: 这是正常现象。主体分割依赖端侧NPU，模拟器没有NPU硬件。必须使用真机测试。

Q2: 分割结果 subjectCount 为 0？

A: 可能原因：

图片中没有明显的显著主体（如纯色背景图）
主体面积太小（小于原图面积的 5‰）
图片过于细长（高宽比 > 3:1）
图片分辨率过低

Q3: foregroundImage 为 undefined？

A: 请检查SegmentationConfig中enableSubjectForegroundImage是否设为true。这是获取前景图的必要开关。

Q4: 如何保存分割后的透明 PNG 到相册？

A: 使用image.createImagePacker()将 PixelMap 打包为 PNG 数据，写入沙箱文件，再通过showAssetsCreationDialog保存至系统相册：

constpacker=image.createImagePacker();constbuffer=awaitpacker.packToData(foregroundImage,{format:'image/png',quality:100});// 写入沙箱 -> showAssetsCreationDialog -> 复制至相册

Q5: init() 和 release() 可以多次调用吗？

A: 可以，但建议在一个页面生命周期内只调用一次init()和一次release()。频繁初始化/释放会影响性能。

Q6: 支持哪些图片格式？

A: 通过PhotoViewPicker选择的图片均支持（JPG、PNG、WEBP等）。关键是必须转换为PixelMap格式后再传入 API。

Q7: 编译报错`arkts-limited-throw`怎么处理？

A: 这是 ArkTS 编译器的安全限制。catch (err)中的err类型为unknown，不能直接throw err。解决方案：

使用throw new Error(...)构造新异常对象
或者不重新抛出，改为日志记录 + 返回默认值

Q8:`@Entry`组件的`build()`方法报错“只能有一个根节点”？

A:@Entry装饰的组件，其build()方法必须有且仅有一个容器组件作为根节点（如Column、Row、Stack等）。不能直接调用自定义组件：

// ❌ 错误：build() 根节点是自定义组件@Entry@Componentstruct MyPage{build(){MyChildComponent()// 编译错误！}}// ✅ 正确：用容器组件包裹@Entry@Componentstruct MyPage{build(){Stack(){MyChildComponent()}.width('100%').height('100%')}}

八、总结

HarmonyOS 的主体分割能力为开发者提供了一套开箱即用的端侧AI抠图方案。核心流程可以概括为五步：

初始化(init) → 选图(PhotoPicker) → 转格式(PixelMap) → 配参数(Config) → 调用接口(doSegmentation)

核心优势：

🚀端侧处理：无需网络，隐私安全
⚡低延迟：NPU加速，秒级响应
🎯高精度：像素级主体分离
📦零依赖：系统SDK内置，无需第三方库

适用边界：

仅支持真机
主体面积需 ≥ 原图 5‰
图片宽高在 20~9000px 之间

希望本文能帮助你快速掌握 HarmonyOS 主体分割能力，在你的应用中实现精彩的抠图功能！