This is a tutorial on how to implement JSON coding into the new JSON Hotspot Widget in the Layar Creator. We will cover how to go from converting a 3D object to .l3d format, to implementing JSON code into the JSON Hotspot Widget, and then finally how to add “actions” and “animations” to a 3D object. The JSON Hotspot Widget can be used for both 2D and 3D objects but for this tutorial, we will focus on 3D.
Since it is an advanced feature, it is best that you already have the knowledge mentioned below:
- Basic knowledge of JSON
- Basic knowledge of 3D modelling
- Experience with using 3D modelling programs
- 3D model converter (provided by Layar: https://www.layar.com/documentation/browser/3d-content-creation/3d-model-converter-copy/)
- For detailed information on all Layar API visit https://www.layar.com/documentation/browser/api/getpois-response/
The general outline of the tutorial is as follows:
This section covers how to go about converting your 3D model into the required .l3d format so that you can host it on a server to be implemented in your Vision Layer. This is done through the use of the 3D Model Converter.
The 3D Model Converter can be found at: https://www.layar.com/documentation/browser/3d-content-creation/3d-model-converter-copy/
This section covers how to go about using the JSON Hotspot Widget and how to attach a 3D object to it. Covered is an explanation of the JSON file used and how to go about inputting your 3D object into it.
The Hotspot API Documentation can be found at: https://www.layar.com/documentation/browser/api/getpois-response/hotspots/
This section covers how to add animations to your 3D object and provides a simple block of code to provide forward movement to an object.
The Animation API Documentation can be found at: https://www.layar.com/documentation/browser/api/getpois-response/animations/
This section covers how to add an action to your 3D object using the appropriate JSON code.
The Action API Documentation can be found at: https://www.layar.com/documentation/browser/api/getpois-response/actions/
By the end of the tutorial, you will find the actual JSON code and you can simply copy & paste in your campaign to try it out.
Before diving into the technical explanation, we have prepared a few examples for you to showcase the possibilities. Scan the images below using Layar App and begin your Introduction into 3D objects.
<image – Earth>
The first image (Earth) is that of a 3D earth. It is a simple 3D object with no animations or actions. Scan it yourself to view the Earth.
<image – Telescope>
The second image (Telescope) is a 3D earth again but this time with added animation when you click on it. It uses a “rotate” animation that keeps spinning the earth. Scan it yourself to view the Earth and then try clicking on it!
<image – Rocket>
The third image (Rocket) is similar to the one before it except now there is music! (If you cannot hear the music, consider checking if your volume is turned on) To do this, the 3D object has an “action” attached that sends a call to the URL where the song is hosted. Scan it yourself to view the Earth.
Before we get into JSON and JSON Hotspot Widget you’ll need to have a 3D model, the 3D model converter and, if you want to alter it or create it yourself, a 3D modelling program.
For a list of 3D modelling programs visit:
We use Blender to create a 3D model. It does have a bit of a harsh learning curve, but once you get the hang of it, it’s a great way to create amazing 3D models. Plus, it’s free. Download Blender: http://www.blender.org/
So, let’s say you download or create a 3D model. Layar only works with 3D models in the .l3d format. This is easily achieved using the 3D model converter (provided by Layar). Simply follow these steps:
- Save your model in .obj format.
- Open the 3D model converter.
- Import the .obj file into the model converter.
- Check to see that any texture images you are using have the size to the second power (i.e: 200 x 200 or 512 x 512, etc).
- Select “File”, then “Save as” and save the object as a .l3d file.
For a detailed explanation on the 3D Model Converter visit: https://www.layar.com/documentation/browser/3d-model-converter/how-to-use-3d-model-converter/
At this point you have a .l3d 3D model ready for Layar. Your 3D model needs to be available on the Internet so upload it onto a server.
<image - 3D Model Converter>
If you just want to play with the 3D capability of Layar, you can download the attached Earth model for Testing Purposes Only.
Add a JSON Hotspot Widget
So, you’ve got a .l3d 3D model and a campaign page to put it on. Now what? It’s time to add a JSON Hotspot Widget.
JSON Hotspot Widget
One of the newest buttons in the Creator is the JSON Hotspot Widget found in the “Advanced” drop down list in the Buttons section. Click on the button and you’ll see something like:
Edit Panel for the JSON Hotspot Widget
Let’s break down what you need to change and what you don’t need to change
Do not alter this part of the code - we’ve got this area covered. If the id and anchor are changed, the changes will be ingnored upon saving the button.
Lets quickly review what each key means here, for detailed explanation, please visit our HOTSPOT API documentation.
“actions” - Actions that are triggered when an object is clicked on (Covered later).
“object” - this defines your 3D model.
“url” - This is the URL of where your 3D model is stored.
“contentType” - This is the type of object you are adding. In the case of a 3D model, this would be “contentType”:” model/vnd.layar.l3d”.
“size” - Leave this to 1 and change the scale in the later part of the code if it is necessary.
“transform” - It controls how an object should be positioned relative to the page uploaded in the Creator.
“scale” - This allows you to control the scale of the 3D model. This is a multiplication factor that will be applied to the actual size of the 3d object.
“translate” - This is the position of your 3D model along the x, y, and z axes of the page that you scanned. The units are in meters. The height of the page is 1 meter. The coordinate system of the page obeys the right hand thumb rule and it looks like:
If the value of all the x, y, z axes is 0, this means the center of the 3d object will be placed at the middle center spot on the page.
Please NOTE that although we can drag and drop the JSON Hotspot Widget to any spot on the page. However, the actual positioning of the button is defined in the "transform" dictionary in the JSON code of this button.
3D Earth Example #1 - Adding 3D object to a page
So let’s breakdown the code for the first Earth 3D model:
This is the part of the code that we do not touch.
Here, we define the 3D object. The “contentType” is set to that of “model/vnd.layar.l3d which is required for 3D objects. The “url” is the location of where the Earth 3D model is hosted and the size is kept at 1.
Here we define the positioning of the model. As you can see, the z-axis has value of 0.5, this means we will move the center of the 3d model up on the z-axis for 0.5m. This was due to the fact that the Earth model would have otherwise been half in the ground. The height of the model is 1m and the center of the 3d model's coordinate system is the center of the 3d model itself. So now, the 3d model will be positioned in the middle of the page. We have scaled the model down to 0.4 so that it does not look too big on the page.
Now you have a great 3D model and you’re seeing it in AR space but maybe you would like it to move. You can review how to add animation in our Layar API Documentation (https://www.layar.com/documentation/browser/api/getpois-response/animations/)
3D Earth Example #2 - Adding Rotation to the 3D object
In this example, we will add an onClick animation to the Earth model that makes it start rotating when you click it:
Let us have a look at the parameters used here:
“animations” - This defines the animation added to the 3D object.
“onClick” - This indicates that the action will occur once the object is clicked. This can be changed to “onCreate”, “onFocus”, “onDelete”, or “onUpdate”. (For more detailed information visit: https://www.layar.com/documentation/browser/api/getpois-response/animations/)
“type” - This defines the type of animation occurring.
“from” - This defines the starting point of the animation. If 0, the animation will occur from the starting position of the 3D object.
“to” - This defines the ending point of the animation. In our case, it is 360, it means it will rotate from 0 to 360 degrees.
“delay” - This defines how much time must first pass before the animation should occur. In our case, we will start the animation immediately when you click on the Earth model.
“axis”- This defines the axes involved in the animation (x, y, or z). In our case, z-axis is 1 which means the Earth model will start rotating around the z-axis.
Please NOTE that Positioning is solely affected by changing the translate and transform values and the translation is relevant to the coordinates system of the page. Rotate and scale transformations are all applied to the local origin of the object. For 2D augments, this is the center point. For 3D models, it is the origin as saved by your 3D modelling tool.
“length” - This defines how long the animation will last for. We set it to 20000 so that the model will take 20 secs to rotate from 0 to 360 degrees.
“persist” - This defines the end point of the animation. If it is set to false, then the object will revert to its starting position. If it is set to true, then the object will remain at the ending point of the animation.
“repeat” - This defines if the animation will repeat or not. In our case, we set it to true so that the model will continue rotating.
Now, you have an amazing 3D object and it’s moving and dancing all over the place. Maybe you want some background music? This is where “actions” come in.
The “actions” line is where uri’s are added according to what is required (for more information on uri’s check our API Documentation at https://www.layar.com/documentation/browser/api/getpois-response/actions/).
3D Earth Example #3 - Adding an auto-triggered action to the Earth model
Let’s add the following code to the object to play a song automatically when the model is loaded:
“uri” - In this case, this the URL where the song is stored on a server.
“autoTrigger” - True if the action should act immediately, False if not.
“autoTriggerOnly” - True if the action should act immediately and if the action cannot be triggered any other way than autoTrigger (for example on click).
"contentType": "audio/mp3" - This determines the type of content, in this case it is an audio file in mp3 format.
This is the end of this tutorial. Below you will find the complete JSON files for these examples.