Android SDK 基础版
所有文档

          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 基础版