Buildwagon Development Tutorial

Introduction

HoloBuild Library

The main library that we will be using and that is part of the buildwagon platform is HoloBuild, a library that creates dynamic holograms and provides a collection of components intended to accelerate the development of HoloLens applications. You can access the library at: https://www.buildwagon.com/documentation/


Buildwagon Online Editor

We’ll use the Buildwagon Online Editor to do our programming.
Buildwagon runs right inside a browser, it lets us type our programming code and see the results immediately.

Open the public Buildwagon Editor to try things out using your web browser at the following link buildwagon online editor. It should look something like this.

 Buildwagon editor and emulator
Buildwagon Online Editor and Emulator

You will notice that Buildwagon allows you to experiment with the code and visualize what you are programming. If your aim is to work on more detailed projects, and to save your code, you have to create a profile at buildwagon and get access to a personalized dashboard that could host your projects.

Buildwagon Development Tutorial

3D Objects


You should first get familiar with the concept of 3D objects that are at the core of our work.
Any 3D object is made up of a specific shape or geometry. The shape is usually formed of small building blocks that depict a general shape like a prism, a sphere, a cube, or any other specific shape. Let’s take the cube as an example.

box skeleton buildwagon

The geometry of the object is like an empty skeleton that could be covered with a specific material, color, pattern, or image.

object material buildwagon

Once we dress up the geometry (or shape) with the material (or cover) we get a HoloMesh, which is the interweaving of the geometry (shape) and the material (cover) together. The names 3D object, HoloMesh, or Hologram basically all mean the same thing in our context.

holomesh buildwagon

This is great but let’s not get ahead of ourselves!

In order to create a HoloMesh (or Hologram), you need a space to host it. This space is where the action takes place and where different holograms can interact and communicate with each other.
So far we have a space where the HoloMesh exist. For us to see the HoloMesh, we need a camera (or a HoloCamera). Think of this concept as a movie production. Action can happen throughout the space, but we are only able to see the action through the camera. In our example, the cube is the action, but if the camera is not looking at the cube, we will not be able to see it.
The HoloCamera will look at the space from a particular angle or perspective. What is nice about mixed reality, is that users can decide what angle to explore in a particular space, and how to interact with the holograms according to preference. In a hololens based mixed reality, the Holocamera is represented by the Hololens device (the hardware you are wearing) and where it is looking at; So, the person wearing the Hololens decides where the camera is looking at. He is the director and the audience at the same time.

Ok, let’s move from narrating to coding. Let’s play around with different shapes, and explore the attributes along the way.

First, we will start by setting a space, and place a camera that oversees that space. From Buildwagon's Library, we can learn more about the HoloSpace component.
A HoloSpace represents a holographic scene, and its main purpose is to act as a container for all the holograms that make up the scene. The code to define the space is:

		  
var holoscene = new HoloBuild.HoloSpace();
		  
		

Similarly, a HoloCamera represents the HoloLens and where it is looking at. To create a new HoloCamera instance you can call:

		  
var Hololens = new HoloBuild.HoloCamera();
		  
		

Once we have the space and the camera, we need to define a renderer, and ask it to draw (or render) the space on that camera:

		  
var holorenderer =  new HoloBuild.HoloRenderer(); 
holorenderer.render(holoscene, hololens);
		  
		
Set the scene buildwagon

Now that we have our landscape set, let’s start adding shapes.

The process of adding shapes is usually similar regardless of the shape's details. It involves the following steps:

  1. Define the new geometric shape.
  2. Cover it with material, pattern, or image.
  3. Dress the geometric shape with the cover to create a HoloMesh (connect them together as a mesh)
  4. Add the new shape to the space
Buildwagon Development Tutorial

Creating Shapes

Let’s create a box, then a ball, then a platform, then a pyramid!!
You will notice that we are following the above process, with minor differences.

A Box

Let’s create a box following the process above.


  1. To create a box, you need to create the 3D geometry shape of a box. From the Holobuild library you can get the code of adding a box. The HoloBoxGeometry is the library component of a 3 dimensional box or a cube. It involves defining the 3 parameters of a box:
    • Width
    • Height
    • Depth

    			    
    var boxgeometry = new HoloBuild.HoloBoxGeometry( 0.1, 0.2, 0.3 );
    			    
    			    

    The 0.1, 0.2, and 0.3 represent the respective values of width, height, and depth of the box in meters.

  2. To cover the boxgeometry with a material, you can use one of the materials available in the Holobuild library such as HoloMeshBasicMaterial or HoloMeshStandardMaterial. These two functions in a similar manner; they describe the geometry appearance such as its color and texture. The HoloMeshStandardMaterial gives a more realistic look, but at the same time requires more computational resources.
    			    
    var boxmaterial = new HoloMesh.HoloMeshStandardMaterial( { color: 'red' } );
    			    
    			    
    The ‘color’ is one parameter of the material element, that could be defined accordingly. In this case, we have chosen ‘red’ for the material color.

  3. Simply connect the boxmaterial with the boxgeometry by using the HoloMesh component from the library:
    			    
    var boxmesh= new HoloBuild.HoloMesh( boxgeometry, boxmaterial );
    			    
    			    

  4. 4- Lastely, add the new shape to the space so that we see it on the Hololens:
    				
    holoscene.add(boxmesh); 
    			    
    			    

Make sure the renderer is the last elements of your code to be able to draw all the components of the scene.

 Box Shape Code Buildwagon

You will notice that the box looks more like a square in 2D dimensions. That’s not what is expected. It is frustrating to see a square instead of a box. This is simply because we are looking to only one side of the box, a façade. In order to see more than one side, we need to move the camera or turn the box.


Rotate

Let’s turn the box by rotating the mesh using the following code.

		  
boxmesh.position.set(0.4,0,0);
		  
		

The above code will rotate the box to make it more visible in a 3D setting.

The 0.5, 0.5, 0 are coordinates used in 3D visualization. This is what we are going to explain next before we continue with the other shapes.
If you run the Emulator after adding the rotation code, you should get something like below. Now we can see 3 different sides of the box instead of only one.
This is looking more exciting.


 Rotate Box Code
Buildwagon Development Tutorial

3D Coordinates


The 3D coordinate system refers to 3-axes: X, Y, and Z. Using these axes we can refer to any position displayed in a 3 dimensional space. The system considers the exact center of the space as the origin with coordinate 0,0,0.
Accordingly, we can position the 3D objects (holograms) in relation to the origin by changing the coordinates of the X, Y, and Z. Let’s understand the axes further.
The X axis, operates on a horizontal level across the screen (left-right), moving from-ve to +ve the more we shift from left to right.
The Y axis, operates on a vertical level of the screen (down-up), moving from –ve to +ve the more we shift from down to up.
As we are working in 3D, we need the Z axes to represent the object’s depth position. The Z axis, operates on a diagonal level of the screen (far-near), moving from-ve to +ve the more we shift towards the camera (Hololens).

 3D Coordinates System Buildwagon

Using these 3 axes, we can now refer to any position by using 3 numbers to represent x, y, and z . This can be referred to as a “vector” and contains all the information we need to position an object anywhere in the space.

For example, if I want my box to be in the center of the space, I can position it by adding the following code:

				
boxmesh.position.set(0,0,0); 
			    
			    

It will look as such:


 Holomesh Center Position Buildwagon

To move the box on the x axis to the right, the code will change to:


			
boxmesh.position.set(0.4,0,0);
			
			

It will look as such:


 Holomesh x-axis Position Buildwagon

Going back to the origin position, to move the box on the x axis to the left, the code will change to:


			
boxmesh.position.set(-0.4,0,0);
			
			

It will look as such:


 Holomesh x-axis Negative Position Buildwagon

Going back to the origin position, to move the box on the y axis to the top of my screen, the code will change to:


			
boxmesh.position.set(0,0.2,0)
			
			

It will look as such:


 Holomesh y-axis Position Buildwagon

Always starting from the origin position, to move the box on the y axis to the bottom of my screen, the code will change to:


			
boxmesh.position.set(0,-0.2,0);
			
			

It will look as such:


 Holomesh y-axis Negative Position Buildwagon

Going back to the origin position, to move the box on the z axis, we will be working with the depth position. To move the object away from the camera (Hololens), the code will change to a -ve value for the z coordinate. You will notice that the box is now far from the camera more into the core of the screen.


			
boxmesh.position.set(0,0,-4);
			
			

 Holomesh z-axis Negative Position Buildwagon

Also, starting from the origin position, to move the box on the z axis closer to the camera (Hololens), the code will change to a +ve value for the z coordinate. You will notice that the box is now very close to the camera, similar to the zoom effect.


			
boxmesh.position.set(0,0,4);
			
			

 Holomesh z-axis Position Buildwagon

Now that we are familiar with the x, y, z coordinates, let’s go back to explain the Rotate feature that we introduced earlier. Starting at the origin position without any rotation, the box will look like a square as below.

 Holomesh Box Buildwagon

The below code, will rotate the boxmesh to make it more visible in a 3D setting. This will help us see a box as a 3-D geometry rather than a 2-D square.


			
boxmesh.rotation.set(0.5,0.5,0);
			
			

The above code will equally rotate the box downward on the x-axis, and to the right on the y-axis by the value of 0.5.


 Rotation on x and y axes Holomesh Buildwagon

The result will look as such:


 Holomesh Rotation on x and y axis Buildwagon

If we would like to have a rotation on the z-axis it will look as such with the below code:


			
boxmesh.rotation.set(0.6,0.6,0.3);
			
			

You will realize that we changed the values of x and Y axis rotations to 0.6, and added a z-axis value of 0.3.


 Rotation on x and y and z axes Holomesh Buildwagon
Buildwagon Development Tutorial

Set Image and Creating More Shapes

Set Image

We can dress (cover) the material of the geometry with any image that we like. The setImage feature will set an image on the HoloMesh, it takes as input an image file name. You can use the following code to set an image as a material.


			
boxmesh.setImage(‘images/woodenbox.png');
			
			

Before I set the Image as a material (cover), I have to upload the image to my project. In my case, I created a folder called “images” under my project, and saved the image under the name of ‘woodenbox’. Thus, after I added the image, I told the program that it is located in the ‘images” folder. In order to be able to upload images to your project, you need to set-up a project by registering an account with the Buildwagon platform. In order to be able to go over these examples on the public emulator, the images are already available for you to put in use.
After you complete the above process, you should get the below image:


 Wooden Material Holomesh Buildwagon

The set image can take other parameters, similar to an object, such as Repeat, Stretch… Feel free to explore and experiment with the parameters described at the HoloBuild library.
Moving on with our mission, let’s proceed now in creating a ball, then a platform, then a pyramid!! For ease of explanation, every time we create a new mesh, we will replace it with the one preceding it.


A Ball

To create a ball, we have to use the geometry shape of a sphere. From the Holobuild library, this is designated by the component: "HoloSphereGeometry". To construct a sphere you need to provide the sphere radius. The code for a sphere in the Holobuild library is:


			
HoloBuild.HoloSphereGeometry( 0.1);
			
			

The radius value 0.1 represents the sphere radius in meters. The radius describes how big the sphere is. Increasing/decreasing the radius will increase/decrease the size of the sphere respectively.
When you run the code at the emulator, you will get something like this.


 Ball Holomesh Buildwagon

You will notice that we changed the color of the material to green.
Another thing you will notice, is that the sphere isn’t really a smooth ball, but sharp and edgy instead. This is because as stated earlier, the shape of the sphere is formed out of small building blocks.
What we want in order to make it look smoother like a ball, is to increase the number of building blocks around the sphere horizontally, as well as up and down the sphere vertically.
The code will now look like this, where 0.1 is the radius in meters, and 30, 30 is the value of the building blocks added around the sphere (horizontally), and up and down the sphere (vertically) respectively.


			
HoloBuild.HoloSphereGeometry( 0.1, 30, 30);
			
			

The ball will now look like this:


 Ball Building Blocks Holomesh Buildwagon

Much better. Later you will notice that choosing a texture for the ball, instead of a color, will make things look even smoother and more realistic.


A platform

To create a platform, we need to work with the geometry shape of the cylinder. A cylinder, which is also sometimes called a tube, is an extremely useful shape in 3D programming. You will be working with it a lot.
The code of the Cylinder from the HoloBuild library is:


			
HoloBuild.HoloCylinderGeometry( 0.15, 0.15, 0.6);
			
			

The values 0.15, 0.15, and 0.6 respectively represents how big the top of the cylinder is, how big the bottom of the cylinder is, and how tall the cylinder is.
If you run it on the Emulator, you will get something like this:


 Cylinder Holomesh Buildwagon

You will notice that we changed the material color to orange, and adjusted the height and depth positions of the cylinder to 0.2and -1 to get a convenient outlook.
To view the cylinder in a more 3D setting, we have to slightly rotate it on the 3 axes to get a visual similar to the below:


 Cylinder Rotate Holomesh Buildwagon

Similar to the sphere earlier, in order to make our cylinder smoother, we need to add is a number of “building blocks” or fillers horizontally and vertically. The following code HoloBuild.
HoloCylinderGeometry ( 0.15, 0.15, 0.4, 30, 30); will add horizontal and vertical building blocks of 30 (horizontally and vertically) to generate a result similar to the below.


 Cylinder Rotate Building Blocks Holomesh Buildwagon

Beautiful! With the appropriate textile as material, the above visual can easily look like a tree trunk, or a tin can.

But, where is our platform. Easy, all we need to do is play around with the HoloCylinderGeometry dimensions, to increase the size value of the “cylinder top” and “cylinder bottom”, and at the same time reduce the length of the cylinder. If you want a classical platform, it is important to give the “cylinder top” and “cylinder bottom” the same value.
Using the code below, The result will render differently:

			
var cylindergeometry = new HoloBuild.HoloCylinderGeometry ( 1, 1, 0.1, 50, 40);
			
			

Have a look!


 Cylinder Platform Holomesh Buildwagon

Lovely! We added the number of building blocks to maintain the smoothness of the shape with the volume increase. We also changed the value of the position depth (z-axis) to have a zoom-out outlook.
To get a more realistic and grounded platform, we have to get rid of the rotation effect on the y and z axes, and decrease the rotation on the x-axis. The result is now as follows:


 Cylinder Platform Unrotate Holomesh Buildwagon

A Cone

Always using the cylinder as the shape, if we use different values of the “cylinder top” and “cylinder bottom”, we can have a variety of possibilities. One possibility is reducing the “cylinder top” to a very small value, and increasing the “cylinder bottom” to a very big value to get a cone. Of course the length of the cylinder shape should be increased accordingly to portray the cone length.
Let’s reduce the “cylinder top” to 0.05, and the “cylinder bottom” to 0.5, and increase the shape length to 1. The result is below:


 Cone Holomesh Buildwagon

Now let’s add some building blocks to have a more realistic cone. If we add the horizontal building blocks to the above, let’s say a value of 40, we’ll get something like this:


 Cone Building Blocks Holomesh Buildwagon

A Pyramid

Ok, this is cool, but where the Pyramid? All we need to do in order to get the pyramid is reduce the “cylinder top” to 0.01, reduce the number of horizontal building blocks to a small figure (let’s say 4), and rotate the shape a little more in order to get a 3D feel. And your pyramid will be ready!


 Pyramid Holomesh Buildwagon

You now can understand how useful and important the cylinder geometry is to 3D visualization.

There is a wide variety of geometries in the HoloBuild library awaiting to get explored. You can access them through this link: https://buildwagon.com/documentation/#!/Geometries
Other important geometries include the plane, torus, and triangles. They all follow the same logic as the ones introduced above.

Buildwagon Development Tutorial

Looping and Animation


Now, let’s work on something cool and extremely important. Whenever there is something changing in the scene, like a rotating object, we have to ask the program to show us this change. This cannot be done by rendering (drawing) the scene only once; but it has to be rendered repetitively so that we realize the difference in the scene before the change takes place, and after it happens (in our case, every instance the object rotates and takes a new position). This also true to scenes that are subject to user interactions, because the scene will change when the interaction takes place.
We can do this by looping the render function.


Render Loop

We have covered so far that by rendering the scene, we ask the program to draw for us what the Hololens (Camera) sees in the space that we have created. When things are changing in the space due to a specific activity, the hololens needs to re-draw the scene after the activity has occurred. Thus, there is a need to animate the frame (or scene) in order to observe the change in the activity.
We can do this by calling a function to animate the scene. Let’s explore the code below:


			
function renderloop(){
    window.requestAnimationFrame(renderloop);
    cylindermesh.rotation.x += 0.01;
    cylindermesh.rotation.y += 0.01;
    holorenderer.render(holoscene, hololens);
}
renderloop();
			
			

In the function ‘renderloop’, the line window.requestAnimationFrame(renderloop) asks the hololens to recall this function again and again and again. It recalls it up to 60 times per second depending on the frame rate.
The code holorenderer.render(holoscene, hololens); will require the scene to be drawn (rendered) every time the function is called, thus we continuously observe any change occurring in the scene.
If you insert the above code, you should get something like the below (you will notice I added a texture of a woodenbox using “setImage”):



Moving forward, a render function should be included at the end of each project we work on, so that it continuously renders all the changes that are taking place.