Importar e visualizar recursos 3D

Saiba como importar modelos 3D, convertê-los no formato de cenário e visualizá-los no Android Studio.

Importar um novo recurso 3D

O Sceneform é compatível com recursos 3D nos seguintes formatos:

  • OBJ
  • glTF (não há suporte para animações)
  • KTX, com ou sem animações.

Siga estas etapas para importar um novo recurso 3D:

  1. Verifique se a pasta app do projeto contém uma pasta sampledata.

    Para criar a pasta, clique com o botão direito do mouse na pasta app na janela Project e selecione New > Sample Data Directory.

    A pasta sampledata faz parte do projeto do Android Studio, mas o conteúdo dela não será incluído no APK.

  2. Copie o arquivo de recurso de origem do modelo 3D (*.obj, *.fbx ou *.gltf) e todas as dependências dele (*.mtl, *.bin, *.png, *.jpg etc.) na pasta sampledata.

    Não copie esses arquivos de origem para a pasta assets ou res do projeto, porque isso fará com que eles sejam incluídos desnecessariamente no APK.

  3. Clique com o botão direito do mouse no recurso de origem do modelo 3D e selecione Import Sceneform Asset para iniciar o processo de importação.

    Os valores são usados pela entrada sceneform.asset() no build.gradle dos apps e determinam onde os arquivos *.sfa e *.sfb serão gerados no projeto.

    Se você estiver importando um modelo pela primeira vez, use os valores padrão.

    Campo Descrição
    Caminho do recurso de origem Nome de arquivo do recurso do modelo 3D OBJ, KTX ou glTF para importar.
    Caminho do Material Design default diz ao Sceneform's para usar o material padrão integrado ou o caminho para um arquivo *.mat de material personalizado.
    Caminho de saída.sfa Use o padrão ou especifique outro caminho na pasta sampledata.

    O arquivo .sfa será gerado se estiver ausente. Ele pode ser modificado para controlar alguns aspectos do processo de importação.

    Isso garante que *.sfa não seja incluído no APK de forma não intencional.
    Caminho de saída do .sfb Por padrão, a pasta src/main/assets/ é usada, o que permite o uso de nomes de arquivo de recursos arbitrários.

    Se o nome do arquivo (sem a extensão de arquivo) for um identificador de recurso válido (por exemplo, R.raw.filename), você poderá usar a pasta src/main/res/raw/ se preferir.

    Consulte Visão geral dos recursos de app do Android para saber mais sobre como usar as pastas assets/ e res/ no seu app.
    Arquivos de animação

    Se você estiver importando arquivos de animação *.fbx, clique no sinal de adição (+) e adicione o restante dos arquivos individualmente.

  4. Clique em Concluir para iniciar o processo de importação.

Para importar seu recurso, o plug-in faz o seguinte:

  1. O plug-in do Gradle do Sceneform foi adicionado ao build.gradle do seu projeto se ele ainda não existe:

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

  2. Atualiza o arquivo build.gradle do app's para incluir uma linha apply plugin e uma entrada sceneform.asset() para o recurso recém-importado:

    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.

    Estas novas entradas no build.gradle do app's criam duas tarefas do Gradle:

    • createAsset-<asset-name> cria um arquivo de definição de recurso do Sceneform (*.sfa) se ele ainda não existir.

      Essa tarefa não substituirá um arquivo *.sfa existente, o que significa que as modificações feitas no arquivo SFA após a importação não serão substituídas.

      O *.sfa é um arquivo de texto que contém uma descrição completa e legível das configurações de importação do recurso. Ele faz referência aos modelos e texturas no recurso de origem e também define os materiais, fornecendo parâmetros para materiais físicos do Sceneform.

    • O compileAsset-<asset-name> compila o arquivo *.sfa em um arquivo de recursos binários do Sceneform (*.sfb).

      Esse arquivo *.sfb é integrado ao APK do seu app e é carregado no momento da execução para criar o elemento de renderização.

    Para ver mais informações, consulte a referência do plug-in do Gradle para Sceneform.

  3. Abre o *.sfa em uma janela de texto e o *.sfb em uma janela Viewer.

Atualizar um recurso 3D importado anteriormente

Quando você atualiza um arquivo de recurso de origem de modelo OBJ, AppSheet ou glTF importado anteriormente (*.obj, *.fbx ou *.gltf), a entrada sceneform.asset() correspondente no build.gradledo app's faz com que o plug-in gere automaticamente um arquivo *.sfb atualizado, com base nos parâmetros *.sfa atuais.

Para iterar os parâmetros de um recurso já importado:

  • Modifique o arquivo de texto *.sfa usando a referência do formato de arquivo SFA como guia.
  • Salve as alterações. Isso faz com que o recurso seja recompilado e atualiza o arquivo *.sfb.
  • Visualize o recurso atualizado clicando duas vezes no arquivo *.sfb para abrir a janela Viewer.

Se você estiver atualizando um recurso já importado que inclui dados de animação, importe cada um dos arquivos *.fbx atualizados individualmente com o sinal de adição (+) na seção Arquivos de animação da caixa de diálogo de importação.

Definições de recursos do Gradle

O processo de importação adiciona todos os arquivos de animação *.fbx ao final do arquivo 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'])

Criar o Renderable

Depois que o recurso for compilado no formato *.sfb, crie um ModelRenderable e anexe-o a um nó na cena da seguinte maneira:

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

Como usar materiais personalizados

Os materiais padrão do Sceneform e permitem que os desenvolvedores consigam resultados com ótima visualização. Você também pode usar materiais personalizados para personalizar profundamente a aparência dos recursos.

Para atribuir um material personalizado ao seu recurso, faça o seguinte:

  1. Crie um arquivo de definição de material personalizado (*.mat) usando a [referência do material personalizado](/sceneform/develop/custom-material como guia.

  2. Aplique o material personalizado ao recurso:

    Ao importar um novo recurso:

    Para atualizar um recurso importado anteriormente:

    • Se o conteúdo de *.sfa não tiver sido personalizado, exclua os arquivos *.sfa e *.sfb existentes e a entrada sceneform.asset() em build.gradle dos apps e depois reimporte o recurso. Isso garante que os atributos *.sfa e os parâmetros do material gerados novamente correspondam aos atributos compatíveis com o material personalizado.

    • Para preservar as personalizações do *.sfa feitas, abra o arquivo *.sfa e mude o atributo source para o caminho do arquivo *.mat do Material Design personalizado. Em seguida, ajuste manualmente os atributos *.sfa e os parâmetros do Material Design para corresponder ao seu material personalizado.