Library Overview

Back to documentation index.

Public-Domain Geometry Utilities Library

This page will introduce the Geometry Utilities Library, an open-source JavaScript library that I wrote.

This library contains classes and utility methods to represent 3-D geometries, including curves and surfaces, in JavaScript, and methods that support the development of 3D applications, including HTML applications that use the 3-D canvas.

The library differs from many others because this one is in the public domain, so no permission is required to use it.

This page includes information on how to use the Geometry Utilities Library and an overview of its features.

Note: The Geometry Utilities Library was formerly called the Public-Domain HTML 3D Library. Classes that involved the HTML 3D canvas, shaders, or the 3-D scene graph were removed, to make this library much more general-purpose. In any case, such classes are not as trivial to port to other 3-D rendering APIs or other programming languages as classes that merely generate and store 3-D geometry or implement math functions (however, shader-based filters are still included as extras, even though the Geometry Utilities Library currently doesn’t use them directly).

Example

The following is a screen shot of a scene generated with the help of the former Public Domain HTML 3D Library. Currently, however, the Geometry Utilities library has no means to render 3-D geometry directly.

Contents

How to Use

  1. Download the Geometry Utilities Library.
  2. Extract the file “h3du_min.js” or “h3du_module.js”, as appropriate.

  3. If using the script version in an HTML Web page, and write the following code in every HTML page where you will use the library.

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

  4. If using the module version in a modern HTML Web page or a modern ECMAScript module, you can import all symbols in this module with either of the following:

    import * from "h3du_module.js";
// -- or --
import * as H3DU from "h3du_module.js";

List of Classes

This is an overview of most of the JavaScript classes available in this library:

For much more information on all of these classes, see my documentation for the Geometry Utilities Library.

The following sections detail how an application that renders 3-D graphics can use this library.

The “Camera”

The MathUtil class contains methods that support the concepts of a “projection transform” and a “view transform”, as are common in many 3D rendering libraries. If we use the concept of a “camera”, the projection is like setting the camera's focus and lens, and the view transform is like setting its position and orientation. MathUtil has methods for generating 4 × 4 matrices that represent some kinds of projection and view transformations, including MathUtil.mat4perspective (a perspective projection) and MathUtil.mat4lookat (a look-at view transform). For more information, see The “Camera” and Geometric Transforms.

3D Models

Most 3D scenes are made up of meshes, or the triangles, lines, and points that make up a geometric three-dimensional object. Meshes can be simple, such as a cube, or very complex, such as a town model complete with houses. You create a mesh using the MeshBuffer class, or create a built-in geometric shape using a method in the Meshes class. The example below shows how you can create a box mesh:

// Create a box mesh 10 units in width, 20 units
// in height, and 25 units in depth
var mesh=Meshes.createBox(10,20,25);

Here are some other built-in methods for creating meshes. This page doesn't explain all the features or parameters in the Meshes class; for that, see the Meshes API documentation.

The methods described above return a MeshBuffer object describing the appropriate mesh’s geometry. Methods that can be called on a MeshBuffer include the following:

Shapes

The Shape constructor method assigns a linear or perspective transformation (including shifting position, scaling, and rotation) to meshes. The library calls this a 3D shape.

// Create a shape based on the mesh
var shape=new Shape(mesh);
// Move it 1 unit along the X axis
shape.setPosition(1,0,0);

Note: The appearance of a 3D shape’s surface is known in the 3D graphics world as a material. It includes textures (images), colors, and light reflection parameters. Materials are not directly supported by this geometry library, not least because there are many ways to describe a material’s parameters, as well as many ways to implement the rendering behavior of materials associated with shapes, such as physically-based rendering, cartoon styling, constant-color shading, the Blinn–Phong model, and so on.

Here are details on some of the Shape class's methods.

The Render Loop

An important part of a 3D application is the render loop. The render loop is a block of code that is called many times a second (or many “frames” a second) to redraw the 3D scene. Each frame, the state of the application is updated, and the 3D scene is re-rendered to account for that state. The exact details of rendering depend on the 3D rendering library in use; the Geometry Utilities Library has no means to directly render 3D objects.

For example, in an HTML Web page, a render loop could look like the following; it depends on the requestAnimationFrame API implemented in most modern Web browsers.

// Set up the render loop
var rafCallback = function(time){
 // This will be called once each frame.
 // Render the scene here before calling
 // requestAnimationFrame again
 requestAnimationFrame(rafCallback);
});
requestAnimationFrame(rafCallback);

In this example, the callback to requestAnimationFrame takes a parameter (here “time”), containing the number of milliseconds since the page was started.  This can be used to implement frame-rate independent animations.

History

See version history.

Back to documentation index.