× Initiating database migration..
× 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 iOS device and iTunes on your machine (for Android, see this tutorial). Start the app on the device. After all the welcoming screens in the app go to Menu › Settings › Developer. Punch in your blippar credentials (same as in Hub, you need to be connected to the internet for this) and in Server Presets select Default. Then Enable Debug Menu and Log, make sure it is in the ON position. Go to Home and start blipping by pointing the camera at the marker below to start a JS blipp. After the blipp has started point the device away from the marker and close the blipp.

 
 


Open this marker in a new tab for further blipping.

Or print it for easier usage and angle choice.
 
 
After the blipp has started you should:
  • 1. Connect the iOS device via USB cable to the computer
  • 2. Open iTunes and select the device, navigate to Apps
  • 3. Scroll down to the File Sharing section select Blippar from the list
  • 4. Add (or drag and drop) files to the Blippar Documents folder (empty by default)
 

 
For an Android alternative please visit this tutorial.

Make sure the sideload app has Blippar chosen in the drop down menu on the upper part of the app.

At first let’s just get the ball rolling by making sure out side-loading process works. To do that we’ll simply add JS and JSON files to the documents folder. If these files are newer on the device than the original blipp source they will be used if that but will use the last blipped marker as if it belonged to your blipp.



 
 
 
 

Writing the first blipp in JS

In any text editor create a file called main.js. 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 JS file and create next to it a JSON file package.json with the following 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.3.13"
    }
}

Now drag the two files (main.js and package.json) to the Blippar Documents folder in iTunes. Pointing the device at the marker should now 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

 
 

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

A tutorial for integrating 3D models will come with plugins for 3DS Max and Blender but until then just flat planes are supported as meshes.

 
 

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