Wikitude Documentation - Expert Edition

# Cylinder Tracking

# Introduction

Cylinder Recognition and Tracking extend the capabilities of the Wikitude SDK to recognize cylinder objects. The feature is based on the Image Tracking module, but instead of recognizing plane images, it is able to recognize cylinder objects like cans through its images.

# Using Cylinder Tracking

To create a Cylinder Tracking example, you will need to follow the Image Tracking section as it uses the WikitudeSDK and the ImageTracker scripts in the same way, with the difference that the targets that are in the .zip file are cylinders.

# ImageTracker as CylinderTracker

To add an image tracker to the scene, simply create a new GameObject and add the ImageTracker script to it.

To recognize cylinder targets, the ImageTracker itself needs a zip file that contains information needed to detect those reference images. Zip files can be generated manually or inside Unity, with the Target Collection Editor.

# Manual Zip File Generation

To generate a zip file manually, 2 things are required. First, a .metadata file that contains the information of the targets and second, the image to recognize.

The .metadata file should look like:

{
    "version": "1.0",
    "targets": [
    {
        "type": "Cylinder",
        "path": "stones.jpg",
        "name": "stones",
        "height": 120,
        "circumference": {
            "base": 1,
            "top": 1
        }
    },
    {
        "type": "Cylinder",
        "path": "corn_can.jpg",
        "name": "corn_can",
        "height": 75,
        "circumference": {
            "base": 1,
            "top": 1
        }
    },
    {
        ...
    }
    ]
}

As you can see, it is a json file that contains as many targets in an array as you want.

  • The type value can be Image in case you want image tracking or Cylinder in case you want cylinder tracking.
  • The name value is the name of the target to recognize.
  • The path value is the path inside the zip to the image.
  • The height value is the height of the target in millimeter.
  • The circumference value is the circumference of the cylinder, it's always relative to the width of the target, so in case the circumference is set to 2 it will create a cylinder with a circumference of 2 times the target width.
  • The base value is the circumference of the base of the cylinder.
  • The top value is the circumference of the top of the cylinder.
  • The custom value is for additional custom data and is free for you to define and use.

WARNING

The top value is not yet supported, which would define a truncated or inverted truncated cone. For now, the base value is used to set the diameter of the cylinder.

In the end the .zip file should look like:

The generated file should be placed into the StreamingAssets folder, so that the Wikitude SDK can load them at runtime. Once the .zip file is created, please take a look at the Image Tracking section steps, as every one of them are exactly the same, except for the type of target that is being tracked.

# Defining the size of the cylinder

An important part of the metadata file to be used for cylinders is the value circumference. With this it is possible to define the size of the cylinder on which the image (label) is placed. In the simplest case, the label is entirely wrapped around the entire cylinder - in this case the value for circumference should be 1. A value lower than 1 is not really practical, as it would indicate that the cylinder is smaller than the label.

In case the label only is placed on part of the cylinder (e.g. a wine label) the value of the circumference needs to express that. For example, when the label is only covering half of the cylinder, the value circumference needs to set to 2.

# Front and back of a cylinder

The image can also contain empty gaps between labels that are on different parts of the cylinder (e.g. front and back label of a wine bottle). Those gaps can either be filled with a solid color in case the cylinder is made of a solid material or being left transparent in case the cylinder is of transparent material.

← Object Tracking →