Getting started with Sceneform

    This page explains key concepts by exploring the code in the Hello Sceneformsample app . Note:

    • This sample uses Sceneform and ARCore.

      To use Sceneform without ARCore, follow the steps below while ignoring the ARCore dependency and CAMERA permission requirements. Use SceneView in your app's layout as described in Build the Scene .

    • This sample app is written as an AR Required app.

      To learn more about AR Optional vs. AR Required apps, see Enabling ARCore .

    To get started with Sceneform in your project, you'll need to:

    1. Import the Sceneform plugin
    2. Configure your project's build.gradle files
    3. Update your AndroidManifest.xml
    4. Perform runtime checks and create a scene view
    5. Create renderables
    6. Build the Scene

    Import the Sceneform plugin into your project

    Once installed, the Sceneform plugin lets you import, view, and build 3D assets in the Sceneform SDK for AR apps in Android Studio. It requires Android Studio versions 3.1 and above.

    To install the plugin:

    1. In Android Studio open the Pluginssettings:

      • Windows: File > Settings > Plugins > Browse Repositories

      • macOS: Android Studio > Preferences > Plugins

    2. Click Browse repositories, and install the Google Sceneform Tools (Beta) .

    Configure your project's build.gradle files

    1. Make sure your project's build.gradle includes Google's Maven repository:

       allprojects {
    repositories {
        google()
        …

    2. Update your app's build.gradle to add the latest ARCore and Sceneform UX dependencies, and ensure that your project settings are compatible with both libraries.

        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' 
 }

    Update your AndroidManifest.xml

    Modify your AndroidManifest.xml to indicate that your app uses ( AR Optional ) or requires ( AR Required ) ARCore and CAMERA access:

     < !-- 
  
 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 
>

    Perform runtime checks and create a scene view

    The easiest way to get started using Sceneform and create a scene view is by using an ArFragment , which automatically handles ARCore session management after performing necessary ARCore runtime checks:

    1. Checks whether a compatible version of Google Play Services for AR is installed, prompting the user to install or update as necessary

    2. Checks whether the app has access to the camera, and asks the user for permission if it has not yet been granted

    If your app needs to request additional permissions, or would like to customize how and when the AR session is created, you can instead:

    • Create a subclass of ArFragment to request additional permissions.

    • Use or extend ArSceneView directly. Your app must perform the ARCore version check and call setupSession() to create the ARCore session manually, as demonstrated in the Solar System sample .

    Once the checks pass, ArFragment creates:

    1. An ArSceneView , accessible via getArSceneView() , that:

      • Renders the camera images from the session on to its surface

      • Renders a built-in Sceneform UX animation that shows users how they should move their phone to activate the AR experience.

      • Highlights detected Planes using the default PlaneRenderer

    2. An ARCore Session , accessible via getSession()

    To use ArFragment in your app, add it to your activity's layout, as demonstrated in activity_ux.xml in the Hello Sceneformsample:

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

    Create renderables

    A Renderable is a 3D model that can be placed anywhere in the scene and consists of Meshes, Materials and Textures.

    Renderables can be created from:

    The sample app creates a renderable from a 3D andy.obj asset file. When this asset is imported, the Sceneform plugin updates the app's build.gradle to apply the plugin and add a sceneform.asset() entry for the imported model:

     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.

    The res/raw/andy resource is used to create a 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 
 ; 
  
 }); 
 }

    Build the Scene

    The ARSceneView has a Scene attached to it. The scene is a tree-like data structure that holds Node s that are the virtual objects to be rendered.

    Here the andy renderable is attached directly to root Scene node:

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

    Each node contains all the information Sceneform needs to render it (including its position, orientation, and renderable object) as well as interact with it (including its collision shape and event listeners).

    Nodes can be added to other nodes, forming a parent-child relationship. When a node is a child of another node, it moves, rotates, and scales with its parent—like how your arms move when your body moves. A node can have multiple children, but only one parent, thus forming a tree-like structure. This structure is known as the scene graph .

    Each frame, Sceneform renders the scene graph from the Camera's point of view (guided by ARCore motion tracking). Your app can interact with the scene by listening for touch and gesture events, performing hit tests against nodes, and placing anchors. For more info, see Build and Interact with the Scene .
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: