【EQ-R】使用EQ-Renderer创建AR加载模型

EQ-R

简介

EQ-Renderer是EQ基于sceneform（filament）扩展的一个用于安卓端的三维AR渲染器。

主要功能

它包含sceneform_v1.16.0中九成接口（剔除了如sfb资源加载等已弃用的内容），扩展了视频背景视图、解决了sceneform模型加载的内存泄漏问题、集成了AREngine和ORB-SLAM3、添加了场景坐标与地理坐标系（CGCS-2000）的转换方法。

注：由于精力有限，文档和示例都不完善。sceneform相关请直接参考谷歌官方文档，扩展部分接口说明请移步git联系。

相关链接

Git仓库

• EQ-Renderer的示例工程

  码云

  • EQ-Renderer的示例工程

    EQ-R相关文档

    • 文档目录

      配置环境

      使用在线依赖

      若使用离线依赖的方式，则跳过本节内容。

      Maven配置

      EQ-Renderer的maven仓库地址为：http://repo.eqgis.cn

      根据AndroidSudio的版本，配置相应的AGP，这里我使用的gradle版本如下：

      • Android Gradle Plugin Version ：8.1.0
      • Gradle Version：8.0

        在工程目录下修改settings.gradle文件，示例如下：

        pluginManagement {    repositories {        google()        mavenCentral()        gradlePluginPortal()        maven {            allowInsecureProtocol = true            url "http://repo.eqgis.cn"        }        maven {url "https://developer.huawei.com/repo" }    }}dependencyResolutionManagement {    repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)    repositories {        google()        mavenCentral()        maven {            allowInsecureProtocol = true            url "http://repo.eqgis.cn"        }        maven {url "https://developer.huawei.com/repo" }    }}rootProject.name = "EQ-Renderer Sample"include ':app'

        注意：后面若要引入AREngine，则这里需要配置华为的maven仓库。

        不同版本的Gradle配置在配置Maven仓库时，有一定差异。

        Gradle 7.0版本后，需参考Android官方对于Gradle版本与Gradle插件的配套关系，把Gradle插件版本也升级到7.0及以上。

        其它版本的gradle配置，请参考之前写的文档：视频地图开发文档#不同版本的Gradle

        引入相关依赖

        eq-renderer：三维渲染器，基于filament

        eq-slam：slam算法库，当前版本（v1.0.2）使用的ORB-SLAM3，暂时仅支持arm-v8a。

        opencv：图像处理

        arcore：谷歌的AR服务

        arengine：华为的AR服务

        在模块的build.gradle文件中添加在线依赖，示例如下：

        dependencies {    //...        //使用在线依赖    implementation 'com.eqgis:eq-renderer:1.0.2'    implementation 'com.eqgis:eq-slam:1.0.2'        //引入opencv    implementation 'org.opencv:opencv-v8a:4.5.5'    //使用ARCore 和 AREngine （按需添加）    implementation 'com.google.ar:core:1.39.0'    //使用AREngine则额外添加下面依赖    //华为仓库        maven {url "https://developer.huawei.com/repo/" }    implementation 'com.huawei.hms:arenginesdk:3.7.0.3'}

        使用离线依赖

        若已使用在线依赖的方式，则跳过本节内容。

        下载AAR

        EQ渲染器：

        eq-renderer

        SLAM算法库：

        eq-slam

        OpenCV(arm-v8a版本)：

        opencv-v8a

        将相关库下载到本地，放入模块的/libs目录下，如图：

        然后再在build.gradle文件中引入

        dependencies {    //...    //使用离线依赖    implementation fileTree(dir: 'libs', include: ['*.aar', '*.jar'], exclude: [])}

        引入ARCore

        PS：若没有用到ARCore，可不添加这个依赖

        ARCore仍采用在线依赖的方式

            //使用ARCore 和 AREngine （按需添加）    implementation 'com.google.ar:core:1.39.0'

        引入AREngine

        PS：若没有用到AREngine，可不添加这个依赖

        AREngine仍采用在线依赖的方式，注意：使用AREngine，需要配置华为的maven仓库。参考上面的Maven配置。

            //使用AREngine则额外添加下面依赖    //华为仓库settings.gradle中添加“ maven {url "https://developer.huawei.com/repo/" } ”    implementation 'com.huawei.hms:arenginesdk:3.7.0.3'

        编写代码

        配置AndroidManifest

        由于示例工程需要用到相机、文件读写权限，因此，这里需要再AndroidManifest.xml中添加如下内容。

        完整AndroidManifest.xml请参考源码内容。

        使用场景组件

        题外话

        1、在2020年之后，华为推出的机型不被Google的ARCore所支持，华为在这之后推出了AREngine。

        2、AREngine与ARCore的接口相似，因此这里将功能统一封装在了ARSceneLayout中。

        3、在开发者同时添加了ARCore和AREngine的依赖后，程序会自动根据机型确定底层使用ARCore还是AREngine。

        4、在2020年前的华为设备，属于既支持AREngine，又支持ARCore的情况。此时，程序默认以AREngine启动。若要强制使用ARCore，则需要在ARSceneLayout初始化之前，执行以下代码。

        AREngine.enforceARCore();

        5、所有带相机的设备都可通过eq-slam来实现AR显示。做这个的初衷是要去适配那些既不支持ARCore又不支持AREngine的设备。

        几种视图组件

        • SceneLayout：创建普通三维场景所用的布局控件
        • ARSceneLayout：创建AR场景（ARCore或AREngine）所用的布局控件
        • EqSlamSceneLayout：创建AR场景（eq-slam）所用的布局控件

          详细代码请参考示例工程。

          渲染模型

          题外话

          本文所用sceneform是谷歌存档（1.16.0）的延续。主要扩展是：接入华为的AREngine和三方SLAM以及解决所遇到的BUG。

          谷歌sceneform1.15.0，1.15.0版本及之前版本都采用sceneform插件将FBX、OBJ等格式的模型转换成*.sfb文件，现已弃用。

          从 1.16.0 开始，Sceneform SDK for Android 已开源，可从 github.com/google-ar/sceneform-android-sdk 获得。

          此网站 (developers.google.com/sceneform) 记录了旧版 Sceneform SDK for Android 1.15.0。

          此外，在sceneform1.16.0存档后，ThomasGorisse 在存档的基础上，继续迭代sceneform（目前最新版本：v1.23.0），里面有sceneform核心的功能演示和示例代码（这些九成以上都适用于本文所用的SDK）。

          ThomasGorisse仓库链接：https://github.com/SceneView/sceneform-android

          获取场景根节点

          上面的视图组件(SceneLayout…)都具有getRootNode()的方法

          通过getRootNode()可以获取场景根节点。

          添加模型节点

          与sceneform（filament）里面加载模型的方式一致，使用ModelRenderable对象

          API参考：

          ​ ModelRenderable

          示例代码如下：

              private void addGltf(Context context, RootNode rootNode) {        modelNode = new Node();        ModelRenderable                .builder()                .setSource(context, Uri.parse(modelPath))                .setIsFilamentGltf(true)                .setAsyncLoadEnabled(true)                .build()                .thenApply(new Function() {                    @Override                    public Object apply(ModelRenderable modelRenderable) {                        modelNode.setRenderable(modelRenderable);                        modelNode.setLocalScale(new Vector3(0.01f, 0.01f, 0.01f));                        modelNode.setLocalRotation(new Quaternion(Vector3.up(),30));                        modelNode.setLocalPosition(new Vector3(0f, -0.1f, -0.5f));                        modelNode.setParent(rootNode);                        return null;                    }                });    }

          详细代码请参考示例工程。

          运行示例

          模型加载

          1、启动页

          2、在普通三维场景中加载gltf模型

          3、在使用ARCore的AR场景中加载gltf模型

          4、在使用ORB-SLAM的AR场景中加载gltf模型