Layar Developer Documentation

Back to

2D and 3D objects

Feature Introduction

2d and 3d objects are well supported in Layar. The introduction of 2d and 3d objects will make your layer more appealing to users. In general, there are two types of layer, the characteristics of each type can be summarized in the table below.

layer typePOI representativeJSON Response
Generic (2D)custom POI widget (CIW) sets that can be defined under "Look and feel" tab of layer editing section on the publishing site. Object and Transform are not needed in the JSON response.
3D and 2D objects in 3D spacePOIs are represented by 2d images or 3d objects. Object is mandatory in the JSON response.

Some developers have asked about the differences between using custom CIWs and 2d images in 3D space, the table below provides some comparisons:

POI representativeDefinitionUsage
Custom IWsEach IW set contains four icons which are used to represent POIs in focus, inner circle,  middle circle and outer circle status, respectively. Each icon has a fixed size. When POIs can be divided into different groups and each group needs the same icon set. The icon set is not directly related to the POI content.
2D imageMore manipulations can be done, such as image size, rotation, angle, reduced image, translation, etc.   When POI representative is used to reflect the POI content, such as billboard, photograph, etc. 

Key Steps to Implement

GetPOIs Response

An "object" object can be used to include a 2d or 3d object. A "transform" object can be used to adjust the size, position and angle of the object if needed. The detailed description can be found here.

Example Response

2d images

 "object": { 
  "contentType": "image/vnd.layar.generic",
  "url": "http:\/\/\/2dimage_full.png",
  "reducedURL": "http:\/\/\/2dimage_reduced.png",
   "size": 120 },
 "transform": {
  "rotate": {
    "axis": { "x": 1},
    "angle": - 50},
  "translate": { "z": -0.075 },
  "scale": 10 }

3d models

 "object": { 
  "contentType": "model/vnd.layar.l3d",
  "url": "http:\/\/\/3dModel_full.l3d",
  "reducedURL": "http:\/\/\/3dModel_reduced.l3d",
   "size": 120 },
 "transform": {
  "rotate": {
    "axis": { "z": 1},
    "angle": 50},
  "translate": { "y": -0.075 },
  "scale": 0.01 }

Tutorials and Sample Code

A tutorial is created to explain how to represent a POI using 1d icons, 2d images and 3d objects.


In order to place 2d images and 3d objects at the right position, you probably need to play with parameters in the "transform" a lot. Depending on whether a POI is geo-location based or Vision based, the layar client uses different rules to render it. Here we will further explain how a POI is rendered in camera/map/list view in the latest version of the Layar client. These rules should be applied to all the supported platforms. 

Prerequisite: a layer with both Geo POIs and Vision enabled POIs.

Vision POIs

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.

On Layar Client, when a target object is recognized, Layar clients will always try to download objects defined in "object.url". If the downloading fails (invalid url or large file size), the client will return an error message. The "icon" object will be ignored while rendering Vision POIs.

Geo-location POIs

NOTE:  The unique POI icons supplied in the "icon" object of the GetPOI Response are not to be used on Map View.  Because the Map renders a large amount of POIs, the calls could take too long and provide a poor user experience given the amount of different icons that could be provided.  Instead, the system will default to the CIW or the default POIs (the circles) as indicated in the rules above.

Best Practices 

How to include more 3D models while having good user experience ?