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

Sceneform-EQR

简介

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'
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

注意：后面若要引入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'
}
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

使用离线依赖

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

下载AAR

EQ渲染器：
eq-renderer

SLAM算法库：
eq-slam

OpenCV(arm-v8a版本)：
opencv-v8a

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

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

dependencies {
    //...

    //使用离线依赖
    implementation fileTree(dir: 'libs', include: ['*.aar', '*.jar'], exclude: [])
}
1
2
3
4
5
6

引入ARCore

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

ARCore仍采用在线依赖的方式

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

引入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'
1
2
3

编写代码

配置AndroidManifest

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

    <!-- Always needed for AR. -->
    <uses-permission android:name="android.permission.CAMERA" />

    <uses-feature android:name="android.hardware.camera" />
    <uses-permission android:name="android.permission.READ_PHONE_STATE" />
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
    <uses-permission android:name="android.permission.INTERNET" />
1
2
3
4
5
6
7
8

完整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();
1

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<ModelRenderable, Object>() {
                    @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
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

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

运行示例

模型加载

1、启动页

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

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

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