AR Scene 技术文档

1. 概述

AR Scene是美摄SDK中用于展示AR效果的特技，现支持道具，美颜，美型，美妆等功能。

2. 使用

2.1 资源加载

AR Scene 中由于使用了人体检测相关的技术，在程序初始化阶段需要加载一些模型以及数据包资源。

2.1.1 模型加载

首先判断该SDK是否包含AR功能，不包含AR功能的SDK无法加载人体检测模型。

// 检测SDK包是否有AR模块
bool hasAR = [NvsStreamingContext hasARModule];

人体检测模型的加载通过调用 NvsStreamingContext.initHumanDetection:licenseFilePath:features: "InitHumanDetection" 和 NvsStreamingContext.initHumanDetectionExt:licenseFilePath:features: "InitHumanDetectionExt" 实现。NvsStreamingContext.initHumanDetection:licenseFilePath:features: "InitHumanDetection" 指定主模型的加载，只能调用一次。NvsStreamingContext.initHumanDetectionExt:licenseFilePath:features: "InitHumanDetectionExt" 指定扩展模型的加载，可以通过多次调用加载多个扩展模型。一般情况下我们使用人脸点位模型作为主模型。

如下是加载人脸点位模型与眼眼球轮廓模型的示例。

// 人脸点位模型加载，使能“视频检测模式”
BOOL initSuccess = [NvsStreamingContext initHumanDetection:landmarksModelPath 
        licenseFilePath:licPath 
        features:NvsHumanDetectionFeature_FaceLandmark | 
        NvsHumanDetectionFeature_FaceAction | 
        NvsHumanDetectionFeature_VideoMode];
 
 
// 眼球轮廓模型加载，使能“视频检测模式”，与人脸模型的检测模式对齐
initSuccess = [NvsStreamingContext initHumanDetection:eyeballModelPath 
        licenseFilePath:licPath 
        NvsHumanDetectionFeature_EyeballLandmark | 
        NvsHumanDetectionFeature_VideoMode];

在程序销毁时还需调用 closeHumanDetection 来卸载安装过的所有模型以及数据包。

[NvsStreamingContext closeHumanDetection];

注：

• 模型初始化操作涉及文件拷贝耗时操作，建议放在子线程去出处理。
• modelFilePath指定模型加载路径，不支持ASSET路径；
• 使用美摄自研点位SDK licenseFilePath为空；
• features项指定模型类型以及所有支持的检测模式；
• 所有 NvsStreamingContext.initHumanDetection:licenseFilePath:features: "InitHumanDetection" 和 NvsStreamingContext.initHumanDetectionExt:licenseFilePath:features: "InitHumanDetectionExt" 调用中的检测模式，建议设置成相同模式，不同检测模式会影响程序运行效率。

2.1.1.1 模型类型

模型分为两种，普通模型与复合模型。普通模型只支持单一的功能，复合模型可以支持多项功能。例如人脸检测模型就是复合模型，同时支持点位检测以及人脸动作检测。

SDK现支持具体如下：

模型	命名	复合模型	Flag
106人脸检测模型	ms_face_vX.X.X.model	是	NvsHumanDetectionFeature_FaceLandmark | NvsHumanDetectionFeature_FaceAction
240人脸检测模型	ms_face240_vX.X.X.model	是	NvsHumanDetectionFeature_FaceLandmark | NvsHumanDetectionFeature_FaceAction
眼球轮廓检测模型	ms_eyecontour_vX.X.X.model	否	NvsHumanDetectionFeature_EyeballLandmark
表情检测模型	ms_avatar_vX.X.X.model	否	NvsHumanDetectionFeature_AvatarExpression
手势检测模型	ms_hand_vX.X.X.model	是	NvsHumanDetectionFeature_HandLandmark | NvsHumanDetectionFeature_HandAction
背景分割模型	ms_humanseg_vX.X.X.model	否	NvsHumanDetectionFeature_Background
天空分割模型	ms_skyseg_vX.X.X.model	否	NvsHumanDetectionFeature_SegmentationSky

注：

• 106人脸检测模型与240人脸检测模型只能选用一个；
• 可以使用240模型，但只使用其中的106点位检测功能，不影响检测效率；
• 对于复合模型，某个功能项没有或上，那么，AR Scene或其他使用到该功能项的特技将无法正常运行。

2.1.1.2 检测模式

检测模式：

模式	Flag	描述
视频检测模式	NvsHumanDetectionFeature_VideoMode	适用于拍摄场景，效率最高，视频间检测结果连续，但首帧通常无检测出来
图片检测模式	NvsHumanDetectionFeature_ImageMode	适用于编辑模式，效率一般，检测结果不连续，首帧能够检测出来
半图片检测模式	NvsHumanDetectionFeature_SemiImageMode	适用于拍摄模式与编辑模式，效率较高，检测结果连续，首帧能够检测出来线程模式：

在调用 NvsStreamingContext.initHumanDetection:licenseFilePath:features: "InitHumanDetection" 和 NvsStreamingContext.initHumanDetectionExt:licenseFilePath:features: "InitHumanDetectionExt" 时features参数需要或上所有支持的检测模式。同时在AR Scene使用时，需要通过 setDetectionMode 指定该特技实例具体使用哪种检测模式。

例如，如下代码在模型加载阶段同时或上了“视频检测模式”和“图片检测模式”，在 AR Scene 特技使用时指定检测模型为“图片检测模式”。

// 人脸点位模型加载，同时使能“视频检测模式”与“图片检测模式”
BOOL initSuccess = [NvsStreamingContext initHumanDetection:landmarksModelPath 
        licenseFilePath:licPath 
        features:NvsHumanDetectionFeature_FaceLandmark |
        NvsHumanDetectionFeature_FaceAction | 
        NvsHumanDetectionFeature_VideoMode |
        NvsHumanDetectionFeature_ImageMode];
 
....
 
// AR Scene 特技选择使用“图片检测模式”进行检测
NvsARSceneManipulate *arSceneManipulate = mArSceneEffect.getARSceneManipulate;
if (arSceneManipulate) {
    [arSceneManipulate setDetectionMode:NvsARSceneDetectionMode_Image];

2.1.2 数据包加载

数据包使用 NvsStreamingContext.setupHumanDetectionData:dataFilePath: "setupHumanDetectionData" 来加载。如下代码展示美妆数据包的加载过程。

// 加载美妆数据包
BOOL setupSuccess = [NvsStreamingContext setupHumanDetectionData:NvsHumanDetectionDataType_Makeup2 dataFilePath:makeup2Path];

数据包类型：

数据包	命名	类型	描述
假脸数据包	fakeface.dat	NvsHumanDetectionDataType_FakeFace	假脸数据，用于AR Scene的人脸道具中，道具紧贴人脸，随面部表情变化而变化
美妆数据包（Deprecated）	makeup2_240_vX.X.X.dat	NvsHumanDetectionDataType_Makeup2	美妆相关数据，用于美妆以及美妆道具中（已废弃, 需替换成人脸通用数据包）
人脸通用数据包	facecommon_vX.X.X.dat	NvsHumanDetectionDataType_FaceCommon	人脸通用数据包，用于美妆以及高级美颜
高级美颜数据包	advancedbeauty_vX.X.X.dat	NvsHumanDetectionDataType_AdvancedBeauty	高级美颜相关数据

注：使用美妆需设置人脸通用数据包，使用高级颜需同时设置人脸通用数据包以及高级美颜数据包。

2.2 特技使用

2.2.1 特技创建

AR Scene 是内建特技，对应特技名称为“AR Scene”。可以使用美摄SDK内建特技的标准创建方式进行创建。例如拍摄模式下：

NvsVideoFx *mArSceneEffect= [self.streamingContext appendBuiltinCaptureVideoFx:@"AR Scene"];

2.2.2 其他设置

检测类特技，如AR Scene需要进行buddy buffer相关设置。分为以下几类情况：

拍摄模式

预览开启时需要设置buddy buffer相关flags，NvsStreamingEngineCaptureFlag_CaptureBuddyHostVideoFrame。

[mStreamingContext startCapturePreviewForLiveStreaming:_currentDeviceIndex
                                         videoResGrade:NvsVideoCaptureResolutionGradeHigh
                                                 flags:NvsStreamingEngineCaptureFlag_CaptureBuddyHostVideoFrame
                                           aspectRatio:&_aspectRatio
                                 liveStreamingEndPoint:_endPoint];

编辑模式

检测类特效推荐以 Raw Filter 形式添加，效率更高。

播放时需要分别设置buddy buffer相关flags，NvsStreamingEnginePlaybackFlag_BuddyHostVideoFrame。

需要注意的是，如果特技是以 Raw Filter 的形式添加，flags 上才能够且必须或上NvsStreamingEnginePlaybackFlag_BuddyOriginHostVideoFrame，否则会造成部分效果异常。

[mStreamingContext playbackTimeline:_timeline 
                          startTime:startTime 
                            endTime:_timeline.duration 
                      videoSizeMode:NvsVideoPreviewSizeModeLiveWindowSize 
                            preload:YES 
                              flags:NvsStreamingEnginePlaybackFlag_BuddyHostVideoFrame | NvsStreamingEnginePlaybackFlag_BuddyOriginHostVideoFrame];

Seek时需要分别设置buddy buffer相关flags。NvsStreamingEngineSeekFlag_BuddyHostVideoFrame。

需要注意的是，如果特技是以 Raw Filter 的形式添加，flags 上才能够且必须或上NvsStreamingEngineSeekFlag_BuddyOriginHostVideoFrame，否则会造成部分效果异常。

[mStreamingContext seekTimeline:_timeline 
                      timestamp:lround(self.sliderProgress.value * _timeline.duration) 
                  videoSizeMode:NvsVideoPreviewSizeModeLiveWindowSize 
                          flags:NvsStreamingEngineSeekFlag_BuddyHostVideoFrame | NvsStreamingEngineSeekFlag_BuddyOriginHostVideoFrame];

Compile时需要分别设置buddy buffer相关flags。NvsStreamingEngineCompileFlag_BuddyHostVideoFrame。

需要注意的是，如果特技是以 Raw Filter 的形式添加，flags 上才能够且必须或上NvsStreamingEngineCompileFlag_BuddyOriginHostVideoFrame，否则会造成部分效果异常。

[mStreamingContext compileTimeline:_timeline
                         startTime:0
                           endTime:_timeline.duration
                    outputFilePath:_outputFilePath
              videoResolutionGrade:NvsCompileVideoResolutionGrade720
                 videoBitrateGrade:NvsCompileBitrateGradeHigh
                             flags:NvsStreamingEngineCompileFlag_BuddyHostVideoFrame | NvsStreamingEngineCompileFlag_BuddyOriginHostVideoFrame];

2.3 特技功能

2.3.1 道具

AR Scene 道具的应用，需要先安装道具包，再把返回的包ID设置给 AR Scene 特技。例如：

// 道具安装
NSString *path = @"../084A6EC1-43AB-40EF-BBD5-D83F692B011B.3.arscene";
NSMutableString *sceneId = [[NSMutableString alloc] init];
NvsAssetPackageManagerError error = [[NvsStreamingContext sharedInstance].assetPackageManager installAssetPackage:path license:nil type:NvsAssetPackageType_ARScene sync:YES assetPackageId:sceneId];
 
// 设置道具效果
[mArSceneEffect setStringVal:@"Scene Id" val:sceneId];    

取消道具“Scene Id”传空。

// 取消道具效果
[mArSceneEffect setStringVal:@"Scene Id" val:@""];

注：道具包使用前，需加载该包要求的人体检测模型以及数据包。各个包的具体要求参见美摄素材平台。

2.3.2 美颜

美颜功能分为普通美颜与高级美颜，普通美颜不需要人体检测的支持，高级美颜需要。

高级美颜与普通美颜都有磨皮的功能，如果同时开启，高级美颜的磨皮效果会覆盖普通美颜效果。

2.3.2.1 普通美颜

普通美颜功能包括：磨皮，Lut，美白，红润，锐化等功能。

具体参数参见 美颜参数

2.3.2.2 高级美颜

高级美颜功能包括：高级磨皮，祛黑眼圈，祛法令纹，眼亮，白牙，哑光，脸部Lut，清晰等功能。

具体参数参见 高级美颜参数 。

高级美颜要求加载106人脸点位检测模型或者240人脸点位检测模型，二者在效果上有细微差别。同时需设置人脸通用数据包以及高级美颜数据包

2.3.3 美型

美型功能能够对面部细节进行一些微调。具体参数参见 美型参数 。

美型要求加载106人脸点位检测模型或者240人脸点位检测模型。二者在效果上没有差别。

美型的各项调节有默认的效果，同时也支持自定义美型包的形式。

如果使用美型包，需要先安装，再把返回的包ID设置给对应的包ID参数。

// 自定义大眼美型包安装
NSString *path = @"../084A6EC1-43AB-40EF-BBD5-D83F692B011B.3.facemesh";
NSMutableString *faceMeshId = [[NSMutableString alloc] init];
NvsAssetPackageManagerError error = [[NvsStreamingContext sharedInstance].assetPackageManager installAssetPackage:path license:nil type:NvsAssetPackageType_FaceMesh sync:YES assetPackageId:faceMeshId];
 
// 设置自定义大眼效果
[mArSceneEffect setStringVal:@"Face Mesh Eye Size Custom Package Id" val:faceMeshId ];

如果要取消自定义美型效果，则对应包ID参数传空。

// 设置自定义大眼效果
[mArSceneEffect setStringVal:@"Face Mesh Eye Size Custom Package Id" val:@""];

2.3.4 美妆

美妆分为：单妆和妆容。

美妆要求加载240人脸点位检测模型，如果使用美瞳也还需要加载眼球轮廓检测模型。

美妆要求加载人脸通用数据包。

**2.3.4.1 单妆**

单妆是单一的美妆效果，现支持的有口红、眉毛、眼影、睫毛、眼线、腮红、高光、修容。

每个单妆需要安装对应单妆包才可使用。

如下是口红包的安装与使用过程。

// 口红包安装
NSString *path = @"../084A6EC1-43AB-40EF-BBD5-D83F692B011B.3.makeup";
NSMutableString *makeupId = [[NSMutableString alloc] init];
NvsAssetPackageManagerError error = [[NvsStreamingContext sharedInstance].assetPackageManager installAssetPackage:path license:nil type:NvsAssetPackageType_Makeup sync:YES assetPackageId:makeupId];
 
 
// 口红应用
[mArSceneEffect setStringVal:@"Makeup Lip Package Id" makeupId];

2.3.4.2 妆容

妆容是若干单妆、美颜、美型、微整型、滤镜的整体效果。对于妆容的接入，美摄提供一套中间层的接口，具体可参考sdkdemo。

3. FAQ

问：为什么道具没有效果？

答：请做如下确认：

1. SDK是否支持美摄的AR功能；
2. 是否有相应功能的授权；
3. 道具所需检测模型是否加载成功；
4. 如果是假脸道具，假脸数据包是否加载成功；
5. 如果是美妆道具，美妆数据包是否加载成功；
6. buddy相关flags是否设置，见文中2.2.2；
7. 道具包是否安装成功；
8. 是否 AR Scene 指定的检测模式在模型加载阶段没有支持；
9. 如果是Effect Sdk，渲染时传入的物理角度是否正确；
10. 图像中人脸是不是过小，目前美摄检测模型支持的最小人脸屏占比为1；

问：为什么高级美颜，美型没有效果？

答：请做如下确认：

1. SDK是否支持美摄的AR功能；
2. 是否有相应功能的授权；
3. 人脸检测模型是否加载成功；
4. 人脸通用数据包和高级美颜数据包是否设置（适用高级美颜没效果的情况）；
5. buddy相关flags是否设置，见文中2.2.2；
6. 开关是否开启，各子项强度是否大于0；
7. 是否 AR Scene 指定的检测模式在模型加载阶段没有支持；
8. 如果是Effect Sdk，渲染时传入的物理角度是否正确；
9. 图像中人脸是不是过小，目前美摄检测模型支持的最小人脸屏占比为1；

问：为什么单妆没有效果？

答：请做如下确认：

1. SDK是否支持美摄的AR功能；
2. 是否有相应功能的授权；
3. 240人脸检测模型是否加载成功，**如果使用美瞳，眼球轮廓检测模型是否加载成功**；
4. 美妆数据包是否加载成功；
5. buddy相关flags是否设置，见文中2.2.2；
6. 美妆开关是否开启，美妆强度是否不为0，各子项强度是否大于0；
7. 美妆包是否安装成功；
8. 是否 AR Scene 指定的检测模式在模型加载阶段没有支持；
9. 如果是Effect Sdk，渲染时传入的物理角度是否正确；
10. 图像中人脸是不是过小，目前美摄检测模型支持的最小人脸屏占比为1；

问：为什么添加AR Scene后，添加的其他特效没有效果？

答：在 单缓冲 模式下，AR Scene之前的特效会失效，需要其他特效移到AR Scene之后，或者改用双缓冲模式。

问：想要自定义美型效果怎么办？

答：AR Scene 支持自定义美型包，请联系美摄设计同学定制。

问：如何确定检没检测到人体信息？

答：通过 NvsARSceneManipulateDelegate 查看检测到的目标个数。前提是，该荐功能已授权。

问：低端机效果卡顿怎么办？

答：需要对低端机做适配，可选配置如下：

1. 背景分割使用快速模型；
2. 禁用哑光效果；
3. 禁用单缓冲模式；
4. 通过 Unified Max Faces 和 Max Faces Respect Min 限制最大检测人脸数；
5. 禁用美瞳；