Jam User's Guide

Jam is a MacOS application for building smooth three-dimensional structures called "metaballs" or (more informally) "blobs" for use with the POV-Ray ray-tracing application. It takes full advantage of POV-Ray's metaball capability: blob components may be spheres or cylinders, and they may be scaled and rotated as desired. These capabilities allow many blob structures to be made with far fewer components than if they were restricted to perfect spheres. Jam saves in a format which can be easily included into a POV-Ray file for quick preview or final use.

(Eventually, I'll put more info here about what blobs are and how they work; for now, I'll assume the reader is already familiar with the concept.)

State of the Program

You can:

• open, save, and close windows
• create spherical or cylindrical blob components
• scale, rotate, and translate these using the keyboard
• (sometimes) translate a component using the mouse
• view with or without outer field limits
• resize the document window
• scale or rotate using the mouse

• have more than one blob per document
• import arbitrary POV-Ray blobs, or export to other formats
• zoom in or out in the document view
• change the blob threshold
• change the keyboard mappings

• objects are drawn and handled at pixel scale; I usually have to scale them down by a factor of 0.03 to get a more reasonable size
• updating is slow when the document contains many components

Usage Overview

A Jam document window has a control bar on the left side, showing the strength and coordinates of the currently selected component. It also shows the keys which can be used to modify the component; the key indicators can be clicked with the mouse as well.

The rest of the window shows you the components in a standard blueprint pattern. The upper left quadrant is a top view, with the front (-Z) of the object facing down. The lower left quadrant is a front view. The lower right is a side view, with the front (-Z) of the object facing to the left. And the upper right is an isometric view, slightly tilted so you get a more natural look. Note that you cannot click or otherwise manipulate objects in the isometric view.

Jam can be driven entirely with the keyboard, or the mouse, or any combination. You create an object by pressing K (for a sphere) or J (for a cylinder), or by using the Model menu. The keyboard mode is selected by pressing S for scale, R for rotate, and P for position (or, if it's easier to remember, T for translate). You then press numbers on the numeric keypad to increase or decrease the current value in the X, Y, or Z axis. Or if you prefer, use the arrow keys; these affect the component relative to the current view pane (the last view pane clicked, indicated with a bold border). The amount of adjustment can be increased by holding the Shift key, or decreased by holding the Control key (see chart below).

To manipulate components with the mouse is even easier. Click on the center of a component to select it. Three control handles will appear, as shown at right. Grab the handle in the center and drag to move the component around in space. Grab the rotation handle to rotate the component. Drag the scale handle to scale it. Note that since you can now combine rotation and scale arbitrarily, you can effectively "shear" blob components. This is a feature, not a bug!

To preview your work, press command-E (or use the Display menu). This will generate a QuickDraw 3D preview, which can be manipulated with the mouse. You can leave the preview window open, but it will not be updated until you use the Preview command again.

To view your blob in POV-Ray, first save the document. This creates a short POV-Ray file containing just the blob. Then, use a POV-Ray test file which includes your blob, scales it, adds lights and texture, and displays it. The cycle is:

1. Modify the Jam document.
2. Save it (command-S).
3. Switch to your POV-Ray test document.
4. Render it (command-R).
5. Go back to step 1 until satisfied.

Keyboard Controls

Questions? Comments?