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.

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

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:\/\/custom.layar.nl\/2dimage_full.png",
  "reducedURL": "http:\/\/custom.layar.nl\/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:\/\/custom.layar.nl\/3dModel_full.l3d",
  "reducedURL": "http:\/\/custom.layar.nl\/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.

Notes

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

• General behavior:

• Camera view
  • Before a target object is recognized, in the status bar, the number of returned POIs in getPOIs response is shown. However, Vision enabled POIs will not show up on the radar but only the Geo POIs (if there is any).
  • When the Layar client recognizes a target object, a loading indicator for each augment is in the place where the augment will be before the actual augment is rendered. At the same time, any Geo POIs will be removed from in the camera view but Geo POIs will still be displayed on the radar.
  • The Geo POIs will come back when the camera moves away from the target object and the target object can not be recognized anymore.
• List view
  • All POIs returned from the getPOIs response are listed here, including both Vision enabled POIs and Geo POIs.
  • For Vision enabled POIs,  the distance value will be 0m since it is not known to the client according to the API v6 definition.
• Map view
  • Vision enabled POIs are not displayed at all since the geolocation of the POI is not known to the client.
  • Geo POIs will be placed on the map view as before. For more information on how they are displayed, please see below.

• Rendering Vision 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.

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

• Displaying Geo POIs on the Map view
  • Affected Layar clients/versions:   IPhone Layar client v4.0 and above; Android Layar client v4.0.3 and above.
  • Background Information: Custom icon widget, known as CIW, can be created to represent the POI appearance in the camera view. Each set of CIW icons is related to a POI type value, from which the client determines which CIW to use if CIWs are defined. 0 = default CIW. 1-3 = use the custom CIW icons specified under Look & feel tab of the layer editing page. Since API v3.0, you can define more than 3 sets of custom CIW icons.
  • Layar Client Behavior:
    • When a set of CIW icons are defined for a POI (This POI has a type value which does not equal to 0),
      • When a custom CIW focus is present, this is displayed as the focus POI.
      • When a custom CIW inner is present, this is displayed as non-focus POI.
      
    • When a set of CIW icons are not defined for a POI (This POI has a type value which equals to 0),
      • When a custom CIW focus is not present for this POI, the system uses the BiwBgColor for the default icon (the circle).
      • When a custom CIW inner is not present for this POI, the system uses the innerColor for all non-focus default icons (the circles). 
      

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.

• Rendering Geo POIs in the Camera view
  • Background information: In Developer API v3.0, we introduced 2d and 3d objects in 3d space. The intention of using 2d and 3d objects in layar is to provide users the same realistic experience in Layar camera view as in real world. 2d images represent billboard, while 3d models can be used to represent real objects such as sculptures.
    
    In order to provide good and realistic user experience, please follow the guidelines provided as below:
    • Provide different models for "object.url", "object.reducedURL" and also "icon.url". Please make sure that all these three fields are filled in with right models. Memory usage is sometimes an issue when loading large object files, therefore, providing less detailed representations for the same object("object.reducedURL") is highly recommended for good user experience.
    • The three models in "object.url", "object.reducedURL" and "icon.url" should represent the same object, while the only difference is level of detail. The "object.url" model should be the most complex one and user can enjoy the model when user is close by. On the other hand, "icon.url" is an image representation of the object with low resolution which will be shown when the object is far away. User only needs to know what he /she can expect when the object is close enough. 
    Since a 2d/3d object can be represented by "object.url", "object.reducedURL" and "icon.url" parameters, which parameter should be picked up is determined by the object projection on the phone screen (rendered object). Actually another very important factor is the memory usage which is related to the response time while loading objects.
    In general, the following factors will influence the rendered size of the 2d/3d objects on the phone screen:
    • object size: The size of an object in meters.
    • object scale: The scale factor applied to the object size parameter.
    • distance: between the object and the phone.
  • Layar Client Behavior:
    • POI icon is considered as a 1d circle.
      
      •  If 'icon' dictionary is defined for this POI, only the image defined for the 'url' parameter of the 'icon' is used. This allows developers to specify a different icon for each POI, not having to use custom CIWs defined under "Look & feel" tab of the layer editing page in the publishing site.
      •  If 'url' parameter in 'icon' is not defined, CIW is the fallback. It is determined by the "type" parameter in 'icon'. default value for "type" is 0. CIW as fallback means: custom CIW if defined (and available) or default 1d circle as last resort.
      •  If 'icon' dictionary is not defined, the standard default 1d circle is used.
    The icon defined in "url" parameter of "icon" dictionary scaling in the camera view follows these rules:
    • The icon is rendered on a 1x1 meter quad in the OpenGL world
    • At 50 meter distance, the maximum icon size is shown, which appears as a 16x16 billboard: scale = 16
    • From 0-50 meters distance, the scale is adjusted to make the icon not appear larger on screen: scale = 16 * poi.distance/50
    • At the end of the range, the size of the icon is 25% of the maximum size (at 50 meter): scale = range/12.5
    • Between 50 meters and the end of the range, the scale is interpolated:
      scale = 16 + (range/12.5 - 16) * (poi.distance - 50) / (range - 50)
    • POI icon is considered as 2d image/billboard in a 3d space.
      
      In order to 'predict' the rendered size of the object, the 'size' and 'scale' parameters should be used. 'size' is an indication by the layer developer for the actual size of the  object. 'scale' is applied to the object 'size' value. Therefore the actual size of the object is 'size' x 'scale'.
      
      For instance, I have an object with the following settings:
      
      • object size: 50
      • object scale: 2
      • distance: 1500
      
      For 2d object, such as billboard, you can imagine that at the distance of 1500m, there is a billboard which is 100m high (originally 50m, after applying the scale factor, now it is 100m). On a typical device, the rendered size will be around 20 pixels high (only!).  By changing object size and object scale, the actual rendered object size can be different at the same distance.
      
      Normally 'object.url' and 'object.reducedURL' are used only to render the object.
      
      
      • If the rendered size is more than 100px, the 'object.url' image is used.
      • If the rendered size is less than 100px, the 'object.reducedURL' image is used. If 'object.reducedURL' is not present, 'object.url' is used all the time.
      • The image is scaled down to smallest size (10 px), as it should be a realistic 2D billboard in space. Below this lowest threshold, we keep it at that size (10px).
      • 'icon.url' is used as fallback if neither 'object.url' nor 'object.reducedURL' can be loaded. As a last resort, CIW defined in "icon.type" is used. In both cases they are scaled as if it was a billboard with the right size, so it also scales down realistically down to minimum (10 px). CIW as fallback means: custom CIW if defined (and available) or default 1d circle as last resort.
      NOTE:  The actual 2d image file size in pixels (for instance, the actual image file size is 128 x 128 pixels), can be used to influence the quality of the rendered 2d object on the phone screen.  For instance, for the 'object.url' image, 256 x 256 pixels, 'object.reducedURL' image, 128 x128 pixels and 32 x 32 pixels for the 'icon.url' image.
    
    
    • POI icon is considered as 3d object in a 3d space.
      In order to 'predict' the rendered size of the object, the 'size' and 'scale' parameters should be used. 'size' is an indication by the layer developer for the actual size of the object. 'scale' is applied to the object 'size'. Therefore the actual size of the object is 'size' x 'scale'.
      
      For instance, I have an object with the following settings:
      
      • object size: 50
      • object scale: 2
      • distance: 1500
      
      For 3d object, such as a cube, you can imagine that at the distance of 1500m, there is a cube which is 100m in height, width and depth. On a typical device, the calculated rendered size will be around 20 pixels high. This calculated rendered size will be used to determine which object ('object.url'/'object.reducedURL'/'icon.url') will be picked up.
      
      Here we use 'object.url', 'object.reducedURL' and 'icon.url':
      
      
      • If the rendered size is more than 100px, the 'object.url' 3d model is used. Fallback is 'object.reducedURL' if there are memory issues or loading issues.
      • If the rendered object size is less than 100px but more than 20px, the 'object.reducedURL' 3d model is used. If 'object.reducedURL' is missing 'object.url' is used down to the 20px threshold (if memory allows).
      • If the rendered size is less than 20px, the 'icon.url' image is used as a billboard in the size of the 3d object and scaled down to smallest size (like 2d). If 'icon.url' is missing, use CIW defined in 'icon.type'. CIW is used as fallback above 20px only if neither 'object.reducedURL' nor 'object.url' can be rendered (missing, cannot be loaded, memory issues). CIW as fallback means: custom CIW if defined (and available) or default 1d circle as last resort.
      NOTE:  For 3d objects, the actual size of the object is embedded in the 3D model file (1 unit is 1 meter). The object 'size' parameter in the response should reflect the real size of the model, but it is just used for the selecting of the ''object.url'/'object.reducedURL'/'icon.url''.  Once the client determines which object to render, during the actual rendering, the embedded size is used with the scaling applied.  For instance, in our previous example, the object size is 50m, while the 3D model is a shape of 50mX40mX30m. In that case with the scale it becomes an object of 100mX80mX60m. This value will be used during the actual rendering on the client.

Best Practices 

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

• Prepare 3d models according to the guidelines mentioned in the 3D model Converter section.
• If the 3D model is quite big, you can use several POIs to represent it instead of one single POI. So, each POI will represent a part of the model. In this case, the layar client can download and render a part of the 3D model that should be firstly seen by the user. For instance, a house with some furniture inside. If the user is outside of the house, you can better return POIs that are representing the outside part of the house and let the layar client render the rest while the user is looking at the house.