Cómo comenzar a usar Sceneform

En esta página, se explican los conceptos clave mediante la exploración del código en la app de muestra Hello Sceneform. Nota:

  • En esta muestra, se usa Sceneform y ARCore.

    Para usar Sceneform sin ARCore, sigue los pasos que se indican a continuación mientras ignoras los requisitos de permisos de CAMERA y dependencia de ARCore. Usa SceneView en el diseño de tu app como se describe en Cómo crear la escena.

  • Esta app de ejemplo está escrita como app Requiere RA.

    Para obtener más información sobre las apps AR Optional y AR Required, consulta Cómo habilitar ARCore.

Para comenzar a utilizar Sceneform en tu proyecto, debes hacer lo siguiente:

  1. Cómo importar el complemento Sceneform
  2. Configura los archivos build.gradle de tu proyecto
  3. Actualiza tu AndroidManifest.xml
  4. Realiza verificaciones del entorno de ejecución y crea una vista de escena
  5. Cómo crear elementos renderizables
  6. Compila la escena

Importa el complemento de Sceneform a tu proyecto

Una vez instalado, el complemento Sceneform te permite importar, ver y compilar elementos 3D en el SDK de Sceneform para apps de RA en Android Studio. Requiere Android Studio 3.1 y versiones posteriores.

Para instalar el complemento, ejecuta lo siguiente:

  1. En Android Studio, abre la configuración de Plugins:

    • Windows: Archivo > Configuración > Complementos > Explorar repositorios

    • macOS: Android Studio > Preferences > Plugins

  2. Haz clic en Explorar repositorios y, luego, instala las Herramientas de Google Sceneform (Beta).

Configura los archivos build.gradle de tu proyecto

  1. Asegúrate de que tu proyecto build.gradle incluya el repositorio Maven de Google:

    allprojects {
    repositories {
        google()
        …

  2. Actualiza el archivo build.gradle de tu app para agregar las dependencias más recientes de UX de ARCore y Sceneform y asegúrate de que la configuración de tu proyecto sea compatible con ambas bibliotecas.

    android {
    …
    defaultConfig {
        // Sceneform requires minSdkVersion >= 24.
        minSdkVersion 24
        …
    }
    // Sceneform libraries use language constructs from Java 8.
    // Add these compile options if targeting minSdkVersion < 26.
    compileOptions {
        sourceCompatibility JavaVersion.VERSION_1_8
        targetCompatibility JavaVersion.VERSION_1_8
    }
}

dependencies {
    …
    // Provides ARCore Session and related resources.
    implementation 'com.google.ar:core:1.15.0'

    // Provides ArFragment, and other UX resources.
    implementation 'com.google.ar.sceneform.ux:sceneform-ux:1.15.0'

    // Alternatively, use ArSceneView without the UX dependency.
    implementation 'com.google.ar.sceneform:core:1.15.0'
}

Actualiza tu AndroidManifest.xml

Modifica tu AndroidManifest.xml para indicar que tu app usa (opcional de RA) o requiere (acceso obligatorio) acceso a ARCore y CAMERA:

<!-- Both "AR Optional" and "AR Required" apps require CAMERA permission. -->
<uses-permission android:name="android.permission.CAMERA" />

<!-- Sceneform requires OpenGL ES 3.0 or later. -->
<uses-feature android:glEsVersion="0x00030000" android:required="true" />

<!-- Indicates that app requires ARCore ("AR Required"). Ensures the app is
     visible only in the Google Play Store on devices that support ARCore.
     For "AR Optional" apps remove this line. -->
<uses-feature android:name="android.hardware.camera.ar" />

<application>
    …
    <!-- Indicates that app requires ARCore ("AR Required"). Causes the Google
         Play Store to download and install Google Play Services for AR along
         with the app. For an "AR Optional" app, specify "optional" instead of
         "required".
    -->
    <meta-data android:name="com.google.ar.core" android:value="required" />
</application>

Cómo realizar verificaciones de tiempo de ejecución y crear una vista de escena

La forma más fácil de comenzar a usar Sceneform y crear una vista de escena es mediante un ArFragment, que controla automáticamente la administración de sesiones de ARCore después de realizar las verificaciones de entorno de ejecución de ARCore necesarias:

  1. Comprueba si hay una versión compatible de los Servicios de Google Play para RA instalada y le solicita al usuario que la instale o actualice según sea necesario

  2. Verifica si la app tiene acceso a la cámara y solicita permiso al usuario si aún no se otorgó.

Si tu app necesita solicitar permisos adicionales o si quieres personalizar cómo y cuándo se crea la sesión de RA, puedes hacer lo siguiente:

  • Crea una subclase de ArFragment para solicitar permisos adicionales.

  • Usa o extiende ArSceneView directamente. Tu app debe realizar la verificación de la versión de ARCore y llamar a setupSession() para crear la sesión de ARCore de forma manual, como se demuestra en la muestra del sistema solar.

Una vez que se aprueban las verificaciones, ArFragment crea lo siguiente:

  1. Un ArSceneView, al que se puede acceder a través de getArSceneView(), y que:

    • Procesa las imágenes de la cámara desde la sesión hasta su superficie.

    • Renderiza una animación de UX con Sceneform integrada que muestra a los usuarios cómo deben mover su teléfono para activar la experiencia de RA.

    • Elementos destacados detectados Planes con el valor predeterminado PlaneRenderer

  2. Un ARCore Session, al que se puede acceder a través de getSession()

Para usar ArFragment en tu app, agrégala al diseño de tu actividad, como se muestra en activity_ux.xml en la muestra Hello Sceneform:

<fragment android:name="com.google.ar.sceneform.ux.ArFragment"
    android:id="@+id/ux_fragment"
    android:layout_width="match_parent"
    android:layout_height="match_parent" />

Cómo crear elementos renderizados

Un objeto Renderable es un modelo en 3D que se puede colocar en cualquier lugar de la escena y que consiste en mallas, materiales y texturas.

Los elementos que se pueden renderizar pueden crearse a partir de los siguientes elementos:

La app de muestra crea un archivo que se puede renderizar a partir de un archivo 3D andy.obj. Cuando se importa este elemento, el complemento de Sceneform actualiza el build.gradle de la app para aplicar el complemento y agregar una entrada sceneform.asset() al modelo 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.

El recurso res/raw/andy se usa para crear un ModelRenderable:

private ModelRenderable andyRenderable;

@Override
protected void onCreate(Bundle savedInstanceState) {
    …

    ModelRenderable.builder()
        .setSource(this, R.raw.andy)
        .build()
        .thenAccept(renderable -> andyRenderable = renderable)
        .exceptionally(
            throwable -> {
            Log.e(TAG, "Unable to load Renderable.", throwable);
            return null;
        });
}

Crea la escena

El ARSceneView tiene un Scene adjunto. La escena es una estructura de datos en forma de árbol que contiene objetos Node que son los objetos virtuales que se renderizarán.

Aquí, el renderizado de andy se adjunta directamente al nodo raíz Scene:

Node node = new Node();
node.setParent(arFragment.getArSceneView().getScene());
node.setRenderable(andyRenderable);

Cada nodo contiene toda la información que Sceneform necesita procesar (incluida su posición, orientación y objeto que se puede renderizar), así como interactuar con él (incluida la forma de colisión y los objetos de escucha de eventos).

Los nodos se pueden agregar a otros nodos para formar una relación de superior y secundario. Cuando un nodo es un elemento secundario de otro nodo, se mueve, rota y escala con su superior, como cuando se mueven los brazos. Un nodo puede tener varios elementos secundarios, pero solo un superior, lo que forma una estructura en forma de árbol. Esta estructura se conoce como el gráfico de escenas.

Cada fotograma renderiza el gráfico de escena desde el punto de vista de la cámara (guiado por el seguimiento de movimiento de ARCore). Tu app puede interactuar con la escena detectando eventos táctiles y gestuales, realizando pruebas de posicionamiento en nodos y colocando anclajes. Para obtener más información, consulta Cómo interactuar con la escena.