HoloLens Development

Holobuild Library version: 2.4.14



Getting started with Javascript HoloLens development using the buildWagon platform.


Core Components

To be able to display anything on a HoloLens we need three things: a HoloCamera, a HoloSpace, and a HoloRenderer.

HoloCamera

A HoloCamera represents the HoloLens and where it is looking at.
To create a new HoloCamera instance you can call: HoloBuild.HoloCamera();

Properties
  • children

    Returns an array of the HoloCamera's children.

  • position

    Represent the HoloCamera's local position.

  • rotation

    Represent the HoloCamera's local rotation (in radians).

  • scale

    Represent the HoloCamera's local scale.

Methods
  • add (object)

    Add a child object to the HoloCamera.

  • getObjectById (id)

    Searches through the HoloCamera's children and returns the object with a matching id.

  • getObjectByName
    (name)

    Searches through the HoloCamera's children and returns the object with a matching name.

  • getWorldPosition ()

    Returns a vector representing the position of the HoloCamera in the world space.

  • getWorldRotation ()

    Returns a vector representing the rotation of the HoloCamera in the world space.

  • getWorldDirection ()

    Returns a vector representing the direction of where the HoloCamera, i.e.: HoloLens user, is looking in the world space.

  • remove (object)

    Removes a child object from the HoloCamera.

HoloCursor of the HoloCamera
  • HoloCursor


    HoloCursor

    The HoloCursor is the a default HoloCamera child that is added by the system. A HoloCursor is a gaze indicator that provides continuous feedback for the HoloLens user about their intentions. The HoloCursor work by following the hololens's position and rotation in addition to casting a ray from the HoloLens into the HoloSpace object to show the user the center of their gaze and to indicate what hologram will respond to the user's input. The cursor will move with the user's head movement and it will lock in depth to whatever hologram or surface the user can is looking at. The cursor is torus shaped and it will provide a visual feedback per user hand state, for example, the cursor will change its shape base on the HoloLens detected the user's hand in the ready position and return to its normal shape when idle. You can use the HoloBuild.HoloCursor object To access the HoloCursor.

HoloCamera
To create a HoloCamera and set it to a variable:
var hololens = new HoloBuild.HoloCamera();
                       
To add a child object to the HoloCamera, in the case you want to follow the user's gaze:
var hololens = new HoloBuild.HoloCamera(); 
hololens.add(object);
                                    
To get a vector representing where the HoloLens user, is looking in the world space, you can use the getWorldDirection as follows:
var hololens = new HoloBuild.HoloCamera();
var vector = hololens.getWorldDirection();
                                    

HoloSpace

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.

Properties
  • children

    Returns an array of the HoloSpace's children.

  • hotspots

    Returns children that are interactable in the space.

  • id

    A unique HoloSpace numeric identifier (readonly).

  • name

    Represent the HoloSpace's name.

  • position

    Represent the HoloSpace's local position.

  • rotation

    Represent the HoloSpace's local rotation (in radians).

  • scale

    Represent the HoloSpace's local scale.

  • visible

    if set to false the HoloSpace and all its content would not get rendered.

  • onHold
    = callbackfunction(
    previousPos,
    currentPos)

    The callbackfunction that is called on a hold event: a combination of user gaze on the HoloSpace and the user hand press and moving gesture. The callbackfunction will be called with 2 positions vectors, the previous position and the current one.

  • onRelease
    = callbackfunction

    The callbackfunction that is called on a release event: a combination of user gaze on the HoloSpace and hand releases gesture. Other ways for the onRelease function to be called is if the user gestures get lost from the frame of view.

Methods
  • add (object)

    Add a child object to the HoloSpace.

  • clone ()

    Returns a clone of this HoloSpace.

  • getObjectById (id)

    Searches through the HoloSpace's children and returns the object with a matching id.

  • getObjectByName
    (name)

    Searches through the HoloSpace's children and returns the object with a matching name.

  • getWorldPosition ()

    Returns a vector representing the position of the HoloSpace in the world space.

  • getWorldRotation ()

    Returns a vector representing the rotation of the HoloSpace in the world space.

  • getWorldScale ()

    Returns a vector representing the scaling factors applied to the HoloSpace in the world space.

  • getWorldDirection ()

    Returns a vector representing the direction of HoloSpace's positive z-axis in the world space.

  • remove (object)

    Removes a child object from this HoloSpace.

  • toJSON ()

    Convert the HoloSpace to JSON format.

  • .onTap = callbackFct

    The callbackfunction will be called when a user taps in the holospace, without interscting with any hologram.

HoloSpace
var holoscene = new HoloBuild.HoloSpace();
                       

HoloRenderer

The HoloRenderer's main purpose is to render the content of the holographic scene into the HoloLens using WebGL. To render the holoscene onto the HoloLens, you will need to call the render function of the HoloRenderer and give it the scene and the hololens as inputs.
HoloRenderer
var holorenderer = new HoloBuild.HoloRenderer();
holorenderer.render(holoscene, hololens);
                       
To render a scene into the hololens:
var hololens = new HoloBuild.HoloCamera();
var holoscene = new HoloBuild.HoloSpace();
var holorenderer =  new HoloBuild.HoloRenderer();
holorenderer.render(holoscene, hololens);
                       

Geometries

The geometry is the shape that you want to draw, it contains all the polygons information that make up a hologram. In addition to creating your own geometry, there is a set of prebuilt geometries that you can use. This section will go over the pre-build geometries: such as a Box, or a Sphere.

HoloBoxGeometry

The HoloBoxGeometry is a geometry of a 3 dimensional box or a cube. To construct a HoloBoxGeomtry you need to provided the width, height, and box depth dimensions.

Constructor
  • width

    A number representing the width of the box in meters.

  • height

    A number representing the height of the box in meters.

  • depth

    A number representing the depth of the box in meters.

HoloBoxGeometry
var box = new HoloBuild.HoloBoxGeometry( 0.1, 0.1, 0.1 );
                       

HoloCircleGeometry

The HoloCircleGeometry is a simple circle geometry made of several triangular segments. To construct a HoloCircleGeomtry you need to provided the radius dimension.

Constructor
  • radius

    A number representing the circle radius in meters.

  • segments

    A number representing the number of triangular segments the circle will be made of.

HoloCircleGeometry
var circle = new HoloBuild.HoloCircleGeometry( 0.1, 30 );
                       

HoloConeGeometry

The HoloConeGeometry is a 3D cone geometry made of several triangular segments. To construct a HoloConeGeomtry you need to provided the cone radius and its height dimensions.

Constructor
  • radius

    A number representing the circle radius in meters.

  • radialSegments

    A number representing the number of radial segments the cone will be made of.

  • heightSegments

    A number representing the number of height segments the cone will be made of.

HoloConeGeometry
var cone = new HoloBuild.HoloConeGeometry( 0.1, 30, 30 );
                       

HoloCylinderGeometry

The HoloCylinderGeometry is a 3D cylinder geometry made of several triangular segments. To construct a HoloCylinderGeometry you need to provided the cylinder top radius, bottom radius, and its height dimensions.

Constructor
  • radiusTop

    A number representing the cylinder top radius in meters.

  • radiusBottom

    A number representing the number of bottom radius in meter.

  • height

    A number representing the height of the cylinder.

  • radialSegments

    A number representing the number of radial segments the cylinder will be made of.

  • heightSegments

    A number representing the number of height segments the cylinder will be made of.

HoloCylinderGeometry
var cylinder = new HoloBuild.HoloCylinderGeometry( 0.1, 0.1, 0.1, 30, 30 );
                       

HoloDodecahedronGeometry

The HoloDodecahedronGeometry is a 3D dodecahedron geometry made of several triangular segments. To construct a HoloDodecahedronGeometry you need to provided the dodecahedron radius.

Constructor
  • radius

    A number representing the dodecahedron radius in meters.

HoloDodecahedronGeometry
var Dodecahedron = new HoloBuild.HoloDodecahedronGeometry( 0.1);
                       

HoloIcosahedronGeometry

The HoloIcosahedronGeometry is a 3D Icosahedron geometry made of several triangular segments. To construct a HoloIcosahedronGeometry you need to provided the Icosahedron radius.

Constructor
  • radius

    A number representing the Icosahedron radius in meters.

HoloIcosahedronGeometry
var Icosahedron = new HoloBuild.HoloIcosahedronGeometry(1);
                       

HoloOctahedronGeometry

The HoloOctahedronGeometry is a 3D octahedron geometry made of several triangular segments. To construct a HoloOctahedronGeometry you need to provided the octahedron radius.

Constructor
  • radius

    A number representing the octahedron radius.

HoloOctahedronGeometry
var Octahedron = new HoloBuild.HoloOctahedronGeometry(1);
                       

HoloPlaneGeometry

The HoloPlaneGeometry is a 3D plane geometry made of several triangular segments. To construct a HoloPlaneGeometry you need to provided the plan width and height.

Constructor
  • width

    A number representing the plane width in meters.

  • height

    A number representing the plane height in meters.

  • HSegments

    The number of the plane horizontal segments (optional).

  • VSegments

    The number of the plane vertical segments (optional).

HoloPlaneGeometry
var Plane = new HoloBuild.HoloPlaneGeometry(0.1,0.1);
                       

HoloRingGeometry

The HoloRingGeometry is a 3D ring geometry made of several triangular segments. To construct a HoloRingGeometry you need to provided the ring innerRadius and OuterRadius.

Constructor
  • innerRadius

    A number representing the ring inner radius.

  • outerRadius

    A number representing the ring o uter radius.

  • Round

    The number of the ring outer segments making it more or less round (optional).

  • PSegments

    The number of the ring segments (optional).

HoloRingGeometry
var Plane = new HoloBuild.HoloRingGeometry(0.1, 0.5);
                       

HoloSphereGeometry

The HoloSphereGeometry is a geometry of a sphere . To construct a HoloSphereGeomtry you need to provided the sphere radius.

Constructor
  • radius

    A number representing the sphere radius in meters.

  • HSegments

    The number of the sphere horizontal segments (optional).

  • VSegments

    The number of the sphere vertical segments (optional).

HoloSphereGeometry
var sphere = new HoloBuild.HoloSphereGeometry( 0.1, 30, 30);
                       

HoloTetrahedronGeometry

The HoloTetrahedronGeometry is a 3D tetrahedron geometry made of several triangular segments. To construct a HoloTetrahedronGeometry you need to provided the tetrahedron radius.

Constructor
  • radius

    A number representing the tetrahedron radius.

HoloTetrahedronGeometry
var Tetrahedron = new HoloBuild.HoloTetrahedronGeometry(1);
                       

HoloTorusGeometry

The HoloTorusGeometry is a 3D tetrahedron geometry made of several triangular segments. To construct a HoloTorusGeometry you need to provided the tetrahedron radius, and tube radius.

Constructor
  • radius

    A number representing the torus radius.

  • tube

    A number representing the tube radius.

  • Segments

    The number of the torus segments (optional).

  • TSegments

    The number of the tubular segments (optional).

  • arc

    A radian representing the central arc of the torus (optional).

HoloTorusGeometry
var Torus = new HoloBuild.HoloTorusGeometry(0.1,0.3);
                       

HoloShapeGeometry

The HoloShapeGeometry is a customizable 3D geometry made of several triangular segments. to construct a HoloShapeGeometry you need to provide a HoloShape and the corresponding shape settings.

Constructor
  • shape

    A customizable shape created using HoloShape().

  • {PARAMETERS}

    Shape settings for further cutomization.
    depth- float. Specifies the depth of the shape.

HoloShapeGeometry
var fishShape = new HoloBuild.HoloShape();
fishShape.moveTo(0,0);
fishShape.quadraticCurveTo(0.05, -0.08, 0.09, -0.01);
fishShape.quadraticCurveTo(0.1, -0.01, 0.115, -0.04);
fishShape.quadraticCurveTo(0.115, 0, 0.115, 0.04);
fishShape.quadraticCurveTo(0.1, 0.01, 0.09, 0.01);
fishShape.quadraticCurveTo(0.05, 0.08, 0, 0);

var fishGeometry = new HoloBuild.HoloShapeGeometry(fishShape, {depth:0.1});

var fishMesh = new HoloBuild.HoloMesh(fishGeometry, new HoloBuild.HoloMeshStandardMaterial({ color: 0x0000ff }));

holoscene.add(fishMesh);

HoloPointsGeometry

The HoloPointsGeometry is a geometry formed from a group of points or vertices. To construct a HoloPointsGeomtry you need to provide an array of points or a HoloShape.

Constructor
  • points or shape.

    An array of points or a shape created prior to the constructor call using HoloShape.

HoloPointsGeometry
Try this with the fishShape example used for HoloShapeGeometry:
var pointsGeo = new HoloBuild.HoloPointsGeometry(fishShape);
var pointsMaterial = new HoloBuild.HoloPointsMaterial({color : 'red', size: 0.01});
var pointsMesh = new HoloBuild.HoloPoints(pointsGeo, pointsMaterial);
holoscene.add(pointsMesh);
                       
or using an array of points:
var pointsGeo = new HoloBuild.HoloPointsGeometry(fishShape.getPoints());
var pointsMaterial = new HoloBuild.HoloPointsMaterial({color : 'red', size: 0.01});
var pointsMesh = new HoloBuild.HoloPoints(pointsGeo, pointsMaterial);
holoscene.add(pointsMesh);
                       

Materials

A material defines how the surface of a geometry is. It describes the geometry appearance such as its color or its texture (i.e. skin).
There are several types of material that you can use such as the HoloMeshBasicMaterial, HoloMeshStandardMaterial, or the HoloMeshPhongMaterial. Each with its own properties and is applyies to a specific Hologram object. For example, a HoloMesh object can have a HoloMeshBasicMaterial, whereas a HoloLine object can have a HoloLineDashedMaterial.
Note: the HoloMeshBasicMaterial has the best performing material for a HoloMesh.

HoloMeshBasicMaterial

The HoloLens HoloMeshBasicMaterial defines how the surface of a geometry is. It describes the geometry appearance such as its color or its texture (i.e. skin). By default, the "Color" of the material is set to white, and you can change it to any color you want.

Properties
  • color

    Represents the color of the material.

  • map

    Represents the color map.

  • wireframe

    Render the mesh geometry as wireframe.

  • opacity

    Represents the mesh opacity ranging from 0 to 1. If set to 0 then the material is fully transparent and if set to 1 then the material is fully opaque. Default is 1.

HoloMeshBasicMaterial
var material = new HoloBuild.HoloMeshBasicMaterial( { color: "green" } );
                       

HoloMeshStandardMaterial

The HoloLens HoloMeshStandardMaterial, similar to a HoloMeshBasicMaterial defines how the surface of a geometry is. It describes the geometry appearance such as its color or its texture (i.e. skin). By default, the "Color" of the material is set to white, and you can change it to any color you want. HoloMeshStandardMaterial give a more realistic looking material for Holograms than all the other material, but it is more expensive in terms of computaional resources.

Properties
  • color

    Represents the color of the material.

  • map

    Represents the color map.

  • wireframe

    Render the mesh geometry as wireframe.

  • opacity

    Represents the mesh opacity ranging from 0 to 1. If set to 0 then the material is fully transparent and if set to 1 then the material is fully opaque. Default is 1.

HoloMeshStandardMaterial
var material = new HoloBuild.HoloMeshStandardMaterial( { color: "green" } );
                       

Holograms

Holograms are 3D digital objects that appear in the world around you as if they are real objects. Holograms respond to your interaction (gaze, gestures...) and to the physical world surfaces around you. For the most part, a HolographicMesh can be used to create different types of Holograms, and to group several Holograms together you use a HoloGroup. For specific types of geometries, such as line or a point, you have to use a different type of a mesh (HoloLineMesh or HoloPointMesh).

HoloMesh

A HolographicMesh is an object that takes a geometry and applies a material to it. So it is the combination of a geometry and material into one 3D object or a hologram that can then be added to a HoloSpace.

Constructor
  • geometry

    The geometry is the structure or the shape of a hologram.

  • material

    A material defines how the appearance of a geometry.

  • {PARAMETERS}

    A set of parameters containing two values:
    propagate: boolean. Specify wheter actions, such as onTap, should propagate to the parent or not. Default is true
    isHotspot: boolean. Default is false.

Properties
  • children

    Returns an array of the HoloMesh's children.

  • id

    A unique HoloMesh numeric identifier (readonly).

  • name

    Represent the HoloMesh's name.

  • parent

    Represent the HoloMesh's parent.

  • position

    Represent the HoloMesh's local position.

  • rotation

    Represent the HoloMesh's local rotation (in radians).

  • scale

    Represent the HoloMesh's local scale.

  • holoType

    Returns the type of this object. Example: HoloMesh.

  • userData

    An object that could be used by developers to store their own custom data about the HoloMesh.
    Note:It should not hold references to functions.
    Example: HoloMesh.userData = { propertyname: “property value” };
    And to use the property: HoloMesh.userData.propertyname;

  • visible

    if set to false the HoloMesh would not get rendered.

Methods
  • onGaze
    = callbackfunction

    The callbackfunction that is called when a user gazes on a mesh. Note: This function depends on two other properties.onGaze.repeat: boolean that specifies if the callback function will repeat if the user is still gazing on the mesh. Default is false. onGaze.timer: float that represents the time to fire the callback after the user gazes on the mesh. And in the case that repeat is true, it acts as an interval between every callback.

  • onGazeEnter
    = callbackfunction

    The callbackfunction that is called onGazeEnter event: when the user gaze on the HoloMesh.

  • onGazeExit
    = callbackfunction

    The callbackfunction that is called onGazeExit event: when the user gaze does not intersect with the HoloMesh anymore.

  • onTap
    = callbackfunction

    The callbackfunction that is called on a tap event: a combination of user gaze on the HoloMesh and hand presses and releases gesture. Other ways for the onTap function to be called is by pressing the button on a HoloLens Clicker or by speaking the voice command "Select".
    Note: for the onTap event to work, the object hotspot parameter must be set to true.

  • onHold
    = callbackfunction(
    previousPos,
    currentPos)

    The callbackfunction that is called on a hold event: a combination of user gaze on the HoloMesh and the user hand press and moving gesture. The callbackfunction will be called with 2 positions vectors, the previous position and the current one.

  • onRelease
    = callbackfunction

    The callbackfunction that is called on a release event: a combination of user gaze on the HoloMesh and hand releases gesture. Other ways for the onRelease function to be called is if the user gestures get lost from the frame of view.

  • setAnimImage(image, {PARAMETERS})

    The setAnimImage sets an animated image on the HoloMesh, it takes as input an image file name. The image file contains a set of images (or frames) concatenaded next to each, which will be played in a loop (similar to an animated gif). An example animated gif: animated-block.gif Optionally the set image can take other parameters as an object that can contain the following:
    textureAnimWidth — Float. The frame width, by default the frame width is considered equale to the image height.

  • setImage(image,
    {PARAMETERS},
    callback)

    The setImage sets an image on the HoloMesh, it takes as input an image file name. Optionally the set image can take other parameters as an object that can contain the following:
    repeat — Boolean. If true the image will be repeated across the HoloMesh. Default is false.
    stretch — Boolean. If true the image will be stretched across the HoloMesh. Default is true.
    textureRepeatX — Number. How many times the texture is repeated across the X axis. Default is 1.
    textureRepeatY — Number. How many times the texture is repeated across the Y axis. Default is 1.
    Note: the image should be sized to a power of 2 (ie 256, 512, 1024).

  • setTagAlong(boolean,{PARAMETERS})

    if set to true, the HoloMesh will never fully leaves the user's view. it will act as if it is attached to the user's head by rubber bands: When the user moves, the content will stay in his view. {PARAMETERS}:
    distance: HoloVector3. Specifies how far the HoloMesh would be from the user: var tagAlongDistance = new HoloBuild.HoloVector3(0,0,0.5);
    radius: - float. Specifies how far should the cursor be from the holoMesh before it adjusts and return to the field of view. Default is the radius of the bounding sphere of the HoloMesh.

  • setTooltip(value,
    {PARAMETERS})

    The setTooltip shows a text on top of the HoloMesh that will be shown if the user hover at the HoloMesh for over a 1 second, it takes as input a text value. Optionally the setTooltip can take other parameters as an object that can contain the following:
    fontSize — number. The tooltip size. Default is 0.021 meters.
    color — color. The tooltip text color. Default is 0xFFFFFF.
    bgColor — color. The tooltip backgrounf color. Default is 0x048ad7.
    showLine — Boolean. If set to true the tooltip will have a dotted line drawn from the ToolTip down to the HoloMesh. Default is false.
    rounded — Boolean. If true, the tooltip will be rounded. Default is set to true.
    borderColor- color. The tooltip border color. Default is null.
    hoverTime- float. Time to show the tooltip. Default 0.7 seconds
    position- stirng. Specify wheter the toolTip should appear from above or below the mesh. Options are "top" and "bottom". Default is "top"
    gap — number. The gap in meteres between the HoloMesh and the tooltip. Default is 0.035.
    yPos — number. The tooltip size. Default is 0.
    faceCamera — Boolean. If the tooltip will always face the user or not. Default is true.

  • unsetTooltip()

    Removes any attached tooltip from the mesh. This does not hide the tooltip, so once you unset it you must set it again using the setTooltip method above.

  • animateMove (loc, duration, pause, callback,
    {parameters})

    animateMove method provides an animated move that interpolate between the current position and the new location. Location is a 3D vertix. It also takes as input an animation duration, an animation pause before start, and a callback function when the animation is done.
    Optional parameters include:
    incrementX, incrementY, and incrementZ a boolean parameter for each axis, if set to false it will move the mesh to the new pos, if set to true it will increment the mesh current position with the old position based on that axis. Default is true
    Example 1:
    holomesh.position.set(0, 0, 0.5);
    holomesh.animateMove({ x: 0, y: 0, z: 0.1 }, 750, 250);

    In This example the holomesh will move to Z 0.6 (an increment on its current position), the animation will then pause for 250 milliseconds, and will last for 750 milliseconds.

    Example 2:
    holomesh.animateMove( { x: 0, y: 0, z: 0.1 }, 750, 250, '', {incrementZ:false} );

    In This example the holomesh will move to Z 0.1, the animation will then pause for 250 milliseconds, and will last for 750 milliseconds.

  • animateScale (scale, duration, pause, callback,
    {parameters})

    animateScale is similar to animateMove but for scaling. This method provides an animated scale that interpolate between the current scale and the new scale. Scale is a 3D vertix. It also takes as input an animation duration, an animation pause before start, and a callback function when the animation is done.
    Optional parameters include: incrementX, incrementY, and incrementZ a boolean parameter for each axis, if set to false it will scale the mesh to the new scale, if set to true it will increment the mesh current scale with the old scale based on that axis. Default is true

  • animateRotate(angles, duration, pause,
    callback, {parameters})

    animateRotate is similar to animateMove, and it provides an animated rotation. Note that animate Rotate optional parameter only has increment parameter that is set to true or false and that affect all axis.


  • animateFade(opacity, duration, pause,
    callback)

    animateFade is similar to animateMove, and it provides an animated opacity change.

  • moveOnSpline(parameters,
    callback)

    Move the holomesh along a spline or a curve and returns a HoloSplineMovement object which has the methods start() and stop() to control the animation at any point. Start() is called implicitly upon calling moveOnSpline(). The function takes the following set of parameters:
    time — number. The time where you start the movement in a curve, a numbe between 0 and 1. Default is 0.
    counter — number. A percentage out of 1 of the number of steps in a single loop. the step counter is a number between 0 and 1. The higher the number the faster the movement. Default is 0.01
    interval — number. The number in miliseconds for each movement step, the lower the number the faster the movement. Default is 10.
    loop — boolean. If true, the movement will repeat otherwise it wll run onc. Default is true.
    spline — HoloCurve. The curve that the movement will follow. The following is a set of predefined curves: HoloSplineCurve([HoloVector2]), HoloEllipseCurve(x,y,xradius, yradius, startangle, endangle), HoloLineCurve3(HoloVector3, HoloVector3), HoloCatmullRomCurve3([HoloVector3]), HoloCubicBezierCurve3(HoloVector3, HoloVector3, HoloVector3, HoloVector3), QuadraticBezierCurve3(HoloVector3, HoloVector3, HoloVector3)

    Example: var curve = new HoloBuild.HoloLineCurve3(new HoloBuild.HoloVector3(-0.1, 0, 0),new HoloBuild.HoloVector3(-0.05, 0.15, 0));
    mesh.moveOnSpline({counter: 0.001, loop: true, spline: curve}, function () {});

    This method can be chained with the following two methods for additional functionalities
    setFunction: sets a call back function that is called on each interval.
    clearFunction: clears the function set with setFunction.
    Example: mesh.moveOnSpline().setFunction(function () {console.log('moving');})

    You can also set the parameters of the spline movmenet by using the method: setParam({ parametername: parameterValue })
    Example: var moveOnSpline = mesh.moveOnSpline({counter: 0.001, loop: true, spline: curve}, function () {});
    moveOnSpline.setParam({spline: newSpline});

  • show ()

    Calling the Show methods will enable the renderer to render the HoloMesh on its next update. Note that the method Show will also affect the opacity of the mesh: it will reset the mesh opacity to 1. If you don't want the opacity to be affected you can use visible to true instead.

  • hide ()

    Calling the hide methods will hide the HoloMesh from the HoloSpace.

  • dispose

    Calling the dispose methods will deallocate the HoloMesh from memory.

  • add (object)

    Add a child object to the HoloMesh.

  • clone ()

    Returns a clone of the HoloMesh.

  • getObjectById (id)

    Searches through the HoloMesh's children and returns the object with a matching id.

  • getObjectByName
    (name)

    Searches through the HoloMesh's children and returns the first object with a matching name.

  • getObjectByProperty
    (propertyname)

    Searches through the HoloMesh's children and returns the first object with a matching propertyname.

  • getWorldPosition ()

    Returns a vector representing the position of the HoloMesh in the world space.

  • getWorldRotation ()

    Returns a vector representing the rotation of the HoloMesh in the world space.

  • getWorldScale ()

    Returns a vector representing the scaling factors applied to the HoloMesh in the world space.

  • getWorldDirection ()

    Returns a vector representing the direction of HoloMesh's positive z-axis in the world space.

  • remove (object)

    Removes a child object from the HoloMesh.

  • toJSON ()

    Convert the HoloMesh to JSON format.

  • showAdjust
    ({PARAMETERS})

    Once the showAjdust method is called, a helper box will be drawn on top of the attached HoloMesh to allow the user to manipulate the object. Manipulation of the mesh includes: moving, rotating, and scaling the mesh. You set which manipulation capabilities you want the user to be allowed to do by setting the parameters as follows:
    rotate — Boolean. True will enable the vertical and horizontal rotation of a mesh. Default is true.
    rotateVertical — Boolean. True will enable the vertical rotation of a mesh. Default is true.
    rotateHorizontal — Boolean. True will enable the horizontal rotation of the mesh. Default is true.
    scale — Boolean. True will enable the scaling of the mesh. Default is true.
    move — Boolean. True will enable the moving of the mesh. Default is true.
    done — Boolean. True will enable a done button to be shown with the adjust controls, false will not show the done button. Default is true.

  • animationClip
    (clipname)

    animationClip is a special method that loads the animation clips available for the mesh using the clip name. This method returns an instance of the HoloAnimation class that includes the following methods to manage an animation clip:
    run() — a method to start running the animation.
    pause() — a method to pause the animation.
    stop() — a method to stop the playing animation.
    reset() — a method to reset the playing animation.
    isRunning() — a method that returns true if the action is running.
    isEnabled() — a method that returns true for the current clip.
    setEffectiveTimeScale(number) — a method to set the timescale of the clip: 0 will pause the animation, a postive number will play the animation and anegative will paly it backward.
    fadeIn(time) — a method to fade in the playing animation by a time in seconds.
    fadeOut(time) — a method to fade in the playing animation by a time in seconds.
    crossFadeFrom(clip, time, warp) — a method to fade in a clip and fade out another clip within a time (wrap is a boolean if set to true will wrap the animation from one to the other).
    crossFadeTo(clip, time, warp) — a method to fade out a clip and fade out to another clip within a time (wrap is a boolean if set to true will wrap the animation from one to the other).
    startAt(time) — a method to start the animation at a given numeric time in seconds.

  • addIndicator
    ({PARAMETERS});

    Sometims a HoloMesh is outside of the user's field of view, or occlude by real world objects, and it is important to make it easier for the user to find that HoloMesh. You can use the addIndicator method which will shows in the form of a directional arror, or your own holomesh object, in order to alert the user to that important content and provide guidance related to the user's position.
    The directional indicator will appear when the user is looking away from the HoloMesh. The arrow like direction indicator will point the user toward the HoloMesh, if it is away from the user's view and away to a specfic distance you can specify.
    This function takes an array of Parameters:
    distance — The indicator will continue to show until the minimum distance in meter to the HoloMesh is reached. Default
    color — By default the indicator is an arrow, you can change the default cursor color by specifing the color parameter. Default: 'red'
    object — This own HoloMesh object that you can use as a direction indicatory (optional).

  • removeIndicator();

    Removes the direction indicator that was already set on that HoloMesh (see addIndicator for more information).

  • tapToPlace
    (objTap, callback,
    {parameters});

    This method is used when you want to position a mesh according to another tagged along mesh. It is useful when you start a scene and you want the user to select where to position their mesh.
    objTap HoloMesh- The tagged along mesh (usually a button that the user will tap on to place a mesh).
    callback Function- The callback function to be called when the tagged along mesh is tapped.
    parameters set of parameters: onSurface (boolean - if true the object must be placed on a surface), positon (vector3 - default tag along position).
    Example: MainMesh.tapToPlace(btnTaptoPlace, undefined, {position: new HoloBuild.HoloVector3(0,0,1)});

  • placeOnObject
    (mesh, targetObj, {parameters});

    This method is used when you want to position a mesh on an object and according certain parameters.
    mesh HoloMesh- The mesh you want to place.
    targetObject HoloMesh/Hologroup- The target object.
    parameters set of parameters: axis (char - the axe you want to position: 'x', 'y', 'z'), rotate (boolean - whether to rotate the mesh or not).
    Example: this.placeOnObject(mesh, planeMeshD, { rotate: true, axis: 'y' });

HoloMesh

var geometry = new HoloBuild.HoloBoxGeometry( 0.1, 0.1, 0.1 );
var material = new HoloBuild.HoloMeshBasicMaterial( { color: 'red' } );
var holomesh= new HoloBuild.HoloMesh( geometry, material );
                       

OnGaze example:
holomesh.onGaze = function () {
    /*Some logic that executes onGaze every "timer" seconds*/
};
holomesh.onGaze.repeat = true;
holomesh.onGaze.timer = 3;
                       
You can use the onTap property if you want to add a function to when the user tap the holomesh. Note how we set the hotspot property to true to the holomesh to enable interaction witht he HoloCursor. For example, if we want to rotate the holomesh on the x axis when the user tap on it we can do the following:
var holomesh= new HoloBuild.HoloMesh( geometry, material , true);
holomesh.onTap = function () {
holomesh.rotation.x +=0.1;
}
    
You can use the onHold property if you want to add a function to when the user gaze on the holomesh and moving his hand while holding the press gesture. For example, if we want to change the holomesh position on the x axis according to the users hand, we can do the following:
holomesh.onHold = function (previousPos, CurrentPos) {
holomesh.position.x -= (previousPos.x - CurrentPos.x);
}
    

You can use the setImage method to set an image to the HoloMesh.
holomesh.setImage('imagename.png')
If you want to use the setImage parameters, you do the following:
holomesh.setImage('imagename.png',{repeat:true})

setToolTip example
Let us show a tooltip showing a line on top of a HoloMesh:
HoloMesh ToolTip
A ToolTip saying hello over a yellow box holomesh. Notice the cursor, the tooltip only shows when the user is looking at the holomesh.

var holomesh= new HoloBuild.HoloMesh( geometry, material , true);
holomesh.setTooltip('Hello', {showLine:true});

ShowAdjust example
Let us show a HoloMesh Adjust box when a user tap on a holomesh:
HoloMesh Adjust Box
ShowAdjust Box on a yellow sphere holomesh. Notice the holocursor showing a rotation icon, and the done button to commit the adjustment when the user click on the done button.

var holomesh= new HoloBuild.HoloMesh( geometry, material , true);
holomesh.onTap = function (){
holomesh.showAdjust();    
};

HoloGroup

A HoloGroup is a component that holds a group of HoloMeshes.

Properties
  • children

    Returns an array of the HoloGroup's children.

  • id

    A unique HoloGroup numeric identifier (readonly).

  • name

    Represent the HoloGroup's name.

  • parent

    Represent the HoloGroup's parent.

  • position

    Represent the HoloGroup's local position.

  • rotation

    Represent the HoloGroup's local rotation (in radians).

  • scale

    Represent the HoloGroup's local scale.

  • holoType

    Returns the type of this object. Example: Group.

  • userData

    An object that could be used by developers to store their own custom data about the HoloGroup.
    Note:It should not hold references to functions.
    Example: holoGroup.userData = { propertyname: “property value” };
    And to use the property: holoGroup.userData.propertyname;

  • visible

    if set to false the HoloGroup would not get rendered.

  • onTap
    = callbackfunction

    The callbackfunction that is called on a tap event: a combination of user gaze on any child mesh of the HoloGroupand hand presses and releases gesture. Other ways for the onTap function to be called is by pressing the button on a HoloLens Clicker or by speaking the voice command "Select".
    the tap even will be called for the HoloGroup and the HoloMesh that was tapped (only one level up and down). Note: for the onTap event to work, the object hotspot parameter must be set to true.

Methods
  • add (object)

    Add a child object to the HoloGroup.

  • clone ()

    Returns a clone of the HoloGroup.

  • getObjectById (id)

    Searches through the HoloGroup's children and returns the object with a matching id.

  • getObjectByName
    (name)

    Searches through the HoloGroup's children and returns the first object with a matching name.

  • getObjectByProperty (propertyname)

    Searches through the HoloGroup's children and returns the first object with a matching propertyname.

  • getWorldPosition ()

    Returns a vector representing the position of the HoloGroup in the world space.

  • getWorldRotation ()

    Returns a vector representing the rotation of the HoloGroup in the world space.

  • getWorldScale ()

    Returns a vector representing the scaling factors applied to the HoloGroup in the world space.

  • getWorldDirection ()

    Returns a vector representing the direction of HoloGroup's positive z-axis in the world space.

  • setTagAlong(boolean, distance)

    if set to true, the HoloGroup will never fully leaves the user's view. it will act as if it is attached to the user's head by rubber bands: When the user moves, the content will stay in his view. The distance paramerts is an optional parameter that specify how far the HoloGroup is from the user. The distance is a HoloVector3: var tagAlongDistance = new HoloBuild.HoloVector3(0,0,0.5);

  • remove (object)

    Removes a child object from the HoloGroup.

  • toJSON ()

    Convert the HoloGroup to JSON format.

  • show ()

    Calling the Show method will enable the renderer to render the HoloGroup on its next update. Note that the method Show will also affect the opacity of the group: it will reset the mesh opacity to 1. If you don't want the opacity to be affected you can use visible to true instead.

  • hide ()

    Calling the hide methods will hide the HoloGroup from the HoloSpace.

  • showAdjust
    ({PARAMETERS})

    Once the showAjdust method is called, a helper box will be drawn on top of the attached HoloGroup to allow the user to manipulate the group. Manipulation of the group includes moving, rotating, and scaling the group. You set which manipulation capabilities you want the user to be allowed to do by setting the parameters as follows:
    rotate — Boolean. True will enable the vertical and horizontal rotation of a group. Default is true.
    rotateVertical — Boolean. True will enable the vertical rotation of a group. Default is true.
    rotateHorizontal — Boolean. True will enable the horizontal rotation of the group. Default is true.
    scale — Boolean. True will enable the scaling of the group. Default is true.
    move — Boolean. True will enable the moving of the group. Default is true.

  • hideAdjust ()

    Once the hideAjdust method is called, the helper box shown in the showAdjust will be forces to be hidden. The user adjust changes will be commited.

  • tapToPlace
    (objTap, callback,
    {parameters});

    This method is used when you want to position a hologroup according to another tagged along mesh. It is useful when you start a scene and you want the user to select where to position their group.
    objTap HoloMesh- The tagged along mesh (usually a button that the user will tap on to place a group).
    callback Function- The callback function to be called when the tagged along mesh is tapped.
    parameters set of parameters: onSurface (boolean - if true the object must be placed on a surface), positon (vector3 - default tag along position).
    Example: MainGroup.tapToPlace(btnTaptoPlace, undefined, {position: new HoloBuild.HoloVector3(0,0,1)});

  • dispose ()

    Calling the dispose methods will deallocate the HoloGroup from memory.

HoloGroup
var group = new HoloBuild.HoloGroup();
group.add(holomesh);
                       

HoloPoints

The HoloPoints is a class that represents 3d points, it takes as input a geometry of vertices and apply a points material to them. Use this class if you want to add points into your 3d space.

Constructor
  • geometry

    a geometry containing the vertices.
    To define a geometry of vertices use the class HoloGeometry() to define the gometry and HoloVector3() to define the vertices.
    var pointsGeometry = new HoloBuild.HoloGeometry();
    var point1 = new HoloBuild.HoloVector3(0.1, 0.1, 0.1);
    pointsGeometry.vertices.push(point1);

  • pointsmaterial

    A points material that could applied to points.
    To define a points material use the class HoloPointsMaterial(parameters)
    HoloPointsMaterial parameters includes:
    color — Color. the material color. Default is 0xffffff or white.
    size — Number. the default point size. Default is 1.

HoloPoints
var pointsGeometry = new HoloBuild.HoloGeometry();
var point1 = new HoloBuild.HoloVector3(0.1, 0.1, 0.1);
var point2 = new HoloBuild.HoloVector3(0.2, 0.2, 0.2);

pointsGeometry.vertices.push(point2);
pointsGeometry.vertices.push(point1);

var pointsMaterial = new HoloBuild.HoloPointsMaterial({color : 'red', size: 0.01});
var points = new HoloBuild.HoloPoints(pointsGeometry, pointsMaterial);
holoscene.add(points)
                       

HoloLine

The HoloLine is a class that represents a line, it takes as input a geometry of vertices and apply a line material to them. Use this class if you want to add a lines into your 3d space.

Constructor
  • geometry

    a geometry containing the vertices.
    To define a geometry of vertices use the class HoloGeometry() to define the gometry and HoloVector3() to define the vertices.
    var pointsGeometry = new HoloBuild.HoloGeometry();
    var point1 = new HoloBuild.HoloVector3(0.1, 0, 0);
    var point2 = new HoloBuild.HoloVector3(0, 0.2, 0);
    pointsGeometry.vertices.push(point1);
    pointsGeometry.vertices.push(point2);

  • linematerial

    A line material that could applied to points.
    To define a line material you can use one of the following two classes HoloLineBasicMaterial(parameters) or HoloLineDashedMaterial(parameters)
    The first draw a simple line, the second draws a dashed one
    the HoloLineBasicMaterial parameters includes:
    color — Color. the material color. Default is 0xffffff or white.
    the HoloLineDashedMaterial parameters includes:
    color — Color. the material color. Default is 0xffffff or white.
    dashSize — Number. the dash size. Default is 3.
    gapSize — Number. the gap size. Default is 1.

HoloLine
var pointsGeometry = new HoloBuild.HoloGeometry();
var point1 = new HoloBuild.HoloVector3(0.1, 0, 0);
var point2 = new HoloBuild.HoloVector3(0, 0.2, 0);
var point3 = new HoloBuild.HoloVector3(0.3, 0.0, 0.0);

pointsGeometry.vertices.push(point1);
pointsGeometry.vertices.push(point2);
pointsGeometry.vertices.push(point3);

var lineMaterial = new HoloBuild.HoloLineBasicMaterial({color : 'red'});
var lines = new HoloBuild.HoloLine(pointsGeometry, lineMaterial);
holoscene.add(lines);
                       

HoloLoaders

The HoloLoaders is a class loads objects from file and return a mesh, a geometry, or a group.

Methods
  • loadModel
    (type, filename,
    callback(model),
    {parameters})

    Load a 3d model from a file.
    type — String. The model type that you want to load, values include: HoloBuild.loader.OBJ(), HoloBuild.loader.STL(), orHoloBuild.loader.JSON()

    filename — Color. the material color. Default is 0xffffff or white.
    callback(model) — Function. the function that will be called back when the model is loaded, with the actual model.
    parameters — List of optional parameters to apply. This includes: material to apply a specific material to your model, mtlPath to apply a material to the model loaded from a file, hotspot() a boolean that if set to true will enable the interaction with the model, or group a boolean to whether to return the model as a group or merge it as one mesh. Note that mtlPath requires a group so you must set the parameters group to true for the material to be applied. resetModel a boolean that specifies whether the model should get loaded in the center of the scene. This is only supported for OBJ format models.

  • loadGeometry
    (type, filename,
    callback(geometry)

    Load a geometry from a file.
    type — String. The geometry type that you want to load, values include: HoloBuild.loader.OBJ(), HoloBuild.loader.STL(), orHoloBuild.loader.JSON()
    filename — Color. the material color. Default is 0xffffff or white.
    callback(geometry) — Function. the function that will be called back when the geometry is loaded, with the actual geometry. The retuned geometry object return is a holder of multiple types of geometry such as meshGeometry, lineGeometry, or pointGeometry. To access a meshGeometry for example you must call the geometry.meshGeometry object.
    parameters — List of optional parameters to apply. This include: array boolean parameter if set to true will return an array of geometries instead of one geometry.

HoloLoaders
var loaders = new HoloBuild.HoloLoaders();
loaders.loadModel(HoloBuild.loader.JSON, 'flamingo.js', function (model) {
    model.scale.set(0.003, 0.003, 0.003);
    holoscene.add(model);
}, {
        hotspot: true
});
                       
var loaders = new HoloBuild.HoloLoaders();
loaders.loadModel(HoloBuild.loader.OBJ, 'model.obj', function (model) {
    //note that some model could be too large so you need to scale them down otherwise they will not be visible
    model.scale.set(0.03, 0.03, 0.03);
    holoscene.add(model);
}, {
        hotspot: true,
        mtlPath: 'material.mtl',
        group: true
});
                       
var loaders = new HoloBuild.HoloLoaders();
loaders.loadGeometry(HoloBuild.loader.STL, 'flamingo.stl', function (geometry) {
    var mesh = new HoloBuild.HoloMesh(geometry.meshGeometry,
        new HoloBuild.HoloMeshBasicMaterial({ color: 0xA3ADAB })); 
    holoscene.add(mesh);
}, {
        array: false;
});
                       

Lights

A light provides a digital illumicatio of the Holograms in your HoloSpace. There are several types of lights that you can add to you HoloSpace. The system by default adds an ambient light, otherwise all Holograms will show up as black. An ambinet light will light all the Holograms in your scene equally as it doesn't have a directon. If you want a light that emits in a specific direction, then you need to use a HoloDirectionalLight. For a light that emits from a single point, such as from a light bulb, use a HoloPointLight. The following section will go over the different types of lights available in more details:

HoloDirectionalLight

The HoloDirectionalLight emits light in a specific direction similar to a light from the sun.

Constructor
  • color

    Represents the color of the light, default is 0xffffff or white.

  • intensity

    A numeric value representing the intensity of the light, default is 1.

HoloDirectionallight
var dirLight = new HoloBuild.HoloDirectionalight( 0xf1f1f1, 0.7 );
                       

HoloPointLight

The HoloPointLight emits light from a specific point, similar to a light from a bulb.

Constructor
  • color

    Represents the color of the light, default is 0xffffff or white.

  • intensity

    A numeric value representing the intensity of the light, default is 1.

  • distance

    The distance the light can travel, default is 1.

HoloPointlight
var pointLight = new HoloBuild.HoloPointlight( 0xf1f1f1, 0.7, 0.5 );
                       

HoloSpotLight

The HoloSpotLight emits light from a specific point as a cone shape.

Constructor
  • color

    Represents the color of the light, default is 0xffffff or white.

  • intensity

    A numeric value representing the intensity of the light, default is 1.

  • distance

    The distance the light can travel, default is 1.

  • angle

    The angle of the cone that light will form.

HoloSpotlight
var spotLight = new HoloBuild.HoloSpotlight( 0xf1f1f1, 0.7, 0.5, 0.4 );
                       

UI Components

The following section go over the holobuild library User Interface components. These include components ranging from navigation Holograms, such as a HoloButton or a HoloToolbar, to input controls such as a HoloStepper.

HoloLabel

The HoloLabel represents a label component used to display text in a HoloSpace. The HoloLabel is also useful when you want to show a text with a language that is not supported by the HoloLens, such as Chinese, Arabic, or Russian letters. The HoloLabel extends the HoloGroup class, it inherits all the HoloGroup's properties and methods.

Constructor
  • name


    The label name. It should be a unique name in your application.

  • text

    The text to be displayed.
    text — String. One line text.
    OR
    text — Array of Strings. Multi-line text.

  • {PARAMETERS} optional

    An object that can contain the following parameters:
    fontSize — Float. Size of the text (text height). Default is 0.015 meters..
    color — Color. The text color. Default is set to 0x101010.
    width — Float. The label width. Default is set to 0.08.
    height — Float. The label height. Default is set to 0.
    padding — Float. The text padding to its background. Default is 0.02.
    bgColor — Color. The text background color. Default is transparent.
    borderColor — Color. The label border color. Default is transparent.
    rounded — Boolean. If true, the HoloLabel will be rounded. Default is set to false.
    hotspot — Boolean. If true, the cursor will intersect with the HoloLabel. Default is set to true.
    align — String. ('left', 'right', 'center'). the label text will be aligned accordingly. Default is set to center. The width parameter needs to be filled for the left or right alignemnt to work.

Methods
  • setText(text,
    {PARAMETERS})

    Set or Change the HoloLabel text to text
    text — String. One line text.
    OR
    text — Array of Strings. Multi-line text.
    PARAMETERS is an optional object that can contain the following parameters:
    fontSize — Float. Size of the text (text height). Default is 0.015 meters..
    color — Color. The text color. Default is set to 0x101010.
    align — String. ('left', 'right', 'center'). the label text will be aligned accordingly. Default is set to center. The width parameter needs to be filled for the left or right alignemnt to work.

  • getText()

    Return the HoloLabel text as a string.

  • getHeight()

    Return the HoloLabel current height.

  • setParam({ parametername: parameterValue })

    Set any of the HoloLabel's parameters. Taking the parameter name and parameter value.
    Example: setParam({ text: 'setParam', color: 0xFF0000});

HoloLabel
var labelTest = new HoloBuild.HoloLabel('lblName', 'hello', { fontSize: 0.02, color: 0x101010, bgColor: 0xFFFF00, padding: 0.03 } );
                       
To change the text of the label above:
labelTest.setText('world');
To change the text to multiple lines of text:
labelTest.setText(['Hello', 'World']);
'Hello' will be one line and 'World' will be on the next line.

HoloButton

The HoloButton represents an image based button component in a HoloSpace. Since the HoloButton extends the HoloMesh class, it inherits all the HoloMesh's properties and methods.

Constructor
  • name

    The HoloButton Name. It should be a unique name in your application.

  • width

    The HoloButton width.

  • height

    The HoloButton height.

  • depth

    The HoloButton depth, 0 for a plane geometry and > 0 for a box geometry.

  • {PARAMETERS} optional

    An object that can contain the following parameters:
    bgColor — String Hex Color. Background button color. Default is 0x3c3c3c.
    bgTransparent — Boolean. If set to true, the button will have a transparent background. Default is false.
    bgShape — String. Options are 'circle' and 'square'. Default is 'square'.
    borderColor — String Hex Color. Border color that will be shown when the button is clicked.
    borderThickness — Float. Border thickness in pixels that will be shown when the button is clicked. Default is 3 pixles.
    borderGap — Boolean. Specify whether the border should be offset a little into the button or not. If set to true(default value) the border will be drawn inside the button by a very small offset.
    hoverState — Boolean. Whether a hover effect is available or not. Default is true.
    hoverBorderColor — String Hex Color. Hover border color that will be shown when the button is hovered.
    hoverBorderThickness — Float. Hover border thickness in pixels that will be shown when the button is hovered. Default is 3 pixles.
    clickState — Boolean. Whether a click effect is available or not. Default is true.
    clickBorderColor — String Hex Color. Click border color that will be shown when the button is clicked.
    clickBorderThickness — Float. Click border thickness in pixels that will be shown when the button is clicked. Default is 4 pixles.
    image — String. Image filename that will show as the button background.
    text The button text. Default is null.
    fontSize The button text font size. Default is 0.015 meters.
    fontColor The button text font color. Default is 0xFFFFFF.
    fontWeight The button text font weight. Default is 'normal'.
    textAnchor: The button text position: HoloBuild.textAnchor.CENTER, .TOPLEFT, .TOPCENTER, .TOPRIGHT, .BOTTOMLEFT, .BOTTOMCENTER, .BOTTOMRIGHT . Default is .CENTER.
    soundMute — Boolean. if set to true will disable the spatial sound that will be played when a user tap on the button.
    sound — String. the filename of the sound file that will be played when a user tap on the button.

    To create your button image, use the Selawik Regular font for consistency and the following PSD file for buttons icons icons.psd For the icon set used by the Hololens, use the following fonts: holomdl2.ttf and HoloSymMDL2.ttf

Methods
  • setEnabled();

    This method will either disable the button or enable it. . If the button is disabled, it cannot take any user interaction.

  • setText(text,
    {PARAMETERS});

    Set or Change the HoloButton text text value.
    PARAMETERS is an optional object that can contain the following parameters:
    fontSize The button text font size. Default is 0.015 meters.
    fontColor The button text font color. Default is 0xFFFFFF.
    fontWeight The button text font weight. Default is 'normal'.
    textAnchor: The button text position: HoloBuild.textAnchor.CENTER, .TOPLEFT, .TOPCENTER, .TOPRIGHT, .BOTTOMLEFT, .BOTTOMCENTER, .BOTTOMRIGHT . Default is .CENTER.

  • getText()

    Return the HoloButton text. text — String. Button text.

  • setVoiceCommand(command,toolTip)

    Set the button voice command, when the voice command is said by the user, the button is tapped.
    Command- String. The cvoice command to attach to the button.
    toolTip- Boolean. Specify whether a tooltip should appear when the user gazes at the button explaining the availability of the voice command.

  • clearVoiceCommand()

    Clears the button voice command.

  • setParam({ parametername: parameterValue })

    Set any of the HoloButton's parameters. Taking the parameter name and parameter value.
    Example: setParam({ text: 'setParam', color: 0xFF0000});

HoloButton
var btnPrevMesh = new HoloBuild.HoloButton("CtrlPrev", 0.1, 0.1, 0,{ image:'prev.png'});
                              

HoloSwitch

HoloSwitch is a switch like component that is very similar to the button but that keeps its on state or image once the user tap on it and returns to its off state once the user tap on it again. Since the HoloSwitch extends the HoloMesh class, it inherits all the HoloMesh's properties and methods.

Constructor
  • name

    The HoloSwitch Name. It should be a unique name in your application.

  • width

    The HoloSwitch width.

  • height

    The HoloSwitch height.

  • depth

    The HoloSwitch depth, 0 for a plane geometry and > 0 for a box geometry.

  • {PARAMETERS} optional

    An object that can contain the following parameters:
    bgColor — String Hex Color. Background button color. Default is 0x3c3c3c.
    borderColor — String Hex Color. Border color that will be shown when the button is clicked.
    borderThickness — Float. Border thickness in pixels that will be shown when the button is clicked. Default is 3 pixles.
    hoverState — Boolean. Whether a hover effect is available or not. Default is true.
    hoverBorderColor — String Hex Color. Hover border color that will be shown when the button is hovered.
    hoverBorderThickness — Float. Hover border thickness in pixels that will be shown when the button is hovered. Default is 3 pixles.
    clickState — Boolean. Whether a click effect is available or not. Default is true.
    clickBorderColor — String Hex Color. Click border color that will be shown when the button is clicked.
    clickBorderThickness — Float. Click border thickness in pixels that will be shown when the button is clicked. Default is 4 pixles.
    image — String. Image filename that will show as the button background.
    text The button text. Default is null.
    fontSize The button text font size. Default is 0.015 meters.
    fontColor The button text font color. Default is 0xFFFFFF.
    fontWeight The button text font weight. Default is 'normal'.
    textAnchor: The button text position: HoloBuild.textAnchor.CENTER, .TOPLEFT, .TOPCENTER, .TOPRIGHT, .BOTTOMLEFT, .BOTTOMCENTER, .BOTTOMRIGHT . Default is .CENTER.

    To create your button image, use the Selawik Regular font for consistency and the following PSD file for buttons icons icons.psd For the icon set used by the Hololensuse the following fonts: holomdl2.ttf and HoloSymMDL2.ttf

Methods
  • toggle();

    This method will toggle the switch status: it will visually turn the switch on if it was off or the other way around.

  • setEnabled();

    This method will either disable the button or enable it.

HoloSwitch
var btnPrevMesh = new HoloBuild.HoloSwitch("CtrlPrev", 0.1, 0.1, 0);
                       
Two switches in one group, one switch can be selected at a time:

var groupMenu = new HoloBuild.HoloGroup();
var btnWidth = 0.105;
var btnHeight = 0.105;
var btnOne = new HoloBuild.HoloSwitch("ControlOne", btnWidth, btnHeight, 0,{ clickBorderColor: 0xFF0000, groupName: "first" });
var btnTwo = new HoloBuild.HoloSwitch("ControlTwo", btnWidth, btnHeight, 0,'icon-Two.png', '', { clickBorderColor: 0x00FF00, groupName: "first" });
groupMenu.add(btnOne);
groupMenu.add(btnTwo);
                                          

HoloStepper

A HoloStepper is a component that holds two buttons ( + and - ) that increment or decrement a numeric label value.

Constructor
  • name

    The stepper component name. It should be a unique name in your application.

  • value

    The stepper value.

  • width

    The stepper control width.

  • {PARAMETERS} optional

    An object that can contain the following parameters:
    fontSize — Float. Size of the text (text height). Default is 0.02 meters.
    color — The text color. Default is set to 0x101010.
    bgColor — The text background color. Default is 0xFFFFFF.
    padding — Float. The text padding to its background. Default is 0.02.
    min — Float. The lowest possible numeric value for the HoloStepper. Default is 0.
    max — Float. The highest possible numeric value for the HoloStepper. Default is 100.
    increment — Float. The increment, or step, value for the HoloStepper. Default is 1.

HoloStepper
var stepperTest = new HoloBuild.HoloStepper('stepper1', '0', 0.08, { max: 100, increment: 5 });
                       

HoloToolbar

A HoloToolbar is a component that holds buttons and that is usually used as an application menu.

Constructor
  • btnWidth

    The default button width.

  • btnHeight

    The default button height.

  • {PARAMETERS} optional

    vertical An optional Boolean value that if enabled will draw the HoloToolbar vertically. reverse An optional Boolean value that if enabled will draw the HoloToolbar in the reverse direction (from right to left). margin — Number. This number represent the margins between toolbar button in meters, the default is 0.005.

Methods
  • addButton (name,
    {PARAMETERS})

    addButton will add a button to the toolbar with a specific name and a set of parameters: image — String. This is the image filename that will show on the button.

  • addSwitch (name,
    {PARAMETERS})

    addSwitch will add a switch to the toolbar with a specific name and a set of parameters:
    image — String. This is the image filename that will show on the switch.
    groupRadio — Boolean. Specifies wheter this switch follows the radioButton behaviour.
    groupName: — String. Group name used to group switches together.

  • addSubToolbar
    (toolbarSub, btn,
    toggleMode);

    Add a child HoloToolBar to the main toolbar an link it to a specfic button or switch. If a use tap on the linked button or switch, the subtoolbar will be automatically toggled. toggleMode is an enumerator that specificy the position of the sub toolbar: toggleMode elements include the following : toggleMode.LEFT, toggleMode.RIGHT, toggleMode.TOP, toggleMode.BOTTOM.

  • reset();

    Resets the toolbar by turning off any switches and closing any subtoolbar.

  • reverseOrder();

    Reverses the direction of the toolbar from LTR to RTL or the otherway around.

  • hideChild
    (controlname);

    Hides a HoloToolbar child by referencing the child name. This function is usefull if you want to temporary hide one of the toolbar children without messing the button spacing. You can use the showChild function to show back the child control.

  • showChild
    (controlname);

    Shows a HoloToolbar hidden child by referencing the child name.

  • getParent();

    Returns the toolbar parent button or switch if it exists.

HoloToolbar
var menuCtrl = new HoloBuild.HoloToolbar(0.105, 0.105);

menuCtrl.addButton("CtrlAdjust", {image: "adjust.png"});

menuCtrl.addButton("CtrlMove", {image: "move.png"});

menuCtrl.getObjectByName('CtrlMove').onTap = function () {
menuCtrl.position.x +=0.1;
}

//Sub toolbar
var toolbarSub = new HoloBuild.HoloToolbar(0.125, 0.125);
toolbarSub.addButton("ControlAbout", {
    image: "about-off.png"
});
var btnAdjust = toolbar.getObjectByName('CtrlAdjust');
menuCtrl.addSubToolbar(toolbarSub, btnAdjust, HoloBuild.toggleMode.RIGHT);

                       

HoloPanel

A HoloPanel is a panel component that can hold other components such as HoloLabel, a HoloButton, or a HoloSwitch. Since the HoloPanel extends the HoloMesh class, it inherits all the HoloMesh's properties and methods.

Constructor
  • name

    The HoloPanel name. It should be a unique name in your application.

  • width

    The HoloPanel width.

  • height

    The HoloPanel height.

  • {PARAMETERS}

    bgColor The HoloPanel background color. Default is 0x3c3c3c.
    close A Boolean value that if set to true will show an X like button on top of the HoloPanel that will close the panel once the user tap on it.
    rounded A Boolean value specifying whether the panel will have rounded edges or not.

Methods
  • addChild(object, pos);

    Add a child object to the panel. pos is the position of the child in respect to the panel.

  • onClose
    = callbackfunction

    The callbackfunction that is called when the panel close button tap event..

  • setHeight(height);

    Set or Change the HoloPanel height to height value.

Properties
  • height

    Height of the panel.

  • width

    Width of the panel.

HoloPanel
var panelTest = new HoloBuild.HoloPanel('panel1', 0.5, 0.3, {bgColor:0x010123, close:true});
var labelTest = new HoloBuild.HoloLabel('lblName', 'hello', { fontSize: 0.02, color: 0x101010, bgColor: 0xFFFF00, padding: 0.03 } );

panelTest.addChild(labelTest, { x: 0.07, y: 0.05 });

var panelImage = new HoloBuild.HoloPanel('panelImage', 0.2, 0.2, {bgColor:0xFFFFFF});

panelImage.setImage('SampleImage.png');

panelTest.addChild(panelImage, { x: -0.11, y: 0 });
                       
To have a function called when the panel is closed:
panelName.onClose = function () {
// your function logic here
}
                       

HoloDialog

A HoloDialog is a dialog component that can be used as either message notification to the user or when needing a confirmation from the user. Since the HoloPanel extends the HoloGroup class, it inherits all the HoloGroup's properties and methods.

Constructor
  • name

    The HoloDialog name. It should be a unique name in your application.

  • title

    The HoloDialog Title.

  • text

    The HoloDialog text.

  • PARAMETERS

    Optionally the HoloDialog can take other parameters as an object that can contain the following:
    mode — enumerator. The mode of the dialog: (dialogMode.DEFAULT, dialogMode.CONFIRM, or dialogMode.INFO). dialogMode.DEFAULT for a notification like dialog with a close button; dialogMode.CONFIRM for a confirmation like dialog with a YES and NO buttons; HB.Enum.dialogMode.INFO for an information only dialog without any buttons. Default is dialogMode.DEFAULT.
    bgColor — color. The HoloDialog background color. Default is 0x070707.
    titleColor — color. The HoloDialog title color. Default is 0xFFFFFF.
    titleBgColor — color. The HoloDialog title background color. Default is 0x1C1C1C.
    bodyColor — color. The HoloDialog body color. Default is 0xFFFFFF.
    bodyBgColor — color. The HoloDialog body backgrounf color. Default is 0x070707.
    titleAlign — String. ('left', 'right', 'center'). the HoloDialog title alignment. Default is left.
    bodyAlign — String. ('left', 'right', 'center'). The HoloDialog body alignment. Default is left.

  • callbackfunction optional

    The callbackfunction is the call back function that will be called when the user perform an action on the HoloDialog. If the dialog mode is dialgMode.CONFIRM, the callback function will be called with one boolean argument. The boolean value will be true if the YES button is tapped, or false otherwsie.

Methods
  • setText(text);

    Set or Change the HoloDialog text text value.

HoloDialog
Message dialog example:

var dialogAlert = new HoloBuild.HoloDialog('dialog1', 'Alert', 'this is an alert message!', {mode: HoloBuild.dialogMode.DEFAULT },
      function (action) {
            console.log('dialog callback');
      }
);
                       
Confirmation dialog example:

var dialogGroup = new HoloBuild.HoloDialog('dialogConfirm', 'Confirm', 'Are you sure you want to do this?', {mode: HoloBuild.dialogMode.CONFIRM });
                       

HoloCheckBox

A HoloCheckBox is a checkbox component that allows the user to choose between two options. Since the HoloCheckBox extends the HoloButton class, it inherits most of the HoloButton's properties and methods.

Constructor
  • name

    The HoloCheckBox Name. It should be a unique name in your application.

  • size

    A number denoting the HoloCheckBox width and height, it is one number since the checkbox has a square form.

  • depth

    The HoloCheckBox depth, 0 for a plane geometry and > 0 for a box geometry.

  • {PARAMETERS} optional

    An object that can contain the following parameters:
    bgColor — String Hex Color. Background button color. Default is 0x3c3c3c.
    bgTransparent — Boolean. If set to true, the checkbox will have a transparent background. Default is false.
    borderColor — String Hex Color. Border color that will be shown when the button is clicked.
    borderThickness — Float. Border thickness in pixels that will be shown when the button is clicked. Default is 3 pixles.
    hoverState — Boolean. Whether a hover effect is available or not. Default is true.
    hoverBorderColor — String Hex Color. Hover border color that will be shown when the button is hovered.
    hoverBorderThickness — Float. Hover border thickness in pixels that will be shown when the button is hovered. Default is 3 pixles.
    clickState — Boolean. Whether a click effect is available or not. Default is true.
    clickBorderColor — String Hex Color. Click border color that will be shown when the button is clicked.
    clickBorderThickness — Float. Click border thickness in pixels that will be shown when the button is clicked. Default is 4 pixles.
    image — String. Image filename that will show as the button background.
    fontSize The button text font size. Default is 0.015 meters.
    fontColor The button text font color. Default is 0xFFFFFF.
    fontWeight The button text font weight. Default is 'normal'.
    textAnchor: The button text position: HoloBuild.textAnchor.CENTER, .TOPLEFT, .TOPCENTER, .TOPRIGHT, .BOTTOMLEFT, .BOTTOMCENTER, .BOTTOMRIGHT . Default is .CENTER.
    soundMute — Boolean. if set to true will disable the spatial sound that will be played when a user tap on the button.
    sound — String. the filename of the sound file that will be played when a user tap on the button.
    checked — Boolean. if set to true will have an X on the checkbox and its sstatus to checked.
    symbol — Character. The checkbox character that will be shown when the user tap on the checkbox. the default is ✓

Property
  • checked

    This property will return a boolean representing the checkbox staus, true for checked and false for not checked.

Methods
  • setEnabled();

    This method will either disable the button or enable it.

  • setParam({ parametername: parameterValue })

    Set any of the HoloCheckbox's parameters. Taking the parameter name and parameter value.
    Example: setParam({ text: 'setParam', color: 0xFF0000});

HoloCheckBox
var checkbox = new HoloBuild.HoloCheckBox("CtrlCheckBox", 0.05,{ bgColor:0x3c3c3c , fontColor: 0xFFFFFF, borderColor: 0xFFFFFF, checked: false});
checkbox.onTap = function () {
    // checkbox has been tapped
}
holoscene.add(checkbox);
                              

HoloText3D

The HoloText3D represents a component used to display 3D text in a HoloSpace. The HoloText3D is also useful when you want to show a text with depth. The HoloText3D extends the HoloMesh class, it inherits all the HoloMesh's properties and methods.

Constructor
  • name


    The HoloText3D component name. It should be a unique name in your application.

  • text

    The text to be displayed.
    text — String. One line text.
    OR
    text — Array of Strings. Multi-line text.

  • {PARAMETERS} optional

    An object that can contain the following parameters:
    fontSize — Float. Size of the text (text height). Default is 0.03 meters..
    color — Color. The text color. Default is set to 0x101010.
    height — Float. The label height. Default is set to 0.
    padding — Float. The text padding to its background. Default is 0.02.
    hotspot — Boolean. If true, the cursor will intersect with the HoloText3D. Default is set to true.
    align — String. ('left', 'right', 'center'). the label text will be aligned accordingly. Default is set to center. The width parameter needs to be filled for the left or right alignment to work.

Methods
  • setText(text,
    {PARAMETERS})

    Set or Change the HoloText3D text to text
    text — String. One line text.
    OR
    text — Array of Strings. Multi-line text.
    PARAMETERS is an optional object that can contain the following parameters:
    fontSize — Float. Size of the text (text height). Default is 0.015 meters..
    color — Color. The text color. Default is set to 0x101010.
    align — String. ('left', 'right', 'center'). the label text will be aligned accordingly. Default is set to center. The width parameter needs to be filled for the left or right alignment to work.

  • getText()

    Return the HoloText3D text as a string.

HoloText3D
var text = new HoloBuild.HoloText3D('txtValue', 'hello', { fontSize: 0.025, width: 0.2, color: 0xFF0000, height: 0.005 } );
text.position.set(0, -0.055, 0);
holoscene.add(text);				
                       
To change the text of the label above:
text.setText('hello world');

HoloTextBox

The HoloTextBox represents a textbox component that allows users to enter text as an input in HoloSpace. Once a user tap on the textbox, a keyboard will be displayed for the user to enter the text. The HoloTextBox extends the HoloGroup class, it inherits all the HoloGroup's properties and methods.

Constructor
  • name


    The textbox name. It should be a unique name in your application.

  • text

    The textbox default text (optional)

  • {PARAMETERS} optional

    An object that can contain the following parameters:
    fontSize — Float. Size of the text (text height). Default is 0.015 meters..
    color — Color. The text color. Default is set to 0x101010.
    width — Float. The textbox width. Default is set to 0.1.
    height — Float. The textbox height. Default is set to 0.025.
    bgColor — Color. The text background color. Default is transparent.
    hotspot — Boolean. If true, the cursor will intersect with the HoloTextBox. Default is set to true.
    border — Boolean. If true, the HoloTextBox will have a border. Default is set to false.

Methods
  • getText()

    Return the HoloTextBox text entered by the user as string.

  • onExit
    = callbackfunction

    The callbackfunction that is called when the used exit the textboox keyboard.

HoloTextBox
var textbox = new HoloBuild.HoloTextBox("txtSample1", "", { width: 0.2, fontSize: 0.0234 });
                       
To get the text in the box:
var textvalue = textbox.getText();

Speech

This section details the various classes that deal with speech.

HoloSpeechRecognition

HoloSpeechRecognition is the class that deals with continous speech recognition that will help you enabling your application to recognize voice commands. By default your application have the "select" command enabled: users can tap on a mesh by simply saying "select".

Methods
  • addVoiceCommand
    (command, callback);

    This method will add a voice command that the speech recognition system will monitor for. Once the command is recognized with a high confidence, the callback function will be called.
    command String- The voice command string that you want the system to recognize
    callback Function- The function that will be called once the system recoginize the command. An event object is added as an arugment to the callback function, the event can return the command name: e.command

  • updateVoiceCommand
    (command, callback);

    This method will update the callback function of an already defined voice command.
    command String- The voice command string that you want the recognizer to update
    callback Function- The new function that will be called once the system recoginize the command

  • deleteVoiceCommand
    (command);

    This method will delete an already set voice command.
    command String- The voice command string that was set with the addVoiceCommand function.

  • resetVoiceCommand
    ();

    This method will remove all the voice commands that are already set.

  • setConfidence (level);

    This method will update how confident the system should before calling the callback function.
    level Float- The minimum level of confidence to recognize a command. Default is 0.5

HoloSpeechRecognition
HoloBuild.HoloSpeechRecognition.addVoiceCommand('start', function () {
    var geometry = new HoloBuild.HoloBoxGeometry(0.05, 0.05, 0.05);
    var material = new HoloBuild.HoloMeshBasicMaterial({ color: 'red' });
    var holomesh = new HoloBuild.HoloMesh(geometry, material, true);
    holomesh.position.set(0, 0, -0.5);
    holoscene.add(holomesh);
});
Once the user says 'start' a red holomesh will be added to the scene.

Sound

The section details the various classes that deal with sound. the main for playing a sound and related to a mesh is the HoloSpatialSound:

HoloSpatialSound

HoloSpatialSound is the class that deals with simulating placing a sound in 3 dimensional space. You simply load a sound file (supported audio type: ogg), attach it to the object that you want the sound to come from, and run the HoloSpatialSound play method to play the sound. The spatial sound takes into consideration the direction and distance of the object to gives the impression that the sound is coming from that object.

Constructor
  • filename

    String - The sound file name that you want to load.
    Note: alternatively you can provide a url of the sound file to load the sound remotely (make sure to use PlayWhenReady function to play remote files as you don't know when they will be loaded.).

Properties
  • offset

    Number - set the number of seconds that you want to start playing the audio from. Default is 0.

Methods
  • play()

    play the sound file.

  • playWhenReady()

    play the sound file as soon as it becomes loaded. This method is useful for a large audio file that you do not know how much time it will take to be load to the buffer.

  • pause()

    Pause the sound play.

  • setLoop ( isloop )

    Set the playing to be looped or not
    isloop - Boolean : if set to true the sound file will keep on playing.

  • setPlaybackRate
    ( rate )

    Set the play back speed. Default is 1
    rate - Number : a number representing the speed of the sound.

  • setVolume
    ( volume )

    Set the volume of the sound. Default is 1
    volume - Number : a number that reflects the playing sound volume gain. Increasing the number will increase the gain on the sound volume. 0 means silence and 1.0 is the highest supported volume.

  • stop()

    Stop the playing sound.

  • isPlaying

    Returns a boolean denoting if the audio is currently playing or not.

HoloSpatialSound
var spatialsound = new HoloBuild.HoloSpatialSound('Ring.wav');
var geometry = new HoloBuild.HoloBoxGeometry(0.05, 0.05, 0.05);
var material = new HoloBuild.HoloMeshBasicMaterial({ color: 'red' });
var holomesh = new HoloBuild.HoloMesh(geometry, material, true);
holomesh.position.set(0, 0, -0.5);
holoscene.add(holomesh);
holomesh.add(spatialsound);
    
holomesh.onTap = function () {
    spatialsound.play();
};

HoloTextToSpeech

HoloTextToSpeech is the class that converts text to audio in real time. The speech is based on a cloud neural network that makes the voice nearly indistinguishable from people voices. The resulted sound is a HoloSpatialSound that could be placed in 3 dimensional space.
*** Not available with the personal plan ***

Constructor
  • {PARAMETERS}

    parameters to fetch a specific voice. A default voice will be used if no parameters are passed. You can use the getVoices() method to get the information about different voices.
    name: name of the voice.(optional)
    locale: accent of the voice.(optional)

Methods
  • getVoices
    (callback)

    Method to fetch information about available voices.

  • getSpeech
    (text)

    Method that returns a SpatialSound. Which you can then play by calling playWhenReady(). (See example)

HoloTextToSpeech
To get information about available voices:
var tts = new HoloBuild.HoloTextToSpeech();
tts.getVoices(function (voices) {
 console.log(voices);
});
For a female voice you can use:
var ttsJenna = new HoloTextToSpeech({locale:'en-US', name:'en-US-Jessa24KRUS' });
var speech = ttsJenna.getSpeech('Hello there!')
speech.playWhenReady();
For a male voice you can use:
var ttsBen = new HoloTextToSpeech({locale:'en-US',name:'en-US-Guy24kRUS' });
var speech = ttsJenna.getSpeech('Hello there!')
speech.playWhenReady();

Spatial World

This section details the various classes that deal with the real world around you. This includes, the mapping of the space arround you, anchoring holograms to your real space, and more.

HoloSpatialMap

The HoloSpatialMap class provides with a detailed map of the real world surfaces around the hololens, the resulted surfaces are then returned to the developer to use in their application. First you must start a spatial map scan to collect the surfaces around the hololens, once done, the system will process these surfaces and return an array of planes for you to use.

Methods
  • start()

    Start spatial mapping the space around you, a visual texture will be displayed to help guide the user with the spatial mapping.

  • stop
    (callback)

    Stop an already started spatial map scan. callback - Function(geometries) : an optional call back function will be called with the resulted geometries for the developer processing. Note that the resulted geometries are the raw data and it is not recommended to render them onto the scene as is.

  • getPlanes()

    a functions that returns an array of planes resulted from a spatial map. If the user has not performed a spatial map, the plan array will be empty.

HoloSpatialMap
HoloBuild.HoloSpatialMap.start();
var material = new HoloBuild.HoloMeshBasicMaterial({ color: 'red' });
var holomesh = new HoloBuild.HoloMesh(geometry, material, true);
holoscene.add(holomesh);

holomesh.onTap = function () {
    HoloBuild.HoloSpatialMap.stop();    
};

HoloMarkerTracking

HoloMarkerTracking provides an object that uses the device's camera to track an Aruco Marker in the Spatial World.

Constructor
  • {PARAMETERS}

    preview- boolean. If set to true will shows a video preview at position (0,0,0) on the web for debugging purposes. Default is false;
    markerSize float. The size of the marker size in mm to track. All the markers in the scene should me of the same size, otherwise the positioning will be off. Default markersize is 0.038.
    Note: you can use the http://chev.me/arucogen/ to create markers (Select the original marker type).

Methods
  • Start
    (callback(result))

    This function will start detecting markers in your scene using the device camera. The default camera used is the device's front camera, if not available, the first available camera will be used. The detection will continue on detecting for markers until you specifically call the Stop function.
    callback(result)- Function: this function is called when a marker is detected. Result is an array containing marker objects with the following properties:
    -id: Marker id
    -translation: a vector3 representing the position of the marker (the center of the marker)
    -rotation: a vector 3 representing the rotation of the marker.

  • Stop()

    This function stops the detection process of the markers.

HoloMarkerTracking

                                        
var geometry = new HoloBuild.HoloBoxGeometry( 0.1, 0.1, 0.1 );
var material = new HoloBuild.HoloMeshBasicMaterial( { color: 'red' } );
var holomesh= new HoloBuild.HoloMesh( geometry, material );
                      
var tracker = new HoloBuild.HoloMarkerTracking({ preview: true, markerSize: 0.055 });
holomesh.onTap = function () {
    tracker.Start(function (result) {
        var detected = '';
        for (var i = 0; i < result.length; i++) {
        detected += result[i].id + ' ';
        holomesh.rotation.x = result[i].rotation.x;
        holomesh.rotation.y = result[i].rotation.y;
        holomesh.rotation.z = result[i].rotation.z;
holomesh.position.copy(result[i].translation.clone()); } }); }

HoloSpatialAnchor

The system automatically create a stage frame of reference when the user first start the application to provide you with one single coordniate system to render your holograms. This will make your hologram look stable and not drift around. However, if you need to maintain the position of a hologram through multiple appliction sessions, or you the user might move beyound 5 meters away from the hologram, it would be better to use a spatial anchor to keep the hologram position stable.
HoloSpatialAnchor is the manager that handles spatial positions relative to real world positions (or anchors) and maintain them even when the application is restarted and over long distances.
You simply setAnchor on a mesh to save its position relative to the real world on the Hololens and give that anchor a name, then you can loadAnchor saved using its name and set it on that holomesh.

Methods
  • loadAnchor
    (object, anchorname,
    callback(success) )

    load a saved anchor position, with the name anchorname, and place an object on that position.
    object - Object : the hologram whose anchor is to be saved. anchorname - String : the anchor's name. It should be a unique name in your application. callback(success) - Function : a callback function that will be called when load anchor completes it task, success is a boolean that will be set to true if the anchor is loaded successfully.

  • setAnchor
    (object, anchorname,
    callback(success) )

    Save an anchor, with the name anchorname, and get the anchor position and rotation from the object.
    object - Object : the hologram whose anchor is to be saved. anchorname - String : the anchor's name. It should be a unique name in your application. callback(success) - Function : a callback function that will be called when set anchor completes its task, success is a boolean that will be set to true if the anchor is set successfully.

  • deleteAnchor
    (anchorname, callback(success) )

    delete a saved anchor, with the name anchorname.
    anchorname - String : the anchor's name. callback(success) - Function : a callback function that will be called when delet anchor completes its task, success is a boolean that will be set to true if the anchor is deleted successfully.

SpatialAnchor
var geometry = new HoloBuild.HoloBoxGeometry(0.1, 0.1, 0.1);
var material = new HoloBuild.HoloMeshBasicMaterial({ color: 'red' });
var holomesh = new HoloBuild.HoloMesh(geometry, material, true);
holoscene.add(holomesh);

HoloBuild.HoloSpatialAnchor.loadAnchor(holomesh, "holomesh", function (success) {
    console.log('holomesh anchor loaded');
});

holomesh.onTap = function () {
    holomesh.showAdjust();
    holomesh.getAdjust().onDone = function () {
        HoloBuild.HoloSpatialAnchor.setAnchor(holomesh, "holomesh", function (success) {
            if (success) {
                console.log('set success')
            } else {
                holomesh.position.set(0, 0, 0);
            }
        });
    };
};

HoloSpatialUnderstading

Similar to the HoloSpatialMap, the HoloSpatialUnderstanding class provides a way for the developer to use a specific set of physical, real world surfaces(Floors, Walls and Platfoms) to make the experience more coherent with the physical environment surrounding the user. First you must start with a scan of the room to collect the surfaces around the hololens. Once done, the system will process these surfaces and return a set of arrays for each surface type.

Methods
  • start
    ({PARAMETERS})

    displays a panel that shows the 'quality' of the scan.This panel has a "start scan" to allow the user to start the scan whenever they're ready. This button turns to an 'end scan' button when a minimum sufficient quality is reached to allow the user to end the scan. Callback functions for these events can be added if needed(See Properties section below). In addition to the normal map done by the HoloSpatialMap start() method, this method analyzes the environment and returns the various surfaces found.
    Parameters include:
    occlusion: Boolean to specify whether you want the holograms in the scene to get occluded when they're further away from the user than real surfaces.
    autofinsih: Boolean to specify wheter the scan should automatically finish when the scan reaches a sufficient level of quality specified by the parameteres 'minFloorPct', 'minWallPct', and 'minPlatformPct'.
    room: Parameters for the mesh shown to the user while scanning. These parameters include:visible: Boolean specifying if the mesh is visible or not.wireframe:: Boolean specifyin if the mesh is a wireframe mesh or not.
    minFloorPct: Float to specify the sufficient percentage of found floors before the user is allowed to end the scan or before the scan ends automatically in the case where the 'autofinish' parameter is set to true.
    minWallPct: Float to specify the sufficient percentage of found walls before the user is allowed to end the scan or before the scan ends automatically in the case where the 'autofinish' parameter is set to true.
    minPlatformPct: Float to specify the sufficient percentage of found platforms before the user is allowed to end the scan or before the scan ends automatically in the case where the 'autofinish' parameter is set to true.
    panel: Boolean. Specify whether the panel should appear to the user or if the scan should start and end automatically according to the 'minFloorPct', 'minWallPct', and 'minPlatformPct' parameters.

  • findPositionsOnWalls
    ({PARAMETERS})

    returns an array of center positions of wall surfaces in the spatial environment, based on the parameters(contraints) specified. These surfaces have a 'center' property and a 'normal' property. PARAMETERS: a set of constraints to filter the returned positions. These params include:
    resultCount: Integer. Limit the number of results returned in the array. Default is null.
    minHeightOfWallSpace: Float. Minimum allowed height of a recognized wall(vertical surface). Any surface with height less than the minimum will not be returned in the array. Default is 0.5.
    minWidthOfWallSpace: Minimum allowed height of a recognized wall. Default is 0.5.
    minHeightAboveFloor: Float. Minimum distance above floor of a recognized wall. Default is 0.1 .
    minFacingClearance: Float. Minmimum allowed distance between a recognized wall and a facing surface. Default is 0.1 .

  • findPositionsOnPlatforms
    ({PARAMETERS})

    returns an array of center positions of Platform surfaces in the spatial environment, based on the parameters(contraints) specified. These surfaces have a 'center' property and a 'normal' property. Platforms are flat, horizontal surfaces in the room(excluding floor and cieling). PARAMETERS: a set of constraints to filter the returned positions. These params include:
    resultCount: Integer. Limit the number of results returned in the array. Default is null.
    minHeight: Float. Minimum allowed distnace from the floor of a recognized platform. Default is 0.125.
    maxHeight: Float. Maximum allowed distance from the floor of a recognized platform . Default is 1.0 .
    minFacingClearance: Float. Minmimum allowed distance between a recognized platform and a facing surface. Default is 0.1 .

  • findPositionsOnFloors
    ({PARAMETERS})

    returns an array of center positions of Floor surfaces in the spatial environment, based on the parameters(contraints) specified. These surfaces have a 'center' property and a 'normal' property. PARAMETERS: a set of constraints to filter the returned positions. These params include:
    resultCount: Integer. Limit the number of results returned in the array. Default is null.
    minLength: Float. Minimum allowed length of a floor surface. Default is 0.5.
    minWidth: Float. Minimum allowed width of a recognized floor. Default is 0.5.

  • findLargestWall
    ()

    returns the largest wall surface found in the room. In addition to the 'center' and 'normal' properties, this returned object has 'width' and 'length' properties.

  • placeObject
    (mesh, onSurfaceType, {PARAMETERS})

    Places the mesh on a random surface. mesh: HoloMesh. The mesh affected.
    onSurfaceType: String. Options are "OnCielling" , "OnEdge", "OnWall", "OnFloor".
    {PARAMETERS} : faceSurface Boolean specifying whether the mesh should be rotated to face the normal of the surface.

Properties
  • onEnd
    = callback

    function to execute when the user taps on the 'end scan' button.

  • onMinimumReached
    = callback

    function to execute when the scan reached the specified minimum quality. Note that this event happens before the user taps on the 'end Scan' button.

HoloSpatialUnderstanding

HoloBuild.HoloSpatialUnderstanding.start({
occlusion: false, autoFinish: false, minFloorPct: 0.1, minPlatformPct: 0.3, minWallPct: 0.1,room: { visible: true, wireframe: true }
});


HoloBuild.HoloSpatialUnderstanding.onEnd = function(){
    holoscene.add(btn);
};

var btn = new HoloBuild.HoloButton("showPositions", 0.1, 0.1, 0, {
    fontSize: 0.013,
    text: ['show', 'Positions'],
});

btn.onTap = function(){
    
var wallPositions = HoloBuild.HoloSpatialUnderstanding.findPositionsOnWalls({
    resultCount: null,
    minHeightOfWallSpace: 0.5,
    minWidthOfWallSpace: 0.5,
    minHeightAboveFloor: 0.1,
    minFacingClearance: 0.1
});

var platformPositions = HoloBuild.HoloSpatialUnderstanding.findPositionsOnPlatforms({
        resultCount: null,
        minHeight: 0.125,
        maxHeight: 1.0,
        minFacingClearance: 1.0
});

var floorPositions = HoloBuild.HoloSpatialUnderstanding.findPositionsOnFloors({
        resultCount: null,
        minLength: 0.5,
        minWidth: 0.5
});

var largestWall = HoloBuild.HoloSpatialUnderstanding.findLargestWall();

    var floorMaterial = new HoloBuild.HoloMeshBasicMaterial({ color: 'purple', side: HoloBuild.DoubleSide });
    var wallMaterial = new HoloBuild.HoloMeshBasicMaterial({ color: 'red', side: HoloBuild.DoubleSide });
    var platformMaterial = new HoloBuild.HoloMeshBasicMaterial({ color: 'green', side: HoloBuild.DoubleSide});
    var largestWallMaterial = new HoloBuild.HoloMeshBasicMaterial({ color: 'blue', side: HoloBuild.DoubleSide, wireframe: true });

     for (var i = 0; i < platformPositions.length; i++) {
        var center = platformPositions[i]['center'];
        var normal = platformPositions[i]['normal'];
        var geometry = new HoloBuild.HoloBoxGeometry(0.25, 0.25, 0.01);
        var plane = new HoloBuild.HoloMesh(geometry, platformMaterial);
        holoscene.add(plane);

        plane.position.set(center.x, center.y, center.z);
        plane.rotation.x = Math.PI / 2;
    }

    for (var i = 0; i < wallPositions.length; i++) {
        var center = wallPositions[i]['center'];
        var normal = wallPositions[i]['normal'];
        var geometry = new HoloBuild.HoloBoxGeometry(0.5, 0.5, 0.05);
        var plane = new HoloBuild.HoloMesh(geometry, wallMaterial);
        holoscene.add(plane);

        plane.position.set(center.x, center.y, center.z);
        // normalize the direction vector
        normal.normalize();
        plane.geometry.lookAt(normal);
    }

     for (var i = 0; i < floorPositions.length; i++) {
        var center = floorPositions[i]['center'];
        var normal = floorPositions[i]['normal'];
        var geometry = new HoloBuild.HoloBoxGeometry(0.25, 0.25, 0.01);
        var plane = new HoloBuild.HoloMesh(geometry, floorMaterial);
        holoscene.add(plane);

        plane.position.set(center.x, center.y, center.z);
        plane.rotation.x = Math.PI / 2;
    }

    if (largestWall) {
        var geometry = new HoloBuild.HoloBoxGeometry(largestWall.width, largestWall.length, 0.01);
        var plane = new HoloBuild.HoloMesh(geometry, largestWallMaterial);
        holoscene.add(plane);

        plane.position.set(largestWall.center.x, largestWall.center.y, largestWall.center.z);
        plane.geometry.lookAt(largestWall.normal.normalize());
    }
}

Utilities

The utilities section details the various functionalities that could help you in your development.

HoloHelper

HoloHelper contains methods to help in various miscellaneous situations.

Methods
  • getObjectByPropertyName
    (propertyname);

    This method is used when you want to return an object by a specific property name.

    propertyname: string - the name of the property you are looking for.

  • getArrayObjectsByProperty
    (array, property, value);

    This method searches an array for all objects with a matching property value, returning an array of the matched objects.

    array: Array - the array to be searched
    property: String - the property to search for
    value: String - the property value to search

  • getGroupObjectsByProperty
    (propertyname);

    This method searches a group for all objects with a matching property value, returning an array of the matched objects.

    group: HoloGroup - the group to be searched
    property: String - the property to search for
    value: String - the property value to search

  • recalculateUVs
    (geometry);

    This method calculate uvs vectors of a geometry.


HoloHelper
var helper = new HoloBuild.HoloHelper();
                       

HoloSettings

HoloSettings contains the default settings and preference of the HoloBuild Library.

Methods
  • setDebug
    (showDebug);

    This method will either enable or disable showing the console log information on your Hololens. The information will be show next the buildWagon version number.
    showDebug Boolean- If true the debug information will be displayed. Default is false.

  • setLoading
    (boolean);

    This method will either enable or disable showing the loading indicator. The loading indicator appears whenever an asset is being loaded over the network.

HoloSettings
var settings = new HoloBuild.HoloSettings();
To set the debugging method:

var settings = new HoloBuild.HoloSettings();
settings.setDebug(true);

HoloShape

HoloShape is a customizable 2D shape that can be used with HoloShapeGeometry to create new Geometries.

Properties
  • currentPoint

    Represents the starting point of reference for drawing any curve. Before calling any of the drawing functions below, currentPoint is {x:0 , y:0}.



Methods
  • moveTo(x ,y)

    float x, y.
    Changes the current reference point (a.k.a. currentPoint) to the point p{x:x, y:y}.

  • lineTo(x ,y)

    float x, y.
    Draws a line from currentPoint to the point p(x,y).

  • quadraticCurveTo(cpX, cpY, x, y).

    float cpX, cpY, x, y.
    Draws a quadratic curve from the currentPoint to the point p(x,y) with point cp(cpX, cpY) as a control point.

  • bezierCurveTo(cp1X, cp1Y, cp2X, cp2Y, x, y).

    float cp1X, cp1Y, cp2X, cp2Y, x, y.
    Draws a Bezier curve from currentPoint to the point p(x,y) with points cp1(cp1X, cp1Y) and point cp2(cp2X, cp2Y) as control points.

  • absarc(x, y, radius, startAngle, endAngle, clockWise).

    float x, y, radius, startAngle, endAngle.
    boolean clockWise.
    Draws an arc with center c(x,y) and with the specified parameters.

  • absellipse(x, y, xRadius, yRadius, startAngle, endAngle, clockWise, rotation).

    float x, y, xRadius, yRadius, startAngle, endAngle, rotaion.
    boolean clockWise.
    Draws an arc with center c(x,y) and with the specified parameters. Rotation is the rotation angle of the ellipse around the x-axis.

HoloShape
var shape = new HoloBuild.HoloShape();

lineTo(x,y):
var shape = new HoloBuild.HoloShape();
shape.moveTo(0,0);
shape.lineTo(0.1,0.1);
shape.lineTo(0.2,0.1);
shape.lineTo(0,0);
var geometry = new HoloBuild.HoloShapeGeometry(shape, shapeSettings);
var mesh = new HoloBuild.HoloMesh(geometry, new HoloBuild.HoloMeshStandardMaterial({ color: 0x0000ff }));
holoscene.add(mesh); 

absarc(x, y, radius, startAngle, endAngle, clockWise):
var shape = new HoloBuild.HoloShape();
shape.moveTo(0,0);
shape.lineTo(0.1,0);
shape.absarc(0,0,0.1,0,Math.PI/4,false);
shape.lineTo(0,0);
var geometry = new HoloBuild.HoloShapeGeometry(shape, shapeSettings);
var mesh = new HoloBuild.HoloMesh(geometry, new HoloBuild.HoloMeshStandardMaterial({ color: 0x0000ff }));
holoscene.add(mesh);

absellipse(x, y, xRadius, yRadius, startAngle, endAngle, clockWise, rotation):
var shape = new HoloBuild.HoloShape();
shape.moveTo(0,0);
shape.absellipse(0,0,0.1,0.2,0,2*Math.PI, true,Math.PI/4);
var geometry = new HoloBuild.HoloShapeGeometry(shape, shapeSettings);
var mesh = new HoloBuild.HoloMesh(geometry, new HoloBuild.HoloMeshStandardMaterial({ color: 0x0000ff }));
holoscene.add(mesh);

HoloDB

This component offers an interface for saving presistent data for your application. Data is stored in Key-Value pairs where keys are strings and values are JSON objects.

Methods
  • saveData
    (key, obj, callback)

    use this method to save data to the HoloDB.


  • retrieveData
    (key , callback)

    use this method to query data from the HoloDB by key.

HoloDB
var holoDB = new HoloBuild.HoloDB();
To add data:

var obj = { testProp1: "abc", testProp2: [1, 2, 3], testProp3: { testObj: 1, testObj2: "me myself I" } };
    holoDB.saveData(test, obj, function (data) {
        console.log('data saved');
        console.log(data.response);
    });
To retrieve data:

holoDB.retrieveData('test', function (data) {
        console.log(data.response['testProp1']);
    });

HoloCanvas

HoloCanvas is a two dimensional canvas that offers a space to draw on which then can be used to create a texture.

Properties
  • height

    The height of the canvas in pixels.

  • width

    The width of the canvas in pixels.

  • ctx.fillStyle

    sets the contexts filling color.

  • ctx.strokeStyle

    sets the contexts stroking color.

  • ctx.lineWidth

    sets the contexts line width. Default is 1.0 .

  • ctx.lineCap

    Specifies the shape of a line endings. Options include: "butt", "line", "square"

  • ctx.lineJoin

    Specifies the shape when two lines join. Options include: "round", "bevel", "miter"

  • ctx.miterLimit

    sets the contexts miter limit ratio. Default is 10.

  • ctx.font

    sets the contexts fonts

  • ctx.textAlign

    sets the contexts text alignment setting. Options include: "end", "right", "center", "middle".

  • ctx.textAlign

    sets the contexts baseline alignment setting. Options include: "bottom".

  • ctx.shadowBlur

    sets the contexts blurring effect. Default is 0.

  • ctx.shadowColor

    sets the contexts shadow color. Default is transparent black.

  • ctx.shadowOffsetX

    sets the contexts horizontal distance offset of the shadowing effect. Default is 0.

  • ctx.shadowOffsetY

    sets the contexts vertcal distance offset of the shadowing effect. Default is 0.

  • ctx.globalAlpha

    Alpha value(transparency) applied to an object to be drawn. Default is 1.

Methods
  • getContext("2d")

    This method will return a 2 dimensional drawing context, which you can then use to call the drawing methods.

  • ctx.clearRect
    (x, y, w, h)

    Clears all the pixels in the rectangle with width w and height h, starting from pixel (x,y). Cleared pixels are set to transparent black.

  • ctx.fillRect
    (x, y, w, h)

    Fills all the pixels in the rectangle with width w and height h, starting from pixel (x,y) with a preset colour. To set the colour, you have to set the context's fillStyle property to that colour (i.e. ctx.fillStyle).

  • ctx.fillText
    (text, x, y)

    Writes the given text starting at pixel (x,y).

  • ctx.measureText
    (text)

    Returns width in pixels of the given text.

  • ctx.createLinearGradient
    (x1, y1, x2, y2)

    This returns a gradient which you can then assign to the contexts 'fillStyle' and 'strokeStyle' properties. the returned gradient object has a function addColorStop(offset, color) to add stops to the gradient.

  • ctx.createRadialGradient
    (x1, y1, r1, x2, y2, r2)

    This returns a gradient which you can then assign to the contexts 'fillStyle' and 'strokeStyle' properties. the returned gradient object has a function addColorStop(offset, color) to add stops to the gradient.

  • ctx.beginPath()

    Begins a new drawing path.

  • ctx.closePath()

    closed the drawing path by connecting the last defined path point to the start point. If the path is already closed, or if the path is only one point, this function is obsolete.

  • ctx.moveTo
    (x, y)

    Move the current point to point (x,y) on the canvas.

  • ctx.lineTo
    (x,y)

    Connects current point to point (x,y) on the canvas with a straight line.

  • ctx.bezierCurveTo
    (cp1x, cp1y, cp2x, cp2y, x, y)

    Connects current point to point (x,y) using a bezier curve with the control points (cp1x,cp1y) and (cp2x,cp2y).

  • ctx.quadraticeCurveTo
    (cp1x, cp1y, x, y)

    Connects current point to point (x,y) using a bezier curve with the control point (cp1x,cp1y).

  • ctx.arc
    (x, y, r, angle1, angle2, antiClockWise)

    Create an arc with center (x,y), r as a radius, and angle1 and angle2 as the start and end angles respectively. AntiClockWise is an optional boolean to specify the direction of drawing the arc. Default is false.

  • ctx.rect
    (x, y, w, h)

    creates a rectangular path starting at point (x,y) with width w and height h.

  • ctx.fill()

    Fill the current path with current ctx.filltSyle.

  • ctx.stroke()

    Strokes the current path(without filling) with current ctx.strokeStyle.

  • ctx.setTransform
    (a, b, c, d, e, f)

    Sets current transformation matrix to the passed matrix. See MDN docs for more details.

  • ctx.transform
    (a, b, c, d, e, f)

    Multiplies current transformation matrix with the passed matrix.See MDN docs for more details.

  • ctx.rotate
    (angle)

    Adds rotation transformation from the point(0,0)(top left corner of the canvas) to the current transformation matrix.

  • ctx.scale
    (x, y)

    Adds scaling transformation to the current transformation matrix.

  • ctx.translate
    (x,y)

    Adds translation transformation to the current transformation.

  • ctx.drawImage
    (img, sx, sy, swidth,
    sHeight, dx, dy, dWidth,
    dHeight)

    Draws an image with source img on the canvas. dx and dy specify the position to draw on the canvas starting from the top left corner.
    The rest of parameters are optional.dWidth and dHeight specify the area of the rectangle to draw on starting from point(dx,dy) on the canvas. sx and sy represent the coordinate offsets from the top left corner of the actual image. sWidth and sHeight specify the area of the image to draw. See MDN docs for more details.

  • ctx.save
    ()

    Saves the current drawing state(set of properties) to be restored when needed. See MDN docs for more details.

  • ctx.restore
    ()

    Restores the last saved drawing state. See MDN docs for more details.

Canvas


var meshgeo = new HoloBuild.HoloPlaneGeometry(0.2, 0.2);
var meshmat = new HoloBuild.HoloMeshBasicMaterial({ color: 'white' });
var mesh = new HoloBuild.HoloMesh(meshgeo, meshmat, false);
holoscene.add(mesh);

var holocanvas = new HoloBuild.HoloCanvas({ width: 1024, height: 1024 });
var ctx = holocanvas.getContext('2d');
var texture = new HoloBuild.HoloTexture(holocanvas);
var w = holocanvas.width;
var h = holocanvas.height;


var gradient = ctx.createLinearGradient(100,10, 220,0)
gradient.addColorStop(0, 'green');
gradient.addColorStop(0.5, 'cyan');
gradient.addColorStop(1, 'green');

ctx.fillStyle = gradient;
ctx.fillRect(0, 0, 256, 256);
texture.needsUpdate = true;
mesh.setMaterial({ map: texture });


HoloImage

The HoloImage class allows you to create an image object by loading it from a certain source.

Constructor
  • path

    The image path.

Properties
  • onLoad =
    callback()

    Callback function for when the image is loaded.