JS3D (alpha) : 3d with text in Javascript 2007

Click the cube to toggle animation

What is JS3D

JS3D is a library which allows you to have interactive 3d objects on your website, such as the spinning cube at the top of the page. The 3d effect is created using actual text, try selecting the text on the cube above! This is different from the approach of, for instance, these folks , who have made a better quality renderer, which is much more processor intensive. To see more functionality scroll to the demo section.

It is extremely preliminary, so bug reports or feature suggestions are appreciated (but I don’t guarantee getting around to anything). It has also only been tested in Firefox and Safari. Apparently it may work in IE6+ now thanks to a bug-fix from Alessio Carnevale, however I have no means to test this.

Is this useful?

Maybe not. If you actually want to use 3d on the web you should consider using SVG or the new canvas element in HTML5. An OpenGL-based canvas allowing true hardware accelerated graphics in the browser called WebGL is also in the works and should show up soon.

How do I use JS3D?

Simple! (Well not actually). For now it involves a bit of knowledge of javascript and HTML (and some matrix math wouldn’t hurt.)

Download it

Download js3d.js (which is free and licensed under the GPL) and put it in a directory your page can access. For the sake of this example we’ll assume it’s located at /js/js3d.

Configure your markup

Import the js3d by adding this code into the <head> section

<script type="text/javascript" src="/js/js3d.js"></script>

Now you’ll need to make an empty div somewhere on your page (inside the <body> tags, which will serve as the canvas to which it will paint your 3d images. Note that at the moment, this div must be either fixed or absolute positioned. Also, the its styling code must be in-line (not in an external stylesheet). An example div could be:

<div id="canvas" style="position:absolute;
				left:10px;
				top:10px;
				width:500px;
				height:400px;
				border:thin solid black;">
</div>

Next we need to initialize a renderer, and tell it to render into the div we just created. First, we’ll make it initialize once the page has loaded by adding an onLoad property to the body tag thus:

<body onLoad="init();">

Next place the following code in your head tag. This defines what that init() method mentioned earlier does.

<script type="text/javascript">
    var canvas;
    function init() {
        // This creates the renderer. The parameter to the constructor
        // (in quotes) gives the id of the div to render in.
        canvas = new JS3D("canvas");
    
    }
</script>

Add objects to the scene

The bad news is, at the moment the only built-in objects you can add are points and lines. The good news is, as with the cube above, you can make other shapes with these.

The function to add a point is called addPoint(x,y,z,text,m). The first three parameters are mandatory, they correspond to the coordinates of the point (in pixels, from the top-left of the canvas by default). The fourth parameter defines the symbol to use to represent the point (the symbol character in the cube at the top). I’m not going to get in to the fifth parameter, but it defines a transformation matrix to apply to the point. If that doesn’t make sense, ignore it.

Nothing will be drawn if it has a z component of greater than 0, since that would mean it was closer to you than the screen.

To add lines use the function addLine(x1,y1,z1,x2,y2,z2,num,text,m). In this function, x1, y1, and z1 are the coordinates for the start of the line, and x2, y2, and z2 are the coordinates of the end of the line. num defines how many points should make up the line. The last two parameters are optional, and have the same behaviour as for points.

Transform the scene<

The functions for transforming the scene are as follows, note that m can be omitted from all of them.

  1. rotateX(angle,m) Rotate around the x-axis by the given number of radians
  2. rotateY(angle,m) Rotate around the y-axis by the given number of radians
  3. rotateZ(angle,m) Rotate around the z-axis by the given number of radians
  4. translate(dx,dy,dz,m) Translate by the given number of pixels
  5. scale(x,y,z,m) Scale in each direction by the given amount, where 1 is unchanged, 2 would be twice as big, 0.5 would be half as big, and so on.

The syntax to use these functions is as follows

canvas.matrix = canvas.rotateY(0.1);

and similarly with the other functions. Note that the canvas.matrix part is necessary, as it specifies what we are rotating.

Render the scene

Okay, so you've added all the objects you want, and rotated the scene as you see fit. Now how do you get it to show up? Simple, just use the paint() method. That is: 

canvas.paint();

Advanced Features

Well, I’m tired of writing these instructions right now, so for now this section is still to come. However, if you’re really such an advanced user just read the code of the examples. These features allow you to do things such as have individual objects rotated seperately from the scene. Also, things like animation and colour changing are feasible using standard javascript techniques like setTimeout

Demos

## News
  1. 2007-02-05
    • v0.1a released
    • Fix: no longer paints objects outside the bounds of the canvas.
    • Added an optional limit for the closest z-index points to draw
    • Added the double helix demo.
  2. 2007-02-03
    • Initial release

The end. Back to top?