项目源码 · README

社区与框架:开源鸿蒙跨平台开发者社区 · CPF-Cordova · Cordova 鸿蒙平台源码

前言

商品图从相册拖进排版工具,最难确认的往往不是瓶子有没有被认出来,而是照片的背景究竟有没有被拿掉。看预览时,瓶子浮在一块棋盘格上,很容易把这个画面当成已经拿到的成品;等把文件贴进深底的海报,原来那块浅色矩形又冒了出来。这个问题值得用两次观察来解决:先用眼睛看同一个结果换底时边缘有没有变化,再打开实际导出的文件,检查背景像素的 Alpha 值。第一种方法帮助定位问题,第二种才回答文件是否透明。

这里做了一个 Cordova 商品图工作台。它没有画笔、图层或背景编辑器,任务只有一个:选择一张照片,调用鸿蒙系统主体分割,保存一份可以继续排版的透明 PNG。原图与抠图共用一个画布,右侧直接显示系统返回的主体数、完全透明像素占比和 PNG 大小。样片也刻意保留了三种容易看错的情况:一个轮廓清楚的瓶子、两个互相分离的瓶子、一块没有明显前景的纹理。它们用的是同一套分割和导出逻辑,结果不靠网页按样片名预设。

界面设计借鉴了 Adobe Firefly 的主体预览 和 remove.bg 的换底检查方式。画布底色只能用于检查;一旦切换底色也会改动文件,操作者就很难分辨自己是在验收抠图还是在重新合成照片。因此本例把三枚底色开关放在画布下面,和「保存 PNG」分开。

真机演示

MatePad Edge 真机录屏(MP4) · 打开录屏原片

MatePad Edge 真机完整操作

在 MatePad Edge 上选择「琥珀瓶」。原图外面已经能看见棋盘格,但原图所在的矩形内仍是一整块浅色。点击「分离主体」,系统返回一个前景图,瓶身周围露出棋盘格。把底色切成深蓝,再切回原图,可以很快发现先前那块矩形背景和瓶盖旁的阴影去了哪里。看起来像浮在画布上的瓶子,至少通过了最直观的一关。

MatePad Edge 真机全屏:分割前,照片内仍有背景

MatePad Edge 真机全屏:分割前,照片内仍有背景

MatePad Edge 真机全屏:系统返回一个主体,棋盘格可透过背景区域

MatePad Edge 真机全屏:系统返回一个主体,棋盘格可透过背景区域

MatePad Edge 真机全屏:同一份 PNG 在深色底上预览

MatePad Edge 真机全屏:同一份 PNG 在深色底上预览

MatePad Edge 实际操作:启动分割、切换底色、回看原图

MatePad Edge 实际操作:启动分割、切换底色、回看原图

但在商品图工作台里,能换底不代表能交付。点「保存 PNG」后,系统文件选择器给到一个保存目标,插件把刚才那份 PNG 的字节原样写过去。把保存的文件从设备取回,用独立的解码器读取,得到尺寸 1000 × 800、文件大小 63,249 字节,像素模式为 RGBA。800,000 个像素里有 665,774 个完全透明、122,847 个完全不透明,还有 11,379 个 Alpha 介于两者之间。网页显示的 83.2% 对应的是完全透明那一组;它不会把边缘所有半透明像素一股脑算进背景。

用这三个数字看结果,比只看到文件后缀更有用。全不透明可能说明导出时已把背景合成进去了;全透明说明连瓶子也没有留下。对这张样片而言,完全透明区与不透明区同时存在,再结合深底效果,可以确认导出的图不是在白底上画出来的「透明感」。半透明像素的存在也不等于轮廓已经完美。贴到反差很大的背景上,浅边、反光、半透明包装仍要逐张看;这里的直方图证明文件携带透明度,不替代主观或像素级质量评估。

MatePad Edge 真机全屏:系统保存完成,文件字节数回传到 Cordova 页面

MatePad Edge 真机全屏:系统保存完成,文件字节数回传到 Cordova 页面

输入或操作预期实测结果证据
真机 · 琥珀瓶分割后保存保留瓶子,背景有透明度,文件可重新解码1 个主体;1000 × 800;63,249 字节;完全透明 665,774 个像素保存的原始 PNG
真机 · 双件摆拍合并图同时保留两个瓶子2 个主体;1000 × 800;92,831 字节双主体全屏效果
真机 · 空白纹理没有可用结果时,保存入口不开放系统返回 1011000001;未生成 PNG;保存按钮保持禁用失败路径全屏效果
API 26 模拟器 · 点击分离设备能力缺失时,在调用前停止UNSUPPORTED_DEVICE;能启动页面、载入样片并展示提示模拟器全屏效果

预览和落盘为什么是同一份 PNG

工作台有一条很实用的约束:如果已经证明某份文件有 Alpha,保存时就写那一份文件。这里由鸿蒙插件调用 Image Kit,把主体分割返回的前景图编码成 PNG。编码后的缓冲区在原生层留一份,网页拿到相同字节的 Base64,用来显示和校验。保存动作没有走网页截图、Canvas 重编码或「把当前看到的区域存成图」。这样,换成浅色还是深色、画布缩小还是放大,都不会改变最终写出去的内容。

页面可以直接读出原生返回的宽、高和字节数,但这些字段不够证明透明度。它新建一块与 PNG 像素尺寸相同的离屏 Canvas,让浏览器解码并画出这张 PNG,然后逐四字节取出 Alpha。离屏 Canvas 上没有铺底色,所以在 DOM 上给预览区域设置背景并不会改变统计结果。计算时只统计 Alpha 等于零的像素,同时要求至少还有一个不完全透明的像素。这道检查是给商品图抠图这个流程设的门槛;如果业务允许导出一张本来就没有透明背景的图片,就不应该把同样的门槛强塞给所有 PNG。

这也解释了为什么切换「原图」时导出仍然指向上一轮抠图结果。原图/抠图按钮切换的是显示内容,不生成第二份输出。只有真正选了另一张图或者重新发起分割时,才会让网页上的旧结果失效。否则用户浏览时随手回看原图,就可能改变原先已经确认过的导出对象。反过来,新任务失败也不能保留旧结果可导出的假象。页面发起计算前会把旧对象清掉,插件在新一轮处理前也会清空缓存;收到失败回调时保存按钮维持禁用。

VS Code 实际工程:网页重读 PNG 并统计 Alpha

VS Code 实际工程:网页重读 PNG 并统计 Alpha

从网页按钮到系统分割

在宿主的 Index.ets 中,把一个 CutoutPlugin 实例注册到 Cordova 的 MainPage,服务名取 SubjectCutout。网页等到 deviceready 才读默认样片,后面通过 cordova.exec 调用插件。这里的四个动作各自只做一件事:sample 读内置样片,pick 走系统选图,run 处理一个已经选定的输入,save 写当前缓存。把选图和推理拆开以后,可以先展示原图,还可以取消选图而不丢掉已经验证的上一张。

插件的 execute 先判断动作名再返回。返回 true 只代表 Cordova 的请求已由这个插件接管,分割是否成功还要等异步回调。网页把成功与失败转换为 Promise;忙碌时页面会禁用其他可能替换输入的按钮,插件本身也会拒绝重入。这样即使后续把入口放到菜单或者增加键盘快捷键,也不会因为同一个按钮事件被触发两次,就让两轮请求争同一份 PNG 缓存。一个状态用于页面提示,一个状态保护平台端调用,两处并不重复承担同一责任。

从图库选择照片用系统选择器返回的 URI,只读用户本次选中的文件。不能把 URI 当成普通路径交给网页。插件用文件描述符读入内容,检查压缩文件的字节长度,再建立 ImageSource。Base64 是这个演示的桥接格式,它让 Cordova 回调和预览都比较简单,不过同一份数据在运行时可能同时以压缩字节、字符串、解码像素等形态存在。本例给选图设了 20 MB 上限,同时将送入模型的最长边控制在 1800 像素。两道限制分别照顾读文件和解码后的内存成本;它们也意味着本例不是一款保留超高分辨率的生产级抠图工具。

官方要求输入为 RGBA_8888 PixelMap。插件先读取宽高,拒绝尺寸和比例过于极端的输入,再按比例生成所需像素格式。比较容易混淆的是,RGBA_8888 输入不是说原图已经有透明背景。它是模型要求的内存排列方式,一张普通 JPEG 也可以被解码为四通道,输入 Alpha 仍然可以全为 255。让背景变透明的是下一步的分割结果,而不是解码参数。

真正调用时先判断设备是否暴露 SystemCapability.AI.Vision.SubjectSegmentation,再初始化引擎。传给 doSegmentation 的配置把最大主体数设为五,开启前景图输出,不开启逐个主体的详细结果。这里要的是一张商品照片的合并前景,分离摆放的两件商品也要同时留在画布上,读取 fullSubject.foregroundImage 就够了。若需求改成「点左边瓶子,只导出它」,需要开启并使用 subjectDetails,再把每个主体和用户的选区对应起来;改一个显示标签不会让合并前景变成逐件导出。主体分割接口与返回类型

VS Code 实际工程:前景图配置与 PNG 编码位置

VS Code 实际工程:前景图配置与 PNG 编码位置

释放顺序也跟数据所有权有关。原图 PixelMap 活到分割回调结束;返回的前景 PixelMap 活到编码完成;ImagePacker 完成工作后释放;引擎由负责初始化的这次请求在退出时释放。异步阶段抛异常也会走清理路径。网页上的预览来自独立 PNG 字节,即使前景 PixelMap 已经释放,也不会丢失图片。保存阶段只处理编码结果,重复选择保存位置不会重新跑一遍模型。

文件选择器接管最后一步

保存时给系统文件选择器一个建议文件名,用户决定目标位置。拿到返回的 URI 后,插件用写入模式打开它,把整份缓冲区写入,然后比较实际写入的字节数和期望长度。如果两者不同,前端显示失败,不会只因为对话框已经退出就宣布保存完成。文件描述符通过 finally 关闭,取消时继续保留当前画布。选图和保存都使用系统选择器提供的访问范围,示例没有申请整个相册或共享存储的读取权限。

这里不使用把画布转为图片再下载的常见网页写法。网页截图可能把底色和按钮一起烘焙进去,依赖 WebView 下载行为还会让路径、格式、对话框与宿主不同。由原生负责落盘让回调能直接回答两件具体的事:用户有没有选择目标,以及那个目标实际写了多少字节。另一个好处是可以用独立的文件检查工具拿回那份文件,和页面报告的字节数逐一对上。两者对不上时,应优先核对用户取回的是否为本轮文件,再排查截断或重新编码,而不应该靠把页面上的数值改得一致来掩盖问题。

设备与构建

项目实际版本或配置验证范围
真机HUAWEI MatePad Edge(QXS-W00),HarmonyOS 7.0.0,软件版本 7.0.0.111(SP16C00E111R6P5),API 26;ARM64主体分割、错误路径、换底与文件保存
模拟器DevEco Emulator 26.0.0.402,MatePad Pro 13 平板配置(PADEMU-FD00),2880 × 1920,x86_64;HarmonyOS 7.0.0,软件版本 7.0.0.107(SP8DEVC00E16R1P1),API 26运行 Cordova 页面、载入样片、能力检测与提示
开发环境DevEco Studio 6.1.1.300;HarmonyOS Command Line Tools 26.0.0.865;Hvigor 6.26.9构建与检查
工程配置SDK 26.0.0.105,编译、目标、最低兼容均为 API 26;@cordova-ohos/ohos 14.0.2同时打包 ARM64 和 x86_64 的 Cordova 原生库

MatePad Edge 系统设置全屏:实际机型、软件和 API 版本;个人字段已遮挡

MatePad Edge 系统设置全屏:实际机型、软件和 API 版本;个人字段已遮挡

API 26 模拟器系统设置全屏:设备及软件版本

API 26 模拟器系统设置全屏:设备及软件版本

DevEco Studio 原生关于窗口

DevEco Studio 原生关于窗口

VS Code 实际工程配置:编译、目标和兼容 API

VS Code 实际工程配置:编译、目标和兼容 API

主体分割 API 本身的起始版本是 API 12,表里的三个 API 26 说的是这份 Cordova 工程的构建选择和验证范围。低版本理论上能否使用,要看宿主框架、工程依赖和目标设备有没有相应的系统能力。连使用相同 API 26 的平板模拟器也出现了「无主体分割能力」的情况,所以不能用系统版本号替代运行时能力判断。

工程根目录的 build-profile.json5 固定了构建目标;入口模块通过本地依赖引用 Cordova,原生库按 ABI 分开打包。HTML、JS、CSS 和固定样片作为 rawfile 随应用安装;无需等开发机开网页服务。读者改完插件的注册名或入口路径,建议先在模拟器看界面是否收到 deviceready,再去真机调模型。模拟器把 Cordova 启动和系统能力这两个故障点拆开了,省去每次修改前端就重新占用真机。

文末的「构建步骤」列出了工具版本、依赖安装和签名方式。运行时先试内置的三张样片,确认结果和失败状态都能复现,再换自己的商品图。样片是为演示绘制的固定输入,可以确认软件在每次运行时面对的是同一批像素。它们也限制了本次结论的范围:两个瓶子被正确分开,不代表系统对透明玻璃、毛发、低对比边缘或拥挤背景都能得到一样干净的结果。遇到这些素材时,用深浅两个背景检查实际边缘,比拿这几张的成功率当作指标更有意义。

复测时先看哪一层

网页按钮没有反应、系统引擎没有给结果、以及写盘之后找不到文件,表面上都像「抠图没有成功」,实际上可以用很短的三步分开。第一步只载入内置图片。按钮状态改变后,证明网页已经收到一轮插件回调;假如连这一步都失败,先核对服务名和页面入口,不必怀疑模型。第二步发起分割,同时看页面和 hilog。日志有主体数却没有 PNG 的宽高和字节数,说明问题发生在拿到前景之后;只有错误码而没有主体数,要先看设备能力、输入和引擎返回。第三步单独按保存,拿到文件后独立解码。到了这一步再去改预览 CSS 不会让一个被截断的文件变完整。

可以用相同的方式检查「保存了错误的一张」。先让单瓶分割成功,按一次原图,再回到抠图,检查尺寸和字节数应保持不变。随后改选双瓶,页面要等新一轮编码成功才允许导出。最后选空白纹理,连上一张图的保存入口也应失效。三次操作分别对应只改变视图、更换输入和计算失败,最容易漏掉的恰恰是最后一次。只跑一条正常路径时,看不出旧缓冲区是否被错误沿用。

如果把这套交互用在批量商品录入里,我会保留文件尺寸与保存结果两个提示,但会重新设计数据传递:网页只拿一张受控尺寸的预览图,原尺寸输出由原生层用文件或受控 URI 持有。原因是压缩后的文件、编码为字符串的内容和解码后的像素是三笔不同的内存账。在这个例子里,输入与输出都在受控范围,直接走 Base64 足够清楚;一次导入十几张大图时,同一种传法会把这些临时数据同时留在内存里。届时应逐张释放、区分预览分辨率和导出分辨率,再决定是否把队列、取消和后台恢复纳入实现。文中的三张图只能验证当前单图流程,不能推导出批处理性能。

还有一个会影响复测的细节,是两台设备的包必须包含各自能加载的原生库。只在模拟器验证时,即使工程漏打了 ARM64,网页也照样能打开;这类问题到了平板才会在启动或加载桥接时暴露。本次构建后实际检查了 HAP 内两个架构的 libcordova.so,再分别安装。真机和模拟器的启动证据不等于它们的能力表相同:一个包中有两份架构产物,解决的是应用进程怎么加载 Cordova;系统主体分割能不能工作,还是由每台设备自己报告。排障时把这两步混在一起,很容易在模型报错时去重装依赖,或在应用白屏时先去调整图片。

比对透明像素时,记得分母取的是输出图片自己的像素数。预览区可以随平板窗口变化,浏览器也会按显示密度缩放;用截图数棋盘格不能和文件直方图比较。最直接的复查是在同一个文件上读宽高与 Alpha 通道,把直方图三部分相加,应该刚好等于宽乘高。如果总数能对上,但透明度与网页提示不同,先检查两边统计的是「完全透明」还是「只要不是完全不透明」。这两个定义在柔和边缘上本来就会得到不同结果,并不一定表示 PNG 编码出了问题。

再补一个容易误解的词:「主体数」不等于「商品数」。系统找的是画面中显著的对象;同一个商品连同底座可能被并为一个主体,也可能把多件相邻商品识别为一组。这里双瓶刻意留出间隔,是为了观察合并前景会不会同时保留两件;没有把真实货架里互相遮挡的商品当成这个结果的延伸。若业务需要逐件出图,先让用户确认识别对象,再把输出和被确认的对象绑定,不能用一个检测数量直接作为库存、SKU 或质检结论。

关键调用和分层见附录源码。日志筛选用下面这一行,定位时只看本次操作的时间段;不要把上一轮应用实例的成功日志当作这次保存的结果。

hdc -t <设备标识> shell hilog -x -T SubjectCutout

真机 hilog 节选:双主体的编码结果与空白纹理的错误码

真机 hilog 节选:双主体的编码结果与空白纹理的错误码

FAQ

模拟器和真机都是 API 26,为什么一个能抠、一个不能?

工程能在模拟器启动,说明对应架构的 HAP 与 Cordova 桥接可用;模型能力是另外一层。用 canIUse 判断系统能力后,模拟器走到了 UNSUPPORTED_DEVICE。这里保留了这一分支和可读提示。若遇到的是点击无回调,先看 deviceready 与服务名是否一致,不能把所有失败都归为模拟器不支持。

空白图应该返回 0 个主体,为什么日志里是 1011000001?

这台真机处理本文的空白纹理时,直接返回接口错误 1011000001。华为文档把它归为运行失败,不能把所有这个错误都解释成画面里没有主体。因此应用对外只提示本次未生成抠图,保留错误码;如果接口成功返回了零个主体或前景字段为空,才走应用自己的 NO_SUBJECT。两条路径都禁用保存,重选正常图片后能发起新的请求。

已经关闭图片资源压缩,为什么 Windows 构建还报 11201001?

这次命令行构建在资源编译时尝试加载图片压缩扩展,失败点在 CompileResource,不是在 ArkTS 主体分割代码。排查时对比同一份资源配置,移除未使用的压缩扩展项后,资源工具能处理同一批输入。工程保留了一个只在显式启用时运行的构建钩子:它先确认没有启用压缩和过滤器,再清理本次生成的临时配置。之后重新构建通过,HAP 也在两类设备上完成安装。这个办法只用于出现同类报错的 Windows 构建环境,不适用于真正要压缩图片资源的项目。

导出的图有透明背景,为什么边缘还是可能看起来发白?

完全透明像素只是背景清理的底线,半透明边缘保留多少颜色取决于模型结果和原片。先在同一张图上轮换浅底与深底,看看问题是铺满画布的矩形还是仅围绕主体的一圈,再看原片该处是否存在反光、阴影或低对比边缘。前者先查是否保存了预览层或导成 JPEG;后者要重新选片、拍摄或另行处理边缘。本示例只提供核对工具,不把更换预览底色误说成边缘修复。

总结

这次 MatePad Edge 实测把选图、鸿蒙系统分割、前景 PNG 编码、网页预览和系统文件保存串了起来。判断导出是否成立的证据不只是一张棋盘格:保存后的实际文件可以重读,并同时拥有透明、半透明和不透明像素。双主体样片说明合并前景适用于这个摆拍场景,空白样片说明应用不会在失败时放行导出。模拟器验证的是前端与能力检测路径,模型结果以真机为准。

如果只带走一条建议,先决定哪份字节才是最终的输出,再从那份字节生成预览和验证结果。预览层换底可以做得很方便,但文件是否透明,始终由独立解码后的 Alpha 决定。

附录:核心源码

页面的 HTML、CSS、固定样片和 Cordova 平台模块随工程提供。以下三段是同一工程中的完整文件。

插件注册:Index.ets

/*
 * Copyright (c) 2025 Huawei Device, Inc. Ltd. and <马弓手>.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 *     http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

import { MainPage, pageBackPress, pageHideEvent, pageShowEvent, PluginEntry } from '@cordova-ohos/ohos/Index';
import { CutoutPlugin } from '../entryability/CutoutPlugin';

@Entry
@Component
struct Index {
  private plugins: PluginEntry[] = [{ pluginName: 'SubjectCutout',
    pluginObject: new CutoutPlugin(this.getUIContext().getHostContext()!) }];

  onPageShow(){
    pageShowEvent(); //页面显示通知cordova
  }
  onBackPress() {
    pageBackPress(); //拦截返回键由cordova处理
    return true;
  }
  onPageHide() {
    pageHideEvent(); //页面隐藏通知cordova
  }
  build() {
    RelativeContainer() {
      //默认加载rawfile/www/index.html
      MainPage({ isWebDebug: false, cordovaPlugs: this.plugins });
    }
    .height('100%')
    .width('100%')
  }
}

原生插件:CutoutPlugin.ets

import { Context } from '@kit.AbilityKit';
import { BusinessError } from '@kit.BasicServicesKit';
import { subjectSegmentation } from '@kit.CoreVisionKit';
import { fileIo, picker } from '@kit.CoreFileKit';
import { image } from '@kit.ImageKit';
import { photoAccessHelper } from '@kit.MediaLibraryKit';
import { util } from '@kit.ArkTS';
import { hilog } from '@kit.PerformanceAnalysisKit';
import { CallbackContext, CordovaPlugin } from '@cordova-ohos/ohos/Index';

const TAG: string = 'SubjectCutout';
const SAMPLES: string[] = ['bottle', 'pair', 'paper'];

interface PngResult {
  png: string;
  width: number;
  height: number;
  bytes: number;
  subjects: number;
}

export class CutoutPlugin extends CordovaPlugin {
  private busy: boolean = false;
  private lastPng?: ArrayBuffer;
  private host: Context;

  constructor(host: Context) {
    super();
    this.host = host;
  }

  execute(action: string, args: ESObject[], callback: CallbackContext): boolean {
    if (!['sample', 'pick', 'run', 'save'].includes(action)) {
      return false;
    }
    if (this.busy) {
      callback.errorByString('BUSY');
      return true;
    }
    this.busy = true;
    void this.dispatch(action, typeof args[0] === 'string' ? args[0] : '', callback);
    return true;
  }

  private async dispatch(action: string, argument: string, callback: CallbackContext): Promise<void> {
    try {
      if (action === 'save') {
        if (!this.lastPng) {
          throw new Error('NO_RESULT');
        }
        // 保存对话框授予所选 URI 的访问权,不申请整盘读写权限。
        const options = new picker.DocumentSaveOptions();
        options.newFileNames = ['cutout.png'];
        const paths = await new picker.DocumentViewPicker(this.host).save(options);
        if (!paths.length) {
          throw new Error('CANCELLED');
        }
        const file = await fileIo.open(paths[0], fileIo.OpenMode.WRITE_ONLY | fileIo.OpenMode.TRUNC);
        try {
          const size = await fileIo.write(file.fd, this.lastPng);
          if (size !== this.lastPng.byteLength) {
            throw new Error('SHORT_WRITE');
          }
          hilog.info(0, TAG, 'saved format=image/png bytes=%{public}d', size);
          callback.successByNumber(size);
        } finally {
          await fileIo.close(file);
        }
        return;
      }

      // 新输入由 JS 在确认选择后替换;取消操作不会清空先前的结果。
      if (action === 'sample') {
        if (!SAMPLES.includes(argument)) {
          throw new Error('BAD_SAMPLE');
        }
        const bytes = this.host.resourceManager.getRawFileContentSync(`www/samples/${argument}.jpg`);
        callback.successByString(new util.Base64Helper().encodeToStringSync(bytes));
        return;
      }
      if (action === 'pick') {
        const options = new photoAccessHelper.PhotoSelectOptions();
        options.MIMEType = photoAccessHelper.PhotoViewMIMETypes.IMAGE_TYPE;
        options.maxSelectNumber = 1;
        const photos = await new photoAccessHelper.PhotoViewPicker().select(options);
        if (!photos.photoUris.length) {
          throw new Error('CANCELLED');
        }
        const file = await fileIo.open(photos.photoUris[0], fileIo.OpenMode.READ_ONLY);
        try {
          const size = (await fileIo.stat(file.fd)).size;
          if (size < 1 || size > 20 * 1024 * 1024) {
            throw new Error('IMAGE_SIZE');
          }
          const raw = new ArrayBuffer(size);
          if (await fileIo.read(file.fd, raw) !== size) {
            throw new Error('SHORT_READ');
          }
          callback.successByString(new util.Base64Helper().encodeToStringSync(new Uint8Array(raw)));
        } finally {
          await fileIo.close(file);
        }
        return;
      }
      this.lastPng = undefined;
      if (!argument || argument.length > 28 * 1024 * 1024) {
        throw new Error('IMAGE_SIZE');
      }
      if (!canIUse('SystemCapability.AI.Vision.SubjectSegmentation')) {
        throw new Error('UNSUPPORTED_DEVICE');
      }
      const bytes = new util.Base64Helper().decodeSync(argument);
      const input = image.createImageSource(bytes.buffer as ArrayBuffer);
      try {
        const info = await input.getImageInfo();
        const width = info.size.width;
        const height = info.size.height;
        if (width <= 20 || height <= 20 || width > 8999 || height > 8999 ||
          Math.max(width, height) > 3 * Math.min(width, height)) {
          throw new Error('IMAGE_DIMENSIONS');
        }
        // 控制 PixelMap 和掩码占用;小图保持原尺寸。
        const ratio = Math.min(1, 1800 / Math.max(width, height));
        const source = await input.createPixelMap({
          desiredPixelFormat: image.PixelMapFormat.RGBA_8888,
          desiredSize: { width: Math.round(width * ratio), height: Math.round(height * ratio) }
        });
        try {
          const result = await this.segment(source);
          callback.successByJson(result);
        } finally {
          await source.release();
        }
      } finally {
        await input.release();
      }
    } catch (error) {
      const failure = error as BusinessError;
      const message = failure.code ? String(failure.code) : (failure.message || 'FAILED');
      hilog.warn(0, TAG, 'action=%{public}s code=%{public}s', action, message);
      callback.errorByString(message);
    } finally {
      this.busy = false;
    }
  }

  private async segment(source: image.PixelMap): Promise<PngResult> {
    if (!await subjectSegmentation.init()) {
      throw new Error('ENGINE_INIT');
    }
    let foreground: image.PixelMap | undefined;
    try {
      const result = await subjectSegmentation.doSegmentation({ pixelMap: source }, {
        maxCount: 5,
        enableSubjectDetails: false,
        enableSubjectForegroundImage: true
      });
      foreground = result.fullSubject?.foregroundImage;
      hilog.info(0, TAG, 'engine subjects=%{public}d', result.subjectCount);
      if (result.subjectCount === 0 || !foreground) {
        throw new Error('NO_SUBJECT');
      }
      const encoder = image.createImagePacker();
      try {
        const info = await foreground.getImageInfo();
        const png = await encoder.packing(foreground, { format: 'image/png', quality: 100 });
        this.lastPng = png;
        hilog.info(0, TAG, 'png width=%{public}d height=%{public}d bytes=%{public}d',
          info.size.width, info.size.height, png.byteLength);
        return {
          png: new util.Base64Helper().encodeToStringSync(new Uint8Array(png)),
          width: info.size.width, height: info.size.height, bytes: png.byteLength, subjects: result.subjectCount
        };
      } finally {
        await encoder.release();
      }
    } finally {
      try {
        await foreground?.release();
      } finally {
        await subjectSegmentation.release();
      }
    }
  }
}

网页桥接与透明度检查:studio.js

'use strict';
const $ = id => document.getElementById(id);
const samples = { bottle: '01 / 琥珀瓶', pair: '02 / 双件摆拍', paper: '03 / 空白纹理' };
const errors = { UNSUPPORTED_DEVICE:'本机没有主体分割能力。', ENGINE_INIT:'主体分割服务未能初始化。', NO_SUBJECT:'没有检测到主体,试试轮廓清楚的照片。', IMAGE_DIMENSIONS:'图片长宽或比例超出范围。', IMAGE_SIZE:'图片为空或超过 20 MB。', CANCELLED:'已取消,保留当前画布。', SHORT_WRITE:'PNG 未写完整,请重新导出。' };
errors['1011000001']='本次未生成抠图(1011000001)。请换一张轮廓清楚的照片。';
const state = { source:'', output:null, sample:'bottle', busy:false, view:'original', ready:false, missing:false };
function native(action, value) {
  return new Promise((resolve,reject) => cordova.exec(resolve,reject,'SubjectCutout',action,value?[value]:[]));
}
function originalUrl() {
  if (samples[state.sample]) return 'samples/'+state.sample+'.jpg';
  const base64=state.source;
  const type=base64.startsWith('/9j/')?'jpeg':base64.startsWith('iVBOR')?'png':
    base64.startsWith('R0lGOD')?'gif':base64.startsWith('UklGR')?'webp':'*';
  return 'data:image/'+type+';base64,'+base64;
}
function paint() {
  for (const key of ['original','result']) $(key).setAttribute('aria-pressed', String(key===state.view));
  $('result').disabled = !state.output;
  if (state.source) $('preview').src = state.view==='result' ? 'data:image/png;base64,'+state.output.png :
    originalUrl();
  $('caption').textContent = samples[state.sample] || '自选照片';
  $('pixels').textContent = state.view==='result' ? state.output.width+' × '+state.output.height : '原图预览';
  $('subjects').textContent = state.output?.subjects ?? (state.missing ? '0' : '—');
  $('alpha').textContent = state.output?.alpha ?? '—';
  $('size').textContent = state.output ? (state.output.bytes/1024).toFixed(1)+' KB' : '—';
  $('run').disabled = state.busy || !state.source;
  $('pick').disabled = state.busy || !state.ready;
  $('save').disabled = state.busy || !state.output?.transparent;
  document.querySelectorAll('.sample').forEach(b => { b.disabled=state.busy || !state.ready; b.setAttribute('aria-pressed',String(b.dataset.id===state.sample)); });
}
async function work(note, body) {
  if (!state.ready || state.busy) return;
  state.busy=true;
  $('status').textContent=note;
  paint();
  try { await body(); }
  catch(e) {
    const code=String(e);
    $('status').textContent=errors[code] || '处理失败:'+code;
    if(code==='NO_SUBJECT') state.missing=true;
  } finally { state.busy=false; $('busy').hidden=true; paint(); }
}
function load(id) {
  return work('正在载入照片…',async()=>{
    const next=await native(id?'sample':'pick',id);
    Object.assign(state,{source:next, output:null, sample:id, view:'original', missing:false});
    $('status').textContent='照片已载入,可以开始分离。';
  });
}
// 画布底色不参与导出。这里对编码后的 PNG 重新解码,验证像素本身的 Alpha。
async function verifyAlpha(png) {
  const img=new Image();
  img.src='data:image/png;base64,'+png;
  await img.decode();
  const canvas=document.createElement('canvas');
  canvas.width=img.naturalWidth;
  canvas.height=img.naturalHeight;
  const ctx=canvas.getContext('2d',{willReadFrequently:true});
  ctx.drawImage(img,0,0);
  const rgba=ctx.getImageData(0,0,canvas.width,canvas.height).data;
  let clear=0;
  for(let i=3;i<rgba.length;i+=4) if(rgba[i]===0) clear++;
  const count=rgba.length/4;
  return {alpha:(100*clear/count).toFixed(1)+'%',transparent:clear>0 && clear<count};
}
$('run').onclick=()=>work('系统正在分离前景…',async()=>{
  Object.assign(state,{output:null,view:'original',missing:false});
  $('busy').hidden=false;
  paint();
  const result=await native('run',state.source);
  state.output={...result,...await verifyAlpha(result.png)};
  state.view='result';
  $('status').textContent=state.output.transparent?'已检查 Alpha 通道,可以导出。':'未检测到可用的透明背景。';
});
$('save').onclick=()=>work('等待选择保存位置…',async()=>{
  const bytes=await native('save');
  $('status').textContent='已保存 PNG · '+bytes.toLocaleString('zh-CN')+' 字节';
});
$('pick').onclick=()=>load('');
document.querySelectorAll('.sample').forEach(b=>{b.onclick=()=>load(b.dataset.id);});
for(const key of ['original','result']) $(key).onclick=()=>{state.view=key;paint();};
for(const key of ['check','light','dark']) $(key).onclick=()=>{
  $('stage').dataset.bg=key;
  for(const bg of ['check','light','dark']) $(bg).setAttribute('aria-pressed',String(bg===key));
};
document.addEventListener('deviceready',()=>{state.ready=true;void load('bottle');});
paint();

结果补图

模拟器全屏效果

模拟器全屏效果

保存的原始 PNG

保存的原始 PNG

双主体全屏效果

双主体全屏效果

失败路径全屏效果

失败路径全屏效果

构建步骤

使用 HarmonyOS Command Line Tools 26.0.0.865、SDK 26.0.0.105 和 JDK 21。设置 DEVECO_SDK_HOME 指向该 SDK,并把工具 bin、Node 和 JDK 的 bin 加到 PATH。在工程根目录安装依赖并构建:

ohpm install --all --cache .ohpm-cache
hvigorw --mode module -p product=default -p module=entry@default assembleHap --no-daemon

出现 Windows 图片资源扩展错误 11201001 时,按 FAQ 确认没有启用资源压缩后,可设置 CUTOUT_NO_RESOURCE_COMPRESSION=1 再构建。真机安装需要与设备和包名匹配的调试签名。

Logo

AtomGit 是由开放原子开源基金会联合 CSDN 等生态伙伴共同推出的新一代开源与人工智能协作平台。平台坚持“开放、中立、公益”的理念,把代码托管、模型共享、数据集托管、智能体开发体验和算力服务整合在一起,为开发者提供从开发、训练到部署的一站式体验。

更多推荐