Get Started With Android VR and Google Cardboard: Panoramic Images

During the 2014 Google I/O conference, Google introduced the Cardboard VR viewer, an inexpensive device made of cardboard, which uses lenses and a user's phone to provide simple access to virtual reality apps. Two years later, Google announced plans to expand on this platform by selling a more durable viewer with a controller, known as the Daydream View, which is built following the same concept of using a phone as the main VR provider. In order to get more apps developed that support this platform, Google released Cardboard SDKs for Android (standard SDK and the NDK), iOS, the Unity game engine, and the Unreal game engine. 

This tutorial is the first in a short series about the Android Cardboard and Daydream SDK. In this series, I'll show you how to use some of the SDK's tools and pre-made views to add simple features to your apps. There are a surprising number of ways you can integrate the Cardboard SDK into your apps for games and multimedia! 

I'll focus on three examples that will get you started in the world of VR development: a photosphere viewer, a 360 video viewer, and an input reader for the Daydream controller. We will focus on the photosphere viewer in this tutorial, and revisit the other two topics in subsequent lessons.

Download the Cardboard SDK and Run the Sample Projects

Unlike most libraries in Android, the Android Cardboard SDK is not officially available in a remote repository that can be imported as a dependency through Gradle. In order to use it, you will need to clone the Android Cardboard SDK from GitHub to your computer via Git. 

Once you've downloaded the SDK, let's start by running one of the prepackaged samples. On the Android Studio launch screen, select Import project. Next, select the root folder for the SDK that you just cloned and press OK.

Directory structure of the Cardboard library

At this point you'll have access to all of the library components and samples available in the Cardboard SDK for Android. You can select one of the samples to run on your device from the module dropdown menu at the top of the Android Studio window. To make sure everything is working as expected, select samples-sdk-simplepanowidget and click on the green Run arrow.

Cardboard simple panoramic widget module selection

Once the sample has compiled and installed, you should see an info screen about Machu Picchu, complete with a view that rotates around a photosphere when you move your Android device.

Cardboard panoramic sample

Now that you're able to run the sample applications on your device, let's dive into creating new Cardboard-enabled Android apps.

Creating a Panoramic Viewer

Let's start by creating a new Android project with a minimum SDK version of 19 (KitKat). After you've run through the standard steps of selecting and creating one of the app templates, you will need to copy the necessary libraries for your project from the Cardboard SDK libraries directory into your project's root folder. For this example, copy over the following folders: common, commonwidget, and panowidget.

Included libraries for a new cardboard project

Once your library files are in their proper place, open your project's settings.gradle file. You will need to add those library modules to your project through this file.

Next, you will need to reference these libraries in your build.gradle file under the dependencies node, allowing you to access the pre-made components for Cardboard. You will also need to add Google's Protocol Buffers JavaNano library, which is a code generation and runtime library to help manage the limited resources of Android devices.

After your dependencies have been set up, open your project's AndroidManifest.xml. At the top of the file, within the manifest node, you will need to add the INTERNET and READ_EXTERNAL_STORAGE permissions for the Cardboard SDK.

Within the activity node for your MainActivity class, add a category to the intent-filter for the CARDBOARD viewer.

Now that the setup process is done, we can dig into the fun part: the code. This project will read a photosphere image from app/src/main/assets and place it into a VrPanoramaView. You can take a photosphere image through the standard Android camera application and place it into this directory. For this example, I will use an image named openspace.jpg.

Photosphere for displaying in a cardboard app

In the layout file for your Activity, add a VrPanoramaView that you will use in your app.

Next, open the MainActivity class. You will need to first obtain a reference to your VrPanoramaView in onCreate(Bundle), and then you can load your Bitmap into it via the loadPhotoSphere() helper method that we will define in a moment.

loadPhotoSphere() retrieves our image from the assets folder and loads it into the VrPanoramaView with a VrPanoramaView.Options object. It's worth noting that these images can be relatively large, so this operation would normally occur on a background thread, though this lesson will keep everything on the UI thread for simplicity.

Notice that for the VrPanoramaView.Options.inputType value, we're using TYPE_MONO. This means that the VrPanoramaView is expecting a single channel image to display, whereas a inputType of TYPE_STEREO_OVER_UNDER would expect an image that is split vertically with the right and left eye seeing the top and bottom halves of that image, respectively.

OverUnder photosphere image for a cardboard app

The final thing you will need to do is pause and resume rendering the VrPanoramaView in onPause() and onResume(), as well as properly disconnect it in onDestroy().

Now that we're done setting up the app, let's go ahead and run it. Your app should display your photosphere on the screen, and you should be able to move your phone around to view different portions of the image.

Our panoramic image in the view outside of a VR viewer

If you press on the cardboard icon in the lower right corner of the View, it will split the image into two slightly offset images that can be seen through a Cardboard or Daydream viewer.

Our panoramic image in the view inside of a VR viewer

Although not used in this tutorial, it's also worth noting that the VrPanoramaView can accept a VrPanoramaEventListener object that will notify your app when a new image has succeeded or failed to load.


Congratulations—you've created your first cardboard app, an image viewer for panoramic and photosphere pictures! Although this is a simplified example, it does give you the basics of how to create your own apps to use the Cardboard viewer. For an amazing example of an app that takes this concept a step further, I highly recommend Google's Expeditions education app. 

I hope you've enjoyed dipping your toes into the world of VR. In the next tutorial, I'll show you how to play 360-degree video files through the Cardboard SDK.

In the meantime, check out some of our other Android VR courses and tutorials, right here on Envato Tuts+.



Related Articles