zincjs 1.0.16 → 1.1.0

package/src/primitives/augmentShader.js

@@ -1,3 +1,7 @@
+
+/**
+ * Provide additional shaders to render time dependent color.
+ */
 exports.augmentMorphColor = function() {
     return function(shader) {
         shader.vertexShader = shader.vertexShader.replace(

package/src/primitives/geometry.js

@@ -7,7 +7,7 @@ const THREE = require('three');
  * 
  * @class
  * @author Alan Wu
- * @return {Zinc.Geometry}
+ * @return {Geometry}
  */
 const Geometry = function () {
   (require('./zincObject').ZincObject).call(this);
@@ -15,6 +15,19 @@ const Geometry = function () {
 	this.videoHandler = undefined;
   this.isGeometry = true;
 
+  /**
+   * Create the mesh for rendering
+   * 
+   * @param {THREE.Geomtry} geometryIn - Geometry to be rendered.
+   * @param {THREE.Material} materialIn - Material to be set for the geometry.
+   * @param {Object} options - Provide various options
+   * @param {THREE.Color}  options.colour - colour to be set for the geometry
+   * @param {Boolean} options.localTimeEnabled - A flag to indicate either the geometry is
+   * time dependent.
+   * @param {Boolean} options.localMorphColour - A flag to indicate either the colour is
+   * time dependent.
+   * @param {Number} options.opacity - Opacity to be set for the geometry
+   */
 	this.createMesh = (geometryIn, materialIn, options) => {
 		if (this.geometry && this.morph && (geometryIn != undefined))
 			return;
@@ -73,7 +86,10 @@ const Geometry = function () {
 		let mesh = new THREE.Mesh(geometry, material); 
 		this.setMesh(mesh, options.localTimeEnabled, options.localMorphColour);
 	}
-	
+
+  /**
+   * Calculate the UV for texture rendering.
+   */
 	this.calculateUVs = () => {
 		this.geometry.computeBoundingBox();
 		const max = this.geometry.boundingBox.max, min = this.geometry.boundingBox.min;

package/src/primitives/glyph.js

@@ -4,107 +4,127 @@ const THREE = require('three');
  * Zinc representation of glyph graphic, it contains the colours, 
  * geometry and transformation of the glyph.
  * 
- * @param {THREE.Geometry} geometry - Geometry of the glyph.
- * @param {THREE.material} materialIn - Material of the glyph.
+ * @param {THREE.Geometry} geometry - Geometry of the glyph .
+ * @param {THREE.Material} materialIn - Material of the glyph.
  * @param {Number} idIn - Id of the glyph.
  * 
  * @class
  * @author Alan Wu
- * @return {Zinc.Glyph}
+ * @return {Glyph}
  */
-const Glyph = function(geometry, materialIn, idIn, glyphsetIn)  {
+const Glyph = function (geometry, materialIn, idIn, glyphsetIn) {
   (require('./zincObject').ZincObject).call(this);
-	let material = undefined;
-	if (materialIn) {
-		material = materialIn.clone();
-		material.vertexColors = THREE.FaceColors;
-	}
-	const parent = glyphsetIn;
-	this.id = idIn;
-	let label = undefined;
-	let labelString = undefined;
-	const group = new THREE.Group();
-	this.isGlyph = true;
-	
-	this.fromMesh = meshIn => {
-		if (meshIn && meshIn.isMesh) {
-			this.morph = meshIn.clone();
-			this.morph.userData = this;
-			group.add(this.morph);
-			return true;
-		} 
-		return false;
-	}
-	
-	if (geometry && material) {
-		this.fromMesh(new THREE.Mesh( geometry, material ));
-	}
-	
-	this.getGlyphset = function() {
-		return parent;
-	}
-	
-	this.setLabel = text => {
-		if (text && (typeof text === 'string' || text instanceof String)) {
-			labelString = text;
-			if (this.morph)
-      this.morph.name = text;
-		}
-		if (label)
-			this.showLabel();
-	}	
-	
-	this.showLabel = (colour) => {
-	  if (label) {
-		  position = label.getPosition();
-		  group.remove(label.getSprite());
-		  label.dispose();
-		  label = undefined;
+  let material = undefined;
+  if (materialIn) {
+    material = materialIn.clone();
+    material.vertexColors = THREE.FaceColors;
+  }
+  const parent = glyphsetIn;
+  this.id = idIn;
+  let label = undefined;
+  let labelString = undefined;
+  const group = new THREE.Group();
+  this.isGlyph = true;
+
+  /**
+   * Create a glyph using mesh
+   * @param   {THREE.Mesh} meshIn - Mesh to create the glyph from
+   *
+   * @returns {Boolean} true if successful
+   */
+  this.fromMesh = meshIn => {
+    if (meshIn && meshIn.isMesh) {
+      this.morph = meshIn.clone();
+      this.morph.userData = this;
+      group.add(this.morph);
+      return true;
+    }
+    return false;
+  }
+
+  if (geometry && material) {
+    this.fromMesh(new THREE.Mesh(geometry, material));
+  }
+
+  /**
+   * Get the {Glyphset} containing this glyph.
+   *
+   * @returns {Boolean} true if successful
+   */
+  this.getGlyphset = function () {
+    return parent;
+  }
+
+  /**
+   * Set and update the text containing this glyph.
+   * @param   {String} text - Label to be set for this instance
+   */
+  this.setLabel = text => {
+    if (text && (typeof text === 'string' || text instanceof String)) {
+      labelString = text;
+      if (this.morph)
+        this.morph.name = text;
+    }
+    if (label)
+      this.showLabel();
+  }
+
+  /**
+   * Display label with the choosen colour. It will replace the current
+   * label.
+   * @param   {THREE.Color} colour - Colour for the label.
+   */
+  this.showLabel = (colour) => {
+    if (label) {
+      position = label.getPosition();
+      group.remove(label.getSprite());
+      label.dispose();
+      label = undefined;
+    }
+    if (labelString && (typeof labelString === 'string' || labelString instanceof String)) {
+      let position = [0, 0, 0];
+      label = new (require('./label').Label)(labelString, colour);
+      label.setPosition(position[0], position[1], position[2]);
+      group.add(label.getSprite());
     }
-	  if (labelString && (typeof labelString === 'string' || labelString instanceof String)) {
-		  let position = [0, 0, 0];
-	    label = new (require('./label').Label)(labelString, colour);
-	    label.setPosition(position[0], position[1], position[2]);
-	    group.add(label.getSprite());
-	  }
-	}
-	
-	/**
-	 * Get the group containing the label and mesh.
-	 * @return {THREE.Group}
-	 */
-	this.getGroup = () => {
-		return group;
-	}
-	
-	/**
-	 * Get the label of this glyph
-	 * @return {Label}
-	 */
-	this.getLabel = () => {
-		return labelString;
-	}
-  
-	/**
-	 * Get the mesh of this glyph.
-	 * @return {THREE.Mesh}
-	 */
-	this.getMesh = () => {
-		return this.morph;
   }
 
-	/**
-	 * Set the transformation of this glyph.
-	 * @param {Array} position - Three components vectors containing position of the
-	 * transformation.
-	 * @param {Array} axis1 - Three components vectors containing axis1 rotation of the
-	 * transformation.
-	 * @param {Array} axis2 - Three components vectors containing axis2 rotation of the
-	 * transformation.
-	 * @param {Array} position - Three components vectors containing axis3 rotation of the
-	 * transformation.
-	 */
-	this.setTransformation = (position, axis1, axis2, axis3) => {
+  /**
+   * Get the group containing the label and mesh.
+   * @return {THREE.Group}
+   */
+  this.getGroup = () => {
+    return group;
+  }
+
+  /**
+   * Get the label of this glyph
+   * @return {Label}
+   */
+  this.getLabel = () => {
+    return labelString;
+  }
+
+  /**
+   * Get the mesh of this glyph.
+   * @return {THREE.Mesh}
+   */
+  this.getMesh = () => {
+    return this.morph;
+  }
+
+  /**
+   * Set the transformation of this glyph.
+   * @param {Array} position - Three components vectors containing position of the
+   * transformation.
+   * @param {Array} axis1 - Three components vectors containing axis1 rotation of the
+   * transformation.
+   * @param {Array} axis2 - Three components vectors containing axis2 rotation of the
+   * transformation.
+   * @param {Array} position - Three components vectors containing axis3 rotation of the
+   * transformation.
+   */
+  this.setTransformation = (position, axis1, axis2, axis3) => {
     if (this.morph) {
       this.morph.matrix.elements[0] = axis1[0];
       this.morph.matrix.elements[1] = axis1[1];
@@ -124,10 +144,15 @@ const Glyph = function(geometry, materialIn, idIn, glyphsetIn)  {
       this.morph.matrix.elements[15] = 1.0;
       this.morph.matrixAutoUpdate = false;
     }
-		if (label)
-		  label.setPosition(position[0],  position[1], position[2]);
-	}
-  
+    if (label)
+      label.setPosition(position[0], position[1], position[2]);
+  }
+
+  /**
+   * Set the color of the glyph and its label.
+   * 
+   * @param {THREE.Color} color - Colour to be set.
+   */
   this.setColour = (color) => {
     if (label)
       label.setColour(color);
@@ -136,14 +161,14 @@ const Glyph = function(geometry, materialIn, idIn, glyphsetIn)  {
     this.geometry.colorsNeedUpdate = true;
   }
 
-	/**
-	 * Clear and free its memory.
-	 */
-	this.dispose = () => {
-	  if (this.material)
-	    this.material.dispose();
-		this.morph = undefined;
-	}
+  /**
+   * Clear and free its memory.
+   */
+  this.dispose = () => {
+    if (this.material)
+      this.material.dispose();
+    this.morph = undefined;
+  }
 }
 
 Glyph.prototype = Object.create((require('./zincObject').ZincObject).prototype);

package/src/primitives/glyphset.js

@@ -2,14 +2,14 @@ const THREE = require('three');
 const JSONLoader = require('../loaders/JSONLoader').JSONLoader;
 
 /**
- * This is a container of {@link Zinc.Glyph} and their graphical properties 
+ * This is a container of {@link Glyph} and their graphical properties 
  * including transformations, colors, number of time steps, duration of animations
  * and group name. Please note that all glyphs in the glyphset share the same geometry
  * however they may have different transformations.
  * 
  * @class
  * @author Alan Wu
- * @return {Zinc.Glyphset}
+ * @return {Glyphset}
  */
 const Glyphset = function () {
   (require('./zincObject').ZincObject).call(this);
@@ -49,25 +49,25 @@ const Glyphset = function () {
     _points[i] = new THREE.Vector3();
   }
 
-	/**
-	 * Get the {@link Three.Group} containing all of the glyphs' meshes.
-	 * @returns {Three.Group}
-	 */
+  /**
+   * Get the {@link Three.Group} containing all of the glyphs' meshes.
+   * @returns {Three.Group}
+   */
   this.getGroup = () => {
     return this.morph;
   }
 
-	/**
-	 * Copy glyphset data into this glyphset then load the glyph's geoemtry 
-	 * with the provided glyphURL. FinishCallback will be called once
-	 * glyph is loaded.
-	 * 
-	 * @param {Array} glyphsetData - contains the informations about the glyphs.
-	 * @param {String} glyphURL - URL to the geometry which will be applied to all
-	 * all the glyphs in the glyphset once loaded.
-	 * @param {Function} finishCallback - User's function to be called once glyph's
-	 * geometry is loaded.
-	 */
+  /**
+   * Copy glyphset data into this glyphset then load the glyph's geoemtry 
+   * with the provided glyphURL. FinishCallback will be called once
+   * glyph is loaded.
+   * 
+   * @param {Array} glyphsetData - contains the informations about the glyphs.
+   * @param {String} glyphURL - URL to the geometry which will be applied to all
+   * all the glyphs in the glyphset once loaded.
+   * @param {Function} finishCallback - User's function to be called once glyph's
+   * geometry is loaded.
+   */
   this.load = (glyphsetData, glyphURL, finishCallback, isInline, displayLabels) => {
     axis1s = glyphsetData.axis1;
     axis2s = glyphsetData.axis2;
@@ -101,11 +101,12 @@ const Glyphset = function () {
     }
   }
 
-	/**
-	 * Calculate the actual transformation value that can be applied 
-	 * to the transformation matrix.
-	 * @returns {Array}
-	 */
+  /**
+   * Calculate the actual transformation value that can be applied 
+   * to the transformation matrix.
+   * 
+   * @returns {Array}
+   */
   const resolve_glyph_axes = (point, axis1, axis2, axis3, scale, return_arrays) => {
     if (repeat_mode == "NONE" || repeat_mode == "MIRROR") {
       let axis_scale = [0.0, 0.0, 0.0];
@@ -166,7 +167,7 @@ const Glyphset = function () {
           mirrored_axis3[1] = -mirrored_axis3[1];
           mirrored_axis3[2] = -mirrored_axis3[2];
         }
-        return_arrays[1] =[mirrored_point, mirrored_axis1, mirrored_axis2, mirrored_axis3];
+        return_arrays[1] = [mirrored_point, mirrored_axis1, mirrored_axis2, mirrored_axis3];
       }
     }
     else if (repeat_mode == "AXES_2D" || repeat_mode == "AXES_3D") {
@@ -236,9 +237,9 @@ const Glyphset = function () {
     return return_arrays;
   };
 
-	/**
-	 * Update transformation for each of the glyph in this glyphset.
-	 */
+  /**
+   * Update transformation for each of the glyph in this glyphset.
+   */
   const updateGlyphsetTransformation = (
     current_positions,
     current_axis1s,
@@ -298,9 +299,9 @@ const Glyphset = function () {
     this.morph.instanceMatrix.needsUpdate = true;
   };
 
-	/**
-	 * Update colour for each of the glyph in this glyphset.
-	 */
+  /**
+   * Update colour for each of the glyph in this glyphset.
+   */
   const updateGlyphsetHexColors = current_colors => {
     let numberOfGlyphs = 1;
     if (repeat_mode == "AXES_2D" || repeat_mode == "MIRROR")
@@ -323,11 +324,11 @@ const Glyphset = function () {
     this.morph.instanceColor.needsUpdate = true;
   };
 
-	/**
-	 * Update the current states of the glyphs in this glyphset, this includes transformation and
-	 * colour for each of them. This is called when glyphset and glyphs are initialised and whenever
-	 * the internal time has been updated.
-	 */
+  /**
+   * Update the current states of the glyphs in this glyphset, this includes transformation and
+   * colour for each of them. This is called when glyphset and glyphs are initialised and whenever
+   * the internal time has been updated.
+   */
   const updateMorphGlyphsets = () => {
     const current_positions = _current_positions;
     const current_axis1s = _current_axis1s;
@@ -387,11 +388,11 @@ const Glyphset = function () {
             _bot_colour.b * proportion + _top_colour.b * (1 - proportion));
           current_colors[i] = _bot_colour.getHex();
         }
-				/*
-				for (var i = 0; i < bottom_colors.length; i++) {
-					current_colors.push(proportion * bottom_colors[i] + (1.0 - proportion) * top_colors[i]);
-				}
-				*/
+        /*
+        for (var i = 0; i < bottom_colors.length; i++) {
+          current_colors.push(proportion * bottom_colors[i] + (1.0 - proportion) * top_colors[i]);
+        }
+        */
       } else {
         current_colors = colors["0"];
       }
@@ -399,12 +400,20 @@ const Glyphset = function () {
     }
   };
 
+  /**
+   * Display the label of the glyphs in the glyphset.
+   */
   this.showLabel = () => {
     for (let i = 0; i < glyphList.length; i++) {
       glyphList[i].showLabel(this.morph.material ? this.morph.material.color : undefined);
     }
   }
 
+  /**
+   * Create the glyphs in the glyphset.
+   * 
+   * @param {Boolean} displayLabels -Flag to determine either the labels should be display or not.
+   */
   const createGlyphs = (displayLabels) => {
     if ((labels != undefined) && displayLabels) {
       for (let i = 0; i < numberOfVertices; i++) {
@@ -433,6 +442,11 @@ const Glyphset = function () {
     this.boundingBoxUpdateRequired = true;
   };
 
+  /**
+   * Add a custom {@link Glyph} to this {@link Glyphset}.
+   * 
+   * @param {Glyph} Glyph to be added.
+   */
   this.addCustomGlyph = glyph => {
     if (glyph.isGlyph)
       glyphList.push(glyph);
@@ -440,6 +454,12 @@ const Glyphset = function () {
     this.boundingBoxUpdateRequired = true;
   }
 
+  /**
+   * Add a THREE.Mesh object to be displayed as glyph in this {@link Glyphset}.
+   * 
+   * @param {THREE.Mesh} Mesh to be added.
+   * @param {Number} id of the mesh.
+   */
   this.addMeshAsGlyph = (mesh, id) => {
     if (mesh.isMesh) {
       const glyph = new (require('./glyph').Glyph)(undefined, undefined, id, this);
@@ -453,12 +473,13 @@ const Glyphset = function () {
     return undefined;
   }
 
-	/**
-	 * A function which iterates through the list of glyphs and call the callback
-	 * function with the glyph as the argument.
-	 * @param {Function} callbackFunction - Callback function with the glyph
-	 * as an argument.
-	 */
+  /**
+   * A function which iterates through the list of glyphs and call the callback
+   * function with the glyph as the argument.
+   * 
+   * @param {Function} callbackFunction - Callback function with the glyph
+   * as an argument.
+   */
   this.forEachGlyph = callbackFunction => {
     for (let i = 0; i < glyphList.length; i++) {
       callbackFunction(glyphList[i]);
@@ -539,24 +560,11 @@ const Glyphset = function () {
     return undefined;
   }
 
-  this.applyMatrix4ToBox = (box1, box2, matrix) => {
-    _points[0].set(box1.min.x, box1.min.y, box1.min.z).applyMatrix4(matrix); // 000
-    _points[1].set(box1.min.x, box1.min.y, box1.max.z).applyMatrix4(matrix); // 001
-    _points[2].set(box1.min.x, box1.max.y, box1.min.z).applyMatrix4(matrix); // 010
-    _points[3].set(box1.min.x, box1.max.y, box1.max.z).applyMatrix4(matrix); // 011
-    _points[4].set(box1.max.x, box1.min.y, box1.min.z).applyMatrix4(matrix); // 100
-    _points[5].set(box1.max.x, box1.min.y, box1.max.z).applyMatrix4(matrix); // 101
-    _points[6].set(box1.max.x, box1.max.y, box1.min.z).applyMatrix4(matrix); // 110
-    _points[7].set(box1.max.x, box1.max.y, box1.max.z).applyMatrix4(matrix); // 111
-    box2.setFromPoints(_points);
-  }
-
-
-	/**
-	 * Get the bounding box for the whole set of glyphs.
-	 * 
-	 * @return {Three.Box3};
-	 */
+  /**
+   * Get the bounding box for the whole set of glyphs.
+   * 
+   * @return {Three.Box3};
+   */
   this.getBoundingBox = () => {
     if (this.morph && this.ready && this.morph.visible) {
       if (this.boundingBoxUpdateRequired) {
@@ -564,7 +572,7 @@ const Glyphset = function () {
           this.morph.geometry.attributes.position);
         for (let i = 0; i < numberOfVertices; i++) {
           this.morph.getMatrixAt(i, _transformMatrix);
-          this.applyMatrix4ToBox(_boundingBox1, _boundingBox2, _transformMatrix);
+          _boundingBox2.copy(_boundingBox1).applyMatrix4(_transformMatrix);
           if (i == 0) {
             _boundingBox3.copy(_boundingBox2);
           } else {
@@ -573,6 +581,8 @@ const Glyphset = function () {
         }
         if (_boundingBox3) {
           this.cachedBoundingBox.copy(_boundingBox3);
+          this.morph.updateWorldMatrix();
+          this.cachedBoundingBox.applyMatrix4(this.morph.matrixWorld);
           this.boundingBoxUpdateRequired = false;
         } else
           return undefined;
@@ -582,11 +592,11 @@ const Glyphset = function () {
     return undefined;
   }
 
-	/**
-	 * Set the local time of this glyphset.
-	 * 
-	 * @param {Number} time - Can be any value between 0 to duration.
-	 */
+  /**
+   * Set the local time of this glyphset.
+   * 
+   * @param {Number} time - Can be any value between 0 to duration.
+   */
   this.setMorphTime = time => {
     if (time > this.duration)
       this.inbuildTime = this.duration;
@@ -612,14 +622,19 @@ const Glyphset = function () {
     return false;
   }
 
+  /**
+   * Get the current inbuild time of the 
+   * 
+   * @return {Number}
+   */
   this.getCurrentTime = () => {
     return this.inbuildTime;
   }
 
 
-	/**
-	 * Clear this glyphset and its list of glyphs which will release them from the memory.
-	 */
+  /**
+   * Clear this glyphset and its list of glyphs which will release them from the memory.
+   */
   this.dispose = () => {
     for (let i = glyphList.length - 1; i >= 0; i--) {
       glyphList[i].dispose();
@@ -638,12 +653,14 @@ const Glyphset = function () {
     this.groupName = undefined;
   }
 
-  //Update the geometry and colours depending on the morph.
+  /**
+   * Update the glyphsets if required the render.
+   */
   this.render = (delta, playAnimation, options) => {
     if (playAnimation == true) {
       let targetTime = this.inbuildTime + delta;
       if (targetTime > this.duration)
-        targetTime = targetTime - this.duration
+        targetTime = targetTime - this.duration;
       this.inbuildTime = targetTime;
       if (morphColours || morphVertices) {
         updateMorphGlyphsets();