Layar Developer Documentation

Back to layar.com

Enable Layar Vision in a layer

Feature Introduction

Using Layar Vision, layer developers can attach virtual augments to a target object in the physical world. If you are new to the concept, please check here for some general introduction.

A virtual augment is a digital model (2D or 3D) rendered on a target object as seen through the mobile phone camera lens.

A target object is a physical or digital visual entity that contains enough detail to be unique whereby a person can point their phone at said “object” to see the augment (if available). 

The connection between the virtual augment and target object is done via uploading a reference image of the target object to the layer publishing site. This reference image is called a page. A Page is the file uploaded by a developer for analysis so that the object depicted in the file can become a target object; thereby, enabling target tracking of said object. Layar will extract the details of each image to create the unique fingerprint of the object.  We will store this as specified in our updated Terms and Conditions. We will keep the page in our database as they might be needed for future improvements of our algorithm. Please check Reference Image Best Practices on how to create good Pages.

With Layar Vision, many nice use cases are possible now, for instance, you can put virtual buttons on magazines and these buttons can directly link magazine users to online shops. To see it in action, you can check out this showcase video. We also created a few other demo layers to give you more inspirations. You can find them at the Notes section below.

Key Steps to Implement

Configurations on the publishing site

To enable Layar Vision, the following changes need to be made on the layar publishing site.

1. Enable "Layar Vision"

There are two ways to enable Layar Vision. When a layer is created, on "create a new layer" page, an option to enable "Layar Vision" is added. This option can be edited later under the "General" tab of the "layer editing" page.

NOTE: If "Layar Vision" is enabled, this will also change the Layer type to 3D and 2D objects in 3D spaces and the Minimum API version to version 6.0 automatically after the settings are saved.

NOTE: Mixed geo and vision layers are deprecated. In future client versions, Vision enabled layers cannot contain any geo-based objects.

2. Upload and maintain Pages

Once "Layar Vision" is enabled (and settings are saved), a new tab called "Pages" is shown. Developers can add and manage Pages here.

upload pages

For the uploaded page, the following information needs to be provided:

FieldsDescriptionRequirement (Best Practices)
ImageThe image itself that is uploaded from your computerImage resolution must be at least 640 x 480 pixels, though larger images are accepted and encouraged. Supported file types include .JPG, .PNG, and .GIF. File size may not exceed 10MB.
Image keyThe key that is used to identify a reference image. It is the value of "referenceImage" defined in "anchor" object of a POI in getPOI response.The image key is a quick way to identify your images. It has to be unique for a layer. We recommend using a personalized, easily remembered key.
NOTE: After you create an Image Key, the image will be processed by our server and you will not be able to edit it. To change the image or its key, you must delete the original and upload a replacement.
Real World HeightHow high is your image in the real world in meters?Fill in the real height of the target object that you want to augment. This determines how the unit length of the coordinate system is scaled with respect to the target object. So it will determine the size of the augment with respect to the target object and the lengths when "transform" or "animation" are applied to the augment.

Once a page is uploaded, the legend below is used to show ratings assigned by Layar server based on the quality and clarity of images and their ability to be used for Layar Vision.

created vision layer

GetPOIs Response

Once Pages are uploaded successfully, you can attach a 2D or 3D object to a reference image in the GetPOIs response. This can be done in the "anchor" object for each POI defined in "hotspots" object.

anchor object_Vision POI
KeyTypeExampleExplanation
anchorjson dictionary
"anchor": { "referenceImage": "myreferenceimage" }
The key of a reference image for feature tracking should be returned. In the example, it is "myreferenceimage".

The detailed description of "hotspots" object in GetPOIs Response can be found here .

General Interaction Flow

The key components to enable Layar Vision are:

If we have a layer which has Layar Vision enabled and a page is uploaded to the layer definition on the publishing site, the interaction among Layar server, Third-party developer POI server and Layar client can be demonstrated using the diagram below:

Example Response

{
    "hotspots": [
        {
            "id": "test_1",
            "anchor": {
                "referenceImage": "my_reference_image"
            }
        }
    ],
    "layer": "snowy4",
    "errorString": "ok",
    "errorCode": 0
}

Tutorials & Sample Code

A tutorial is create to explain how to write a Vision enabled layer. Sample Code written in php is available for downloading at the end of the tutorial.

Notes

Here you can find some demo layers which show case the new possibilities in Layar Vision.

1. Cantine Layer

Our first demo layer for Layar Vision. Just search for "cantine" on the iPhone /Android market version (v6.0 or above). You can also watch it below:

We also created a tutorial which further explains how to create the demo Cantine layer. The complete JSON response of this layer together with the Pages are provided in the Cantine_layer.zip file in the attachment. This zip folder contains:

2. Kitten Edition Layer

Kitten Edition shows the functionality of Layar Vision through the Internet-renowned image of an adorable kitten who happens to be dressed as Link from The Legend of Zelda.

The tutorial focuses on how to create the laser eyes effect !! The complete JSON response of this layer together with the reference images and 3d models are provided here in the attachment.

Clue menu in Vision enabled layer

For Vision enabled Layer, by default, a new clue button is added to the camera view to indicate that the user can view the images of the target objects. Once the user selects the button, a "clue" menu is displayed containing the thumbnails of the reference images that are loaded for tracking.  Users can use these thumbnails to find target objects.

Please NOTE that:  

Rendering Vision enabled POIs in the Camera view

Vision enabled 2d and 3d objects are placed in the coordinate system of the target object. It also obeys the right hand thumb rule. Please see the image below:

The origins of Objects are placed around the origin (center point) of the target object. Positioning is solely affected by changing the translate transform values and the translation is relevant to the coordinate system of the target object.

Rotate and scale transformations are all applied to the local origin of the object. For 2D augments, this is the center point. For 3D augments, it is the origin as saved by your 3D modelling tool.

upload pages

Attachments