快速接入指南

NveEffectKit使用说明文档

---

NveEffectKit集成了美颜、美型、美妆、妆容、滤镜、人脸道具功能。依赖库为3.8.0以上的美摄Effect库

快速体验

• 美摄官方网站下载SDK人脸版本(下载**zip**包为NvStreamingSdk_Android_..._ARSCENE_MS.zip )
• 使用Android Studio打开./samples/android/NvEffectKitDemo快速体验相关功能。
• 运行demo时可查阅常见问题。

如何导入项目？

Android打包为AAR库(NveEffectKit.aar)，复制到libs目录下(./app/libs)，在build.gradle设置aar的编译引入 >NveEffectKit.aar路径： ./samples/android/NvEffectKitDemo/libBase/libs/NveEffectKit.aar

api fileTree(dir: 'libs', include: ['*.jar', '*.aar'])

初始化SDK

init时需传入授权文件路径，该路径可以是assets下路径，或本地的绝对路径。 effectsdkdemo.lic请联系美摄商务获取

 
String licPath = "assets:/effectsdkdemo.lic";
NveEffectKit.getInstance().init(this, licPath);

初始化人脸检测模型

初始化模型，需传入模型类型和路径（路径可以为assets路径或本地绝对路径）

 
NveEffectKit.getInstance().initModel(this, NveDetectionModelType.FACE, faceModelPath);

类型	名称	用途
NveDetectionModelType.FACE	人脸	人脸道具使用
NveDetectionModelType.FAKE_FACE	假脸	人脸道具使用
NveDetectionModelType.MAKEUP2	美妆	美妆使用
NveDetectionModelType.FACE_COMMON	人脸通用	美颜和美妆使用
NveDetectionModelType.ADVANCED_BEAUTY	高级美颜	美颜和妆容使用
NveDetectionModelType.EYEBALL	眼球	部分人脸道具会用到眼球效果
NveDetectionModelType.SEGMENTATION	背景分割	部分人脸道具会用到分割效果
NveDetectionModelType.AVATAR	Avatar	根据表情动的特效果类别会使用这个模型

• NveDetectionModelType.MAKEUP2在SDK3.13.x以上已废弃
• NveDetectionModelType.FACE_COMMON和NveDetectionModelType.ADVANCED_BEAUTY最低支持版本为 SDK3.13.x
• 人脸模型详情可查看demo代码

  samples/android/NvEffectKitDemo/app/src/main/java/com/meicam/effectsdkdemo/Constants.java

  samples/android/NvEffectKitDemo/app/src/main/java/com/meicam/effectsdkdemo/MainActivity.java
   
  private void initEffectModel() {}

• 更多可查看常见问题。

相机预览，录制参考demo代码

samples/android/NvEffectKitDemo/app/src/main/java/com/meicam/effectsdkdemo/camera/...

samples/android/NvEffectKitDemo/app/src/main/java/com/meicam/effectsdkdemo/MainActivity.java
 
private GLSurfaceView mGlView;
private RenderCameraUtil mRenderCameraUtil;

美颜使用

//美颜的使用
NveBeauty beauty= new NveBeauty();
//开关可以通过enable参数控制
beauty.setEnable(true);
//只设置一次即可，后续修改参数可直接调用beauty的参数set方法。
NveEffectKit.getInstance().setBeauty(beauty);
 
//磨皮和美白有多种类型，默认类型如下
beauty.setBlurType(NveBeautyBlurTypeEnum.AdvancedBuffingSkin1);
beauty.setWhiteningType(NveBeautyWhiteningTypeEnum.WhiteningA);

参数	类型	用途
enable	boolean	美颜功能开关
blurType	NveBeautyBlurTypeEnum	磨皮类型
blurIntensity	float	磨皮强度，[0-1]
whiteningType	NvBeautyWhiteningTypeEnum	美白类型
whiteningIntensity	float	美白强度，[0-1]
matteIntensity	float	去油光强度，[0-1]
matteFillRadius	float	去油光半径，[0-1]
reddeningIntensity	float	红润强度，[0-1]
definitionIntensity	float	清晰度强度，[0-1]
sharpnessIntensity	float	锐度强度，[0-10]

磨皮类型

名称	用途
NveBeautyBlurTypeEnum.BuffingSkin	普通磨皮
NveBeautyBlurTypeEnum.AdvancedBuffingSkin1	高级磨皮1
NveBeautyBlurTypeEnum.AdvancedBuffingSkin2	高级磨皮2
NveBeautyBlurTypeEnum.AdvancedBuffingSkin3	高级磨皮3

• 更多可查看常见问题。

美白类型

名称	用途
NvBeautyWhiteningTypeEnum.WhiteningA	美白A
NvBeautyWhiteningTypeEnum.WhiteningB	美白B

• 更多可查看常见问题。

美型使用

//使用美型
NveShape shape= new NveShape();
shape.setEnable(true);
NveEffectKit.getInstance().setShape(shape);
//如何使用美型包？
//瘦脸 为例
//新增美型，分别传入类型，shapeDegree:美型强度[-1,1]，
float shapeDegree = 1f;
//packagePath 此处为模拟路径，替换为实际资源包路径
String packagePath = "assets:/beauty/shape/shapePackage/63BD3F32-D01B-4755-92D5-0DE361E4045A.1.facemesh";
// 资源包授权文件路径
String packageLicPath = "assets:/beauty/shape/shapePackage/63BD3F32-D01B-4755-92D5-0DE361E4045A.1.lic";
//如果资源的结尾是facemesh则类型为ASSET_PACKAGE_TYPE_FACE_MESH，如果是warp则为ASSET_PACKAGE_TYPE_WARP
//63BD3F32-D01B-4755-92D5-0DE361E4045A.1.facemesh
int packageType = NvsAssetPackageManager.ASSET_PACKAGE_TYPE_FACE_MESH;
//63BD3F32-D01B-4755-92D5-0DE361E4045A.1.warp
// int packageType = NvsAssetPackageManager.ASSET_PACKAGE_TYPE_WARP;
//shapePackageID：美型包ID(包需要安装,安装见下面安装使用)
String shapePackageID = NveAssetPackageManagerUtil.installFxPackage(packagePath, packageLicPath, packageType);
shape.setShapeData(NveShapeTypeEnum.FACE_SIZE, new NveShapeData(shapeDegree, shapePackageID));
//修改美型强度
shape.setDegreeByType(NveShapeTypeEnum.FACE_SIZE, shapeDegree);
NveEffectKit.getInstance().setShape(shape);

名称	用途
NveShapeTypeEnum.FACE_WIDTH	窄脸，[-1,1]
NveShapeTypeEnum.FACE_LENGTH	小脸，[-1,1]
NveShapeTypeEnum.FACE_SIZE	瘦脸，[-1,1]
NveShapeTypeEnum.FORE_HEAD	额头，[-1,1]
NveShapeTypeEnum.CHIN	下巴，[-1,1]
NveShapeTypeEnum.EYE_SIZE	大眼，[-1,1]
NveShapeTypeEnum.EYE_ANGLE	眼角，[-1,1]
NveShapeTypeEnum.NOSE_WIDTH	瘦鼻，[-1,1]
NveShapeTypeEnum.NOSE_LENGTH	长鼻，[-1,1]
NveShapeTypeEnum.MOUTH_SIZE	嘴型，[-1,1]
NveShapeTypeEnum.MOUTH_CORNER	嘴角，[-1,1]

微整形使用

//使用微整形
NveMicroShape microShape = new NveMicroShape();
microShape.setEnable(true);
NveEffectKit.getInstance().setMicroShape(microShape);
 
//新增微整形，分别传入类型，shapeDegree:微整形强度，
float shapeDegree = 0.5f;
//packagePath 此处为模拟路径，替换为实际资源包路径
String packagePath = "assets:/beauty/shape/shapePackage/63BD3F32-D01B-4755-92D5-0DE361E4045A.1.facemesh";
// 资源包授权文件路径
String packageLicPath = "assets:/beauty/shape/shapePackage/63BD3F32-D01B-4755-92D5-0DE361E4045A.1.lic";
//如果资源的结尾是facemesh则类型为ASSET_PACKAGE_TYPE_FACE_MESH，如果是warp则为ASSET_PACKAGE_TYPE_WARP
//63BD3F32-D01B-4755-92D5-0DE361E4045A.1.facemesh
int packageType = NvsAssetPackageManager.ASSET_PACKAGE_TYPE_FACE_MESH;
//63BD3F32-D01B-4755-92D5-0DE361E4045A.1.warp
// int packageType = NvsAssetPackageManager.ASSET_PACKAGE_TYPE_WARP;
//shapePackageID：微整形ID(包需要安装,安装见下面安装使用)
String shapePackageID = NveAssetPackageManagerUtil.installFxPackage(packagePath, packageLicPath, packageType);
//HEAD_SIZE 为例
shape.setMicroShapeData(NveMicroShapeTypeEnum.HEAD_SIZE, new NveMicroShapeData(shapeDegree,shapePackageID));
//修改微整形强度
shape.setDegreeByType(NveMicroShapeTypeEnum.HEAD_SIZE, shapeDegree);

名称	用途
NveMicroShapeTypeEnum.HEAD_SIZE	缩头，[-1,1]
NveMicroShapeTypeEnum.CHEEKBONE_WIDTH	颧骨宽，[-1,1]
NveMicroShapeTypeEnum.JAW_WIDTH	下颌宽，[-1,1]
NveMicroShapeTypeEnum.TEMPLE_WIDTH	太阳穴宽，[-1,1]
NveMicroShapeTypeEnum.NASOLABIAL_FOLDS	法令纹，[0,1]
NveMicroShapeTypeEnum.DARK_CIRCLES	黑眼圈，[0,1]
NveMicroShapeTypeEnum.BRIGHTEN_EYES	亮眼，[0,1]
NveMicroShapeTypeEnum.WHITEN_TEETH	美牙，[0,1]
NveMicroShapeTypeEnum.EYE_ANGLE_DEGREE	眼角度，[-1,1]
NveMicroShapeTypeEnum.EYE_DISTANCE	眼离，[-1,1]
NveMicroShapeTypeEnum.EYE_HEIGHT	眼高度，[-1,1]
NveMicroShapeTypeEnum.EYE_WIDTH	眼宽度，[-1,1]
NveMicroShapeTypeEnum.EYE_ARC	眼弧度，[-1,1]
NveMicroShapeTypeEnum.EYE_Y_OFFSET	眼上下，[-1,1]
NveMicroShapeTypeEnum.PHILTRUM	人中，[-1,1]
NveMicroShapeTypeEnum.NOSE_BRIDGE_WIDTH	鼻梁宽度，[-1,1]
NveMicroShapeTypeEnum.NOSE_HEAD	鼻头，[-1,1]
NveMicroShapeTypeEnum.EYEBROW_THICKNESS	眉毛粗细，[-1,1]
NveMicroShapeTypeEnum.EYEBROW_ANGLE	眉角度，[-1,1]
NveMicroShapeTypeEnum.EYEBROW_Y_OFFSET	眉上下，[-1,1]
NvMicroShapeTypeEnum.EYEBROW_X_OFFSET	眉间距，[-1,1]

美摄SDK For Android: 特效名称列表 (meishesdk.com)

美颜、美型、微整形的各个参数均来自于美摄文档仓库中AR Scene的说明，更多进阶用法见上方链接。

---

美妆

//使用美妆
NveMakeup makeUp= new NveMakeup();
makeUp.setEnable(true);
NveEffectKit.getInstance().setMakeup(makeUp);
 
//新增美妆中的单妆，NvSingleMakeUp来自单妆包中解析的makeup.json
//(包需要安装,安装见下面安装使用)
makeUp.addSingleMakeUp(NveMakeupTypeEnum, NveSingleMakeUp);
//根据单妆类型删除使用的单妆，每个类型的单妆只能加一个，例如只能加一种类型的口红。            
makeUp.removeSingleMakeUp(NveMakeupTypeEnum);
 
//妆容的使用，NvComposeMakeup来自妆容包中解析的info.json
//(包需要安装,安装见下面安装使用)
makeUp.setComposeMakeup(NveComposeMakeup);
//妆容的删除。妆容是由多个单妆、美颜、美型、微整形、滤镜等组成，每次只能应用一个妆容
makeUp.removeComposeMakeUp();
 
//调节单妆强度
makeUp.setIntensityByType(NveMakeupTypeEnum.Brighten,1);
//调节单妆颜色
makeUp.setColorByType(NveMakeupTypeEnum.Brighten,new NvsColor(0,0,0,0));

json解析安装等可参考： samples/android/NvEffectKitDemo/app/src/main/java/com/meicam/effectsdkdemo/data/NvAssetManager samples/android/NvEffectKitDemo/app/src/main/java/com/meicam/effectsdkdemo/data/AssetInfoData

名称	用途
NveMakeupTypeEnum.Lip	口红
NveMakeupTypeEnum.Eyebrow	眉毛
NveMakeupTypeEnum.Eyeshadow	眼影
NveMakeupTypeEnum.Eyelash	睫毛
NveMakeupTypeEnum.Eyeliner	眼线
NveMakeupTypeEnum.Blusher	腮红
NveMakeupTypeEnum.Shadow	修容
NveMakeupTypeEnum.Brighten	高光
NveMakeupTypeEnum.ComposeMakeup	妆容

滤镜

//必传ID，包滤镜需安装，传入安装后的ID(安装见下面安装使用)
NveFilter filter = new NveFilter(effectId);
NveEffectKit.getInstance().addFilter(filter);
 
//setFilter表示使用滤镜，后续可以进行其他修改参数操作，例如修改强度：
filter.setFilterIntensity(0.5f);
 
//移除滤镜
NveEffectKit.getInstance().removeFilter(filter);

json解析安装等可参考： samples/android/NvEffectKitDemo/app/src/main/java/com/meicam/effectsdkdemo/data/NvAssetManager samples/android/NvEffectKitDemo/app/src/main/java/com/meicam/effectsdkdemo/data/AssetInfoData samples/android/NvEffectKitDemo/app/src/main/java/com/meicam/effectsdkdemo/data/FilterJsonParseData

道具

NveFaceProp faceProp = new NveFaceProp();
faceProp.setEnable(true);
NveEffectKit.getInstance().setFaceProp(faceProp);
 
//设置道具Id(道具包需要安装,安装见下面安装使用)
String propId = "xxx"
faceProp.setPropId(propId);

json解析安装等可参考： samples/android/NvEffectKitDemo/app/src/main/java/com/meicam/effectsdkdemo/data/NvAssetManager samples/android/NvEffectKitDemo/app/src/main/java/com/meicam/effectsdkdemo/data/AssetInfoData samples/android/NvEffectKitDemo/app/src/main/java/com/meicam/effectsdkdemo/data/StickerJsonParseData

自定义特效

NveEffectKit除了上述已有功能，用户可自已创建美摄支持的特效，使用中间层来渲染。比如背景分割功能（需提前初始化人脸和分割模型），实现如下：

//创建背景分割
NvsRational aspectRatio = new NvsRational(9, 16);
NvsVideoEffect mSegmentationEffect = NvsEffectSdkContext.getInstance().createVideoEffect("Segmentation Background Fill", aspectRatio);
mSegmentationEffect.setIntVal("Stretch Mode", 2);
mSegmentationEffect.setMenuVal("Segment Type", "Half Body");
mSegmentationEffect.setColorVal("Background Color", new NvsColor(0, 1, 0, 1));
 
//添加渲染
NveEffectKit.getInstance().addEffect(mSegmentationEffect);
 
//根据索引添加渲染
NveEffectKit.getInstance().insertEffect(mSegmentationEffect,0);
 
//移除创建的特效
NveEffectKit.getInstance().removeEffect(mSegmentationEffect);

---

包安装

上述的内容中基本都涉及包安装，官网有安装说明

美摄SDK For Android: 素材包安装 (meishesdk.com)

可以使用已经封装好的工具类（NvAssetPackageManagerUtil）示例代码：

//packagePath 此处为模拟路径，替换为实际资源包路径
String packagePath = "assets:/beauty/shape/shapePackage/63BD3F32-D01B-4755-92D5-0DE361E4045A.1.facemesh";
// 资源包授权文件路径
String packageLicPath = "assets:/beauty/shape/shapePackage/63BD3F32-D01B-4755-92D5-0DE361E4045A.1.lic";
//如果资源的结尾是facemesh则类型为ASSET_PACKAGE_TYPE_FACE_MESH，如果是warp则为ASSET_PACKAGE_TYPE_WARP
//63BD3F32-D01B-4755-92D5-0DE361E4045A.1.facemesh
int packageType = NvsAssetPackageManager.ASSET_PACKAGE_TYPE_FACE_MESH;
//63BD3F32-D01B-4755-92D5-0DE361E4045A.1.warp
// int packageType = NvsAssetPackageManager.ASSET_PACKAGE_TYPE_WARP;
//shapePackageID：资源包ID(包需要安装,安装见下面安装使用)
String shapePackageID = NveAssetPackageManagerUtil.installFxPackage(packagePath, packageLicPath, packageType);

其中需要重点关注的参数有：

1、packagePath– 安装包的路径，可以为assets路径或者本地绝对路径

2、packageLicPath– 安装包的授权文件路径

3、packageType– 安装包类型，具体类型见：美摄SDK For Android: com.meicam.sdk.NvsAssetPackageManager类 参考 (meishesdk.com)

---

渲染

1.RenderCore相关初始化

//注：需提前初始化SDK
NveEffectKit.getInstance().initialize();

2.NveRenderInput说明

NveRenderInput主要包括渲染配置（NveRenderConfig），纹理（NveTexture），Buffer（NveImageBuffer），图像的格式（pixelFormat）。具体参数如下：

（1）NveRenderConfig相关参数，包括相机朝向（cameraOrientation）和渲染模式（NveRenderMode）

NveRenderMode	说明
NveRenderConfig.NveRenderMode.TEXTURE_TEXTURE	纹理入，纹理出
NveRenderConfig.NveRenderMode.BUFFER_TEXTURE	Buffer入，纹理出
NveRenderConfig.NveRenderMode.BUFFER_BUFFER	Buffer入，Buffer出

（2）NveTexture相关参数

参数	说明
textureId	纹理ID
mirror	是否水平翻转，OES纹理转Texture 2D纹理需要
NveSize	纹理宽高
NveTextureType	纹理类型
NveTextureLayout	纹理方向

NveTextureType	说明
NveTextureType.NV_COMMON_TEXTURE	普通纹理
NveTextureType.NV_OES_TEXTURE	OpenGL OES纹理

NveTextureLayout	说明
NveTextureLayout.UP_SIDE_DOWN	上下颠倒
NveTextureLayout.DOWN_SIDE_UP	正常

（3）NveImageBuffer相关参数

名称	说明
data	Buffer数据
NveSize	Buffer宽高
mirror	是否水平翻转
displayRotation	当前图像需要旋转的角度
rowPitchY	图像每行在Frame中占的字节数，如果图像格式是NV21,YUV420, 则指Y平面
rowPitchUV	图像每行在Frame中占的字节数 一般是指UV平面,如果格式为RGBA,这个量没有意义

（4）pixelFormat图像格式，其封装在NvFormatType中，具体对应可参考官网视频帧像素格式

3.NveRenderOutput说明

NveRenderOutput主要包括渲染结果（NveRenderError），输出纹理（NveTexture，参数同上），输出Buffer（NveImageBuffer，参数同上）。其渲染结果参数如下

名称	说明
NveRenderError.NO_ERROR	成功
NveRenderError.ERROR_UNKNOWN	未知错误
NveRenderError.INVALID_TEXTURE	无效的纹理
NveRenderError.INVALID_INPUT_PARAM	无效的输入参数，针对NvRenderInput

4.渲染

//输入配置
NveRenderInput  mRenderInput = new NveRenderInput();
mRenderInput.setPixelFormat(NveFormatType.VIDEO_FRAME_PIXEL_FROMAT_NV21.getType());
NveRenderConfig config = new NveRenderConfig()
                .setRenderMode(NveRenderConfig.NveRenderMode.TEXTURE_TEXTURE)
                .setCameraOrientation(mCameraProxy.getOrientation()).build();
mRenderInput.setConfig(config);
 
//输入纹理
NveTexture nvTexture = new NveTexture();
nvTexture.setTextureId(displayTex);
Texture.setTextureType(NveTextureType.NV_OES_TEXTURE);
nvTexture.setSize(new NveSize(texWidth, texHeight));
nvTexture.setMirror(mCameraProxy.isFlipHorizontal());
mRenderInput.setTexture(nvTexture);
 
//输入Buffer
NveImageBufferbuffer = new NveImageBuffer();
buffer.setData(data);
buffer.setSize(new NveSize(bufferWidth, bufferHeight));
buffer.setDisplayRotation(mOrientation);
buffer.setMirror(mCameraProxy.isFlipHorizontal());
mRenderInput.setImageBuffer(buffer);
 
//渲染
NveRenderOutput renderOutput = mNvEffectKit.renderEffect(mRenderInput);
 
  ......
 
if (null != renderOutput) {
     //回收render out
     NveEffectKitt.recycleOutput(renderOutput);
}

5.资源释放

在退出或者不再需要渲染时，需要释放相关资源，可调用下面的方法

NveEffectKit.getInstance().cleanUp();

注意：该方法需要在GLContext所在的线程调用

销毁

在页面退出或者应用杀死的情况下进行SDK的销毁，可调用下面的方法

NveEffectKit.getInstance().destroy();

注意：如果是在某个页面退出时进行销毁，那么在其他地方还需要使用SDK，那么在使用前就需要重新初始化SDK，即调用init方法

常见问题

1.使用Android Studio较高版本时run apk失败，需要修改Gradle JDK版本为 jdk 11

>Settings->Build,Execution,Deployment->Build Tools->Gradle->Gradle JDK (java 11)

类似错误：

FAILURE: Build completed with 2 failures.
 
1: Task failed with an exception.
-----------
* What went wrong:
Execution failed for task ':app:processDebugMainManifest'.
> Unable to make field private final java.lang.String java.io.File.path accessible: module java.base does not "opens java.io" to unnamed module @16a1c82d
 
* Try:
Run with --info or --debug option to get more log output. Run with --scan to get full insights.
 
* Exception is:
org.gradle.api.tasks.TaskExecutionException: Execution failed for task 
Caused by: java.lang.reflect.InaccessibleObjectException: Unable to make field private final java.lang.String java.io.File.path accessible: module java.base does not "opens java.io" to unnamed module @16a1c82d

2.模型中face240和face106有什么区别？

240和160指的是人脸模型的点位数量，240效果更佳。160点位不支持美妆。

3.普通磨皮，高级磨皮1，高级磨皮2，高级磨皮3有什么区别？

高级磨皮1是Android端标准效果，高级磨皮2是iOS端标准效果，高级磨皮3是男性效果. 详情见文档：AR Scene Advanced Beauty Type

4.美颜A，美颜B有什么区别？

实现方式不同，美颜B使用Lut文件。 详情见文档：AR Scene Whitening Lut File

5.是否支持自定义GLSurfaceView/相机预览？

代码中示例供参考，如果用户已有相关实现，可以提供要渲染的纹理或者buffer 数据即可。详情可咨询美摄技术支持

6.导入项目后，渲染无效果或黑屏？

检查项目中lic文件与applicationId是否绑定。详情可咨询美摄商务

7.已接入NvAndroidStreamingSdk.jar，冲突如何处理？

删除项目中原NvAndroidStreamingSdk.jar，重新依赖NveEffectKit.aar。