Markers

Useful information regarding markers and Kudan’s image tracking.

Features

  • No limit on the number of markers it can load, capable of handling hundreds.
  • An API for creating images programatically using image files.
  • An API for combining/manipulating sets of markers, leading to differential updates.
  • Offline tools for processing markers to use with the framework.
  • Extended Detection and Tracking capabilities for tracking markers at long distances.
  • Auto-cropping functionality for improved tracking performance.

Upcoming features

  • Command line tools for converting markers outside the Toolkit that can be scripted to process in batch. (Please contact us to get Kudan AR Toolkit CLI.)

Markers

Markers are images that have been loaded into the image tracker. While any marker can be used in theory, there are good and bad markers. If a marker is too poor to detect or track reliably, the tracker will not load it.

A good marker has the following properties:

  • Lots of high contrast corners.
  • A non-repeating pattern.
  • Fairly large in the camera view from its typical viewing position.
  • When combined with other markers in the same trackable set, markers should be fairly unique compared to the others.

For more information, please read more about What Makes a Good Marker?

Creating a marker

To use your own custom markers, there are two approaches:

  1. Create a marker using the API

KudanAR provides an API for creating markers from image files. This way, you can add images to your device and load them as markers at runtime. Kudan’s image tracker will support any format that is also supported by the native OS.

To create a marker from an image file, we use the ARImageTrackable class.

Objective-CSwiftJava
ARImageTrackable *imageTrackable = [[ARImageTrackable alloc] initWithImage:[UIImage imageNamed:@"example.jpg"] name:@"Example Marker"];

let imageTrackable = ARImageTrackable(image: UIImage(named: "example.jpg"), name: "Example Marker")

ARImageTrackable imageTrackable = new ARImageTrackable("Example Marker");
imageTrackable.loadFromAsset("example.jpg");
  1. Create a marker using the Toolkit

KudanAR also provides an external tool for converting image files and batching them together into a single KARMarker file. This lightweight format is optimised for smart devices and reduces file size as well as providing a way to store multiple markers.

We can use the same ARImageTrackable class to load .KARMarker files, and we have two options. We can either bundle them with the app and load them when we need them:

Objective-CSwiftJava
ARImageTrackable *imageTrackable = [[ARImageTrackable alloc] initWithBundledFile:@"example.KARMarker"];

let imageTrackable = ARImageTrackable(bundledFile: "example.KARMarker")

ARImageTrackable imageTrackable = new ARImageTrackable("Example Marker");
imageTrackable.loadFromAsset("example.KARMarker");

But for apps with a lot of markers, this isn’t an ideal solution, because bundling 500 markers or so into an app will massively bloat its size. Fortunately, we have a separate method for loading files from a file path. This is especially useful because the file can be stored anywhere on your device, including the camera roll, or even downloaded at runtime, and still be used as a marker:

Objective-CSwiftJava
NSString *filePath = [[[NSBundle mainBundle] resourcePath] stringByAppendingString:@"example.KARMarker"];
ARImageTrackable *imageTrackable = [[ARImageTrackable alloc] initWithPath:filePath];

var filePath: String = Bundle.main.resourcePath? + ("example.KARMarker")
let imageTrackable = ARImageTrackable(path: filePath)

ARImageTrackable imageTrackable = new ARImageTrackable("Example Marker");
imageTrackable.loadFromPath("/mnt/sdcard/images/example.KARMarker");

Marker names

Markers within the same trackable set, or registered with the same tracker if marker sets have been combined, require a unique name. This name can be set via the marker creator tools or via the API, and can be used to locate the marker easily.

Objective-CSwiftJava
imageTrackable.name = @"Example Marker";

imageTrackable.name = "Example Marker"

imageTrackable.setName("Example Marker");

Marker dimensions

Markers have an arbitrary size property. This is used to define the scene units for rendering and can be set via the marker tools or the API. If a marker is 20×10 then a 3D model with width 20 and height 10 will fit the marker perfectly. It can sometimes be useful to assign real-world units to the marker, for example, the dimensions of the marker in millimeters.

While the dimensions are arbitrary, the aspect ratio of the dimensions should match the aspect ratio of the source image, otherwise the behaviour will be undefined.