Importar elementos y vistas previas en 3D

Obtén información sobre cómo importar modelos 3D, convertirlos en formato Sceneform y obtener una vista previa de ellos en Android Studio.

Importar un nuevo elemento 3D

Sceneform admite elementos 3D en los siguientes formatos:

  • OBJ
  • glTF (las animaciones no son compatibles)
  • FBX, con o sin animaciones.

Sigue estos pasos para importar un nuevo elemento 3D:

  1. Verifica que la carpeta app de tu proyecto contenga una carpeta sampledata.

    Para crear la carpeta, haz clic con el botón derecho en la carpeta app en la ventana Project y, luego, selecciona New > Sample Data Directory.

    La carpeta sampledata forma parte de tu proyecto de Android Studio, pero su contenido no se incluirá en el APK.

  2. Copia el archivo del elemento fuente de tu modelo 3D (*.obj, *.fbx o *.gltf) y todas sus dependencias (*.mtl, *.bin, *.png, *.jpg, etc.) en la carpeta sampledata.

    No copies estos archivos de origen en la carpeta assets o res de tu proyecto, ya que esto los incluirá en el APK sin necesidad.

  3. Haz clic derecho en el elemento de fuente del modelo 3D y selecciona Import Sceneform Asset (Importar elemento de formato de escena) para comenzar el proceso de importación.

    Los valores se usan en la entrada sceneform.asset() de build.gradle de la app y determinan dónde se generarán los archivos *.sfa y *.sfb en tu proyecto.

    Si importas un modelo por primera vez, usa los valores predeterminados.

    Campo Descripción
    Ruta del elemento de origen Nombre del archivo del elemento 3D de OBJ, FBX o glTF para importar.
    Ruta de acceso del material default le indica a Sceneform que use el material predeterminado incorporado o la ruta a un archivo de material personalizado *.mat.
    .sfa Output Path (Ruta de salida de .sfa) Usa la ruta predeterminada o especifica otra en la carpeta sampledata.

    El archivo .sfa se genera si falta. Se puede modificar para controlar algunos aspectos del proceso de importación.

    Esto garantiza que *.sfa no se incluya en tu APK de manera indefinida.
    .sfb Output Path (Ruta de salida .sfb) De forma predeterminada, se usa la carpeta src/main/assets/, que permite el uso de nombres de archivos de elementos arbitrarios.

    Si el nombre de archivo (sin extensión de archivo) es un identificador de recursos válido (p.ej., R.raw.filename), puedes usar la carpeta src/main/res/raw/ si lo prefieres.

    Consulta la descripción general de los recursos de la app para obtener más información sobre el uso de las carpetas assets/ y res/ en tu app.
    Archivos de animación

    Si importas archivos de animación *.fbx, haz clic en el signo más (+) y agrega el resto de los archivos individualmente.

  4. Haz clic en Finalizar para comenzar el proceso de importación.

Para importar tu elemento, el complemento hace lo siguiente:

  1. Agrega el complemento de Gradle de Sceneform al build.gradle de tu proyecto si no existe:

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

  2. Actualiza el archivo build.gradle de tu app a fin de incluir una línea apply plugin y una entrada sceneform.asset() para el elemento recién 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 entradas nuevas en la build.gradle de app crean dos tareas de Gradle:

    • createAsset-<asset-name> crea un archivo de definición de elementos de Sceneform (*.sfa) si aún no existe.

      Esta tarea no reemplazará un archivo *.sfa existente, lo que significa que cualquier modificación que realices en el archivo SFA después de la importación no se sobrescribirá.

      El archivo *.sfa es un archivo de texto que contiene una descripción completa y legible de la configuración de importación del elemento. Hace referencia a los modelos y las texturas del elemento de origen y, además, define los materiales mediante parámetros de material para los materiales basados en la forma física de Sceneform.

    • compileAsset-<asset-name> compila el archivo *.sfa en un archivo binario de elemento de Sceneform (*.sfb).

      Este archivo *.sfb se compila en el APK de tu app y se carga durante el tiempo de ejecución para crear el elemento que se puede renderizar.

    Para obtener más información, consulta la referencia del complemento de Gradle de Sceneform.

  3. Abre *.sfa en una ventana de texto y *.sfb en una ventana de Viewer.

Actualizar un elemento 3D importado anteriormente

Cuando actualizas un archivo de elementos de origen OBJ, FBX o glTF importado (*.obj, *.fbx o *.gltf), la entrada sceneform.asset() correspondiente en tu build.gradle app hace que el complemento genere automáticamente un archivo *.sfb actualizado, según los parámetros *.sfa actuales.

Para iterar los parámetros de un elemento ya importado, sigue estos pasos:

  • Modifica el archivo de texto *.sfa mediante la referencia de formato de archivo de SFA como guía.
  • Guarda los cambios. Esto hace que se vuelva a compilar el elemento y se actualice el archivo *.sfb.
  • Para obtener una vista previa del elemento actualizado, haz doble clic en el archivo *.sfb a fin de abrir la ventana Viewer del elemento.

Si actualizas un elemento importado anteriormente que incluye datos de animación, importa cada uno de los archivos *.fbx actualizados de forma individual con el signo más (+) en la sección Animation Files del diálogo de importación.

Definiciones de elementos de Gradle

El proceso de importación agrega cualquier archivo de animación *.fbx al final del archivo 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'])

Cómo crear el Renderable

Una vez que se compila el elemento en formato *.sfb, puedes compilar un ModelRenderable y adjuntarlo a un nodo de la escena de la siguiente manera:

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

Usa materiales personalizados

Los materiales predeterminados de Sceneform facilitan a los desarrolladores obtener excelentes resultados. También puedes usar materiales personalizados para personalizar el aspecto de tus elementos.

Sigue estos pasos para asignar un material personalizado a tu activo:

  1. Crea un archivo de definición de material personalizado (*.mat) con la guía de [referencia de material personalizado](/sceneform/develop/custom-material) como guía.

  2. Aplica el material personalizado al elemento:

    Cuando importas un nuevo elemento:

    Para actualizar un elemento importado anteriormente:

    • Si no se personalizó el contenido de *.sfa, borra los archivos *.sfa y *.sfb existentes, y la entrada sceneform.asset() de build.gradle de la appsceneform.asset() y, luego, vuelve a importar el elemento. Esto garantiza que los atributos *.sfa y los parámetros de material regenerados coincidan con los admitidos por tu material personalizado.

    • Para conservar las personalizaciones de *.sfa que hayas realizado, abre el archivo *.sfa y cambia el atributo source a la ruta de acceso al archivo *.mat de material personalizado. Luego, ajusta manualmente los atributos *.sfa y los parámetros de material para que coincidan con el material personalizado.