CV-鸿蒙接入文档--智能美化特效-火山引擎

文档中心

立即注册

导航

CV-鸿蒙接入文档

最近更新时间：2025.04.16 16:01:44首次发布时间：2025.04.16 16:01:44

适用平台：HarmonyOS Next

SDK快速接入指南

在项目中加入SDK

从发版链接中取到effectApi.har
在oh-package.json5 中配置工程对该har 的依赖

"dependencies": {
  "effectapi": "file:./package/effectApi.har",
},

将提供的素材和鉴权文件（存储在entry/src/main/resources/rawfile目录下）拷贝到项目的assets 中

代码中集成SDK

以下指南针对使用 sample 中封装的 ArkTS代码进行集成，如果直接在项目中使用 CVSDK 提供的 C 接口集成，可以参考接口说明-特效及接口说明-算法。
以特效SDK为例，特效SDK 的统一封装接口为 EffectManager，SDK 的使用可以分为三个阶段：

初始化特效SDK
使用特效SDK 进行图像处理
特效SDK 参数设置，如设置美颜、贴纸、滤镜等

注意，SDK 的所有操作都应该在GL环境中进行。

初始化特效SDK

鸿蒙ArkTS 层未提供 GL 环境接口，需要配合 XComponent 完成图形绘制和媒体数据的写入。SDK 提供EglWrapper 工具类来进行 GLContext 的创建和管理。

// 在XComponent onLoad 回调中调用以拿到其管理的 nativeWindow 对象，用来创建 EGLContext
this.mEffectManager = new EffectManager()
this.mEffectManager.init(720, 1280, this.mXComponentController)

使用 SDK 进行特效处理

鸿蒙ArkTS 层未直接提供相机流对应的回调，需要创建 NativeImage 来完成回调的注册，NativeImage 对象关联用于创建相机的 SurfaceID，同时提供setOnFrameAvailAbleLister 方法来设置逐帧更新的回调。
SDK 提供NativeImageWrapper 工具类来实现 ArkTS 层对 NativeImage 的封装。NativeImage 作为相机流消费者的链路当前仅支持绑定 OES 纹理，传入SDK前需要进行Texture_2D 的格式转换。
SDK 提供GlWrapper 工具类来实现ArkTS 层对常用 GL 绘制命令的封装，提供纹理创建、FrameBuffer绑定、纹理格式转换、readPixel、上屏和资源销毁的方法。

// NativeImageWrapper 对象的创建及回调注册
this.mNativeImage = new NativeImageWrapper()
this.mNativeImage.setOnFrameAvailAbleLister(this, this.frameAvailable)

// frameAvailable 回调实现
// GLContext 设置为当前上下文
this.mEglCore?.makeCurrent()
// NativeImage 刷新
this.mNativeImage?.update()
// 获取NativeImage 关联的TextureID
let oesId = this.mNativeImage?.getTextureId()
// 使用GLUtils 完成OES纹理到2D纹理的转换
this.mGlUtils?.transferOesTo2DTex(oesId, this.mSrcTexture, this.mWidth, this.mHeight, tmp.mData)
// 设置SDK 传入纹理宽高
this.renderManager?.setWidthHeight(this.mWidth, this.mHeight)
console.time("effectProcess")
// 传入逐帧处理纹理，该输入纹理格式必须为2D纹理，输入和输出纹理需要单独创建，传入时间戳单位为ms
this.renderManager?.processTexture(this.mSrcTexture, this.mDstTexture, systemDateTime.getTime(false))
console.timeEnd("effectProcess")

RenderManager对象process接口说明

参数名	含义
inputTex	输入纹理ID，需要确保该纹理是一张人脸为正的图像，如果是前置摄像头，需要同时完成镜像处理
outTex	输出纹理ID
width	输入纹理宽度
height	输入纹理高度
timeStamp	当前时间，单位为ms

process 方法的输出为渲染后的 2D 纹理。

SDK 参数设置，如设置美颜、贴纸、滤镜等

注意，SDK 参数设置需要在初始化之后调用，请尽量与 SDK图像处理处于同一线程使用，以避免可能出现的问题。

(1)设置美颜、美型、美妆、滤镜

美颜、美型、美妆、滤镜的设置使用的是同一个接口，一般来说使一个美颜生效需要两步：
第一步：设置素材对应的路径
第二步：设置素材中，特效的强度（一般强度默认为 0，所以这一步不执行会没有效果）
设置素材路径接口

/**
 * 设置特效组合，目前支持美颜、美形、美体、美妆、滤镜特效的任意叠加
 */
setComposerNodes(nodes:string[]):number
// 示例
this.mEffectManager?.renderManager?.setComposerNodes(Array.from(this.curNodes))

此处的素材路径需要为素材包的绝对路径，可以使用SDK提供 FileUtils 工具类来辅助获取
注意，SDK 内部不会保存已设置的素材，所以此方法每次调用都需要将所有需要生效的素材路径加上。
设置素材中，特效强度接口

/**
 * 更新组合特效(美颜、美形、美体、 美妆)中某个节点的强度
 */
updateComposerNode(node:string, key:string, value:number):number
// 示例
this.mEffectManager?.renderManager?.updateComposerNode(FileUtils.getComposerPath(node), tag, value/100.0)

以美颜素材为例，需要通过 key 来控制我们要修改的是美白、磨皮还是锐化的强度，素材中 key 与功能的对应关系参见素材key对应说明（421及以上）

(2)设置贴纸

设置贴纸接口

/**
 * 开启或者关闭贴纸 如果path为空 关闭贴纸
 * @param path 贴纸素材的文件路径
 */
setEffect(path:string):number
// 示例
this.mEffectManager?.renderManager?.setEffect(FileUtils.getStickerPath(effect))

Sample文件结构

. 
├── entry # Demo主Module入口 
│   ├── ets  
│   │   ├── common # 通用接口封装
│   │   │   ├── utils # demo 功能相关，各种工具类
│   │   │   │   ├── FileUtils.ets # 资源，道具等文件操作封装
│   │   │   │   ├── MatrixUtils.ets # 矩阵运算操作封装
│   │   │   └── Constants.ets
│   │   ├── effect #SDK 能力调用接口封装，含特效、算法调用
│   │   │   ├── Camera.ets # camera 接口封装
│   │   │   └── EffectManager.ets # SDK能力调用主入口 接口封装
│   │   ├── entryability # module主活动
│   │   │   └── EntryAbility.ets# module主活动入口，权限请求，加载界面
│   │   ├── entrybackupability 
│   │   │   └── EntryBackupAbility.ets
│   │   ├── pages # UI界面布局
│   │   │   ├── BaseBar.ets # 相机切换UI界面
│   │   │   ├── EffectPage.ets # Effect道具包UI界面布局
│   │   │   └── Index.ets # Module主UI界面
│   ├── resources # UI以及Effect道具包资源
│   │   ├── base # UI相关资源
│   │   ├── rawfile # Effect道具包相关资源
│   │   │   ├── ComposeMakeup.bundle
│   │   │   ├── LicenseBag.bundle
│   │   │   ├── ModelResource.bundle # 模型资源
│   │   │   └── StickerResource.bundle # 贴纸道具包资源
│   │   │   │   └── XXX
├── package # Effect SDK包
│   └── effectApi.har
├── oh-package.json5 # 项目对har的依赖配置

Sample运行指南

本地环境配置

DevEco Studio 最新版（测试所在IDE环境为5.0.0.61，API Version 12 Beta6）
如果遇到其他版本编译不过的，请将版本切换到上面指定版本。

使用方式

解压 ohossample.zip
使用 DevEco Studio 打开 BytedEffects 中ohos鸿蒙项目
工程内进行 sync 后 build 运行

注意事项

鉴权

cv sdk 有鉴权机制，会验证 bundleName 是否和 license 中的匹配，证书需要申请

注意授权时间

如手机时间不在授权范围内，cv sdk 调用会失败，具体授权时间段，可参考如下本地资源授权文件

授权操作指南

注：以对外 demo 为例，具体需以开发项目路径为准。在测试阶段，仅提供绑定包名的 license 文件，用户可配合 demo 素材体验所有特效能力。而在正式授权时，将提供对应的 license 和素材。

第一步：将取得的授权与素材文件全部替换掉byted_effect_sdk/byted_effect/ohos/app/entry/src/main/resources/rawfile文件夹中资源文件（测试阶段仅替换license即可）

第二步：将FileUtils类中LICENSE_NAME修改为当前使用的授权文件名

若授权失败，首先排查以下可能的情形

检查手机系统时间是否在license授权时效内
检查 app.json5 中的 bundleName 是否与授权绑定包名一致
检查license路径是否正确，有无被SDK正确读取到

智能美化特效