更新记录
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 混编,不能用标准基座运行,需按下述步骤打包自定义基座:
- 用 HBuilderX 打开 uni-app x 项目,确认
uni_modules/bgyx-cutout存在。 - 菜单 运行 → 运行到手机或模拟器 → 制作自定义调试基座,选择 Android,等待云端打包完成。
- 之后 运行 → 运行到手机或模拟器 → 运行到 Android App 基座,选择刚生成的自定义基座。
- 首次调用会加载模型(约 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。

收藏人数:
购买普通授权版(
试用
使用 HBuilder 导入示例项目
赞赏(0)
下载 0
赞赏 0
下载 12778816
赞赏 1960
赞赏
京公网安备:11010802035340号