ShapeJS Developer Tutorials

ShapeJS Scripts

ShapeJS Scripts are Javascript programs over top the AbFab3D Voxel library. All standard Javascript functionality is supported. In particular we use the Rhino Scripting engine in Java. You can find the project documentation here: Rhino Documentation

1. The Scene

Before we really get started, we need to learn how to have our shapes and models (data sources) actually show up. If you fire up ShapeJS and simply describe a lot of data sources to it, it will not display any of them. This is because it does not know which of these data sources you want displayed, or how. This tutorial will show you how to create scenes and modify their bounding box so that they properly display what you want them to display.

Setting up a scene in ShapeJS is quite simple.

return new Scene(Data Source, Bounds);

Of course, this by itself is not too useful. We don't know what "Data Source" or "Bounds" are. We will discuss the first part, the creation and manipulation of data sources in subsequent tutorials. For now, let's look at the second part of the scene, the bounds.

2. Data Sources

A data source is a function which calculates the distance to the surface of your object. For our purpose here, though, we can visualize it as a discription of geometry. A simple example is a primitive such as a cube. 

function main(args) {
  var box = new Box(10*MM,10*MM,10*MM);
  var s = 7*MM;
  return new Scene(box, new Bounds(-s,s,-s,s,-s,s));
}
Try it!

3. Bounds

Bounds, are quite simply the area in which ShapeJS will endeavor to display. The Bounds are a box, defined as Bounds(X minimum, X maximum, Y minimum, Y maximum, Z minimum, Z maximum). These distances are relative to the center of everything, which you will generally use as the center of your bounds as well, (0,0,0), which is also called the origin. It is the center of the scene, as well as the default center for data sources.

If whatever data source you are displaying is red and cut off at its edges, this is a warning that part of it is extending out of the Bounds of your scene. To remedy this, simply enlarge the scene size.

Let's look at an example of a sphere with a diameter greater than the bounds of the scene. 

function main(args) {
  var radius = 22 * MM;
  var sphere = new Sphere(radius);
  var s = 20*MM;
  return new Scene(sphere, new Bounds(-s,s,-s,s,-s,s));
}

(Note: If you are wondering why everything is being multiplied by this mysterious "MM", it is in order to convert the scale to millimeters. A number put in without this adjustment will be read as meters which is likely not the scale you want.)

Try it!

We can now see the problem discussed, as the Bounding Box is cutting off part of our sphere. We have set all the Bounds to a single variable, "s", making it easy to resize the entire bounding region. If we increase the Bounds and generate the new scene... 

function main(args) {
  var radius = 20 * MM;
  var sphere = new Sphere(radius);
  var s = 20*MM;
  return new Scene(sphere, new Bounds(-s,s,-s,s,-s,s));
}
Try it!

Much better.

4. Voxel Resolution

We now have a free and happy sphere, with no red on the edges. Just try to avoid going crazy on scene size, or you will end up without enough voxels to properly define your data source. Too large of a voxel size (low resolution), and your object will look pixelated. Too small of a voxel size (high resolution) will give more accurracy, but at the cost of high compute and memory cost. Not to mention that it will take longer to process.

Not your goal. This should only become an issue when working a scene of truly enormous proportions or detail far beyond what the printers can actually make. Under normal circumstances, you will never need to worry about running low on voxel resolution. If you still, somehow, find that you need to adjust voxel size, you can simply change it when you generate your scene, as shown below. 

  return new Scene(Data Source, Bounds, Voxel Size);

The default voxel size is 0.1*MM, and can be adjusted to suit your needs. Just remember that the more voxels in the scene the longer it will take to render, or give you a high quality image.

Next