K3D JavaScript Canvas Library/Source files

The canvas K3D libraries at http://kevs3d.co.uk/dev/canvask3d by Kevin Roast are JavaScript libraries for three dimensional graphics using HTML5 canvas. As of October 18th, 2011, they included these files:

example1.html

Runs the simplest possible K3D example, showing setup of a simple HTML5 page with a canvas element, importing the K3D libraries, set up and display of an animated wireframe 3D cube.

example2.html

A simple K3D example, showing setup of a simple HTML5 page with a canvas element, importing the K3D libraries, set up and display of an animated lightsourced 3D cube - the cube animated by bouncing around a virtual bounding box.

example3.html

Another simple example, displaying an animated texture mapped lightsourced 3D cube.

k3d_test.html

Shows five demonstrations; "Click the demos above to start or stop them! Last Updated: 22/08/11"; the author's contact information; links to more demos and the link to download the source code .zip files described here. In the center the initially running demonstration shows a couple dozen wireframe cubes composited over a texture of chili peppers. The icosahedron in the lower left will respond to spacebar key presses to transition between polygons, a wireframe, and points, while the sphere on the lower right shows texture mapping to animated objects.

k3d_test_DEBUG.html

As k3d_test.html above but TPF (time per frame) and FPS (frames per second) statistics are shown.

scripts/k3ddemos.js

This file used by k3d_test.html and k3d_test_DEBUG.html sets up the five demos on five canvas elements:

1. "A snake of cubes", using 24 new K3D.K3DObject()s, each with a different .ophi and .otheta property, and the same drawmode="wireframe", addgamma, add{gamma,theta,phi}, about{x,y,z}, and scale properties, init(points in coordinates, vertices in point pairs, faces as a color and four vertices each); then K3D.Controller(canvas element).addK3DObject() for all 24 cubes
2. "distribute points on the surface of a sphere in a spiral", first creating a list of points and edges around a sphere, then K3DObject's add{gamma,theta,phi}, linescale, init(pts, edges, []), then addK3DObject()
3. "wireframe spiral sphere" same as the previous except with drawmode="wireframe"
4. "Icosahedron" generator code, drawmode="solid" initially, shademode="lightsource", fillstroke="false" initially, with init(points, edges, polygons by vertices with colors)
5. "tesselated sphere - strips of tris have been converted to quads" drawmode="solid", shademode="lightsource", but with init(points, [], polygons by vertices with textures)

Also included are sections of code as useful examples with the following headings:

• "add lightsource for solid object demo"
• "add an object to represent the lightsource so it is visible in the scene" (also for solid object demo #5 above)
• "render first frames"
  • "use motion blur background fill"
• "bind document keyhandler to aid debugging"

ultralight.html

This runs a pointer-manipulable animated demo that is an example of animated colour lights and also manipulating the vertices of an object in real-time via the callback interface.

ultralight_DEBUG.html

As ultralight.html above but TPF (time per frame) and FPS (frames per second) statistics are shown.

scripts/ultralight.js

This file used by ultralight.html and ultralight_DEBUG.html sets up the demos 3D object on the canvas element, the object vertex callback method to modify the object and pointer interaction to rotate the object.

Included are sections of code as useful examples with the following headings:

• "generate test objects" "A tesselated sheet", generates a flat sheet of rectangles (tesselated plane) as a K3D object. The function tesselatedPlane() could be reused in other demos for this purpose.
• "manipulate points", example of modifying the vertices of an object in real-time via the callback method.
• "add light sources", add multiple colour lights
• "add 3D objects to represent the light sources so they are visible in the scene", example of adding visible 3D objects that represent the location of the lights in the scene.
• "nifty drag/touch event capture code borrowed from Mr Doob http://mrdoob.com/", public domain code to bind the mouse and mobile device touch events into handlers to allow user controlled real-time rotation of the object.

html5logo.html

This runs a pointer-manipulable animated demo that is an example of the new HTML5 logo in 3D. There is also an animated background generated using standard canvas 2D APIs.

html5logo_DEBUG.html

As html5logo.html above but TPF (time per frame) and FPS (frames per second) statistics are shown.

scripts/html5logo.js

This file used by html5logo.html and html5logo_DEBUG.html sets up the demos 3D objects on the canvas element and pointer interaction to rotate the object. The HTML5 logo object is composed of several object sections defined as separate K3D objects and added to a single K3D controller for compositing together.

Included are sections of code as useful examples with the following headings:

• "add render loop callback", example of a K3D render callback function
• "manually clear bg - as we want to render some extra goodies, draw bg effect before K3D does its 3D rendering", manually clearing the background and performing some canvas 2D API calls to generate a custom background before K3D is used to render the HTML5 logo.
• "nifty drag/touch event capture code borrowed from Mr Doob http://mrdoob.com/", public domain code to bind the mouse and mobile device touch events into handlers to allow user controlled real-time rotation of the object.

scripts/mathlib.js

This math library begins with the mathematical constants and functions RAD (pi/180), PI, TWOPI, ONEOPI (1/pi), PIO2 (pi/2), PIO4, PIO8, PIO16, PIO32, Rnd=Math.random(), Sin(), Cos(), Sqrt(), Floor(), Atan2(), Ceil(), followed by randomInt(low, high), weightedRandom(weight) -- which seems to return a float from [0,1] -- and the calcNormalVector(x1,y1,z1,x2,y2,z2) function returning a new Vector3D.

They are followed by the extend(subclass to modify, superclass to inherit, overrides properties and/or methods) utility function, "to set up the prototype, constructor and superclass properties to support an inheritance strategy that can chain constructors and methods. Static members will not be inherited." It is used for some of the K3D classes defined in the k3d_... files below, and not in this file.

Then isArray(object), a boolean function is defined as object.constructor.toString().indexOf("Array") !== -1.

Then the two dimensional Vector class is defined with a vector(x,y) initializer, .x and .y properties initialized to 0, followed by the .clone(), .set(vector), .add(v), .sub(v), .dot(v), .length(), .distance(v), .theta(), .thetaTo(v), .thetaTo2(v), .norm(), .rotate(angle), .invert(), .scale(s), and .scaleTo(size) methods.

Then the Vector3D class is defined similarly with a vector3D(x,y,z) initializer, a .prototype property {x:0,y:0,z:0}, the methods shown above along with .cross(vector3D), .norm(), but not including .theta(), .thetaTo2(), or .scaleTo().

Finally, an image Preloader class is provided with the .addImage(image, url) and .onLoadCallback(fn) method.

scripts/k3d_*.js

The various k3d JavaScript files k3d_main.js, k3d_controller.js, k3d_object.js, k3d_light.js and k3d_renderer.js contain the source for the library itself. Refer to the API Reference pages for library reference information and code examples.

scripts/DEBUG.js

This very short source file (DEBUG = { FPS: false };) suggests that statistics are turned off by default, unless the DEBUG.FPS value is set to true, which is done with script tags in the ..._DEBUG.html files included with the source code zipfile above.

phpobj/obj_to_kv3d.php

A PHP script for converting from Wavefront .obj file format to arguments for K3D.Controller's init() method. There is example output on http://www.kevs3d.co.uk/dev/canvask3d/example_phpobj.html — "view source" and scroll down to "// pasted output from the .kv3d file output by obj_to_kv3d.php script".

Example usage: php obj_to_kv3d.php cube.obj > cube.k3d

This will direct the output of the script converting the cube.obj file to a new file cube.k3d. Example contents of the file:

[{x:0.0,y:0.0,z:0.0},{x:0.0,y:0.0,z:1.0},{x:0.0,y:1.0,z:0.0},{x:0.0,y:1.0,z:1.0},{x:1.0,y:0.0,z:0.0},{x:1.0,y:0.0,z:1.0},{x:1.0,y:1.0,z:0.0},{x:1.0,y:1.0,z:1.0}],
[],
[{vertices:[0,6,4]},{vertices:[0,2,6]},{vertices:[0,3,2]},{vertices:[0,1,3]},{vertices:[2,7,6]},{vertices:[2,3,7]},{vertices:[4,6,7]},{vertices:[4,7,5]},{vertices:[0,4,5]},{vertices:[0,5,1]},{vertices:[1,5,7]},{vertices:[1,7,3]}]

This 3D data can be pasted directly into the init() method for a K3DObject - such as in this example: http://en.wikibooks.org/wiki/K3D_JavaScript_Canvas_Library/Tutorial#Example_1:_Minimum_simple_page_set-up_and_Hello_World_example_K3D_object

images/{peppers,texture{0,1,2,3,4,5}}.png

These are six .PNG format graphics files, the first of which is used for a compositing background and the others for polygon textures during the various demos.