× Initiating database migration review
× Database migration started
 
 
 

Your First Blipp
Difficulty: Introduction

 
 
Here is a quick tutorial that will help you get started by building your own Augmented Reality experience using the Blippar app, iTunes or our transfer apk with a browser for Android and of course JavaScript coding.
 
 

Installs and configurations

First things first - you need to install the Blippar app on your device. If you have an iOS device, you may need to also install iTunes on your computer.
Start the app on the device. After all the welcoming screens in the app go to Menu › Settings › Developer. Enter your credentials (ie login and password used for your account with Blippar). Note that you need to be connected to the internet for this. Then make sure that Enable Debug Menu and Log is in the ON position. This will enable the Debugging Menu on the top-center of your screen where you can enable console logging, turn on wireframe display and other debugging features.
Go to Home and start blipping by pointing the camera at the marker below to start a blipp. After the blipp has started point the device away from the marker and close the app.

 
 


Open this marker in a new tab for further blipping.

Or print it for easier usage and angle choice.
 
 
 
 

Writing your first blipp in JS

Create a 3-folder structure for your blipp as described here.
blipp_root_directory/
    + assets/
    + javascript/
        + package.json
        + main.js

In any text editor open main.js from the javascript directory . Edit it and type in the following code that will make the script reach the blipp core of the app (each code snippet will be the full JS source unless specified otherwise):
var blipp = require('blippar').blipp;

Then create a scene that will host all the models:
var blipp = require('blippar').blipp;
var scene = blipp.addScene();

On that scene place a flat plane that will stick to the marker when pointing at it:
var blipp = require('blippar').blipp;
var scene = blipp.addScene();

// Scene creation
scene.onCreate = function() {
    var Plane = scene.addSprite().setColor('#ff7d32aa').setScale(400);
}

Save the main.js file and open in a text editor the package.json from the same javascript directory. Edit it and type in the following code content using the latest Blippbuilder Script library version:
{
    "version": "1.0.0",
    "description": "Blippar JS test application",
    "main": "main.js",
    "blipp" : {
        "title": "My first blipp",
        "shortTitle": "1st blipp"
    },
    "dependencies": {
        "blippar": "1.4.6"
    }
}

Let’s just get the ball rolling by side-loading the blipp we just created in order to test it.
To do so, push those two files (main.js and package.json) to the device (iOS instructions here and Android instructions here ).
Note that at that point, we haven't associated a marker to our blipp in order to trigger it. That is because we're relying on the fact that the content is side-loaded and that, in such a case, the app will use any valid marker to trigger the side-loaded content.
In other words, pointing the device at the marker shown above should trigger your side-loaded contant and show an orange rectangle covering the center of the marker.

 
 

Marker world and screen world

There are two coordinate systems in Blippar: the marker one (with origin in the center of the marker, X pointing toward the right, Y towards the upper part of the marker and Z from the face of the marker towards the user), that binds models to the marker (AR) and the screen one (originating from the center of the screen, when holding the device in portrait, main button on the bottom, X points to the right, Y up and Z toward user) that binds object to the screen (GUI).

 
 
The orange square you see is (by default) in marker space.

Create two variables that will measure the marker dimensions and apply those to the orange plane (as it is flat the Z dimension is irrelevant so we’ll use 1):
var blipp = require('blippar').blipp;
var scene = blipp.addScene();

// Global variables
var mW = blipp.getMarker().getWidth();
var mH = blipp.getMarker().getHeight();

// Scene creation
scene.onCreate = function() {
    var Plane = scene.addSprite().setColor('#ff7d32aa').setScale(mW, mH, 1);
}

Now the orange plane should cover the marker as much as possible when tracking (when the marker is in the view of the camera). After each code change re-upload the main.js file to the Blippar Documents folder, close the blipp and then point the camera at the marker again to re-start with the updated script.

An alternative way to re-start the blipp and see any changes to blipping the marker is to close it and then go to the main menu, click on History and pick the latest blipp (also the one with the short name chosen in the JSON file uploaded on the device). When the marker is not in view of the camera and the blipp peels you can manipulate the tracking models by pinch and twist on the screen.

Now add a screen space model and texture it with Corner.png.
var blipp = require('blippar').blipp;
var scene = blipp.addScene();

// Global variables
var mW = blipp.getMarker().getWidth();
var mH = blipp.getMarker().getHeight();

// Scene creation
scene.onCreate = function() {
    var Plane = scene.addSprite().setColor('#ff7d32aa').setScale(mW, mH, 1);
    var Corner = scene.getScreen().addSprite();
        Corner.setType('aura').setTexture('Corner.png').setScale(200);
}

Before starting the blipp copy the texture to the same Documents folder on the device. As you can see the model attached to the screen does not track with the Plane model on the marker but is always stuck to the screen and it is also in the center of the screen. The screen measurements can be obtained through the app and they need to be used when positioning model on the screen to give them a relative scale and position on any device (screen height is always the long side of the screen and width is the short side):
var blipp = require('blippar').blipp;
var scene = blipp.addScene();

// Global variables
var mW = blipp.getMarker().getWidth();
var mH = blipp.getMarker().getHeight();
var sW = blipp.getScreenWidth()  * 1.003;
var sH = blipp.getScreenHeight() * 1.003; 

// Scene creation
scene.onCreate = function() {
    var Plane = scene.addSprite().setColor('#ff7d32aa').setScale(mW, mH, 1);
    var Corner = scene.getScreen().addSprite();
        Corner.setType('aura').setTexture('Corner.png').setScale(sW/5);
}

As device screen pixel measurements are to a degree inaccurate (for example iPhone 6S reports a height of 2001 pixels instead of the real 2000 value) and having gaps on the edges of the screen for GUI elements would look bad, a choice of padding screen width and height by 0.3% was taken to grow all the screen space elements. In our case a scale of ⅕ of screen width was chosen for the side of the corner sprite. It will be placed in the top right corner of the screen by setting its align parameters horizontally and vertically and translating it by half screen on both X and Y axis (both positive for top right corner):
var blipp = require('blippar').blipp;
scene = blipp.addScene();

// Global variables
var mW = blipp.getMarker().getWidth();
var mH = blipp.getMarker().getHeight();
var sW = blipp.getScreenWidth() * 1.003;
var sH = blipp.getScreenHeight() * 1.003; 

// Scene creation
scene.onCreate = function() {
    var Plane = scene.addSprite().setColor('#ff7d32aa').setScale(mW, mH, 1);
    var Corner_TR = scene.getScreen().addSprite();
        Corner_TR.setType('aura').setTexture('Corner.png').setScale(sW/5);
        Corner_TR.setTranslation([sW/2,sH/2,0]).setHAlign('right').setVAlign('top');
}
 
 

Blipp models with common features

Now that the corner element is in the correct position let’s discuss the alignment code: the app-generated flat planes (sprites) have as a default pivot its center. You can change that pivot by setting align, but of course when rotating it will be around the new pivot position: setHAlign and setVAlign functions.

 
 
 
 

As all 4 corners that we’ll implement in the blipp will have common features other than rotation and position. Because of this we should create a common class-like function that will help generate all the corners:
var blipp = require('blippar').blipp;
scene = blipp.addScene();

// Global variables
var mW = blipp.getMarker().getWidth();
var mH = blipp.getMarker().getHeight();
var sW = blipp.getScreenWidth() * 1.003;
var sH = blipp.getScreenHeight() * 1.003; 

// Scene creation
scene.onCreate = function() {
    var Plane = scene.addSprite().setColor('#ff7d32aa').setScale(mW, mH, 1);
 
    createCorner(  0,  sW/2,  sH/2);
    createCorner( 90, -sW/2,  sH/2);
    createCorner(180, -sW/2, -sH/2);
    createCorner(270,  sW/2, -sH/2);
}

// User functions
function createCorner(rotZ, posX, posY) { 
    var sprite = scene.getScreen().addSprite()
                                  .setTexture('Corner.png')
                                  .setTranslation(posX, posY, 0)
                                  .setRotation(0, 0, rotZ)
                                  .setScale(sW/5)
                                  .setType('aura')               
                                  .setHAlign('right')
                                  .setVAlign('top');
    return sprite; 
}
scene.onShow = function() {
    console.log("Marker: " + blipp.getMarker().getWidth() + "*" + blipp.getMarker().getHeight() + " px");
    console.log("Screen: " + blipp.getScreenWidth() + "*" + blipp.getScreenHeight() + " px");
}

Sizes of sprites are in pixels, relative to pixel sizes of screen. Log those using the functions added in onShow.
 
 

Texturing

As you noticed we used a texture earlier on the corner sprites but there are more ways of texturing sprites and models in blippar. A texture can be opaque (download Flower.jpg):

 
 
 
 

Transparent, like the corner texture or composed from an image and a mask:
 
 
 
 

This technique is very useful for the best image quality and asset size as any combination of JPG, PNG8 or PNG24 can be used for the image-mask asset also they can have different dimensions but with some restrictions but also with some possible enhancements. Read more here.

Here are the two images we’ll use for the corners texture, note that they are different file formats and combined they yield a transparent asset:

 
 
Here is the code that will need to be used to replaced on line 23:
.setTexture('Corner.png')
Instead we’ll use a two-texture array [image, alpha]:
.setTexture(['Corner_C.jpg','Corner_A.png'])

We can at this point texture the sprite tracking to the marker (Plane) with Flower.jpg but if you leave setColor active on it it will tint the image with that color and the last two digits will set its opacity value (Alpha). The function setColor accepts the following arguments:

  • A hex RGB code with or without ‘#’ such as:
    model.setColor('#FF0000');
    model.setColor('FF0000');

  • A RGB Array of values between 0 and 1, not the usual 0 to 255:
    So for RGB = 255,0,0 or FF0000 we’ll use setColor(1,0,0)
    Or as a general conversion setColor(R/255, G/255, B/255)

  • An added parameter for alpha either in hex: 'FF000080' or array: [1, 0, 0, 0.5]
    Note that this will actually change the alpha property of the model


IMPORTANT:
It is crucial to note that model order creation and model types determine how they are drawn finally on the screen. Experiment will all model types and attachment to marker or screen to get as better sense of how it works.
 
 

Interactivity

Here is the current code after removing setColor from the Plane model:
var blipp = require('blippar').blipp;
scene = blipp.addScene();

// Global variables
var mW = blipp.getMarker().getWidth();
var mH = blipp.getMarker().getHeight();
var sW = blipp.getScreenWidth() * 1.003;
var sH = blipp.getScreenHeight() * 1.003; 

// Scene creation
scene.onCreate = function() {
    var Plane = scene.addSprite().setTexture('Flower.jpg').setScale(mW, mH, 1);
 
    createCorner(  0,  sW/2,  sH/2);
    createCorner( 90, -sW/2,  sH/2);
    createCorner(180, -sW/2, -sH/2);
    createCorner(270,  sW/2, -sH/2);
}

// User functions
function createCorner(rotZ, posX, posY) { 
    var sprite = scene.getScreen().addSprite()
                                  .setTexture(['Corner_C.jpg','Corner_A.png'])
                                  .setTranslation(posX, posY, 0)
                                  .setRotation(0, 0, rotZ)
                                  .setScale(sW/5)
                                  .setType('aura')               
                                  .setHAlign('right')
                                  .setVAlign('top');
    return sprite; 
}

scene.onShow = function() {
    console.log("Marker: " + blipp.getMarker().getWidth() + "*" + blipp.getMarker().getHeight() + " px");
    console.log("Screen: " + blipp.getScreenWidth() + "*" + blipp.getScreenHeight() + " px");
}

Now let’s add some interactivity to the models.

By default models are not clickable unless they have a function associated with that event (and in that case they are not explicitly made not clickable) so we can add a click event listener: when the current blipp is started click on the top developer panel then turn on Hotspots and then Bounding box.

Notice how all the sprites have the same red then green highlighting.

Now make all the corner sprites non clickable by using setClickable(false) in the Corner function and give the Plane model a function to hide itself when touched:
var blipp = require('blippar').blipp;
scene = blipp.addScene();

// Global variables
var mW = blipp.getMarker().getWidth();
var mH = blipp.getMarker().getHeight();
var sW = blipp.getScreenWidth() * 1.003;
var sH = blipp.getScreenHeight() * 1.003; 

// Scene creation
scene.onCreate = function() {
    var Plane = scene.addSprite().setTexture('Flower.jpg').setScale(mW, mH, 1);
    Plane.onTouchEnd = function() { this.setHidden(true) };
 
    createCorner(  0,  sH/2,  sW/2);
    createCorner( 90, -sH/2,  sW/2);
    createCorner(180, -sH/2, -sW/2);
    createCorner(270,  sH/2, -sW/2);
}

// User functions
function createCorner(rotZ, posX, posY) { 
    var sprite = scene.getScreen().addSprite()
                                  .setTexture(['Corner_C.jpg','Corner_A.png'])
                                  .setTranslation(posX, posY, 0)
                                  .setRotation(0, 0, rotZ)
                                  .setScale(sW/5)
                                  .setType('aura')               
                                  .setHAlign('right')
                                  .setVAlign('top')
                                  .setClickable(false);
    return sprite; 
}

scene.onShow = function() {
    console.log("Marker: " + blipp.getMarker().getWidth() + "*" + blipp.getMarker().getHeight() + " px");
    console.log("Screen: " + blipp.getScreenWidth() + "*" + blipp.getScreenHeight() + " px");
}

Turn both Hotspots and then Bounding box on and you will notice now how just Plane has a red highlight denoting it is clickable. The onTouchStart and onTouchEnd functions can be as complex as necessary and they can refer to the model calling the function by this.

 
 

Dynamic lighting

One more interesting thing to do is add dynamic lighting to the blipp. The light is always attached to the center of the device screen (for now) but can be used on any model. In our case let’s set a dynamic light on the Plane model. First a light and material need to be defined, then associated with the model:
var blipp = require('blippar').blipp;
scene = blipp.addScene();

// Global variables
var mW = blipp.getMarker().getWidth();
var mH = blipp.getMarker().getHeight();
var sW = blipp.getScreenWidth() * 1.003;
var sH = blipp.getScreenHeight() * 1.003; 

// Scene creation
scene.onCreate = function() {

    var defaultLight    = scene.addLight('light');
    var defaultMaterial = scene.addMaterial('material');

    var Plane = scene.addSprite().setTexture('Flower.jpg').setScale(mW, mH, 1)
                                 .setLight(defaultLight).setMaterial(defaultMaterial);
    Plane.onTouchEnd = function() { this.setHidden(true) };
 
    createCorner(  0,  sW/2,  sH/2);
    createCorner( 90, -sW/2,  sH/2);
    createCorner(180, -sW/2, -sH/2);
    createCorner(270,  sW/2, -sH/2);
}

// User functions
function createCorner(rotZ, posX, posY) { 
    var sprite = scene.getScreen().addSprite()
                                  .setTexture(['Corner_C.jpg','Corner_A.png'])
                                  .setTranslation(posX, posY, 0)
                                  .setRotation(0, 0, rotZ)
                                  .setScale(sW/5)
                                  .setType('aura')               
                                  .setHAlign('right')
                                  .setVAlign('top')
                                  .setClickable(false);
    return sprite; 
}

scene.onShow = function() {
    console.log("Marker: " + blipp.getMarker().getWidth() + "*" + blipp.getMarker().getHeight() + " px");
    console.log("Screen: " + blipp.getScreenWidth() + "*" + blipp.getScreenHeight() + " px");
}

Now blipp again and hover over the Plane sprite - you’ll notice how the light reflect on it giving it a shiny metal-like appearance.

This can be heavily configured as you can see here.

In future use, on 3D models dynamic lighting has a huge effect even to the point where a model can have just a solid color and all its features are noticed by light reflection, environment map reflection and self shading.

 
 

3D models

More details on integrating 3D models can be found in Guides > Models section.

 
 

Further reading

For starters all the documentation located in the devs portal is to be read and tested:
Guides
Documentation
Tutorials

Secondly for more coding examples refer to the demo blipps section on the same portal:
Blipp demos

 
 
For general JavaScript programming queries please visit the following page:
https://developer.mozilla.org/en-US/docs/Web/JavaScript