Mondfarilo: The Tutorial

Here's a skeleton of a tutorial, enough to get you started, I hope. As of 7 May 1997 this tutorial is out of date. I'm leaving it up because it's still useful. Just keep in mind that it no longer describes exactly the same Applet that you can run today.

The World Editor

You are presented with a window known as a Group Editor. This particular Group Editor is responsible for editing the whole world, and so is called the World Editor. Other Group Editors may be used to edit smaller sub-parts of the world. A Group Editor contains four viewing areas arranged in a grid. The upper-left area is the top view, the lower-left is the front view, the lower-right is the side view, and the upper-right is the camera view. In the left margin is a scrolling list of the names of the members of this group.

Since you haven't created any objects yet, all these areas are empty.

The three "axis views", Top, Front and Side, contain a grid of bluish lines. These are your guides for sizing and aligning objects as you drag them about in these views. All interactive editing occurs in these editable axis views.

In contrast, the camera view has no graph paper. Instead, it has a pair of heavy black lines describing a horizontal rectangle with a 4:3 aspect ratio. This is the standard TV or computer monitor aspect ratio, for example 640 by 480. Mouse drags do not edit objects in this view. Instead, they move the camera in various ways.

Creating Primitives

Find the Create menu at the top of the World Editor, pull it down, and choose the Box command. Immediately, a new box object appears in the window. The name "box" is added to the list in the left margin. This list item is highlighted because the newly-created box object is selected.

In the axis views the box is drawn with some sort of red "target" on it. This target consists of a number of Editing Handles, places where clicking and dragging will reshape the object.

Moving the Camera

The camera has three characteristics that you can change by dragging with the mouse: its Position, where it is situated; its Focal Point, where it is aimed; and its Focal Length, how much it magnifies the scene before it.

To change the Position, click the mouse anywhere in the camera view and drag freely. The cube seems to rotate as though you were "rolling" it around with the mouse. But actually, the cube remains stationary while your camera position orbits around it.

To change the Focal Point, click and drag while holding down the Shift Key. This does the exact opposite. Instead of orbiting the Position around a stationary Focal Point, it orbits the Focal Point around a stationary Position. A reducing scale factor applies here, so the mouse acts a good deal less "lively" that it does when dragging the Position. Why? Because that's how SCED does it. I must give this more thought.

Another way to change the Position with the mouse is to click and drag while holding down the Ctrl Key. In this mode, horizontal dragging has no effect, but vertical dragging moves the Position closer to or farther away from the Focal Point.

Finally, to change the Focal Length, drag vertically while holding down both the Shift and Ctrl keys.

Place, Resize, Reshape

Let's return our attention to the Editing Handles. All objects have certain standard handles, which perform the basic geometric transformations or translation, rotation and scaling. These handles are the three little red spots arranged around the center of the selected object.

Translation uses the spot in the middle of the circle. This spot is situated at the origin of the object's local coordinate system. Drag this spot in any of the three editing views and the cube will follow your mouse around. The window you clicked in gets updated continuously while you drag. The other three windows don't get updated until after you release the mouse button.

Uniform Scaling also uses the spot in the middle of the circle. Hold down the Ctrl key before you click the spot. Then, as you drag back and forth, the object is uniformly scaled around its own origin.

Non-uniform Scaling uses the spot below and to the right, outside of the circle. Drag this spot to scale the object in the two dimensions parallel to the editing view. The object remains the same size in the dimension perpendicular to the editing view.

Rotation uses the spot lying on the circle, directly to the right of the center. Drag this spot around the center to rotate the object around an axis perpendicular to the editing view and passing thru the object's origin.

Take a few minutes to familiarize yourself with these standard Editing Handles.

Multiple Objects

Using the Create menu again, create a Sphere. Now you have two objects in your world. One of them, the brand new sphere, is selected. That means that its name in the object list is highlighted, it is drawn in dark black, and it has editing handles. The other object, the box you started with, is unselected. Its name is not highlighted, its wireframe is gray, and it has no editing handles.

You may have none, one, some or all of your objects selected at any time. Clicking their names in the object list toggles their selected state on and off.

Cut, Copy, Paste, Clear

These four items on the Edit menu work as you probably suspect. Cut removes all selected items from the group and places them on the clipboard, a sort of holding area. Copy places copies of the selected items on the clipboard without removing them from the group. Both Cut and Copy discard the previous clipboard contents, if any. Paste adds copies of the clipboard items to the group, leaving the originals on the clipboard. Clear removes the selected items from the group and discards them, without any effect whatsoever on the clipboard.

Beyond the Standard Editing Handles

The standard Editing Handles, for translate, rotate, and scale, are enough control for boxes and spheres. But other objects require more controls.

Choose Cone from the Create menu. Now you see something slightly different. In addition to the three standard Editing Handles, the Cone also two green handles, one at the center of each end. Drag these handles back and forth to change the radius at the corresponding end of the Cone.

You can still use the green handles even after the cone has been squashed and stretched beyond recognition by the standard red handles.

Create a Torus. (Delete other objects first, if you want to eliminate some clutter.) Like a Cone, a Torus has two green handles in addition to the standard ones. The green handle near the center of the torus, when dragged back and forth, changes the Major Radius of the torus. The other handle, located near the rim, changes the Minor Radius.

Groups of Objects

There are two ways to create a group: before the fact, and after the fact.

To create a group before the fact, choose New Empty Group from the Create menu. As usual, a new object is born. Its name goes on the object list. Its standard Editing Handles go in the editing views.

With the new Group still selected, choose Open Window from the Edit menu. A new Group Editor window appears. It is in every way exactly like the World Editor you've been using all along, except that it only displays the contents of the Group you just created, and it is capable of performing Constructive Solid Geometry (CSG) on its members.

Add a couple of objects, like a Box and a Sphere, to this new Group. Then choose Close from the File menu. Now you can see the members of the group displayed in the World Editor. Try manipulating the Group's Editing Handles. The members of the group all get transformed together.

To create a group after the fact, select the objects you want grouped and choose Group from the Edit menu. This replaces all the selected objects with a single group containing the originals.

The corresponding Ungroup command performs the reverse operation. Each selected nested group (there can be more than one, of course) is removed and replaced by its separate children. If the group had been transformed, its transformation is bestowed upon its children when they get ungrouped. Making a temporary group, transforming it, and then ungrouping is a useful way to build a world with Mondfarilo.

Constructive Solid Geometry (CSG)

CSG is a powerful way to form complicated shapes from simpler shapes. No 3D modeller is complete without some kind of CSG support, because no decent renderer lacks CSG. But there's a minor paradox. Ray tracing programs are difficult to write, but once you have one working it's quite "easy" to add CSG support to it. On the other hand, wireframe models are easy to create and display, but performing CSG on a wireframe is extremely difficult. So considerable effort must go into a modeller like Mondfarilo in order to support a feature that the renderer gets practically for free.

But that's my problem, not yours.

If we have two objects A and B, their union consists of all points that are inside A or inside B. Their intersection consists of all points that are inside A and inside B. And their difference consists of all points that are inside A and not inside B.

In other words, a union is a simple glomming together of the two objects. Intersections and differences are two different ways of using one object to carve away part of another object.

Using methods already covered above, get yourself a Group Editor window containing two objects, a box and a sphere. Create the box first so that it appears first on the object list. Uniformly scale the sphere down to about half its original size, then translate it so that it overlaps one of the corners of the box. From the CSG Type popup menu, choose Intersection. Hit the Refresh button, then drum your fingers on your desk for several seconds while Mondfarilo calculates the surface. You should be rewarded with a box with a spherical bite taken out of one corner.

Creating a Blob

A Blob is similar to a Group in that it too has subparts, namely its components, and so it too can open a separate window for editing itself.

Choose Blob from the Create menu. You might notice a slight delay while Mondfarilo calculates the surface of the new object. Blobs have much more complicated suface tiling logic than the simpler primitives do.

Then choose Open Window from the Edit menu. You see something that looks very much like a familiar Group Editor, but with a few extra controls in it.

First of all, the Create menu in a Blob Editor has only one item: a Component. This creates an old-fashioned spherical blob component as used by POV-Ray version 2. POV-Ray Version 3 also allows cylindrical components, and components can be transformed and assigned different textures. Mondfarilo does not (yet) exploit any of these capabilities.

Perhaps a quick review of POV-Ray Blobs would be useful. A blob consists of a number of overlapping spherical force fields, known as components in POV-speak. Each component has a radius and a strength. It contributes the given strength at its center, but the strength fades smoothly away as you move away from the center, finally reaching zero at the radius and beyond. The blob as a whole has a threshold value. Everywhere in space where the sum of all the components' strengths equals this threshold is on the surface of the blob. Places where the sum is greater than the threshold are inside the blob.

A newly-created blob has a threshold of 30 and a single component whose strength is 100. The blob looks like a sphere somewhat smaller than the component. The component contributes its full strength at the center, fading to nothing at the boundary; the blob surface is where that strength happens to equal 30.

Interesting things happen where the components overlap. Adding together smoothly changing force fields results in a smoothly blended transition between the components. They sort of "grab" each other, like two lumps of silly putty pressed together and then pulled apart.

You can give a component a negative strength if you want. Such a component will make a dent in its neighbor instead attracting it and blending with it. You form interesting blobs by lumping together positive components and carving them away with negative components.

In the lower-left corner of the Blob Editor are three text entry fields and a Refresh button. Threshold is the threshold of the blob as a whole. Field Strength is the strength of the currently selected Component. If no component is selected, this field is empty. Granularity refers to how finely Mondfarilo approximates the Blob's surface. A value of 20 (the default) in this field means that Mondfarilo approximates the surface by finding where it intersects the edges of a mesh of 20-unit cubes. Decreasing this number increases the accuracy of the approximation, at the cost of increased time and space.

Blob Components are drawn as heavy black or gray circles. They have a single Editing Handle right in the center. Dragging this handle moves the Component. Dragging horizontally with the Ctrl key down changes the radius.

Generating a POV-Ray Scene

Now you can create Boxes, Spheres, Cones, Cylinders, Tori and Blobs. You can group these primitives into larger structures. You can translate, rotate and scale them freely. Now it's time to generate a scene description file for POV-Ray to render.

First of all, you should know that every Group Editor (and Blob Editor) has a POV-Ray command on its File menu. A Group Editor generates a POV-Ray scene from its own contents only. In other words, if you want a POV-Ray description of the whole world, you must choose the POV-Ray command from the World Editor. If you choose the command in, say, a Blob Editor, you will get a POV-Ray description of the Blob only. Sometimes, this is exactly what you want, so be aware of it.

Second, you must be aware that for security reasons, a Java Applet cannot write a file on your local file system.

However, it could send the POV-Ray scene back across the network to whatever machine served up Mondfarilo in the first place. That machine could perform the rendering and mail you the resulting image. I must investigate this possibility more in the future.

To get around this restriction, Mondfarilo simply displays the POV-Ray scene description text in another window. You can use your window system's usual Copy/Paste mechanism to capture this text into something useful.

With the Group Editor of your choice, with the camera angle the way you want it, choose POV-Ray from the File menu. A window full of text appears. You can save this text in a platform-specific way. Under X windows, for instance, I can shift-click at the end of the text to select all of it, then paste it into another window by clicking the middle mouse button. This other window might be running a text editor awaiting typed input, or possibly an xterm window into which I have typed

cat > example.pov

On a Macintosh, I would select all the text, type Cmd-C to copy it to the clipboard, then Cmd-V to paste it into the another program, such as Simple Text, or even POV-Ray itself, that can save the text on disk.

I don't know how to perform this task under Windows, but there has to be a way, or that OS is even worse than I thought.

That's All for Now

That's all there is to say about Mondfarilo for the time being. It's still just taking little baby steps. But before too long it should be pretty formidable.

Send me some mail.