Advertisement
  1. Code
  2. Android SDK
Code

How to Use Free 3D Models From Google Poly in Android Apps

by
Difficulty:IntermediateLength:MediumLanguages:

There is a huge demand these days for Android apps that offer immersive virtual reality or augmented reality experiences. As a developer, there are many different frameworks you can use to create such apps. 

But, unless you are also a skilled 3D artist, how are you going to create the 3D objects you would be displaying in those apps? Are you ready to spend months learning how to work with 3D modeling programs such as Blender or Maya? If you are not, you should consider using Google Poly, an online repository containing thousands of 3D assets that come with Creative Commons licenses.

Most of the assets you can find on Poly today are low poly with simple materials. This is because the average mobile GPU is yet to become powerful enough to display 3D objects with high polygon counts in real time.

In this tutorial, I'll introduce you to the Poly API. I'll also show you how to use Processing for Android to render the 3D assets you download.

Prerequisites

To make the most of this tutorial, you'll need:

1. Acquiring an API Key

All the HTTP requests you make to the Poly API must be accompanied by an API key that belongs to you. To acquire the key, start by logging in to the Google Cloud console and navigating to the APIs dashboard.

APIs dashboard on Cloud console

Next, press the Enable APIs and services button, expand the Other category, and select Poly API.

Other APIs section

You can now press the Enable button to enable the Poly API.

Poly API screen

Once the API is enabled, a set of API keys are generated for it automatically. You can open the Credentials tab to take a look at them.

Credentials page

For this tutorial, you'll be needing only the Android key. Make a note of it so you can use it later.

2. Project Setup

Because Poly currently doesn't have an official toolkit for the Android platform, you'll have to work with the Poly API directly using its REST interface. By using the Fuel networking library, which is optimized for the Kotlin language, you can save a lot of time and effort. So add the following implementation dependency in the app module's build.gradle file:

To be able to display the 3D assets you download from the Poly repository, you'll also need a rendering engine. Processing for Android comes with one, so add it as another dependency.

Lastly, don't forget to request the INTERNET permission in the manifest file of your project.

3. Listing Assets

To be able to download a Poly asset, you must know its unique ID. By using a browser, one that supports WebGL, you can easily determine the ID of any asset. It's right in the address bar.

Poly asset ID shown in the address bar

However, if you want to allow your users to dynamically, at run time, decide which assets they want to use, you can use the assets.list REST method to determine the IDs of those assets. The method allows you to look for assets using a variety of parameters, such as keywords, categories, and 3D file formats.

For the sake of a realistic example, let's now try to find the IDs of a few assets that belong to the animals category. You are, of course, free to choose any other valid category, such as architecture, food, or people.

Before you compose your HTTP request, it's a good idea to declare your API key and the base URL of the Poly API as constants inside your activity.

Using the base URL, you can build the URL of the assets.list REST method as shown below:

At this point, you can create a valid HTTP GET request by calling the httpGet() method and passing your API key and the desired category as query parameters to it. Optionally, you can use the format query parameter to specify the desired format of the assets. Poly supports OBJ, FBX, TILT, and several other popular 3D formats.

Because the method runs asynchronously and its result is a JSON document, you must attach an event handler to it by using the responseJSON() method. The following code shows you how:

Inside the event handler, if your request was successful, you'll have access to a list of Asset objects. The name field of each such object specifies its ID.

Additionally, each object will have fields such as displayName, license, and authorName, which you might find useful. For now, let's simply print the name and displayName of all the objects. The following code shows you how:

If you run your app now, you should be able to see the following output in the Logcat window of Android Studio.

Logcat window showing asset names and IDs

4. Downloading Assets

Once you have the unique ID of an asset, you can directly append it to the base URL of the Poly API to create an asset URL.

When you make an HTTP GET request to the asset URL using the httpGet() method again, you'll get a JSON document containing just one Asset object.

As you may have noticed in the above code, this request too must have a query parameter mentioning your API key.

You've already learned how to use some of the fields present in the Asset object in the previous step. Now, all you need to do is use the formats array present in the object to determine the URLs and names of the files associated with the asset. Each item in the array will have three important fields: 

  • formatType, which lets you determine the type of the asset
  • root, which contains the name and URL of the primary file associated with the asset
  • resources, which contains details about all the secondary files associated with the asset, such as materials and textures

If you're working with the OBJ format, the primary file will be a .obj file containing vertices and faces data, and the secondary files will usually be .mtl files containing data about the materials used. The following code shows you how to determine the URLs of both the primary and secondary files:

In the above code, in addition to the URL of the .mtl file, we're also determining its name using the relativePath field. Doing so is important because the name is hard coded into the mtllib element of the .obj file and should not be changed.

Once you have the URLs of both the files, you can use the httpDownload() method of the Fuel library to download them. Here's how you can download them to your app's private storage directory, whose absolute path can be determined using the filesDir property:

5. Displaying Assets

You'll need a 3D canvas to draw the Poly asset you downloaded. To create one, you must extend the PApplet class offered by the Processing for Android library. However, a canvas created this way will, by default, support only 2D shapes. To configure it to draw 3D shapes as well, override the settings() method and pass P3D as an argument to the fullScreen() method, which also makes the canvas as large as the user's screen.

Next, create a new property inside the class to represent the Poly asset as a PShape object.

To initialize the property, override the setup() method and call the loadShape() method, passing the absolute path of the .obj file you downloaded as an argument to it.

You can now start drawing on the canvas by overriding the draw() method. Inside the method, the first thing you need to do is call the background() method to ensure that you are always drawing on a blank canvas.

When drawn directly, most Poly assets look very small and inverted. You can fix this either by using a custom camera or by using canvas transformations. To keep this tutorial simple and intuitive, let's use canvas transformations.

To increase the size of the asset, use the scale() method and pass a large negative value to it. The value must be negative to make sure that the asset is flipped vertically. Optionally, you can use the translate() method to adjust its position along the X and Y axes. The following code shows you how:

You can now go ahead and draw the asset by calling the shape() method.

The canvas is currently not a part of your activity's view hierarchy. Therefore, if you try running your app now, you won't be able to see the asset. To fix this, first add a new FrameLayout widget to the activity's layout XML file.

Then, create a new PFragment instance using the canvas and point it to the FrameLayout widget.

At this point, you can run the app again to see the asset.

App showing Poly asset

Conclusion

You now know how to use the Poly API to search for and download 3D assets. In this tutorial, you also learned how to render and manipulate those assets using Processing for Android.

It's worth noting that many of the assets available on Poly were created using Google Blocks, an application available for users of HTC Vive and Oculus Rift. If you own those VR headsets, do consider creating and submitting your own models.

To learn more about the Poly API, you can refer to the official documentation.

Advertisement
Advertisement
Looking for something to help kick start your next project?
Envato Market has a range of items for sale to help get you started.