| 
View
 

Client Specifications

Page history last edited by xuan wang 12 years, 10 months ago

 

Please NOTE that this documentation will not be updated anymore. Please see our new Developer Documentation Site for the latest updates!

 

 

On this page, we will list all the expected client specifications for the Layar Reality Browser. The rules should be applied to all the mobile platforms that Layar client is running on.

 

1. Auto-triggered Actions Options

2. Displaying POIs in the Map view

3. alt VS relativeAlt usage

4. Rendering POIs in the Camera view

5. The maximum number of returned POIs

6. Navigation in Layar client

 

1. Auto-triggered Actions Options

 

Background information:

 

 Since Layar Developer API 3.0, auto-triggered actions have been introduced. The following two parameters were defined to control the auto-triggered actions.

 

Category Key Value Example Explanation Minimum API version

autotrigger control

(optional)

autoTriggerRange integer "autoTriggerRange":25

The presence of this parameter indicates whether of not this action can be autotriggered by reaching the POI. Note that only one action can be auto-triggered, the client will use the first one in the array having this parameter.

The parameter itself is the distance in m within which the user must be of the POI position in order for the auto-trigger to launch.

NOTE: not included in the new Actions object (layer level) defined in the JSON response.

v3.0
autoTriggerOnly
boolean "autoTriggerOnly":false

Indicates whether of not this action can also be invoked manually by the user outside of the range specified. If true, the action will not be shown when pressing the button to display all possible actions, unless the user is within the give range of the POI.

NOTE: not included in the new Actions object (layer level) defined in the JSON response.

v3.0

 

NOTE:

  • It may happen that the user enters a region that by chance is covered by 2 auto-triggered actions from two POIs. Only the closest POI is triggered in such case.  
  • An action should be triggered only when the location changes from outside to inside the trigger area. If an action was already triggered, it does not get triggered repeatedly when the user stays inside the trigger area.
  • External applications can not be triggered automatically (using custom URL schemes).  

 

Layar Client Behavior:

 

Affected Layar clients/versions: IPhone Layar client v4.0 and above; Android Layar client v4.0.3 and above.

 

By default, auto-triggered actions are launched automatically without warning the user. 

 

In the layar client settings, there should be one setting regarding auto-triggers:

 

  • Title: Automatic actions
  • Option: Show trigger alers on/off (by default: off)
  • Explanation: Certain objects in the camera view can automatically trigger actions when you are close by, like open a web page, play a sound or play a video.

 

When the user sets this option to true, an alert is shown each time that an auto-trigger action is to be launched asking whether or not to launch the action. This pop-up alert has the following attributes:

 

  • Title: Title of the POI
  • Text: You've reached an object that wants to [open a website | play a sound | play a movie | launch an action] depending on the action content-type.
  • Two buttons: Launch + Don't Launch

 

NOTE: The user cannot disable the alert directly from this pop-up alert. If the alert is shown, it means he enabled it in the settings so he should know how to switch it off.

 

2. Displaying POIs on the Map view

 

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:

 

Affected Layar clients/versions:   IPhone Layar client v4.0 and above; Android Layar client v4.0.3 and above.

 

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. Please NOTE that CIW middle and outer icons are not used.

 

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 object dictionary 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.

 

3. alt VS relativeAlt usage

 

Background information:

 

In API v3.0, we introduced "alt" and "relativeAlt" parameters, so that POIs can have different altitude values in the camera view 

 

API part  Parameter  Format  Example  Optional/Mandatory  Description
 getPOIs request
 alt  integer  alt=345  optional  The current altitude of the user in meters. This is not always known on the client and will only be passed when there is a gps fix.
 getPOIs response
 alt  integer "alt": 500
 optional  Real altitude of object in meters. If this is missing, the same altitude as the user is assumed.

NOTE: This parameter will be used only when the "alt" of the user is passed through in the getPOIs request. Otherwise, the value will be ignored.

 getPOIs response
 relativeAlt  integer  "relativeAlt":  50
 optional  Altitude in meters of the object with respect to the user's altitude (grid surface in the camera view).

NOTE: Not used if 'alt' is supplied and the user's altitude is known.

 

Layar Client behavior:

 

 Altitude known from device API
 "alt" in getPOIs request
 "alt" in getPOIs response
 "relativeAlt" in getPOIs response
 Expected Behaviors when rendering POIs in the camera view
 No  not present
 not present/ "alt": null
 not present/
"relativeAlt": null
 The same altitude as the user is assumed. In the camera view, this means that POIs will be right on top of the grid surface.
 No  not present
  not present/ "alt": null   "relativeAlt": 100  The "relativeAlt" parameter will be picked up. In the camera view, this means that POIs will be 100m above the grid surface.
 No  not present  "alt": 50
 not present/
"relativeAlt": null
 The same altitude as the user is assumed. In the camera view, this means that POIs will be right on top of the grid surface.
 No  not present
 "alt": 50  "relativeAlt": 100
 The "relativeAlt" parameter will be picked up. In the camera view, this means that POIs will be 100m above the grid surface.
Yes
 alt=200  not present/ "alt": null  not present/
"relativeAlt": null
 The same altitude as the user is assumed. In the camera view, this means POIs will be right on top of the grid surface.
 Yes  alt=200
 not present/ "alt": null  "relativeAlt": 100  The "relativeAlt" parameter will be picked up. In the camera view, this means that POIs will be 100m above the grid surface.
 Yes   alt=200  "alt": 50  not present/
"relativeAlt": null
The "alt" parameter in the response (50) will be picked up.  the POIs will be 150m below user's real altitude. In the camera view, this means 150m below the grid surface.
 Yes  alt=200   "alt": 50 "relativeAlt": 100  The "alt" parameter in the response (50) will be picked up.  the POIs will be 150m below user's real altitude. In the camera view, this means 150m below the grid surface.

 

4. Rendering POIs in the Camera view

 

Background Information:

 

POI dimension
Object/Transform
Typical JSON Response per POI
1
Optional

{

  "id": "1",

  "distance": 100,

  "title": "POI 1",

  "lat": 123456,

  "lon": 123456,

  "action": [ ],

  "dimension": 1,

  "object": {
                "baseURL": "http:\/\/custom.layar.nl\/",
                "icon": "icon.png"
                }

}

2
Mandatory

{

  "id": "1",

  "distance": 100,

  "title": "POI 1",

  "lat": 123456,

  "lon": 123456,

  "action": [ ],

  "dimension": 2,

  "object": {
                "baseURL": "http:\/\/custom.layar.nl\/",
                "full": "2dimage_full.png",
                "reduced": "2dimage_reduced.png",
                "icon": "icon.png",
                "size": 120
                },
  "transform": {
                "rel": true,
                "angle": 0,
                "scale": 5
               }

}
3 Mandatory

{

  "id": "1",

  "distance": 100,

  "title": "POI 1",

  "lat": 123456,

  "lon": 123456,

  "action": [ ],

  "dimension": 3,

  "object": {
                "baseURL": "http:\/\/custom.layar.nl\/",
                "full": "3dobject_full.l3d",
                "reduced": "3dobject_reduced.l3d",
                "icon": "icon.png",
                "size": 120
                },
  "transform": {
                "rel": true,
                "angle": 0,
                "scale": 5
               }

}

 

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 "full", "reduced" and "icon". 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 is highly recommended for good user experience.
  • The three models in "full", "reduced" and "icon" should represent the same object, while the only difference is level of detail. The "full" model should be the most complex one and user can enjoy the model when user is close by. On the other hand,  "icon" 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 full/reduced/icon 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 dimension = 1,  POI icon is considered as a 1d circle. 

 

          If 'object' dictionary is defined for this POI, only the image defined for the 'icon' parameter of the 'object' is used. Other parameters in 'object' and 'transform' will be ignored. 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 'icon' parameter in 'object' is not defined, CIW is the fallback. CIW as fallback means: custom CIW if defined (and available) or default 1d circle as last resort.

 

         The icon 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 dimension = 2, 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 'full' and 'reduced' are used only to render the object. 
    • If the rendered size is more than 100px, the 'full' image is used.
    • If the rendered size is less than 100px, the 'reduced' image is used. If 'reduced' is not present, 'full' 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' is used as fallback if neither 'full' nor 'reduced' can be loaded. As a last resort, CIW 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 'full' object, 256 x 256 pixels, 'reduced' object, 128 x128 pixels and 32 x 32 pixels for the 'icon'.

 

 

 

  • POI dimension = 3,  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 ('full'/'reduced'/'icon') will be picked up.

 

          Here we use 'full', 'reduced' and 'icon':
    • If the rendered size is more than 100px, the 'full' 3d model is used. Fallback is 'reduced' if there are memory issues or loading issues.
    • If the rendered object size is less than 100px but more than 20px, the 'reduced' 3d model is used. If 'reduced' is missing 'full' is used down to the 20px threshold (if memory allows).
    • If the rendered size is less than 20px, the 'icon' image is used as a billboard in the size of the 3d object and scaled down to smallest size (like 2d). If 'icon' is missing, use CIW. CIW is used as fallback above 20px only if neither 'reduced' nor 'full' 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 'full'/'reduced'/'icon'.  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. 

 

5. The maximum number of returned POIs
There are actually 2 maximums we need to consider:

- Threshold number of POIs received after which the client will not request a new page (if there still are more pages in the JSON response, morePages=true). This should be 50.

- Maximum number of POIs the client will render, i.e. it will discard POIs from the last JSON response. This should also be 50.

 

So for example:

- A POI provider returns multiple pages, each page has 15 POIs. Client will fetch 4 pages: 15, 30, 45, 60. It will not fetch another page because the number of POIs is > 50 and it will render only the first 5 POIs from the last page.

- A POI provider returns one page containing 80 POIs. Client will render the first 50 POIs of response and discard the last 30.

 

6. Navigation in Layar client

  

In Layar client 5.0, we introduce a new user interface which has designed to promote the visibility of layers and encourage user retention.   

 

Before we started explaining the new navigation, lets review the following definitions in getPOIs request:

 

Parameter Format Example Explanation Introduced API version

countryCode

(mandatory)

string

countryCode=NL

 

list of country code can be found here.

This is the home country of the user, as determined by the network provider of the SIM card in the phone. If this is not available (e.g. iPhone or no SIM card inserted), it will return the locale value set on the phone.

 

NOTE: If you have development mode on, the country setting in developer settings will overrule the values from SIM card and Locale setting.
v2.1

localCountryCode

(optional)

string localCountryCode=JP

country code for the current country the device is located in, based on the country of the current mobile network provider the user is roaming in. If not available (e.g iPhone

In Layar client 5.0, we introduce a new user interface which has designed to promote the visibility of layers and encourage user retention.   

 

Before we started explaining the new navigation, lets review the following definitions in getPOIs request:

 

or no SIM card), the app will try to determine the current country based on the GPS location (reverse geo-coding lookup). However this may be unsuccessful and therefore incorrect.

v3.0

 

 

  1. Layers Tab

 

  •  New List

 

 

 

     Client Specification:

    • Under the Layers tab, there is a New section. 

    • Upon clicking on the New section of Layers, the user is taken to a Catalogue View.

    • The New List contains all Layers within your current country if available (localCountryCode), your Home Country (countryCode), and International Layers. The intent is to display layers most relevant to that user. As some locations contain few layers and/or rarely updated, this combination is important. 

    • The New List is sorted by initial publication date. Initial publication date is the date that a layer was *FIRST* published.

 

  •      Featured List

 

 

Client Specification:

  • Upon selecting Featured from the main "Layers" Menu, the user lands at the Featured List screen.

  • The Featured List contains Layers that are marked as Featured by the Layar Content Manager for the user's home country (countryCode).

  • The Featured List is sorted by the order in which the Layar Content Manager ordered them.

 

  • Popular Lists

 

 

     1) Nearby Tab

    • Upon selecting Popular from the main "Layers" tab, the user lands a the Popular screen.

    • The initial screen on Popular is Nearby.

    • Layers returned:

      • Layers that have been indexed at the location of the user (your layer must have indexing enabled in the Layar Stream options to appear here)

      • and layers which have their bounding box set at the location of the user.

    • Layers are sorted by popularity, where popularity is based on the number of views of a layer.

 

     2) Country Tab

    • Within the Popular Screen, the user can select <Country> tab, where <Country> is the country where the user is currently located (localCountryCode). If the current country cannot be detected, the home country of the user is used (countryCode).

    • Layers are sorted by popularity, where popularity is based on the number of views of a layer.

 

     3) Worldwide Tab 

    • Within the Popular Screen, the user can select the Worldwide tab.

    • Layers returned within this tab are international layers.

    • Layers are sorted by popularity, where popularity is based on the number of views of a layer.

 

 

 

Comments (0)

You don't have permission to comment on this page.