iOS Marker Basics

This tutorial goes over the basics of creating a marker and setting up the image tracker.

This tutorial uses assets for the marker and image node. You can download these assets here.

In this asset bundle you should find:

  • Kudan Lego Marker – This is our marker image that will be detected by the tracker.
  • Kudan Cow – This is the image that will appear when the marker has been detected.

Once you have downloaded the file, unzip it and add the assets to your Xcode project.

Set up the Image Trackable

To create an Image Trackable, you are first going to need an image to track. A marker can be any image natively supported by iOS. Commonly used formats are .jpg and .png.

Bad Markers

If your content appears to twitch or shake, or does not appear at all, a common cause is that the marker being used is bad for tracking. For more information, please read our page on What Makes a Good Marker?

To setup your image trackable, first create an ARImageTrackable object and initialise it with a UIImage. Then, initialise the ARImageTrackerManager and add the trackable to it. The code to do this looks like the following:

ViewController.mViewController.swift
- (void)setupContent
{
  // Initialise the image trackable.
  ARImageTrackable *imageTrackable = [[ARImageTrackable alloc] initWithImage:[UIImage imageNamed:@"Kudan Lego Marker.jpg"] name:@"Lego Marker"];

  // Get the single instance of the image tracker manager.
  ARImageTrackerManager *imageTrackerManager = [ARImageTrackerManager getInstance];
  [imageTrackerManager initialise];

  // Add the image trackable to the image tracker manager.
  [imageTrackerManager addTrackable:imageTrackable];
}
override func setupContent() 
{
	// Initialise the image trackable.
	let imageTrackable = ARImageTrackable(image: UIImage(named:"Kudan Lego 	Marker.jpg"), name:"Lego Marker")
        
	// Get the single instance of the image tracker manager.
	let imageTrackerManager = ARImageTrackerManager.getInstance()
	imageTrackerManager?.initialise()
    
	// Add the image trackable to the image tracker manager.
	imageTrackerManager?.addTrackable(imageTrackable)
}

Add an ARImageNode to the trackable

If you run the app as it is now, the marker will detect and track, but how will we know? We need some feedback, and the easiest way to do that is to add a node to the trackable.

There are various types of node, each of which is designed to work with a specific type of content. For this tutorial, we will be using an ARImageNode, which is tailored towards displaying 2D images.

Add content on the background thread

When adding any AR content to your application, you should consider adding it on the background thread. This will help prevent the camera feed from stalling.

Types of ARNode

For more information on the different types of ARNode, please refer to our API Reference or our Nodes page.

To set up an ARImageNode and add it to our image trackable, add the following code to the end of the setupContent method:

ViewController.mViewController.swift
// Initialise the image node with our image.
// We don't include the file extension for this image because it's a PNG.
ARImageNode *imageNode = [[ARImageNode alloc] initWithBundledFile:@"Kudan Cow"];
 
// Add the image node to our image trackable.
[imageTrackable.world addChild:imageNode];
// Initialise the image node with our image.
// We don't include the file extension for this image because it's a PNG.
let imageNode = ARImageNode(image: UIImage(named: "Kudan Cow"))
        
// Add the image node to our image trackable.
imageTrackable?.world.addChild(imageNode)
Now, if you build and run the app again, the Kudan Cow will appear on the Lego Marker when the marker gets detected by the tracker. It looks good, but it’s a little on the small side.

 

Scale the Image Node

Sometimes, if your content isn’t the same size as your marker, you may wish to scale your node. Provided your content is the same aspect ratio as your trackable, you can divide one width from the other to get the correct scale. This value can then be used to scale your nodes.In this case, we will be scaling our image so that it has the same width as our marker. To do this, add the following code to the end of the setupContent method:

ViewController.mViewController.swift
// Find the scale ratio.
float scaleRatio = (float)imageTrackable.width / imageNode.texture.width;

// Apply it to your ARNode.
[imageNode scaleByUniform:scaleRatio];
// Find the scale ratio.
let scaleRatio = Float(imageTrackable!.width)/Float(imageNode!.texture.width)
        
// Apply it to your ARNode.
imageNode?.scale(byUniform: scaleRatio)

This will scale all three of the image node’s axes by the same value. It’s also possible to scale each axis independently, but you’ll rarely have to do this.

Run the app again, and you should see that the Kudan Cow has increased a bit in size to better fit the marker. This will also work with other types of content, including videos and 3D models.


What’s Next

Go through the basics of setting up Kudan’s ArbiTrack feature for markerless tracking.

ArbiTrack Basics