animations

JSON Response - animations

The animations object can be used on both layer level (root) and POI level (hotspots) in the JSON response. The animations defined on POI level will overrule those defined on the layer level. For Geo POIs, animations are applied to all icons, including normal 1d icon, 2d objects and 3d objects. For Vision POIs, only 2d images and 3d objects.

Coordinate Systems

Geo POIs and Vision POIs have different coordinate systems:

Geo POIs -obeying the right-hand rule.

The positive X axis points east
The positive Y axis points north
The positive Z axis points up (away from the Earth's core)

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:

Vision POI Coordinate System

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.

Simple appearance animations

With the simple appearance animations all that is required is a single keyword: drop, grow or spin. Using this keyword as the value for the animations property is all that is necessary to define a meaningful appearance animation (i.e. when a POI is loaded). These are the descriptions of the simple appearance animations:

Key	Example	Description
drop	"animations":"drop"	The POI drops from the sky.
grow	"animations":"grow"	The POI appears growing from nothing into its real size.
spin	"animations":"spin"	The POI spins like a top when it appears, then slows down until it stops.

Full animations API

Alternatively, Layar provides a fully customizable animations API. It is possible to precisely configure animation behavior when creating, updating and deleting POIs and when they receive focus or become clicked. The full animations API is defined below.

Animation events object definition

`onCreate`	array	A sequence of animations are triggered when the POI is first loaded in the AR view.
Mandatory/Optional:	Optional
Default value:	empty array []
Path:	root.animations or hotspots.animations
Detailed Description:	Animations are triggered when the object is first loaded in the AR view. Can be used to make an appearance animation for the POIs, like growing, fading in, etc.
Example:	"onCreate": [{ "interpolation": "decelerate", "interpolationParam": 1.0, "to": 2, "length": 10000, "from": 0, "delay": 0, "repeat": false, "type": "scale", "axis": { "y": 1, "x": 1, "z": 1 }, "persist": true }]

`onUpdate`	array	A sequence of animations are triggered when the POI is updated in the getPOIs response.
Mandatory/Optional:	Optional
Default value:	empty array []
Path:	root.animations or hotspots.animations
Detailed Description:	Animations are triggered when the object is updated in the getPOIs response. It is useful to animate a transition to the new POI state. It is easy to create transitions by leaving out the "from" and "to" parameters mentioned below in animations object. The Layar client will default these by filling in the old and new values for the updated POI. This works for rotation (using the "angle" parameter of the object), scale (using the "scale" parameter) and translate (using "lat", "lon", "transform.translate" and "alt")
Example:	"onUpdate": [{ "interpolation": "decelerate", "interpolationParam": 1.0, "length": 10000, "delay": 5000, "type": "translate", "axis": { "y": 1, "x": 0, "z": 0 } }]

`onDelete`	array	A sequence of animations are triggered when the POI is removed from the AR view.
Mandatory/Optional:	Optional
Default value:	empty array []
Path:	root.animations or hotspots.animations
Detailed Description:	Animations are triggered when the object is deleted in the getPOIs response when there is a full refresh or the POI is listed in the "deletedHotspots" array.
Example:	"onDelete": [{ "interpolation": "decelerate", "interpolationParam": 1.0, "length": 10000, "delay": 5000, "from": 1, "to": 0, "type": "scale", "axis": { "y": 1, "x": 0, "z": 0 } }]

`onFocus`	array	A sequence of animations are triggered when the POI gets focus in the AR view.
Mandatory/Optional:	Optional
Default value:	empty array []
Path:	root.animations or hotspots.animations
Detailed Description:	Animations are triggered when the object is in focus. This event can be used to highlight the focus, for example by making it grow in size.
Example:	"onFocus": [{ "interpolation": "decelerate", "interpolationParam": 1.0, "length": 10000, "delay": 0, "from": 0, "to": 360, "type": "rotate", "axis": { "y": 0, "x": 0, "z": 1 }, "repeat": true }]

`onClick`	array	A sequence of animations are triggered when user taps onthe POI in the AR view.
Mandatory/Optional:	Optional
Default value:	empty array []
Path:	root.animations or hotspots.animations
Detailed Description:	For 3D POIs, the entire model's bounding box captures the tap.
Example:	"onClick": [{ "interpolation": "overshoot", "interpolationParam": 1.0, "length": 10000, "delay": 0, "from": 0, "to": 2, "type": "scale", "axis": { "y": 1, "x": 1, "z": 1 }, "repeat": false, "persist": true }]

Animation object definition

`type`	string	The animation type, namely rotate, scale and translate
Mandatory/Optional:	mandatory
Path:	root.animations or root.hotspots.animations
Detailed Description:	Rotate and translate animations are performed relative to the global coordinate system. This means that the order of rotation and translation are not relevant. A translation of { "x": 10, "y": 0, "z": 0 } relocates the POI 10 meters eastwards for a Geo POI and 10m along the x axis of the target object for a Vision POI, even if it was preceded by a rotation of 90 degrees over an { "x": 0, "y": 0, "z": 1 } axis. Scale transformations are relative the the POI's coordinate system so that rotating an object with a non-uniform scaling vector does not morph the object during rotation.
Example:	"type": "rotate" "type": "scale" "type": "translate"
rotate	string	Animate the rotation around a specific axis
Path:	root.animations.type or root.hotspots.animations.type
From/to meaning	Angle of rotation in degrees.
"axis" object meaning	The rotation follows the right-hand rule. The "axis" object mentioned below defines the axis around which the rotation occurs. By default, x=0, y=0, z=1.
scale	string	Animate the scale of the POI. It can be used to let buildings grow out of the ground by limiting the scale to the z-axis.
Path:	root.animations.type or root.hotspots.animations.type
From/to meaning	Scaling factor. A negative scaling factor means the object is mirrored.
"axis" object meaning	Ratio of how much the scale factor affects each primary axis. By default, x=1, y=1, z=1
translate	string	Animate movement of a POI. It can be used to position a POI somewhere else.
Path:	root.animations.type or root.hotspots.animations.type
From/to meaning	Scale multiplier for the translation. By default, from=0, to=1
"axis" object meaning	Translation vector in meters. By default, x=0, y=0, z=0

`length`	integer	Animation duration in milliseconds.
Mandatory/Optional:	mandatory
Path:	root.animations or hotspots.animations
Example:	"length": 5000
Detailed Description:	This is the duration between "from" status and "to" status. In this example, the animation will be applied to "from", and stays at "from" status for 5000 milliseconds, then applies to "to" status.

`delay`	integer	Delay in milliseconds before starting the animation.
Mandatory/Optional:	Optional
Default value:	0
Path:	root.animations or hotspots.animations
Detailed Description:	This is the duration before the animation will be applied to "from". In this example, the animation starts after 1 second.
Example:	"delay": 1000

`interpolationParam`	decimal	Parameter for the interpolation algorithm. The interpolation types are explained below.
Mandatory/Optional:	Optional
Path:	root.animations or hotspots.animations
Example:	"interpolationParam": 1.0

`interpolation`	string	The interpolation to use in the animation. See all the possible options below.
Mandatory/Optional:	Optional
Default value:	linear
Path:	root.animations or hotspots.animations
Example:	"interpolation": "accelerate"
Type of interpolation	Description	Meaning of InterpolationParam value
linear	The rate of change of the animation is constant, i.e. stays the same for the entire duration of the animation.	N/A
accelerateDecelerate	The rate of change of the animation starts slow but accelerates until halfway the animation, after when it decelerates back to slow.	N/A
accelerate	The rate of change of the animation starts out slowly and and then speeds up	factor. Degree to which the animation should be eased. Setting the factor value to 1.0f produces a v = t^2 parabola characteristic. Increasing this value above 1.0f exaggerates the ease-in effect (i.e. the effect starts slower and ends faster).
decelerate	The rate of change of the animation starts out quickly and and then slows down	factor. Degree to which the animation should be eased. Setting the factor value to 1.0f produces a v = - t^2 parabola characteristic. Increasing this value above 1.0f exaggerates the ease-out effect (i.e. the effect starts faster and ends slower)
bounce	An interpolator where the change 'bounces' at the end, i.e. the animation is slightly reversed when it reaches it's final state and then applied again.	N/A
cycle	Repeats the animation for a specified number of cycles. The rate of change follows a sinusoidal pattern.	cycles. Number of cycles in the interpolation
anticipateOvershoot	The animation starts out 'in reverse', then accelerates in the specified direction, then decelerates, overshoots the target value, reverse again and finally goes to the specified value.	tension. Amount of anticipation/overshoot. When tension equals 0.0f, there is no anticipation/overshoot and the interpolator becomes an acceleration/deceleration interpolator.
anticipate	The animation starts out 'in reverse' then accelerates in the specified direction towards the specified "to" value.	tension. Amount of anticipation. When tension equals 0.0f, there is no anticipation and the animation is the same as that of an acceleration interpolator.
overshoot	The animation starts out fast, overshoots the specified "to" value then reverses to reach the specified "to" value.	tension. Amount of overshoot. When tension equals 0.0f, there is no overshoot and the animation is the same as that of a deceleration interpolator.

`persist`	boolean	The POI state keeps the end state of the animation.
Mandatory/Optional:	Optional
Default value:	false
Path:	root.animations or hotspots.animations
Detailed Description:	When used for onFocus/onClick, the animation persists until the POI loses focus.
Example:	"persist": true

`repeat`	boolean	Specifies whether the animation is repeated in a loop.
Mandatory/Optional:	Optional
Default value:	false
Path:	root.animations or hotspots.animations
Detailed Description:	Not allowed to set to "true" for onDelete and onUpdate animations. When used for onCreate, the animation repeats the entire lifetime of the POI. When used for onFocus/onClick, the animation repeats until the POI loses focus.
Example:	"persist": true

`from`	decimal	Specifies the start state of the animation.
Mandatory/Optional:	Optional
Default value:	depends on the animation type mentioned above.
Path:	root.animations or hotspots.animations
Detailed Description:	Default is to let the animation use the currently set POI state, except for onUpdate animations where the previous value for the POI is used.
Example:	"from": 0.0

`to`	decimal	Specifies the end state of the animation.
Mandatory/Optional:	Optional
Default value:	depends on the animation type mentioned above. Default is to let the animation use the currently set POI state.
Path:	root.animations or hotspots.animations
Example:	"to": 360.0

`axis`	json dictionary	Axis that this animation resolves around.
Mandatory/Optional:	Optional
Default value:	depends on the animation type mentioned above. Each axis is decimal.
Path:	root.animations or hotspots.animations
Example:	"axis": { "x": 0.0, "y": 1.0, "z": 2.0 }

Complete JSON Response Example

{
  "layer": "animationex01",
  "hotspots": [
    {
      "id": 0,   
      "anchor": {
        "geolocation": {
          "lat": 52.3729,
          "lon": 4.9357
        }
      },
      "text": {
        "title": "bamboo",
        "description": "some description",
        "footnote": "powered by Layar"
      },         
      "object": {
        "url": "http://example.com/full_model.l3d",
        "contentType": "model/vnd.layar.l3d",
        "reducedURL": "http://example.com/reduced_model.l3d",
        "size": 2
      },
      "transform": {
        "rotate": {
          "rel": false,
          "axis": { "x": 0, "y": 0, "z": 1},
          "angle": 0
        },
       "translate": { "x": 0, "y": -0.075, "z": 0 },
       "scale": 0.01
      },
      "animations": { // "animations" on a POI level. This overwrites the "animations" parameter defined on the layer level.
        "onClick": [ // "onClick" event triggers the following animation.
                     // The object size is scaled by a decimal factor from 0 to 2 on X, Y and Z axises.
          {
            "interpolation": "overshoot",
            "to": 2,
            "length": 2000,
            "from": 0,
            "delay": 0,
            "repeat": false,
            "type": "scale",
            "axis": { "y": 1, "x": 1, "z": 1 },
            "persist": true
          },
          // The object is relocated 60m northwards ( Y axis)
          {
            "interpolation": "accelerateDecelerate",
            "to": 60,
            "length": 1000,
            "from": 0,
            "delay": 500,
            "repeat": false,
            "type": "translate",
            "axis": { "y": 1, "x": 0, "z": 0 },
            "persist": true
           }
         ]
        }
      }
    ],
    "animations": { // Layer level animations.
    
        "onCreate": [  // The object size is scaled by a decimal factor from 0 to 2 on X, Y and Z axises.
            {
               "interpolation": "decelerate",
               "interpolationParam": 1.0,
                "to": 2,
                "length": 10000,
                "from": 0,
                "delay": 0,
                "repeat": false,
                "type": "scale",
                "axis": {
                    "y": 1,
                    "x": 1,
                    "z": 1
                },
                "persist": true
            }
        ],
        
        "onUpdate": [ // When the layer is updated, translate the POI from its current location to its new position (for instance, lat, lon).
            {
                "length": 2000,
                "type": "translate"
                  
            }
        ],
        
        "onDelete": [ // When the POI is deleted, its size will be scaled from 1 to 0 on all X, Y, Z axises.
             {
                "to": 0,
                "length": 10000,
                "from": 1,
                "type": "scale",
                "axis": {
                    "y": 1,
                    "x": 1,
                    "z": 1
                },
                "persist": true
            }     
        ],
       
        "onFocus": [ // Rotate the object around its Z-axis repeatedly.
            {
                "to": 360,
                "length": 5000,
                "from": 0,
                "repeat": true,
                "type": "rotate"
            }
        ],

        "onClick": [ // Launch the object along Z-axis from 0m to 100m.
            {
                "axis": {
                    "y": 0,
                    "x": 0,
                    "z": 5
                },
                "interpolation": "accelerate",
                "length": 5000,
                "to": 20,
                "interpolationParam": 1,
                "from": 0,
                "type": "translate",
                "repeat": false
            
            }
        ]
        
    },
    "refreshInterval": 10,
    "fullRefresh": false,
     "errorCode": 0,
    "errorString": "OK"
}