更新记录

1.0.0(2026-11-20)

  • 新增 matte / cutout / bokeh / idPhoto / layoutSheet 及对应异步版本。
  • 基于 MODNet(Apache-2.0)+ onnxruntime-android,全程离线运行。

平台兼容性

uni-app x(4.71)

Chrome Safari Android iOS 鸿蒙 微信小程序
× × √ × × ×

其他

多语言 暗黑模式 宽屏模式 蒸汽模式
× × × √

bgyx-cutout 端侧人像抠图

端侧(离线)人像抠图与换背景插件。基于 ONNX 模型(MODNet,Apache-2.0)完全离线运行,无需联网、无需上传用户照片,适用于隐私敏感与弱网场景。

功能

能力 说明
matte 生成灰度 alpha 蒙版(白=前景,黑=背景)
cutout 抠图换底:透明 PNG / 纯色底 / 自定义背景图
bokeh 背景虚化(人像模式),人像保持清晰、背景模糊
idPhoto 证件照生成:抠图换底 + 按规格裁剪构图(300dpi)
layoutSheet 证件照排版到 4x6 英寸相纸,可直接打印

每个能力均提供同步与异步(xxxAsync,在 IO 线程执行、返回 Promise)两种调用方式。

平台支持

  • Android:App(uni-app / uni-app x,HBuilderX 4.25+ 建议)。依赖 onnxruntime-android,需打包自定义基座。
  • iOS / Web / 小程序:v1.0 暂未实现(调用会抛出「当前平台暂不支持」)。

安装

将本插件目录 bgyx-cutout 放入项目的 uni_modules 目录下即可(插件市场安装或手动拷贝)。

说明:插件内置 25.9MB 模型(utssdk/app-android/assets/modnet.onnx),会随 App 安装包体积增加。

API

import {
  matte, cutout, bokeh, idPhoto, layoutSheet,
  cutoutAsync, idPhotoAsync,
  type CutoutOptions
} from '@/uni_modules/bgyx-cutout'

// 1) 透明背景抠图(输出 PNG)
const p1 = await cutoutAsync(photoPath, outPath)

// 2) 换纯色底
const p2 = await cutoutAsync(photoPath, outPath, { mode: 'color', color: '#438EDB' })

// 3) 换自定义背景图
const p3 = await cutoutAsync(photoPath, outPath, { mode: 'image', image: bgPath })

// 4) 背景虚化
const p4 = await cutoutAsync(photoPath, outPath, { mode: 'color', color: '#FFFFFF' })

// 5) 证件照(一寸、蓝底)
const p5 = await idPhotoAsync(photoPath, outPath, '1inch', 'blue')

// 6) 证件照排版(4x6 相纸)
const p6 = await layoutSheetAsync(photoPath, outPath, '1inch', 'blue')

所有函数返回输出图片的路径;失败时抛出 Error(用 try/catch 捕获)。

CutoutOptions

字段 类型 说明
mode string 'transparent'(默认) / 'color' / 'image'
color string 纯色背景,支持 '#RRGGBB' / '#AARRGGBB' / 'r,g,b'
image string 自定义背景图本地路径
feather boolean 是否羽化蒙版边缘,默认 true

证件照规格(spec)

值 尺寸(mm) 值 尺寸(mm)
1inch(默认) 25×35 2inch 35×49
small_1 22×32 large_1 33×48
small_2 35×45 large_2 35×53
passport 33×48 visa_us 51×51
social 26×32 resume 25×35
license 22×32

证件照底色(bg)

white(白)、blue(默认)、deep_blue、red、gray、light_blue。

构建与联调(重要)

本插件使用原生依赖(onnxruntime-android)与 Kotlin 混编,不能用标准基座运行,需按下述步骤打包自定义基座:

  1. 用 HBuilderX 打开 uni-app x 项目,确认 uni_modules/bgyx-cutout 存在。
  2. 菜单 运行 → 运行到手机或模拟器 → 制作自定义调试基座,选择 Android,等待云端打包完成。
  3. 之后 运行 → 运行到手机或模拟器 → 运行到 Android App 基座,选择刚生成的自定义基座。
  4. 首次调用会加载模型(约 1~2 秒),请使用 xxxAsync 版本以避免阻塞 UI。

云端打包时,utssdk/app-android/config.json 中的 dependencies 会自动合并到工程 Gradle:implementation 'com.microsoft.onnxruntime:onnxruntime-android:1.19.2'。

许可与合规

  • 模型 MODNet:Apache-2.0,可商用。
  • 全程端侧离线,用户照片不出设备,符合隐私合规要求。
  • 插件源码与模型版权归发布方所有;使用者需获得授权后使用。

已知限制

  • v1.0 仅实现 Android;iOS 需另行实现(可用 ONNX Runtime / Core ML)。
  • idPhoto 依据人像前景包围盒构图(不含人脸检测)。对标准半身/正面人像效果良好;后续版本将加入人脸关键点以提升构图精度。
  • 处理耗时与图片分辨率相关;超大图(>20MP)建议先压缩。

变更记录

见 changelog.md。

隐私、权限声明

1. 本插件需要申请的系统权限列表:

保存图片到相册需读写相册权限

2. 本插件采集的数据、发送的服务器地址、以及数据用途说明:

无

3. 本插件是否包含广告,如包含需详细说明广告表达方式、展示频率:

无

暂无用户评论。