Introduction to dojox.gfx3d library

Kun Xi

June 20, 2007

Abstract

dojox.gfx3d is proposed to render 3D objects in web browser, this introduction states the reasoning, desigh philosophy and unleashes some implementation details for the users to have a better understanding how this library works.

1 History of Graphic Library

dojo.gfx library has been developed since the Dojo Summer of Code 2006, This 2D graphics library provides a uniﬁed interface to manipulate the vector graphics, with 95% behavior consistence for SVG and VML render engines, across Mozilla Firefox, Safari, Opera and Microsoft Internet Explorer. Chart developers show great interest in dojo.gfx for data visualization and they encourage us to extend the library to support three dimension objects.

dojox.gfx3d is the new library for this feature request. Careful readers may notice the subtle name change: dojo.gfx is developed in dojotoolkit 0.4 code base, using dojo namespace; and dojox.gfx3d is proposed to work in dojo 0.9 code base only, using dojox namespace. To make things even worse, we have migrated dojo.gfx to the 0.9 code base and rename it as dojox.gfx2d. In short, dojo.gfx and dojox.gfx2d refer to 2D graphics library, with the same functionality but in different code base, dojox.gfx3d is the 3D graphics library.

Notice: all the names are subject to change since we are in quite a early stage.

2 Fundamental of Computer Graphics

Mathematically, three dimensional object is represented by sets of points $(x, y, z)$ . The coordination can be translated, rotated and scaled, i.e world transfrom $^{1}$ in 3D domain; then 3D objects are projected to 2D shapes for presentation, aka Camera transform.

2.1 World Transform

World transform is quite useful for the users. Consider the following scenario: a rotated cube, You may go through all troubles to calculate the coordinations manually; or create an “normal” cubic, and then apply a set of world transformation to move it to the right position.

The world transform matrix consists ﬁve matrices:

T = [\begin{matrix} 1 & 0 & 0 & x \\ 0 & 1 & 0 & y \\ 0 & 0 & 1 & z \\ 0 & 0 & 0 & 1 \end{matrix}] - translation matrix

R_{x} = [\begin{matrix} 1 & 0 & 0 & 0 \\ 0 & c o s α & - s i n α & 0 \\ 0 & s i n α & c o s α & 0 \\ 0 & 0 & 0 & 1 \end{matrix}] - rotation about the x-axis

R_{y} = [\begin{matrix} c o s β & 0 & s i n β & 0 \\ 0 & 1 & 0 & 0 \\ - s i n β & 0 & c o s β & 0 \\ 0 & 0 & 0 & 1 \end{matrix}] - rotation about the y-axis

R_{z} = [\begin{matrix} c o s γ & - s i n γ & 0 & 0 \\ s i n γ & c o s γ & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{matrix}] - rotation about the z-axis

S = [\begin{matrix} S_{x} & 0 & 0 & 0 \\ 0 & S_{y} & 0 & 0 \\ 0 & 0 & S_{z} & 0 \\ 0 & 0 & 0 & 1 \end{matrix}] - scale matrix

We take the OpenGL convention for the world transform, the world transformation matrix is deﬁned as:

W = T \times R_{x} \times R_{y} \times R_{z} \times S

(1)

Note: The order of the transfrom matrix is arbitary

And we apply the world transform matrix on the left side of the corordination $(x, y, z)$ to get the new coordination $(x^{'}, y^{'}, z^{'})$ :

[\begin{matrix} x^{'} \\ y^{'} \\ z^{'} \\ c \end{matrix}] = W \times [\begin{matrix} x \\ y \\ z \\ 1 \end{matrix}]

(2)

2.2 Camera Transform

How the 3D object looks like in 2D surface is determined by where we stand and from which angle we take the view $^{2}$ .

Isometric projection is used in dojox.gfx3d to project the transformed 3D objects to 2D shapes, which is much simpler than persepctive projection and still widely used in the pseudo 3D games. The identity camera transform casts $(x, y, z)$ to $(x, y)$ , you may imagine parallel lights from the Z-axis casting the shadow to $X - Y$ plate. If we transform, rotate the plate, the casted coordinations may change, i.e the idea of camera transform.

C T = [\begin{matrix} 1 & 0 & 0 & - x \\ 0 & 1 & 0 & - y \\ 0 & 0 & 1 & - z \\ 0 & 0 & 0 & 1 \end{matrix}] - inverse object translation

C R_{x} = [\begin{matrix} 1 & 0 & 0 & 0 \\ 0 & c o s α & s i n α & 0 \\ 0 & - s i n α & c o s α & 0 \\ 0 & 0 & 0 & 1 \end{matrix}] - inverse rotation about the x-axis

C R_{y} = [\begin{matrix} c o s β & 0 & - s i n β & 0 \\ 0 & 1 & 0 & 0 \\ s i n β & 0 & c o s β & 0 \\ 0 & 0 & 0 & 1 \end{matrix}] - inverse rotation about the y-axis

C R_{z} = [\begin{matrix} c o s γ & s i n γ & 0 & 0 \\ s i n γ & c o s γ & 0 & 0 \\ 0 & 0 & 1 & 0 \\ 0 & 0 & 0 & 1 \end{matrix}] - inverse rotation about the z-axis

The camera transform matrix is deﬁned as $^{3}$ :

C = C R_{x} \times C R_{y} \times C R_{z} \times C T

(3)

The overall transfrom matrix is:

M = C \times T

(4)

3 Design Philosophy

Unlike dojo.gfx, there is no native 3D render engine available in the main stream web browsers so far, so dojox.gfx3d will project the 3D objects to 2D shapes, then render the surface using gradients and patterns to mimic the lighting and texture.

3.1 Viewport

dojox.gfx3d.Viewport (Viewport in the following $^{4}$ ) is the container for all 3D objects, created by the exported static function, createViewport:

dojox.gfx3d.createViewport(parentNode, width, height)

Viewport would expose the following interfaces to create basic 3D objects:

      dojox.gfx3d.Viewport.createLine(start, end)
      dojox.gfx3d.Viewport.createPath(path)
      dojox.gfx3d.Viewport.createTriangle(a, b, c)

and some high level objects as well:

      dojox.gfx3d.Viewport.createCube(upper, lower)
      dojox.gfx3d.Viewport.createCylinder(top, bottom, r)
      dojox.gfx3d.Viewport.createPipe(path, r)
      dojox.gfx3d.Viewport.createCone(top, bottom, r)

Viewport is the container of 3D objects, and also the environment and viewport.

dojox.gfx3d.Viewport.setCamera(camera)
dojox.gfx3d.Viewport.addLighting(lighting)

We may steal more ideas from Pov-Ray $^{5}$

Viewport is also our home-brewed 3D engine, with the folowing services exported:

dojox.gfx3d.Viewport.applyCameraTransform(point)
dojox.gfx3d.Viewport.renderLighting(surface, texture)

3.2 Scene

dojox.gfx3d.Scene(Scene in the following) is a container for Scene objects and other 3D objects, equivalent to dojo.gfx.Group. Users can group several 3D objects and apply the world transformation to them in one shot. Scene also supports to create 3D objects.

3.3 Object

dojox.gfx3d.Object(Object in the following) is the base class for other 3D objects, equivalent to dojo.gfx.Shape. Here are the available attributes:

Node: the attached DOM node
Object: interface for the users to manipulate the 3D object. For example, dojox.gfx3d.Triangle’s Object is the triple (a, b, c)
Texture: used to render the surface $^{6}$
Stroke: stroke attribute for the line
Transform: world transform matrix

The following 3D objects are derived from Object:

dojox.gfx3d.Line
dojox.gfx3d.Path
dojox.gfx3d.Triangle
dojox.gfx3d.Cube
dojox.gfx3d.Cylinder
dojox.gfx3d.Cone
dojox.gfx3d.Pipe

3.3.1 Line

Line is described as start $(x, y, z)$ and end $(x, y, z)$ . The texture attribute only supports dojox.gfx3d.Texture.Hollow, compliant to the Object interface.

3.3.2 Path

Path supports two mode as dojo.gfx.Path does, Absolute and Relative. In Relative mode, the coordination is the offset of current position, while in Absolute mode, the coordination is the absolute corordination in the 3D space. Only a subset of drawing commands are supported:

moveTo: move current postion to the new position
lineTo: draw a line from current position to a new position
curveTo: draw a bezier curve in 3D space.

The texture attribute only supports dojox.gfx3d.Texture.Hollow

3.3.3 Triangle

Triangle is the fundamental element to build more complicated 3D objects, described as a $(x, y, z)$ , b $(x, y, z)$ , c $(x, y, z)$ . The texture attribute supports all dojox.gfx3d.Texture.*.

3.3.4 Cube

Cube $^{7}$ is deﬁned by the two vertices in the diagram, uppper $(x, y, z)$ and lower $(x, y, z)$ , each surface is perpendicular to one of axises.

3.3.5 Cylinder

Cylinder is deﬁned as top $(x, y, z)$ , bottom $(x, y, z)$ and r (radius). top, bottom are the corordinations of the center of top, bottom surfaces.

3.3.6 Cone

Cone $^{8}$ is deﬁned as top $(x, y, z)$ , bottom $(x, y, z)$ and r (radius). top is the coordination of the tip of cone; bottom is the corordinations of the center of bottom surface; r is the radius of the bottom surface.

3.3.7 Pipe

Pipe $^{9}$ may stir the interest of Chart developers. It is charactized by 3D Path with r(radius) and texture.

3.4 Interoperation

To integrate the dojox.gfx2d and dojox.gfx3d, we are going to derive dojox.gfx3d.Viewport from dojox.gfx2d.Shape, in another word, Viewport is regarded as yet another 2D shape. This may sound ridiculous, but logically, the 3D space is a 2D canvas with a rich set of command, just as dojox.gfx2d.Path is; pragmatically, this enable users to aggregate more than one Viewport into Surface, a good candidate for subgraphic $^{10}$ .

3.5 Meta

All meta data used to describe 3D objects is discussed here.

3.5.1 Transform matrix

Transform matrix is deﬁned as:

[\begin{matrix} x x & x y & x z & d x \\ y x & y y & y z & d y \\ z x & z y & z z & d z \\ 0 & 0 & 0 & 1 \end{matrix}]

so the 3D transform matrix in dojox.gfx3d is deﬁned as a dictionary: ${x x, x y, x z, y x, y y, y z, z x, z y, z z, d x, d y, d z}$

3.5.2 Lighting

TODO

3.5.3 Texture

The following textures are supported:

Solid: Solid color ${r, g, b, a l p h a}$ , alpha indicates the transparency.
Hollow: Specialized Solid, aka ${r : 255, g : 255, b : 255, a l p h a : 1.0}$

4 Implementation Notes

This section discusses the detail plan to implement dojox.gfx3d.

4.1 Projection

This is the design dilemma for Viewport class. Space holds the camera transform matrix and lighting vector, 3D objects hold the object data, and virtually knows best how to draw itself.

The ﬁrst approach is to encapsulate the drawing capacity in each object class, and associate a Space reference. The object class calls dojo.gfx.Sapce.applyCameraTransform to project itself into 2D space, renders the surface using dojo.gfx.Viewport.renderLighting. This approach would not work if we take the z-order and shadow cast from other objects into account.

The second approach is to offload the rendering to Viewport. The Viewport would iterate all 3D objects and only render what are in our horizon and compute the shadow cast from other objects. The main obstacle for this approach is how Viewport knows to render the object:

Abstract 3D objects to fundamental objects like surface, line: The object submits a set of surfaces, lines to Viewport, then let Surface do all the work. Though any surface can be approxmated by polygons or NURB surface theoretically, it is really overkill for simple object like cylinder, cone; and quite computation-extensive.
Object exposes callback functions for Viewport: Object class generally has a better understanding the object data.

dojox.gfx3d.Object exposes the following callback functions for Sapce to render itself:

dojox.gfx3d.Object.getShadows(lightings): Based on the Viewport’s lighting vectors, the shadow vector cast from the object itself.
dojox.gfx3d.Object.render(camera, lightings, shadows): Based on Viewport’s camera transform matrix, the object is projected to 2D surface, using lighting vector, global shadow vectors to render the surface.

A preliminary approach ignores the shadow, so only the lighting and z-order are considered.

5 Conclusion

dojox.gfx3d rocks.