Marker Basics Android

From Kudan AR Engine
Jump to: navigation, search

This tutorial will take you through the basics of getting started with KudanAR, leading on from our previous tutorial which described how to integrate our framework into your Android project. If you have not already set up a project with an ARActivity, we suggest you check it out before going any further.

This tutorial utilises bundled assets so ensure that you have imported the correct assets into your project.

For this sample we have used:

  • Marker : spaceMarker.jpg
  • Image : eyebrow.png
  • Video : waves.mp4
  • Alpha video : kaboom.mp4
  • Model : bloodhound.jet
  • Model Texture : bloodhound.png

All of which can be downloaded here.

Note: For Android 6.0 and above you are going to ensure that you have requested the correct permissions otherwise your application will crash.

Setting Up an Image Trackable

To create an Image Trackable, you are first going to need an image to track. We do not put any restrictions as to what image format you use as long as it is supported natively. For information about what creates a good marker please read our page on What makes a good marker?

If your augmentation appears to twitch or shake, it is likely that the marker being used is poor.

// Initialise image trackable
ARImageTrackable trackable = new ARImageTrackable("Space");
// Get instance of image tracker manager
ARImageTracker trackableManager = ARImageTracker.getInstance();
// Add image trackable to image tracker manager

Adding content to an Image Trackable

To add content to an Image Trackable you need to transform the content you have in the corresponding ARNode and add that to the trackable’s world (the 3D space surrounding the marker). Kudan has 4 different ARNodes for this purpose:

  • ARImageNode
  • ARVideoNode
  • ARAlphaVideoNode
  • ARModelNode

Image Nodes

Images are displayed using the ARImageNode class. These are initialised with an image. This image can use any format that is supported by the device’s operating system. On Android, supported formats include:

  • .jpg
  • .gif
  • .png
  • .bmp
  • .webp
// Initialise image node
ARImageNode imageNode = new ARImageNode("eyebrow.png");
// Add image node to image trackable

Video Nodes

Videos are displayed using ARVideoNode class. Video nodes are initialised using a video file. The video file can be any format supported by the native device. On Android, supported formats include:

  • H.263 - .3gp, .mp4
  • H.264 AVC - .3gp, .mp4, .ts
  • H.265 HEVC - .mp4
  • MPEG-4 SP - .3gp
  • VP8 - .webm, .mkv
  • VP9 - .webm, .mkv
// Initialise video texture
ARVideoTexture videoTexture = new ARVideoTexture();
// Initialise video node with video texture
ARVideoNode videoNode = new ARVideoNode(videoTexture);
// Add video node to image trackable

Alpha Video Nodes

Alpha videos are videos with a transparency channel and can be created through our Toolkit using a set of transparent PNGs. Alpha videos are displayed using the ARAlphaVideo class. They are initialised in the same way as a video node.

// Initialise video texture
ARVideoTexture videoTexture = new ARVideoTexture();
// Initialise alpha video node with video texture
ARAlphaVideoNode alphaVideoNode = new ARAlphaVideoNode(videoTexture);
// Add alpha video node to image trackable

Model Nodes

Models are displayed using the ARModelNode class. The model is imported using the ARModelImporter class. A texture material can be applied to the model’s individual mesh nodes. This can be either a colour material, texture material or a light material.

For more information on using 3D models with Kudan please check out our Wiki page on 3D Models.

Note: If you do not add lighting to your ARLightMaterial your material will show up as black.

// Import model
ARModelImporter modelImporter = new ARModelImporter();
ARModelNode modelNode = (ARModelNode)modelImporter.getNode();
// Load model texture
ARTexture2D texture2D = new ARTexture2D();
// Apply model texture file to model texture material and add ambient lighting
ARLightMaterial material = new ARLightMaterial();
material.setAmbient(0.8f, 0.8f, 0.8f);
// Apply texture material to models mesh nodes
for(ARMeshNode meshNode : modelImporter.getMeshNodes())
// Add model node to image trackable


If the image/video/model you wish to add to the marker isn’t the same size as the marker, you may wish to scale your ARNode. Providing your video/image is the same aspect ratio as your trackable you can divide one width/height from the other to get the correct scale. This value can then be used to scale your nodes. You can scale with a uniform value, or by scaling the X, Y and Z axes separately. This tutorial will use the uniform method.

// Find the scale ratio
ARTextureMaterial textureMaterial = (ARTextureMaterial)node.getMaterial();
float scale = trackable.getWidth() / textureMaterial.getTexture().getWidth();
// Apply it to your ARNode

Content visibility

Each node has a boolean value which can be set to determine whether or not the node is displayed. This is useful when you have multiple nodes attached to a marker and you do not wish to display them all at once. This can be set using:

// Hide ARNode