人脸识别

    美颜滤镜SDK-Android

    1 简介

    本文档主要介绍 美颜滤镜SDK-Android 的集成和使用。在使用本文档前,您需要先了解AR(Augmented Reality)的基础知识,并已经开通了百度AR应用授权,您可以通过“合作咨询”联系我们申请应用授权。

    2 快速入门

    支持的系统和硬件版本

    • 系统:支持 Android 4.4(API Level 19)到 Android 9(API Level 28)系统。需要开发者通过minSdkVersion来保证支持系统的检测。
    • CPU架构:armeabi-v7a,arm64-v8a
    • 硬件要求:要求设备上有相机模块,CPU 4核及以上,内存2G及以上。
    • 网络:支持WIFI及移动网络,移动网络支持使用NET网关及WAP网关(CMWAP、CTWAP、UNIWAP、3GWAP)。

    开发包说明

    DuMix SDK.zip
        |- dumixcam                     // demo工程
        |- dumixcam.apk                 // 体验apk测试包
        |- sdk                          // 包含jar包,so库及依赖的算法模型

    SDK提供的demo工程以Android Studio方式提供。

    3 SDK集成步骤

    第1步:添加授权文件

    您可以通过“合作咨询”联系相关接口人申请授权。

    将授权 license 文件(dumixar.license)放在您应用工程的 assets 目录中,SDK启动后会进行校验。 (注:鉴权会对时间进行校验,不要更改手机系统时间,否则会鉴权不通过。)

    第2步:导入jar包和so库

    将 dumixar.jar 拷贝到您的工程的 libs 文件夹中,并检查编译依赖。 将 arm64-v8a 和 armeabi-v7a 文件夹拷贝到 Android Studio 工程src/main/jniLibs目录中。

    第3步:配置Manifest文件,添加必要的权限

    <uses-permission android:name="android.permission.CAMERA"/>
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-feature android:name="android.hardware.camera"/>
    <uses-feature android:name="android.hardware.camera.autofocus"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>

    第4步:初始化

    算子模型说明

    算子运行需要使用对应的模型,集成方可根据需要选择算子和对应的模型,并将算子模型路径传给SDK,具体可参考demo示例。

    初始化DuMixController

    DuMixCongtroller 是调用 DuMixSDK 的核心类,包括初始化、能力调用等。

    mDuMixController = new DuMixController(context, defaultParams);

    设置默认参数

    DefaultParams 详见下一节说明。

    DefaultParams defaultParams = new DefaultParams();
    // 人脸算法模型路径 path支持sdcard路径或assets路径
    defaultParams.setFaceAlgoModelPath(path); 

    启动AR

    mDuMixController.setup(mDuMixInput, mDuMixOutput, mDuMixCallback);

    注:setup参数详细说明详见下一节说明。

    第5步:加载AR场景(AR case)

    在收到onSetup回调后,调用mDuMixController.loadCase加载ar case。

    mDuMixController.loadCase(casePath, caseId);

    第6步:Proguard配置

    在Proguard配置文件中增加:

    -keep class com.baidu.ar.** {*;} 
    -keep interface com.baidu.ar.** {*;} 

    4 API及回调接口、消息的详细说明

    4.1 基本流程接口IDuMix、基本流程回调DuMixCallback、构造默认参数与输入输出参数详细说明

    4.1.1 基本流程接口IDuMix详细说明

    /**
     * 开启百度AR环境
     *
     * @param input    ar输入参数
     * @param output   ar返回参数
     * @param callback 用于DuMix操作回调
     */
    void setup(DuMixInput input, DuMixOutput output, DuMixCallback callback);
    
    /**
     * 更新ar输出大小,比如Surface change引起的Output大小改变
     *
     * @param width  绘制目标宽
     * @param height 绘制目标高
     */
    void changeOutputSize(int width, int height);
    
    /**
     * 更新ar输出,比如Surface change引起的Output大小改变,纹理作为输出时使用。
     *
     * @param newOutput 新的output
     */
    void changeOutput(DuMixOutput newOutput);
    
    /**
     * 切换AR场景(新3.4及以后,能力通过lua打开)
     *
     * @param casePath case资源路径
     * @param caseId   case的唯一标志,用于统计区分不同case,如不需要统计,可随意设置,如:0
     */
    void loadCase(String casePath, String caseId);
    
    /**
     * 切换AR场景(旧3.4以前,本地单能力)
     *
     * @param arType   case场景类型
     * @param casePath case资源路径
     * @param caseId   case的唯一标志,用于统计区分不同case,如不需要统计,可随意设置,如:0
     */
    void loadCase(ARType arType, String casePath, String caseId);
    
    /**
     * 销毁AR场景
     */
    void clearCase();
    
    /**
     * 暂停AR场景显示,暂停算法与渲染,但是资源并未释放
     */
    void pause();
    
    /**
     * 恢复AR场景显示,开启算法与渲染
     * 前提是资源已经加载,并已经调用了pause
     */
    void resume();
    
    /**
     * 暂停AR场景渲染,算法仍在运行。
     * 主要用于当DuMix AR不在最上层View显示的时候,暂停DuMix AR场景渲染与音乐播放,避免于最上层的View播放的音乐冲突
     */
    void pauseScene();
    
    /**
     * 恢复AR场景渲染。
     */
    void resumeScene();
    
    /**
     * 继承自系统View.OnTouchListener,用于接受View上的点击事件,实现点击交互功能
     * Called when a touch event is dispatched to a view. This allows listeners to
     * get a chance to respond before the target view.
     *
     * @param v The view the touch event has been dispatched to.
     * @param event The MotionEvent object containing full information about
     *        the event.
     * @return True if the listener has consumed the event, false otherwise.
     */
    boolean onTouch(View v, MotionEvent event);
    
    /**
     * 结束ar,释放相关资源
     */
    void release();

    4.1.2 基本流程回调接口DuMixCallback详细说明

    /**
     * 百度AR启动结果返回
     *
     * @param result      是否成功
     * @param duMixInput  实际使用的duMixTarget
     * @param duMixOutput 实际使用的duMixTarget
     */
    void onSetup(boolean result, DuMixInput duMixInput, DuMixOutput duMixOutput);
     
    /**
     * AR场景加载结果回调
     *
     * @param result 是否成功
     */
    void onCaseCreate(boolean result, String casePath, String caseId);
     
    /**
     * AR场景销毁结果回调
     */
    void onCaseDestroy();
     
    /**
     * 百度AR结束结果返回
     */
    void onRelease();
     
    /**
     * 百度AR错误消息返回
     *
     * @param errorType    错误类型
     * @param errorMessage 错误消息
     * @param extra        错误携带的额外信息;
     *                     当errorType==DuMixErrorType.LibraryError时,返回so的完整路径
     */
    void onError(DuMixErrorType errorType, String errorMessage, String extra);

    4.1.3 构造默认参数DefaultParams详细说明

    // 人脸算法模型路径
    private String mFaceAlgoModelPath;
    // MDL算法模型路径
    private String mMdlAlgoModelPath;
    // 渲染引擎使用输入大小进行渲染(优点:可以节约显存,降低功耗,提高帧率;缺点:模型细节不清晰)
    private boolean mUseInputSizeInEngine = true;
    // 是否使用默认磨皮美白(手百需要设置为false)
    private boolean mUseBeautyFilter = true;
    // 是否使用默认人脸滤镜(大眼、廋脸)
    private boolean mUseFaceFilter = true;
    // 是否使用默认美妆滤镜
    private boolean mUseMakeupFilter = true;
    // 是否开启日志打印
    private boolean mLogEnable = true;

    4.1.4 初始化输入参数DuMixInput详细说明

    // 输入纹理的SurfaceTexture,如果为null,则内部创建
    private SurfaceTexture mInputSurface;
    // 输入纹理的宽
    private int mInputWidth = 0;
    // 输入纹理的高
    private int mInputHeight = 0;
    // 是否camera数据来源,即mSurfaceTexture设置给了Camera写数据
    private boolean mCameraInput = true;
    // 如果是相机数据来源,需要设置启动时相机朝向
    private boolean mFrontCamera = true;
    // 输入视频相对与手机竖屏的角度
    private int mInputDegree = 90; // 相机输入默认为横屏采集

    4.1.5 初始化输出参数DuMixOutput详细说明

    // ar绘制目标,用于将最终绘制完的图像返回
    private Object mOutputSurface;
    // 如果mTargetSurface是SurfaceTexture,则此参数有效,设置为true表示需要在使用前先detachFromGLContext
    private boolean mNeedDetach = false;
    // 返回目标的宽高
    private int mOutputWidth;
    private int mOutputHeight;
    // 输出缩放模式
    private ScaleType mScaleType = ScaleType.CENTER_CROP;
    // 输出角度
    private RotationType mRotationType = RotationType.ROTATE_0;
    // 输出镜像
    private MirriorType mMirriorType = MirriorType.NO_MIRRIOR;

    4.2 Lua消息相关接口ILua与Lua消息监听接口LuaMsgListener详细说明

    4.2.1 Lua消息相关接口ILua详细说明

    /**
     * 从上层将消息传入lua中,采用key-value的形式,value只支持int,float,bool和string类型
     *
     * @param msg2lua 发送到lua的参数
     *
     * @return 是否成功发送
     */
    boolean sendMsg2Lua(HashMap<String, Object> msg2lua);
     
    /**
     * 添加Lua消息监听
     *
     * @param listener lua消息监听
     *
     * @return 是否添加成功
     */
    boolean addLuaMsgListener(LuaMsgListener listener);
     
    /**
     * 删除Lua消息监听
     *
     * @param listener lua消息监听
     *
     * @return 是否移除成功
     */
    boolean removeLuaMsgListener(LuaMsgListener listener);
     
    /**
     * 设置原有已定义Lua消息接收回调
     *
     * @param definedLuaListener 回调接口
     */
    void setDefinedLuaListener(DefinedLuaListener definedLuaListener);

    4.2.2 Lua消息监听接口LuaMsgListener详细说明

    /**
     * 获取此LuaMsgListener监听的消息类型,如果不实现则接收不到消息
     *
     * @reture 监听消息类型
     */
    List<String> getMsgKeyListened();
     
    /**
     * lua消息透传给上层的接口
     *
     * @param luaMsg lua消息
     */
    void onLuaMessage(HashMap<String, Object> luaMsg);

    4.3 算法能力相关接口IAbility详细说明

    /**
     * 添加自定义AR能力
     *
     * @param abilityClassName 自定义AR能力类型(注意不要混淆此类,避免DuMix SDK无法找到此类)
     * @param abilityName      此AR类所支持的AR能力,此能力可以通过Lua操作
     *
     * @return 是否添加成功
     */
    boolean addAbility(String abilityClassName, String abilityName);
     
    /**
     * 添加自定义AR能力
     *
     * @param abilityClassName 自定义AR能力类型(注意不要混淆此类,避免DuMix SDK无法找到此类)
     * @param abilityNames     此AR类所支持的AR能力,此能力可以通过Lua操作
     *
     * @return 是否添加成功
     */
    boolean addAbility(String abilityClassName, List<String> abilityNames);
     
    /**
     * 获取当前所有支持的能力
     *
     * @return 当前支持的所有能力
     */
    List<String> getSupportedAbilities();
     
    /**
     * 获取能力是否支持
     *
     * @param abilityName 能力名
     *
     * @return 能力是否支持
     */
    boolean isAbilitySupported(String abilityName);
     
    /**
     * 获取当前正在运行的能力
     *
     * @return 当前正在运行的所有能力
     */
    List<String> getActiveAbilities();
     
    /**
     * 获取能力是否正在运行
     *
     * @param abilityName 能力名
     *
     * @return 能力是否运行
     */
    boolean isAbilityActive(String abilityName);
     
    /**
     * 获取能力是否正在运行
     *
     * @param abilityType 能力类型
     *
     * @return 能力是否运行
     */
    boolean isAbilityActive(AbilityType abilityType);
     
    /**
     * 开启某个能力
     *
     * @param abilityName 能力名称
     * @param params      需要调整的参数
     *
     * @return 是否正确开启
     */
    boolean startAbility(String abilityName, HashMap<String, Object> params);
     
    /**
     * 开启某个能力
     *
     * @param abilityType 能力类型
     * @param params      需要调整的参数
     *
     * @return 是否正确开启
     */
    boolean startAbility(AbilityType abilityType, HashMap<String, Object> params);
     
    /**
     * 调整某个能力的相关参数
     *
     * @param abilityName 能力名称
     * @param params      需要调整的参数
     *
     * @return 是否正确调整,如果能力未被打开,调整会失败
     */
    boolean adjustAbility(String abilityName, HashMap<String, Object> params);
     
    /**
     * 调整某个能力的相关参数
     *
     * @param abilityType 能力类型
     * @param params      需要调整的参数
     *
     * @return 是否正确调整,如果能力未被打开,调整会失败
     */
    boolean adjustAbility(AbilityType abilityType, HashMap<String, Object> params);
     
    /**
     * 结束某个能力
     *
     * @param abilityName 能力名称
     *
     * @return 是否正确结束
     */
    boolean stopAbility(String abilityName);
     
    /**
     * 结束某个能力的相关参数
     *
     * @return 是否正确结束
     */
    boolean stopAbility(AbilityType abilityType);
     
    /**
     * 获取AR能力代理管理类
     *
     * @return AR能力代理管理类
     */
    ARProxyManager getARProxyManager();
     
    /**
     * 设置MDL(不包括人脸)能力模型配置文件路径
     *
     * @param configDir 模型配置文件路径
     */
    void setMdlModelPath(String configDir);

    4.4 滤镜能力相关接口IFilter与滤镜监听回调FilterStateListener详细说明

    4.4.1 滤镜能力相关接口IFilter详细说明

    /**
     * 注册滤镜能力状态监听
     *
     * @param listener 滤镜能力监听
     */
    void setFilterStateListener(FilterStateListener listener);
     
    /**
     * 通过滤镜case文件夹path更新滤镜相关参数,此文件来源于case开发工程师&UI工程师
     *
     * @param casePath 滤镜Case文件夹path
     */
    String updateFilterCase(String casePath);
     
    /**
     * 调整滤镜参数
     *
     * @param value 要调整的滤镜值
     */
    void updateFilter(FilterType filterType, int value);
     
    /**
     * 调整滤镜参数
     *
     * @param value 要调整的滤镜值
     */
    void updateFilter(FilterType filterType, float value);
     
    /**
     * 调整滤镜参数
     *
     * @param value 要调整的滤镜值
     */
    void updateFilter(FilterType filterType, String value);
     
    /**
     * 调整滤镜参数
     *
     * @param value 要调整的滤镜值
     */
    void updateFilter(FilterType filterType, float[] value);
     
    /**
     * 清空所有滤镜效果
     */
    void clearAllFilter();

    4.4.2 滤镜监听回调FilterStateListener详细说明

    /**
     * 滤镜能力状态监听
     *
     * @param state 滤镜能力当前状况
     */
    void onFilterStateChanged(HashMap<String, Float> state);

    4.5 录像接口能力IRecord与录像回调RecordCallback详细说明

    4.5.1 录像能力接口IRecord详细说明

    /**
     * 开始视频录制
     *
     * @param output    录制视频输出文件路径,如文件/sdcard/arrecord/1234.mp4
     * @param maxTimeMs 最大录制时长,即如果不主动调用stopRecord,达到此时长后就会自动结束录制,此参数与录制进度返回相关。
     * @param callback  录制状态调用状态返回
     */
    void startRecord(String output, long maxTimeMs, RecordCallback callback);
     
    /**
     * 暂停视频录制
     */
    void pauseRecord();
     
    /**
     * 恢复视频录制
     */
    void resumeRecord();
     
    /**
     * 结束视频录制
     */
    void stopRecord();

    4.5.2 录像回调RecordCallback详细说明

    /**
     * 开始视频录制回调
     *
     * @param result 开始录制是否正常
     */
    void onRecorderStart(boolean result);
     
    /**
     * 视频录制进度回调
     * 前提:开始录制时设置了录制总时长
     *
     * @param process 当前滤镜进度(0,100)
     */
    void onRecorderProcess(int process);
     
    /**
     * 结束视频录制回调
     *
     * @param result      结束录制是否正常
     * @param outFilePath 视频生成路径
     */
    void onRecorderComplete(boolean result, String outFilePath);

    4.6 拍照能力接口IPhoto与拍照回调PhotoCallback详细说明

    4.6.1 拍照能力接口IPhoto详细说明

    /**
     * 拍照
     *
     * @param output   拍照生成文件,如/sdcard/arphoto/1234.jpg
     * @param callback 拍照返回
     */
    void takePicture(String output, PhotoCallback callback);

    4.6.2 拍照回调PhotoCallback详细说明

    /**
     * 拍照结果返回
     *
     * @param result 是否成功
     * @param output 生成文件的路径
     */
    void onPictureTake(boolean result, String output);

    5 其他

    AR类型说明

    类型 Type 说明
    2D跟踪类型 0 对平面图像进行即时识别和跟踪,可基于商品外包装、宣传海报、印刷品、服饰图案等局部图片触发AR内容
    SLAM类型 5 即时定位与跟踪的AR效果,将AR内容自然地呈现在现实空间中,应用于3D人物角色、商品模型展示等场景。
    本地识图 6 在手机端进行图像识别检索,用于实现基于2D图片的AR内容识别触发。
    云端识图 7 云端图像识别检索,用于实现基于2D图片的AR内容识别触发。
    IMU类型 8 基于手机IMU,实时获取手机在空间中的相对位置和姿态,将AR内容定位呈现在手机当前所处的三维空间中
    FACE类型 10 实时监测跟踪人脸,支持添加人脸2D&3D贴纸、支持美颜滤镜等功能

    可调节的滤镜类型说明

        lutFile("res_path"),
        whitenFile("res_path"),
        lutIntensity("intensity"),
        smooth("intensity_smooth"),
        whiten("intensity_white"),
        // 娃娃脸
        babyFace("babyFace"),
        // 网红脸
        webCelebrityFace("cyberstarFace"),
        // 自然脸
        normalFace("naturalFace"),
        // 大眼
        eye("eyeScale"),
        // 瘦脸
        thinFace("faceThin"),
        // 下巴高
        chinHeight("chinHeight"),
        // 下巴宽
        chinWidth("chinWidth"),
        // 窄脸
        faceWidth("faceWidth"),
        // 下颌角
        jawAngleWidth("jawEdgeWidth"),
        // 眼距
        eyeDistance("eyeDistance"),
        // 眼角
        eyeAngle("eyeAngle"),
        // 眉距
        eyebrowDistance("eyebrowDistance"),
        // 嘴形
        mouthWidth("mouthWidth"),
        // 小脸
        threeCounts("faceLength"),
        // 发际线
        upCount("upperCountHeight"),
        // 中庭距离
        middleCount("middleCountHeight"),
        // 下庭距离
        downCount("lowerCountHeight"),
        // 鼻翼
        noseWingWidth("noseWingWidth"),
        // 鼻梁
        noseBridgeWidth("noseBridgeWidth"),
    
        // -------- 瘦脸自定义参数 ------------
        // 瘦脸左右最高点调节程度
        faceThinLR("faceThinLR"),
        // 瘦脸下巴点调节程度
        faceThinC("faceThinC"),
        // 瘦脸下巴左右点调节程度
        faceThinLRC("faceThinLRC"),
        // 瘦脸下巴上方左右点调节程度
        faceThinLRCU("faceThinLRCU"),
        // 瘦脸下巴点作用半径
        faceThinCRadius("faceThinCRadius"),
        // 瘦脸左右最高半径
        faceThinLRRadius("faceThinLRRadius"),
        // 瘦脸下巴左右点作用半径
        faceThinCCloseRadius("faceThinCCloseRadius"),
        // 瘦脸下巴上方左右点作用半径
        faceThinCUpRadius("faceThinCUpRadius"),
    
        // -------- 窄脸自定义参数 ------------
        // 窄脸左右脸调节程度
        faceWidthRatio("faceWidthRatio"),
        // 窄脸左右脸1调节程度
        faceWidth1Ratio("faceWidth1Ratio"),
        // 窄脸左右脸2调节程度
        faceWidth2Ratio("faceWidth2Ratio"),
        // 窄脸左右下巴高点调节程度
        faceWidthCURatio("faceWidthCURatio"),
        // 窄脸左右下巴低点调节程度
        faceWidthCRatio("faceWidthCRatio"),
        // 窄脸左右脸半径
        faceWidthRadius("faceWidthRadius"),
        // 窄脸左右脸1半径
        faceWidth1Radius("faceWidth1Radius"),
        // 窄脸左右脸2半径
        faceWidth2Radius("faceWidth2Radius"),
        // 窄脸左右下巴高点半径
        faceWidthCURadius("faceWidthCURadius"),
        // 窄脸左右下巴低点半径
        faceWidthCRadius("faceWidthCRadius"),
        // 自定义瘦脸index
        customLandmarkIndex("customLandmarkIndex"),
    
        // 全局缩放参数
        globalScaleValue("globalScaleValue"),
    
        // -------- 全局美妆 ------------
        // 嘴唇mask 全局默认初始化
        lipsMask("lips_mask"),
        // 腮红
        cheeks("cheeks"),
        // 眉毛
        eyebrow("eyebrow"),
        // 睫毛
        eyelash("eyelash"),
        // 眼线
        eyeliner("eyeliner"),
        // 眼影
        eyeshadow("eyeshadow"),
        // 高光
        highlight("highlight"),
        // 嘴唇
        lips("lips"),
        // 一次性设置全部分类的状态
        allMakeups("all_makeups"),
        // 美妆滤镜 开启或者关闭 类似全局美妆关闭恢复
        beautyMakeupFilter("beauty_makeup_filter");
    上一篇
    美颜滤镜SDK-IOS
    下一篇
    虚拟人SDK