# Import and preview 3D assets

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

> [!NOTE]
> **Note:** To import and work with 3D models in Sceneform, ensure you have [installed the Google Sceneform Tools (Beta) plugin](https://developers.google.com/sceneform/develop/getting-started#import-sceneform-plugin).

## 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](https://developers.google.com/sceneform/develop/sfa#parameters_for_default_materials) or the path to a[custom material](https://developers.google.com/sceneform/develop/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](https://developers.google.com/sceneform/develop/sfa) 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](https://developer.android.com/guide/topics/resources/providing-resources) 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](https://developers.google.com/sceneform/develop/import-assets#create_the_renderable).

   For more information, see the
   [Sceneform Gradle Plugin reference](https://developers.google.com/sceneform/reference/gradle/com/google/ar/sceneform/plugin/package-summary).
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](https://developers.google.com/sceneform/develop/sfa) 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`](https://developers.google.com/sceneform/reference/com/google/ar/sceneform/rendering/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](https://developers.google.com/sceneform/develop/sfa#parameters_for_default_materials)
make it easy for developers to get great looking
results. You can also use
[custom materials](https://developers.google.com/sceneform/develop/custom-material) 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**:
   - Specify the custom material `*.mat` file during the [import process](https://developers.google.com/sceneform/develop/import-assets#import_a_3d_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](https://developers.google.com/sceneform/develop/import-assets#import_a_3d_asset) 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`](https://developers.google.com/sceneform/develop/sfa#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.