Import and preview 3D assets

Learn how to import 3D models, convert them into Sceneform format, and preview them in Android Studio.

Import a new 3D asset

Sceneform supports 3D assets in the following formats:

  • OBJ
  • glTF (animations not supported)
  • FBX, with or without animations.

Follow these steps to import a new 3D asset:

  1. Verify that your project's app folder contains a sampledata folder.

    To create the folder, right-click on the app folder in the Project window, then select New > Sample Data Directory.

    The sampledata folder is part of your Android Studio project, but its contents will not be included in your APK.

  2. Copy your 3D model source asset file (*.obj, *.fbx, or *.gltf), and all of its dependencies (*.mtl, *.bin, *.png, *.jpg, etc.) into the sampledata folder.

    Do not copy these source files into your project's assets or res folder, as this will cause them to be included in your APK unnecessarily.

  3. Right click the 3D model source asset and select Import Sceneform Asset to begin the import process.

    The values are used by the sceneform.asset() entry in the app's build.gradle, and determine where the *.sfa and *.sfb files will be generated in your project.

    If you're importing a model for the first time, use the default values.

    Field Description
    Source Asset Path Filename of the OBJ, FBX, or glTF 3D model asset to import.
    Material Path default tells Sceneform's to use the built-in default material or the path to a custom material *.mat file.
    .sfa Output Path Use the default, or specify another path under the sampledata folder.

    The .sfa file is generated if missing. It can be modified to control some aspects of the import process.

    This ensures that *.sfa isn't included in your APK unncessarily.
    .sfb Output Path By default the src/main/assets/ folder is used, which allows the use of arbitrary asset filenames.

    If the filename (without file extension) is a valid resource identifier (e.g. R.raw.filename), then you can instead use the src/main/res/raw/ folder if you prefer.

    See Android's App resources overview for more on using the assets/ and res/ folders in your app.
    Animation Files

    If you are importing *.fbx animation files, click the plus sign (+) and add the rest of the files individually.

  4. Click Finish to begin the import process.

To import your asset, the plugin does the following:

  1. Adds the Sceneform gradle plugin to your project's build.gradle if it doesn't already exist:

    dependencies {
    …
    classpath 'com.google.ar.sceneform:plugin:1.15.0'
}

  2. Updates your app's build.gradle file to include an apply plugin line, and a sceneform.asset() entry for the newly imported 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.

    These new entries in the app's build.gradle create two gradle tasks:

    • createAsset-<asset-name> creates a Sceneform asset definition (*.sfa) file if it does not yet exist.

      This task will not overwrite an existing *.sfa file, which means any modifications you make to the SFA file after import won't be overwritten.

      The *.sfa file is a text file that contains a complete, human-readable description of the asset's import settings. It references the models and textures in your source asset, and also defines materials by providing material parameters for Sceneform's physically based materials.

    • compileAsset-<asset-name> compiles the *.sfa file into a Sceneform binary asset (*.sfb) file.

      This *.sfb file gets built into your app's APK and is loaded at runtime to create the renderable.

    For more information, see the Sceneform Gradle Plugin reference.

  3. Opens the *.sfa in a text window and the *.sfb in a Viewer window.

Update a previously imported 3D asset

When you update a previously imported OBJ, FBX, or glTF model source asset file (*.obj, *.fbx, or *.gltf), the corresponding sceneform.asset() entry in your app's build.gradle causes the plugin to automatically generate an updated *.sfb file, based on the current *.sfa parameters.

To iterate on the parameters for an already imported asset:

  • Modify the *.sfa text file, using the SFA file format reference as a guide.
  • Save your changes. This causes the asset to be recompiled and updates the *.sfb file.
  • Preview the updated asset by double-clicking the *.sfb file to open the asset Viewer window.

If you are updating a previously imported asset that includes animation data, import each of the updated *.fbx files individually using the plus (+) sign in the Animation Files section of the import dialog.

Gradle asset definitions

The import process adds any *.fbx animation files at the end of the build.gradle file.

sceneform.asset('sampledata/models/andy_dance.fbx',
'default',
'sampledata/models/andy_dance.sfa',
'src/main/res/raw/andy_dance',
['sampledata/models/andy_wave_r.fbx',
'sampledata/models/andy_wave_l.fbx'])

Create the Renderable

Once the asset is compiled into *.sfb format, you can build a ModelRenderable and attach it to a node in the scene as follows:

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;
    });

Using custom materials

Sceneform's default materials make it easy for developers to get great looking results. You can also use custom materials to deeply customize the way your assets look.

To assign a custom material to your asset:

  1. Create a custom material definition (*.mat) file, using the [Custom Material Reference](/sceneform/develop/custom-material as a guide.

  2. Apply the custom material to the asset:

    When importing a new asset:

    To update a previously imported asset:

    • If the *.sfa contents have not been customized, delete the existing *.sfa and *.sfb files and the sceneform.asset() entry in the app's build.gradle, then reimport the asset. This ensures that the regenerated *.sfa attributes and material parameters will match the ones supported by your custom material.

    • To preserve any *.sfa customizations you've made, open the *.sfa file and change the source attribute to the path to your custom material *.mat file, then manually adjust the *.sfa attributes and material parameters to match your custom material.