documentation

Poster Tracker Tutorial
Level: Basic
PosterTrackerTutorial_banner.jpg

The following example project demonstrates the general usage of the plugin by setting up poster-based tracking.

Preparations

A webcam is mandatory. Connect one if not done already and be aware that a restart of your computer might be required before it is working.

Example Project Setup

Create a new project

First start Unity. In the launcher window, click on NEW on the upper right, name your project and select the location in your file system. Please remember the latter one, as you will need it later. After assuring that you are about to create a 3D project on the bottom left, click Create project on the bottom right.

posterTrackerTutorial-step1.png

Import the package

Click on Assets in Unity's top menu bar, followed by Import Package and Custom Package.... In the pop-up window, look for a file named vlUnitySDK.unitypackage and open it.

posterTrackerTutorial-step2.png

Delete Main Camera and instantiate VLCamera

Right click on Main Camera in the Hierarchy panel on the left and select Delete. Then drag and drop the VLCamera prefab from the VisionLib/Utilities/Prefabs/Camera directory into the Hierarchy panel on the left.

posterTrackerTutorial-step3.png

Create a Tracking Configuration

Go to your project's directory you chose in the first step (e.g. via macOS Finder or Windows Explorer) and navigate to StreamingAssets/VisionLib/Examples/PosterTracking. Create a new text file and name it TutorialPosterTracker.vl for this example. Make sure your operating system is set to display file endings, so you can correctly rename the whole identifier instead of only the part before the ending. Open your file in a text editor and insert the following content before saving and closing. This is used to describe a poster tracker. Note that you need the referenced image file containing the image on the poster to track (TutorialPoster.png in this example). For more information on the format please refer to the documentation. After that, copy your image to the StreamingAssets/VisionLib/Examples/PosterTracking folder of your project.

{
    "type": "VisionLibTrackerConfig",
    "version": 1,
    "meta": {
        "name": "TutorialPosterTracker",
        "description": "Tracker for a reference image",
        "author": "VisionLib"
    },
    "tracker": {
        "type": "posterTracker",
        "version": 1,
        "parameters": {
            "imageURI": "project-dir:TutorialPoster.png",
            "metric":"mm",
            "realWidth": 269.0, // Width of the reference image image in mm (default metric is mm)
            "transform":{
                "t": [0.0, 0.0, 0.0],
                //"r": [1.5707963, 0.0, 0.0] //  Rotation of 90 deg around x --> ground-plane in XZ
                "r": [0.0, 0.0, 0.0]
            },
            "maxFramesFeaturePrediction": 20,
            "extendibleTracking": false,
            "debugLevel": 1
        }
    }
}
posterTrackerTutorial-step4.jpg

Reference your Configuration File in the Scene

Create a new GameObject, name it VLTracking and add the component VLTrackingConfiguration to it. Drag the tracking configuration file that you created above from the project view into the according inspector field of the component. Also reference your license file here. Afterwards, check the Auto Start Tracking option of the component to start the tracking automatically.

Populate your Scene

Next, drag any object into your scene. For example, to place a simple cube right click on an empty space in the hierarchy panel on the left and select 3D Object and then Cube. Adjust the object's scaling so it's not too small. The scene will be rendered where the tracked real-world object is located in the stream, so it is wise to place your objects close to and above the origin (0|0|0) of the coordinate system in order to be able to see your scene.

posterTrackerTutorial-step7.png

Execute your setup

Run your project by clicking on the play button which you can find above the scene panel in the center. Print the poster and put it on the table or display it on a monitor. Point the camera on it. As soon as VisionLib has detected the poster you should see the cube augmented on it in Unity. Try different positions and angles if VisionLib doesn't recognize the poster immediately.

posterTrackerTutorial-step8.png