Importa e visualizza in anteprima asset 3D

Scopri come importare modelli 3D, convertirli in formato Sceneform e visualizzarne l'anteprima in Android Studio.

Importare un nuovo asset 3D

Sceneform supporta gli asset 3D nei seguenti formati:

  • OBJ
  • glTF (animazioni non supportate)
  • VPAID con o senza animazioni.

Per importare un nuovo asset 3D:

  1. Verifica che la cartella app del progetto contenga una cartella sampledata.

    Per creare la cartella, fai clic con il pulsante destro del mouse sulla cartella app nella finestra Progetto, quindi seleziona Nuovo > directory di dati di esempio.

    La cartella sampledata fa parte del tuo progetto Android Studio, ma i suoi contenuti non saranno inclusi nell'APK.

  2. Copia il file asset delle origini del modello 3D (*.obj, *.fbx o *.gltf) e tutte le sue dipendenze (*.mtl, *.bin, *.png, *.jpg e così via) nella cartella sampledata.

    Non copiare questi file di origine nella cartella assets o res del progetto, altrimenti verranno inseriti inutilmente nell'APK.

  3. Fai clic con il pulsante destro del mouse sull'asset di origine del modello 3D e seleziona Importa asset scena per avviare il processo di importazione.

    I valori vengono utilizzati dalla voce sceneform.asset() nelle app's build.gradle e determinano la posizione in cui verranno generati i file *.sfa e *.sfb nel progetto.

    Se importi un modello per la prima volta, utilizza i valori predefiniti.

    Campo Descrizione
    Percorso asset di origine Nome del file dell'asset modello 3D OBJ, OBA o glTF da importare.
    Percorso del materiale default indica a Sceneform di utilizzare il materiale predefinito integrato o il percorso di un materiale personalizzato *.mat.
    Percorso di output.sfa Usa il percorso predefinito o specifica un percorso nella cartella sampledata.

    Il file .sfa viene generato se mancante. Può essere modificato per controllare alcuni aspetti del processo di importazione.

    In questo modo, l'elemento *.sfa non sarà incluso nell'APK in modo non esplicito.
    Percorso di output.sfb Per impostazione predefinita viene utilizzata la cartella src/main/assets/, che consente l'utilizzo di nomi file arbitrari degli asset.

    Se il nome file (senza estensione file) è un identificatore risorsa valido (ad es. R.raw.filename), se preferisci, puoi utilizzare la cartella src/main/res/raw/.

    Consulta la panoramica delle risorse per le app di Android per scoprire di più sull'utilizzo delle cartelle assets/ e res/ nell'app.
    File di animazione

    Se importi *.fbx file di animazione, fai clic sul segno più (+) e aggiungi gli altri file singolarmente.

  4. Fai clic su Finish (Fine) per avviare la procedura di importazione.

Per importare l'asset, il plug-in svolge le seguenti operazioni:

  1. Aggiunge il plug-in gradle di Sceneform al tuo progetto's build.gradle se non esiste già:

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

  2. Aggiorna il file build.gradle dell'app per includere una riga apply plugin e una voce sceneform.asset() per l'asset appena importato:

    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.

    Queste nuove voci nelle build.gradle delle app creano due attività di Gradle:

    • createAsset-<asset-name> crea un file di definizione dell'asset di Sceneform (*.sfa) se non esiste ancora.

      Questa attività non sovrascriverà un file *.sfa esistente, il che significa che le modifiche apportate al file SFA dopo l'importazione non verranno sovrascritte.

      Il file *.sfa è un file di testo contenente una descrizione completa e leggibile delle impostazioni di importazione dell'asset. Fa riferimento a modelli e texture nell'asset di origine e definisce anche i materiali fornendo parametri materiali per i materiali fisici di Sceneform.

    • compileAsset-<asset-name> compila il file *.sfa in un file binario di Sceneform (*.sfb).

      Questo file *.sfb viene integrato nell'APK dell'app e viene caricato in fase di runtime per creare il rendering.

    Per ulteriori informazioni, consulta il riferimento per il plug-in Sceneform Gradle.

  3. Apre *.sfa in una finestra di testo e *.sfb in una finestra di Visualizzatore.

Aggiorna un asset 3D importato in precedenza

Quando aggiorni un file di asset di origine del modello OBJ, iCal o glTF precedentemente importato (*.obj, *.fbx o *.gltf), la voce sceneform.asset() corrispondente nelle app build.gradle fa sì che il plug-in generi automaticamente un file *.sfb aggiornato, in base ai parametri *.sfa attuali.

Per eseguire l'iterazione dei parametri per un asset già importato:

  • Modifica il file di testo *.sfa utilizzando il riferimento per il formato del file SFA come guida.
  • Salva le modifiche. In questo modo l'asset viene ricompilato e viene aggiornato il file *.sfb.
  • Per visualizzare l'anteprima dell'asset aggiornato, fai doppio clic sul file *.sfb per aprire la finestra Visualizzatore dell'asset.

Se aggiorni un asset importato in precedenza che include dati di animazione, importa ogni file *.fbx aggiornato singolarmente utilizzando il segno più (+) nella sezione File di animazione della finestra di dialogo di importazione.

Definizioni degli asset Gradle

Durante il processo di importazione, vengono aggiunti tutti i file di animazione *.fbx alla fine del file build.gradle.

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'])

Crea il rendering

Dopo aver compilato l'asset in formato *.sfb, puoi creare una ModelRenderable e collegarla a un nodo nella scena nel seguente modo:

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

Utilizzo di materiali personalizzati

I materiali predefiniti di Sceneform consentono agli sviluppatori di ottenere facilmente ottimi risultati. Puoi anche utilizzare materiali personalizzati per personalizzare al meglio l'aspetto dei tuoi asset.

Per assegnare un materiale personalizzato all'asset:

  1. Crea un file di definizione del materiale personalizzato (*.mat) utilizzando il [riferimento materiale personalizzato](/sceneform/develop/custom-material) come guida.

  2. Applica il materiale personalizzato alla risorsa:

    Quando importi un nuovo asset:

    Per aggiornare un asset importato in precedenza:

    • Se i contenuti *.sfa non sono stati personalizzati, elimina i file *.sfa e *.sfb esistenti e la voce sceneform.asset() nelle app build.gradle, quindi reimporta la risorsa. In questo modo, gli attributi *.sfa e i parametri del materiale rigenerati corrisponderanno a quelli supportati dal materiale personalizzato.

    • Per mantenere le personalizzazioni di *.sfa effettuate, apri il file *.sfa e modifica l'attributo source nel percorso del file *.mat personalizzato, quindi modifica manualmente gli attributi *.sfa e i parametri del materiale in modo che corrispondano al materiale personalizzato.