AR technology for Android — Part 2: Wikitude SDK
Hello again, Android developers! As you may have seen in the previous part, this article is your guide in the route to the AR development. Are you ready to learn Wikitude? If the answer is yes, let’s get started!
As I mentioned in the first part of this article (Part 1 — AR Development Tools), Wikitude provides an array of features and extensions that allows developers to create customized AR experiences that perform at the highest level. Let’s see how we can work with this platform as Android developers. You’ll see, it is pretty easy!
Let’s “wikitude” together!
Wikitude provides very detailed documentation and, thanks to this, it is not that hard to integrate it into your own app. As documentation “says”, Wikitude provides two SDK solutions, a Native API and a JavaScript API. Both frameworks expose a Plugin API that can be used to extend the functionality of the SDK.
If you prefer to stay in the native world of your app, the Native API is the option you should go with. But, if you want to control the entire AR experience in JavaScript, you can use the JavaScript API which integrates a fully functional rendering engine with broad support for augmented reality content. If you are not decided about what SDK solution is the best for you, I suggest you analyze which API incorporates all your needed features. You can find the features list of both SDK solutions on the Wikitude documentation.
Wikitude SDK is a commercial solution, but it is also available as a trial version with some limitations like the Wikitude logo in camera view, etc. As a beginner, I suggest you use the free license because it incorporates the whole spectrum of augmented reality experience currently available.
Using the Kotlin programming language, let’s go through all the steps you need to follow to create your first Android AR app (WikitudeArDemo) with the JavaScript API provided by Wikitude SDK. For this demo project, I’ll use an implementation of the various ARchitect Worlds already created by Wikitude. If you are just interested in browsing through the code of the augmented reality experience you can also find the entire source code of the samples on GitHub. But, if you want to advance with Wikitude SDK development, you can create your own implementation of the architect world.
The process of creating an architect world implementation implies multiple steps and some Wikitude tools are required.
- First of all, you need to create a Wikitude Target Collection(.wtc) file. This .wtc file can be created from images using the Wikitude Studio. More details about creating steps can be found in TargetManagement section of the documentation.
- 3D content within Wikitude can only be loaded from Wikitude 3D Format files (.wt3). This is a compressed binary format for describing 3D content which is optimized for fast loading and handling of 3D content on a mobile device. You can still use 3D models from your favorite 3D modeling tools (Autodesk Maya or Blender) but you’ll need to convert them into the wt3 file format. The Wikitude 3D Encoder desktop application (Windows and Mac) encodes your 3D source file. You can download it from Wikitude website.
Let’s start creating a demo project, using an architect world model provided by Wikitude. Step-by-step we will create an Android app that will place a 3D car model on target and, tapping a button will rotate the 3D model on the screen.
Step 1. Open Android Studio IDE and create a project.
Step 2. Add the following permissions and features into AndroidManifest.xml file:
<uses-permission android:name="android.permission.INTERNET"/>
<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
<uses-permission android:name="android.permission.ACCESS_WIFI_STATE"/>
<uses-permission android:name="android.permission.ACCESS_GPS"/>
<uses-permission android:name="android.permission.CAMERA"/>
<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/><uses-feature
android:glEsVersion="0x00020000"
android:required="true" />
<uses-feature
android:name="android.hardware.camera"
android:required="true" />
<uses-feature
android:name="android.hardware.location"
android:required="true" />
<uses-feature
android:name="android.hardware.sensor.accelerometer"
android:required="true" />
<uses-feature
android:name="android.hardware.sensor.compass"
android:required="true" />
<uses-feature
android:name="android.hardware.sensor.gyroscope"
android:required="false" />
Step 3. Download the JavaScript SDK from Wikitude and unzip the archive.
Step 4. Copy the file Library/wikitudesdk.aar into the libs folder of your module. (<project-root>/<module-name>/libs). This file will allow you to build augmented reality worlds using HTML and JavaScript.
Step 5. Open build.gradle from your module, add the wikitudesdk.aar as a dependency and tell gradle to search the libs folder, like in the code below.
android {…}dependencies {implementation fileTree(dir: ‘libs’, include: [‘*.jar’])implementation (name: ‘wikitudesdk’, ext:’aar’)implementation ‘com.android.support:appcompat-v7:21.0.3’implementation ‘com.google.ar:core:1.1.0’}repositories {flatDir{dirs ‘libs’}}
Step 6. Download the following implementation of the ARchitect World from https://github.com/Wikitude/wikitude-sdk-samples/tree/master/07_3dModels_3_Interactivity and copy the content into assets/samples/Interactivity_Model. The implementation is structured as follows:
- index.html: the entry point for the experience
- js/*: includes the necessary JavaScript files
- CSS/*: CSS style sheets required
- assets/*: contains images, 3D models and tracker files
Step 7. Create SimpleArActivity.kt class and declare architectView and arExperience variables. The ArchitectureView is the core of the ARFunctionality. The ArchitectView has its own lifecycle which is very similar to the Activity lifecycle. To ensure that the ArchitectView is functioning properly you must call the following methods inside the corresponding activity lifecycle callbacks.
- onCreate(ArchitectStartupConfiguration)
- onPostCreate()
- onResume()
- onPause()
- onDestroy()
The arExperience variable will hold the path to the AR-Experience : Interactivity_Model/index.html
class SimpleArActivity : AppCompatActivity() {var architectView: ArchitectView? = nullprivate var arExperience = "Interactivity_Model/index.html"}
Step 8. Open activity_main.xml and add a button. When this button is tapped, the activity responsible for loading AR Experience opens.
Step 9. Inside MainActivity.kt add click listener on button added in step 8 and request camera permission using the easypermissions library.
companion object {const val CAMERA_REQUEST = 201}private fun onButtonClicked() {val perms = arrayOf(Manifest.permission.CAMERA)if (!EasyPermissions.hasPermissions(this, *perms)) {EasyPermissions.requestPermissions(this,getString(R.string.camera_permission_rationale),CAMERA_REQUEST,*perms)return}startSimpleArActivity()}@AfterPermissionGranted(CAMERA_REQUEST)private fun startSimpleArActivity() {startActivity(Intent(this, SimpleArActivity::class.java))}override fun onRequestPermissionsResult(requestCode: Int, permissions: Array<String>, grantResults: IntArray) {EasyPermissions.onRequestPermissionsResult(requestCode, permissions, grantResults, this)}
Step 10. Inside SimpleARActivity.kt override onCreate(savedInstanceState: Bundle?) method and:
- Create an architectureConfiguration object. The ArchitectStartupConfiguration is required to call architectView.onCreate(). It controls the startup of the ArchitectView that includes camera settings, required device features to run the ArchitectView and the LicenseKey which has to be set to enable an AR-Experience.
- Set the Wikitude license key. To get a license key visit http://www.wikitude.com/developer/licenses.
architectureConfiguration.licenseKey = getString(R.string.wikitude_license_key)
- Set camera position. The default camera is the first camera available for the system.
architectureConfiguration.cameraPosition = CameraSettings.CameraPosition.BACK
- Set camera resolution. Default resolution is 640x480.
architectureConfiguration.cameraResolution = CameraSettings.CameraResolution.HD_1280x720
- Set camera focus mode. Default focus mode is continuous focusing.
architectureConfiguration.cameraFocusMode = CameraSettings.CameraFocusMode.CONTINUOUS
- Enable/Disable camera 2. Camera2 API is disabled by default (old camera API is used).
architectureConfiguration.isCamera2Enabled = false // if you want to enable, set the property on true
- Instantiate the ArchitectView object with the above configurations.
architectView = ArchitectView(this)architectView?.onCreate(architectureConfiguration)
- Set the architectView as content to SimpeArActivity.
setContentView(architectView)
Step 11. Override onPostCreate() method and load the AR-Experience. It may be a relative path from assets, an absolute path (file://) or a server URL.
architectView?.load(SAMPLES_ROOT + arExperience), where SAMPLES_ROOT = “samples/"
Step 12. Lastly do not forget to override onResume(), onDestroy() and onPause() methods and call the ArchitectView lifecycle methods inside them. Be careful when destroying the architectView object. Before destroying it, all cached files of this instance must be removed. This guarantees that internal storage for this instance of the ArchitectView is cleaned and app-memory does not grow each session.
Step 13. Build your project and run it on your hardware connected device. Tap DISPLAY 3D MODEL ON TARGET and point the camera to the image below.
Note: You cannot run the Wikitude SDK project on Android Emulator due to OpenGL restrictions.
Congratulations! You’ve just implemented your first Android AR app using Wikitude SDK’s Javascript API. It’s not that hard, is it?
Full source code can be found on Github.
Thanks for reading! Your feedback is important to me. If you have any suggestions or questions about the article or about the code, do not hesitate to leave me a comment below.
Zipper Studios is a group of passionate engineers helping startups and well-established companies build their mobile products. Our clients are leaders in the fields of health and fitness, AI, and Machine Learning. We love to talk to likeminded people who want to innovate in the world of mobile so drop us a line here.