Canvas 3d JS Library

There are various 3d modeling tools that you can use to build 3D models.  Which one you use can depend on your level of familiarity with the tool and your budget.  To use the model with canvas 3D, you only need to extract certain information out of of the model.  This can usually be done with scripts and parsers.  This tutorial will look at how to format the data for use with canvas 3D

Modeling Basics and Terminology

This section is meant for those who do not have much experience with 3D models and basic terminology.  If you are familiar with these terms, feel free to skip on to the next section. A model is built of triangles.  Any curved surface requires edges and therefore multiple triangles because each triangle is perfectly flat.  Typically the curvier an object is the more edges there are and the more triangles you have.  Triangles are typically one sided.  If you look at a triangle from the other side, the triangle will not be there.  Each triangle consists of 3 vertex.  Each vertex has a coordinate in 3D space with an x,y, and z component.  Each vertex of a triangle also has a vector called a normal.  Typically this vector is either pointing 90° away from the visible surface of the triangle.  It is also possible to take the normals of all the triangles that share the same vertex and use an average or weighted average of these normals. The triangle coordinates and normals defines the shape of the model  What it does not do is determine how a texture is applied to a model.  Simply put, a texture is a 2D graphic that is applied to each triangle of the model.  Typically it is best if the texture is square with power of 2 dimensions (512X512, 1024X1024 etc.).  If the 2D graphic is not a square with a power of 2 dimension, the library will increase the dimension to the next power of two value.  This can distort the texture and have unwanted visual effects.  To apply a texture to a model, each vertex of the model must be mapped to a point on the 2D graphic.   Thus, each vertex of a triangle also maps to a 2 value co-ordinate on a texture.  These values are typically called UV’s. Different modeling software will allow you to create models and texture them in different ways.  It is best to consult the modeling software’s tutorial on how to do this.  The rest of this tutorial will look at what information is needed and what format is necessary to use the models with the canvas3d js library

Coordinate System

The coordinate system for Canvas 3D is the right-handed coordinate system.   This means that positive Y is up, positive X is to the right, and positive Z is pointing out from the screen.  The following diagram details this. The texture (uv) coordinates have 0,0 at the top left corner of the texture and 1,1 is the bottom right.

File Format

Every model used by the canvas 3d js library requires 4 arrays.  Each of these arrays must have a unique name.  Thus, the easiest way to create a model that the canvas3d js library can use is to create a js file with 4 arrays containing the information needed.  The order of the array does not matter nor does the names of the arrays (as long as they are unique for your application).  This section will describe what information each of these arrays contains. To illustrate this file format we will use the following texture (0,0 will be at the red square with the number 1 in it, 1,1 will be at the red square with 8 in it) and the model of a 4 sided pyramid. Arrays: Vertex Array -  an array of triples that contain the coordinate of all unique vertices of the model.  Multiple triangles can share the same vertex.

var pyramidVertices=[
  [0.0, 10.0, 0.0],
  [-10.0, -10.0, 10.0],
  [10.0, -10.0, 10.0],
  [10.0, -10.0, -10.0],
  [-10.0, -10.0, -10.0]
];

Normal Array - an array of the unique normals for the model.  Similar to vertices, it is possible for different vertices to have the same normal:

var pyramidNormals=[
  [0.0, 0.894427, -0.447214],
  [-0.894427, 0.0, -0.447214],
  [0.0, -0.894427, -0.447214],
  [0.894427, 0.0, -0.447214],
  [0.0, 0.0, 1.0],
  [0.0, 0.0, 1.0]
];

UV - an array of UV coordinates.  For each coordinate, U first then V:

var pyramidUVs=[
  [ 0.5, 0.0],[ 0.0, 1.00187],[ 1.0, 1.0],
  [ 0.5, 0.0],[ 0.0, 1.0],[ 1.0, 1.0],
  [ 0.5, 0.0],[ 0.0, 1.00187],[ 1.0, 1.0],
  [ 0.5, 0.0],[ 0.0, 1.0],[ 1.0, 1.0],
  [ 0.0, 0.0],[ 0.0, 1.0],[ 1.0, 0.0],
  [ 0.0, 1.0],[ 1.0, 1.0],[ 1.0, 0.0]
];

An array of triangles.  Each triangle consist of 3 arrays of triples (below, 1 triangle is defined on each line).  The first array defines the first corner of a triangle, the second array the second corner, the third array for the third corner.  The first value within the array of triple is the index  in the vertex array, the second value is the index of in the UV array, the third is the index in the normal array:

var pyramidFaces=[
  [0, 0, 0],[1, 1, 0],[2, 2, 0],  //first triangle, the first vertex is at (0.0, 10.0, 0.0)
                                  //its UV is (0.5, 0.0)its normal is (0.0, 0.894427, -0.447214)
  [0, 3, 1],[2, 4, 1],[3, 5, 1],
  [0, 6, 2],[3, 7, 2],[4, 8, 2],
  [0, 9, 3],[4, 10, 3],[1, 11, 3],
  [1, 12, 4],[4, 13, 4],[2, 14, 4],
  [4, 15, 5],[3, 16, 5],[2, 17, 5]
];