Jam User's Guide

for Jam version 0.4


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

Jam is still rather preliminary; it is usable, but not very feature-rich.

You can:

You can not: Other known limitations, bugs, and minor annoyances:

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

Component Creation Mode Selection
create a sphere
scale mode
create a cylinder
rotate mode
position mode
Adjustments Modifiers
+/- X
adjust more
+/- Y
adjust less
+/- Z
-/+ strength

Questions? Comments?

If you have any questions or comments about Jam, please write to me at joe@strout.net. I prioritize my projects based on the amount of user feedback, so if you want to see Jam improve, please let me know!

Last Updated: 5/10/99 . . . . . . webmaster@strout.net