K3D JavaScript Canvas Library/API Reference

API Reference

K3D.BaseObject (k3d_object.js)

Abstract base class functionality for all K3D objects. K3D.BaseObject instances are objects that exist within the 3D space managed by a K3D.Controller and feature a number of user definable properties. They can describe the object relative position from the origin and allow set-up of simple animations that increment one or more of the angles or position vector properties for the object over time. The base class is also responsible for the initial part of the 3D rendering pipeline for an object by calculating the 3D matrix each frame for the object based on its rotation and position properties.

Public Properties

The following properties describe the point around which the object should be rotated during animation, default is the origin at 0,0,0:

aboutx (number)

x coordinate for the object rotation origin

abouty (number)

y coordinate for the object rotation origin

aboutz (number)

z coordinate for the object rotation origin

The following properties describe the initial rotatation angles for the object with respect to its rotation origin, default is zero degrees:

otheta (number)

the initial angle in degrees to rotate the object around the X axis

ophi (number)

the initial angle in degrees to rotate the object around the Y axis

ogamma (number)

the initial angle in degrees to rotate the object around the Z axis

The following properties describe how the engine should modify the rotation per animation frame, default is no animation:

addtheta (number)

degrees to add to the rotation around the X axis per animation frame

addphi (number)

degrees to add to the rotation around the Y axis per animation frame

addgamma (number)

degrees to add to the rotation around the Z axis per animation frame

The following properties describe the initial offset of the object in 3D space, this allows the object to be moved into a position, note that the rotation origin is then relative to this location, default is the origin at 0,0,0:

offx (number)

object offset x coordinate

offy (number)

object offset y coordinate

offz (number)

object offset z coordinate

The following properties describe the velocity to be applied to the object offset position in the x,y,z axis per animation frame, used to automatically move the object to create simple animations when combined with the bmin/max properties below, default is no velocity:

velx (number)

object velocity in the x axis

vely (number)

object velocity in the y axis

velz (number)

object velocity in the z axis

The following properties describe a virtual bounding box in which the object will be automatically "bounced" if it's offset location touches the edges of the box, this can be used to create simple 3D bouncing animations when combined with the velocity properties above, default is no bounding box defined:

bminx, bminy, bminz, bmaxx, bmaxy, bmaxz (number)

bounding box x, y, z minimum and maximum coordinates

scale (number)

describes a scaling factor to be applied to the points for the object before initial display. This is a one-time operation. It is generally used to scale up/down an object to fit the current canvas size. So you define an object once with a known size, and scale it before display for different animations etc. It does not actually move the observer closer to the object, just changes the size of the object. Default is 1.0.

Public Methods

The methods on K3D.BaseObject are called by sub-classes and it is not expected that they will be called directly by user code.

K3D.K3DObject (k3d_object.js)

Common functionality for K3D renderable objects. A sub-class of K3D.BaseObject, the K3D.K3DObject represents anything that is potentially rendered by the engine. There are a number of additional public properties that describe how the object should be rendered.

Public Properties

The following properties modify how the object is rendered by the engine:

drawmode (string)

• "point" - only render the points of an object.
• "wireframe" - render the edges of an object as lines,
• "solid" - render the polygons of an objects as solid filled polygons.

shademode (string)

• "plain" - plain color rendering, no attempt to light source or shade the lines or polygons, this is the simplest rendering mode.
• "depthcue" - z-ordered depthcued color rendering - the engine will shade the object from light to dark (using the object color as the lightest color) based on the z-order of the points and also adjust the relative line thickness to make lines in the background look further away than lines closest to the observer.
• "lightsource" - lightsourced color and textured rendering (only available for "solid" drawmode), by default the engine will shade the polygons in a color defined either by the base color of the object or by the color defined by the polygon itself if present and will also take any textures defined into account - the final lighting and shading calculation is based on the angle of the polygon surface from the observer. So with the default lighting, as polygons turn further away from the observer, they will be shaded darker. As well as the default lighting, additional coloured lights can be added to generate cool lighting effects (which themselves can be moved and modified during animation). See K3D.LightSource and also the Ultralight demo for an example of this feature.

color (Array)

default color of the object - used when "plain" shading mode is used for points, lines or polygons. Specified as RGB 0-255 values in an Array e.g. [255,255,255] is the white default color.

perslevel (number)

perspective level multiplier - powers of 2 recommended, default is 512. This value controls how strong the perspective effect is for the 3D->2D projection. Lower values give an intense 3D look, higher values give a flatter looking 3D projection.

linescale (number)

floating point scaling factor for "wireframe" drawing mode - use this to make wireframe edges of an object look thick or thin. Default value is 2.0 pixels.

doublesided (boolean)

by default this value is false as for performance reasons the engine will not render polygons that are not facing the observer. Set this flag to true to always render all polygons, visible or otherwise. This is useful if you want to see the back faces of an object i.e. inside of a cube or similar.

textures (Array)

an Array of texture Image objects available to the object during polygon rendering. When polygons are defined for an 3D object, a texture index can be specified and the index references this Array of images. Default is an empty array. See k3ddemos.js for an example of loading, setting up and defining polygons to use textures.

IMPORTANT: The initial points, edges and faces for an object should be set via the init method as described below, but the values within these structures can be manipulated during animation if required via the callback interface described later. See ultralight.js for an example of using the callback method to manipulate an object vertices in real-time.

points (Array)

the Array of point vertex coordinates for the 3D object. X,Y,Z coordinate values as an continuous single array of Number values. If it is required to manipulate the points during animation, then the underlying array index of the 3D coordinate of the value must be calculated correctly. For example, for the "X" coordinate of the 5nd point in the object: (5-1 * 3 + 0) = 12, for example the index of the "Z" coordinate of the 3rd point in the object: (3-1 * 3 + 2) = 8. The vertex list for an object is mandatory and will always exist after object init.

edges (Array)

the Array of edges for the 3D object. Edges are described as JavaScript objects with the structure {a: p1, b: p2} i.e. each value in the Array is a JavaScript object containing two properties "a" and "b" each referencing a 3D coordinate in the points Array. See example1.html and most other demo files for examples of how edges are described. The edge list is only required to be provided for objects that will be displayed in wireframe drawmode, therefore it can be omitted if required for objects only displayed as points or polygons.

faces (Array)

the Array of polygon faces for the 3D object. Each value in the Array is a JavaScript object with the structure:

{vertices:[p1...pN], color:[r,g,b], texture:n}

• vertices - array of 3D coordinate index values into the points array. At least 3 vertices per polygon must be provided.
• color - the RGB 0-255 integer colour value (optional - default is white)
• texture - index into the texture list for the object (optional - default is no texture)

examples:
{vertices:[0, 1, 2,], color:[0,255,0]} - generate a green triangle connecting 3D coordinates at index 0, 1 and 2.
{vertices:[0, 1, 2, 3], color:[255,0,0], texture:0} - generate a red quad connecting 3D coordinates at index 0, 1, 2 and 3 and use the texture image with index 0. See example3.html for texture mapped cube example. The faces list is only required to be provided for objects that will be displayed in solid drawmode, therefore it can be omitted if required for objects only displayed as points or wireframe.

Advanced rendering properties

recalulatenormals (boolean)

K3D performs a one-time calculation of the polygon normal vectors so that the polygons are correctly lit and correctly removed if not visible. Set this flag to true only if you manipulate the points during an animation (via the callback method) as then the engine will then need to recalculate the normal vectors for each frame. Default value is false.

fillstroke (boolean)

due to the way in which HTML5 canvas fills shapes, if you place two polygons exactly next to each other and render them, there will be a small 0.5 pixel thick gap between the polygons. This leads to a "cracking" effect that makes some objects look like they have thin holes in. To fix this, the engine can render each polygon twice, which causes canvas to "overdraw" the anti-aliased edges of the polygons, this is the fastest way to fix the problem. Set this property to true and the engine will double fill the polygons to fix the cracking effect. However this is a relatively expensive operation and will slow down the rendering.

depthscale (number)

when using depthcued rendering mode, this value controls the "middle point" for the depthcue/perspective scaling calculation. By default it is set to the width of the canvas/2. Generally you will not need to modify this value.

sortmode (boolean)

one of "sorted" or "unsorted", default is "sorted". Can be used to disable z-ordered sorting of objects before they are displayed. Generally you will not need to modify this value.

Public Methods

init(points -> Array, edges -> Array, faces -> Array) :initialise a 3D object with the points, edges and polygon faces to use. The structures expected for points, edges and faces are described above. This is a one-time init function and should only be called once before the K3D engine starts animating the rendering on the canvas.

Setting up a K3D object can be done easily by applying values to the various public properties and the coordinates etc. to the init method in a few lines of code, for example:

   ...
   // create a K3D object for rendering
   var obj = new K3D.K3DObject();
   with (obj)
   {
      color = [255,0,0];      // colour used for wireframe edges and depthcued rendering mode
      drawmode = "wireframe"; // one of "point", "wireframe", "solid"
      shademode = "plain";  // one of "plain", "depthcue", "lightsource" (solid drawing mode only)
      scale = 50;
      init(
         // describe the points of a simple unit cube
         [{x:-1,y:1,z:-1}, {x:1,y:1,z:-1}, {x:1,y:-1,z:-1}, {x:-1,y:-1,z:-1},
          {x:-1,y:1,z:1}, {x:1,y:1,z:1}, {x:1,y:-1,z:1}, {x:-1,y:-1,z:1}],
         // describe the edges of the cube
         [{a:0,b:1}, {a:1,b:2}, {a:2,b:3}, {a:3,b:0},
          {a:4,b:5}, {a:5,b:6}, {a:6,b:7}, {a:7,b:4},
          {a:0,b:4}, {a:1,b:5}, {a:2,b:6}, {a:3,b:7}],
         // describe the polygon faces of the cube
         [{color:[255,0,0],vertices:[0,1,2,3]},{color:[0,255,0],vertices:[0,4,5,1]},
          {color:[0,0,255],vertices:[1,5,6,2]},{color:[255,255,0],vertices:[2,6,7,3]},
          {color:[0,255,255],vertices:[3,7,4,0]},{color:[255,0,255],vertices:[7,6,5,4]}]
      );
   }
   ...

K3D.Controller (k3d_controller.js)

Here is the use of the controller adapted from the Example 1:

  // bind a K3D Controller object to the canvas
  // - it is responsible for managing the K3D objects displayed within it
  var k3d = new K3D.Controller(canvas);

  k3d.fps = 30; // request 30 frames per second animation from the controller

  var obj = new K3D.K3DObject(); // create a K3D object for rendering
  ....
  obj.scale = 50;
  obj.init(vertices, edges, faces);

  k3d.addK3DObject(obj); // add the object to the controller

  k3d.paused = false; // begin the rendering and animation immediately
  k3d.frame(); // render a frame before returning

The second boolean argument in K3D.Controller(canvas[, DisableClickToPause]) disables click-to-pause-animation if true.