导入和预览 3D Asset

了解如何在 Android Studio 中导入 3D 模型,将它们转换成 Sceneform 格式,并对它们进行预览。

安装 Google Sceneform Tools (Beta) 插件

在 Android Studio 中,打开 Plugins 设置:

  • Windows:File > Settings > Plugins > Browse Repositories
  • macOS:Android Studio > Preferences > Plugins

然后点击 Browse repositories 并安装 Google Sceneform Tools (Beta)

导入新 3D asset

Sceneform 支持 OBJ、FBX 和 glTF 格式的 3D asset。

请按以下步骤导入新 3D asset:

  1. 验证您的项目的 app 文件夹是否包含 sampledata 文件夹。

    要创建文件夹,请右键点击 Project 窗口中的 app 文件夹,然后选择 New > Sample Data Directory

    sampledata 文件夹是您的 Android Studio 项目的一部分,但其内容不会包括在您的 APK 内。

  2. 将您的 3D 模型源 asset 文件(*.obj*.fbx*.gltf)及其全部依赖项(*.mtl*.bin*.png*.jpg 等)复制到 sampledata 文件夹中。

    请勿将这些源文件复制到您项目的 assetsres 文件夹内,因为这会导致它们不必要地包括在您的 APK 之中。

  3. 右键点击 3D 模型源 asset 并选择 Import Sceneform Asset 以开始导入过程。

    应用的 build.gradle 中的 sceneform.asset() 条目会使用这些值,并确定 *.sfa*.sfb 文件在您项目中的生成位置。

    如果您是第一次导入模型,请使用默认值。

    字段 说明
    Source Asset Path 要导入的 OBJ、FBX 或 glTF 3D 模型 asset 的文件名。
    Material Path default 会告知 Sceneform 的材料使用内置的默认材料

    高级用户可为自定义材料 *.mat 文件指定路径。

    .sfa Output Path 使用默认值,或者指定 sampledata 文件夹下的另一个路径。

    这样可以确保 *.sfa 不会不必要地包含在您的 APK 中。

    .sfb Output Path 默认情况下,会使用 src/main/assets/ 文件夹,这样就允许使用任意 asset 文件名。

    如果文件名(没有文件扩展名)是有效的资源标识符(例如,R.raw.filename),那么如果您愿意,就可以改用 src/main/res/raw/ 文件夹。

    请参阅 Android 的应用资源概览 了解有关在您的应用中使用 assets/res÷ 文件夹的详细信息。

  4. 点击 Finish 以开始导入过程。

要导入您的 asset,插件需要执行以下操作:

  1. 如果您的项目的 build.gradle 中尚不存在 Sceneform Gradle 插件,执行添加操作:

    dependencies {
        …
        classpath 'com.google.ar.sceneform:plugin:1.5.0'
    }
    
  2. 更新您的应用的 build.gradle 文件,为新导入的 asset 添加一个 apply plugin 行和一个 sceneform.asset() 条目:

    apply plugin: 'com.google.ar.sceneform.plugin'
    
    sceneform.asset('sampledata/models/andy.obj', // 'Source Asset Path' specified during import.
            'default',                            // 'Material Path' specified during import.
            'sampledata/models/andy.sfa',         // '.sfa Output Path' specified during import.
            'src/main/res/raw/andy')              // '.sfb Output Path' specified during import.
    

    应用的 build.gradle 中的这些新条目会创建两个 Gradle 任务:

    • 如果尚不存在 Sceneform asset 定义 (*.sfa) 文件,createAsset-<asset-name> 会创建一个。

      此任务不会覆盖现有的 *.sfa 文件,这意味着您在导入后对 SFA 文件所做的任何修改都不会被覆盖。

      *.sfa 文件是一个包含人类可读、完整的 asset 导入设置说明的文本文件。 它引用您的源 asset 中的模型和纹理,还通过为 Sceneform 的基于物理材料提供材料参数对材料进行定义。

    • compileAsset-<asset-name> 会将 *.sfa 文件编译到 Sceneform 二进制 asset (*.sfb) 文件中。

      *.sfb 文件内置于您应用的 APK 内并在运行时加载以创建可渲染对象

    如需了解详细信息,请参阅 Sceneform Gradle 插件参考

  3. 在文本窗口中打开 *.sfa,在 Viewer 窗口中打开 *.sfb

更新之前导入的 3D asset

当您更新之前导入的 OBJ、FBX 或 glTF 模型源 asset 文件(*.obj*.fbx*.gltf)时,您应用的 build.gradle 中相应的 sceneform.asset() 条目会使插件根据当前的 *.sfa 参数自动生成更新的 *.sfb 文件。

要为已导入的 asset 迭代参数,请执行以下操作:

  • 使用 SFA 文件格式参考作为指导,修改 *.sfa 文本文件。
  • 保存您的更改。 这将导致 asset 被重新编译并更新 *.sfb 文件。
  • 通过双击 *.sfb 文件打开 asset Viewer 窗口,预览更新的 asset。

创建可渲染对象

在 asset 被编译为 *.sfb 格式后,您可以按如下所示构建 ModelRenderable,并将其连接到场景中的某个节点:

ModelRenderable.builder()
    // To load as an asset from the 'assets' folder ('src/main/assets/andy.sfb'):
    .setSource(this, Uri.parse("andy.sfb"))

    // Instead, load as a resource from the 'res/raw' folder ('src/main/res/raw/andy.sfb'):
    //.setSource(this, R.raw.andy)

    .build()
    .thenAccept(renderable -> andyRenderable = renderable)
    .exceptionally(
        throwable -> {
          Log.e(TAG, "Unable to load Renderable.", throwable);
          return null;
    });

使用自定义材料

Sceneform 的默认材料使开发者可以轻松地获得出色的外观。 您还可以使用自定义材料深入自定义您的 asset 显示方式。

要为您的 asset 指定自定义材料,请执行以下操作:

  1. 使用自定义材料参考作为指导,创建自定义材料定义 (*.mat) 文件。

  2. 将自定义材料应用到 asset:

    导入新 asset 时

    • 导入过程中,指定自定义材料 *.mat 文件。

    更新之前导入的 asset

    • 如果未自定义 *.sfa 内容,请删除现有的 *.sfa*.sfb 文件以及应用的 build.gradle 中的 sceneform.asset() 条目,然后重新导入 asset。 这能确保重新生成的 *.sfa 属性和材料参数与您自定义材料支持的内容匹配。

    • 要保留您做的任何 *.sfa 自定义内容,请打开 *.sfa 文件,将 source 属性更改为您的自定义材料 *.mat 文件的路径,然后手动调整 *.sfa 属性和材料参数以匹配您的自定义材料。