开放能力
开发平台
行业应用
生态合作
开发与教学
资讯 社区 控制台
技术能力
语音技术
图像技术
文字识别
人脸与人体识别
视频技术
AR与VR
自然语言处理
知识图谱
数据智能
场景方案
部署方案
行业应用
智能教育
智能医疗
智能零售
智能工业
企业服务
智能政务
智能农业
信息服务
智能园区
智能硬件
AR开放平台

    Android SDK 基础版

    简介

    本文档主要介绍DuMix AR Android SDK 基础版的集成和使用。在使用本文档前,您需要先了解AR(Augmented Reality)的基础知识,并已经开通了百度AR应用授权,您可以在 AR技术开放平台应用控制台 申请应用授权。

    快速入门

    支持的系统和硬件版本

    • 系统:支持 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_AR_Android_SDK_Pro.zip
        |- sdk                           // 包括AR SDK能力所需的的so库及jar包。
        |- dumixdemo                     // demo工程
        |- samplecase                    // 示例AR内
        |- docs                          // 说明文档

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

    SDK集成步骤

    第1步:导入jar包和so库

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

    第2步:配置Mannifest文件,添加必要的权限

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

    第3步:创建AR应用

    请前往百度云控制台 -> 百度AR创建您的AR应用:

    第4步:初始化相关参数

    创建完AR应用后,在“应用详情”页面下载license文件,并将license文件放到您应用的assets目录中(注意:切勿修改license文件名称:aip.license),例如:/src/main/assets/,同时会生成AppID,API Key及Secret Key,并将其配置到代码中初始化。

    初始化参数示例代码如下:

    // 设置App Id
    DuMixARConfig.setAppId("您的App Id");
    // 设置API Key
    DuMixARConfig.setAPIKey("您的API Key");
    // 设置Secret Key
    DuMixARConfig.setSecretKey("您的Secret Key");

    第5步:在代码中启动AR

    创建 DuMixController:

    DuMixController对象,是AR SDK统一对外输出接口,基于该对象,可以完成对AR SDK环境初始化和各种能力调用。

    DefaultParams defaultParams = new DefaultParams();
    // defaultParams参数为扩展能力使用,暂传空对象即可
    mDuMixController = DuMixController.getInstance(context, defaultParams);

    启动 ar

    mDuMixController.setup(mDuMixInput, mDuMixOutput, mDuMixCallback);

    Camera 绑定的SurfaceTexture 传给 DuMixController

    • AR内容的融合依赖Camera数据
    • 将Camera 绑定的SurfaceTexture传给AR SDK的DuMixController对象,作为DumixInput输入参数
    • 同时DuMixController对象会返回一个SurfaceTexture ,作为DumixOutput输出参数

    注:关于Camera功能的操作,Demo内有Camera相关操作的CameraManager封装,开发者可以参考使用。

    DuMixInput: AR输入参数类

        // 输入纹理的SurfaceTexture,如果为null,则内部创建
        private SurfaceTexture mInputSurface;
        // 输入纹理的宽
        private int mInputWidth = 0;
        // 输入纹理的高
        private int mInputHeight = 0;

    DuMixOutput: AR返回参数类

        // ar绘制目标,用于将最终绘制完的图像返回
        private Object mOutputSurface;
        // 如果mTargetSurface是SurfaceTexture,则此参数有效,设置为true表示需要在使用前先detachFromGLContext
        private boolean mNeedDetach = false;
        // 返回目标的宽高
        private int mOutputWidth;
        private int mOutputHeight;

    DumixCallback回调:

    主要处理setup回调,包括setup是否成功,内容case切换状态

        private DuMixCallback mDuMixCallback = new DuMixCallback() {
            @Override
            public void onSetup(boolean b, DuMixInput duMixInput, DuMixOutput duMixOutput) {
                // result为ar启动返回状态,返回true时才可以对arsdk 其他接口进行调用
            }
    
            @Override
            public void onCaseCreate(boolean b, String path, String s1) {
               // 加载case是否成功
            }
    
            @Override
            public void onCaseDestroy() {
                arLog("onCaseDestroy");
            }
    
            @Override
            public void onRelease() {
                arLog("onRelease");
            }
    
            @Override
            public void onError(DuMixErrorType duMixErrorType, String s, String s1) {
               // duMixErrorType 错误状态信息回调
            }

    能力接口说明

    加载case内容:

     /**
     * caseId:内容case上传到内容平台的分配的id,本地case时传Null即可
     * artype case的type 【参考ARType类型说明】
     * path: case的路径(仅支持sdcard路径)
     * caseId:case描述信息,可用于统计相关
     * /
    mDumixController.loadcase(ARType arType, String casepath,String caseId)

    ARType类型说明

    类型 Type 说明
    2D跟踪类型 ARType.TRACK_2D 对平面图像进行即时识别和跟踪,可基于商品外包装、宣传海报、印刷品、服饰图案等局部图片触发AR内容
    SLAM类型 ARType.VO 即时定位与跟踪的AR效果,将AR内容自然地呈现在现实空间中,应用于3D人物角色、商品模型展示等场景。
    本地识图 ARType.ON_DEVICE_IR 在手机端进行图像识别检索,用于实现基于2D图片的AR内容识别触发。
    云端识图 ARType.CLOUD_IR 云端图像识别检索,用于实现基于2D图片的AR内容识别触发。
    IMU类型 ARType.IMU 基于手机IMU,实时获取手机在空间中的相对位置和姿态,将AR内容定位呈现在手机当前所处的三维空间中

    清空case

    mDumixController.clearCase();

    2D跟踪类型消息回调

    在2D跟踪类型过程中,会有多个状态切换,比如识图过程的跟丢,跟上,过远,过近等状态,开发者可以通过实现ITrack2DStateChangedListener 回调监听来处理,并通过onStateChanged内返回的状态来进行区分。demo中可以参考Track2DModule类的实现。

        @Override
        public void onStateChanged(Track2DStateMessage track2DStateMessage, ITrack2DState iTrack2DState) {
            ....
            switch (mTrack2DStateMessage) {
                // 跟丢状态
                case TRACK_LOST:
                    break;
                // 跟上
                case TRACK_FOUND:
                // 过远
                case TRACK_DISTANCE_TOO_FAR:
                case TRACK_DISTANCE_NORMAL:
                 // 过近
                case TRACK_DISTANCE_TOO_NEAR:
                    break;
            }
        }

    本地识图/云端识图消息回调

    识图的过程

    • 根据当前camera输入数据与内容平台上传的2D跟踪类型的识别图进行拼配,识别成功会下发对应的内容case类型及arkey
    • 根据返回的类型和arkey来进行加载对应内容case
    • 本地识图/云端识图区别在于,前者一次性将内容平台的识别图特征下载到本地然后进行拼配,后者是在云端进行配
    • 本地识图/云端识图匹配结果处理,参考DeviceIRModule,CloudIRModule类的处理
     // 以云端识图为例
     @Override
        public void onStateChanged(CloudIRState cloudIRState, ICloudIRResult iCloudIRResult) {
            ...
            switch (cloudIRState) {
                 //识图错误,未找到匹配的识别
                case ERROR:
                    break;
                 //开始云端识图
                case START:
                    break;
                //云端识图成功
                case SUCCESS:
                  // 返回识图成功对应的内容case类型
                  ARType.type = ARType.valueOf(iCloudIRResult.getARType()
                  // 返回识图成功对应的内容case key
                  String arKey = iCloudIRResult.getARKey()
                    break;
                default:
                    break;
            }
        }

    AR内置消息处理

    此函数callback主要处理接收lua发送的内部消息进行处理,主要包括切换camera消息,打开控制浏览器url打开

    mDuMixController.setDefinedLuaListener(new DefinedLuaListener() {
       @Override
       public void onRequireSwitchCamera(int cameraFace) {
                  // camera切换消息
       }
       @Override
       public void onOpenUrl(String url, int type, HashMap<String, Object> more) {
               // case打开url入口
       }
    });

    内容Case与业务层消息通信

    接收内容case内的回调消息

    // LuaMsgListener 消息回调
    mDuMixController.setLuaMsgListener(LuaMsgListener listener)
    
    // 实例:
    LuaMsgListener luaListener = new LuaMsgListener() {
      @Override
      public List<String> getMsgKeyListened() {
         // 过滤监听lua向上层发送包含event_id字段的消息
         List<String> targetMsgs = new ArrayList<String>();
         targetMsgs.add("event_id");
         return targetMsgs;
        }
      @Override
      public void onLuaMessage(HashMap<String, Object> hashMap) {
         // click_me为需要处理业务层的消息,并进行处理
         if (hashMap.get("event_id").toString().equals("click_me")) {
           // todo  ..
         }
    }

    业务层向内容case发送消息

    // 通过此函数可以向内容Case内发送自定义消息。msg2lua为haspmap, 内容Case可以根据此参数进行解析并处理 
    mDuMixController.sendMsg2Lua(HashMap<String, Object> msg2lua)
    
    // 实例:
    /**
    * 业务层向case lua内发消息
    * 接收消息 参考 /sdcard/arcase_list/bridge/ar..
    */
    public void sendMessage2lua() {
      // 业务层向lua层发送消息
      HashMap<String, Object> luaMap = new HashMap<>();
      luaMap.put("event_name", "click_me");
      HashMap eventDataMap = new HashMap();
      eventDataMap.put("msg_id", "自定义message");
      luaMap.put("event_data", eventDataMap);
      mDuMixController.sendMsg2Lua(luaMap);
    }

    下载内容Case平台内的case到本地

    内容case上传到内容平台后,业务方可以通过此接口进行下载到本地。

    resContent = new ContentCloud(this);
    caseDownloader = new CaseDownloader();
     // 下载监听
    caseDownloader.setCaseDownloadListener(new CaseDownloader.ICaseDownloadListener() {
        @Override
        public void onProgress(String arKey, final int progress) {
           //progress 下载进度
        }
        @Override
        public void onFinish(final IARCaseInfo info, final boolean success) {
           // sucess 下载结果
        }
     // 开始下载case 通过内容平台生成的 arKey进行下载
     caseDownloader.downloadCase(resContent, arKey);    
     

    拍摄

     //path: 拍照后图片文件保存路径
    mDuMixController.takePicture(path, new PhotoCallback() {
                @Override
                public void onPictureTake(final boolean result, final String filePath) {
                //result 拍照状态, filePath 返回路径
                }
            });

    录制

     //path: 拍照后图片文件保存路径 mRecordMaxTime :录制最大时间
    mDuMixController.startRecord(path, mRecordMaxTime, new RecordCallback() {
                @Override
                public void onRecorderStart(boolean b) {
                // begin 开始录制
                }
    
                @Override
                public void onRecorderProcess(int i) {
                    // 录制进度 百分比
                }
    
                @Override
                public void onRecorderComplete(final boolean b, final String result) {
                // result b ,result:file path
                }
            });

    停止录制

    mDuMixController.stopRecord();

    Demo说明

    1. camera package是对系统相机的封装,包括打开相机、关闭相机和surface绑定等。
    2. speech module 语音识别能力的封装(具体接口可以参考百度语音识别api)。
    3. tts module 语音合成能力的封装(具体接口可以参考百度语音合成api)。

    第6步:Proguard配置

    在Proguard配置文件中增加:

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

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

    -keep class com.baidu.aip.** {*;}

    注意事项

    1. DuMix AR 引擎正常运行依赖必要的硬件基础,因此对硬件有一定的要求,对不满足的手机采用“黑名单”策略,也就是命中“黑名单”的手机会被屏蔽,不能正常使用 DuMix AR。屏蔽依据的参数主要有内存大小,CPU核数,安卓版本等等手机基本信息;还有针对特殊机型的屏蔽,依据手机型号。
    2. DuMix AR SDK的 minSdkVersion为 19;targetSdkVersion 建议设为 24。

    版本更新说明

    DuMix AR Android SDK 基础版4.7.2-2020年5月 将SDK升级到最新4.7.2版本,更新相关接口。

    DuMix AR Android SDK 基础版2.5-2018年08月 试用授权升级为正式授权。

    DuMix AR Android SDK 基础版2.4.1-2018年07月 新增加载本地内容接口。

    上一篇
    AR SDK基础版介绍
    下一篇
    iOS SDK 基础版