Mondfarilo Reference Manual

Since Mondfarilo is no where near finished, neither is this reference manual. I will use italic type to identify features that are planned but not implemented, or provisionally implemented but expected to change.

Table of Contents

Modelling Concepts
Editing Windows

Features common to all editing windows
The Box Editor
Biparametric Editors
The Sphere Editor
The Cone Editor
The Torus Editor
The Superellipsoid Editor
The Blob Editor
The Group Editor
The CSG Editor

Primitive Objects

Box
Sphere
Cone
Torus
Superellipsoid
Blob

CSG Groups
POV-Ray Output

Modelling Concepts

To fully understand the workings of Mondfarilo, you will first need to understand a few basic concepts.

What it's for: POV-Ray produces excellent results, but its input is a complicated programming language and its output can take a very long time to generate. Mondfarilo, like any good modeller, addresses both of these issues. It lets you build your scene graphically and interactively, so you don't have to learn the scene description language. And it displays your scene using a fast wireframe renderer, so you can see your changes instantly or very nearly so.

Coordinate Systems:

Primitives:

Lights:

Cameras:

Hierarchies:

Textures:

Table of Contents

Editing Windows

Every type of object has its own type of editing window.

Features common to all editing windows

Name Field

in the upper-left corner, displays and edits the name of the object that owns the window.

Texture Button

right below the Name Field, opens a dialog box for editing the object's texture. There is currently no such dialog. Every object is chalk white.

Apply Button

in the lower-left corner, takes new values from the various editing controls and bestows them on the object.

Four Views

in the two-by-two grid that fills most of the window, display and edit the object.

The Camera View occupies the upper-right corner. It displays the object in perspective from the point of view of the current camera. Clicking and dragging in the Camera View changes the position and aim of the camera, as explained below.

The other three views are the Axis Views. They display orthographic views of the object from directions parallel to the three coordinate axes. Clicking and dragging in an Axis View performs a variety of selecting and editing operations, depending on the type of object. The upper-left corner is the Top View, which looks down from +Z, showing +X to the right and +Y up towards the top. The lower-left corner is the Front View, looking North from -Y, with +X to the right and +Z up. Finally, the lower-right corner is the Side View, looking West from +X, with +Y to the right and +Z up.

The Camera View has no scroll bars. You determine how much can be seen by positioning and aiming the camera, and by adjusting the zoom lens. The heavy black lines outline the usual 4x3 aspect ratio. The user will be able to change the aspect ratio. The Axis Views have scroll bars which work in the obvious way.

Number Fields

The Sphere Editor shown above is typical of most Editing Windows in that it contains a few Number Fields. These are the four text entry areas below the Texture button labelled U Divs, V Divs and so on. Number fields can edit either scalar or vector quantities as appropriate. Scalar Number Fields have one number in them. Vector Number Fields contain three numbers separated by spaces.

Menu Bar

contains several commands more generally useful commands.

Window Menu

POV-Ray: generates a window full of POV-Ray code, describing the object as seen in the Camera View. Since Java applets cannot write files on your hard disk, you must copy and paste the POV code from this window using native window system methods.
Close: closes this window.

Camera Menu

Normal Lens: resets the focal length of the lens to its default value, which in POV-Ray terms would be a direction vector with a length of one unit. In other words, a 90-degree angle of view. This is a bit wider than what most photographers would consider "normal."
Edit...: opens a dialog box for the exact specification of the parameters of the camera. This dialog doesn't exist yet.

The Box Editor

Minima and Maxima: These two Number Fields define size and position of the Box by placing two opposite corners, one at the minimum value of X, Y and Z, and the other at the maximum values. Mondfarilo verifies and applies the values you type when you hit the Apply button.

Biparametric Editors

U Divs and V Divs: The biparametric shapes, sphere, cone, torus, superellipsoid, lathe, prism and bicubic patch mesh, are approximated by dividing their surfaces into a grid, then joining the grid points into triangles. These two Number Fields control how many "slices" the approximating grid has in each dimension. The exact meaning of U and V depends on the object type, and so is described more fully with the individual editors. Generally, increasing these numbers makes the wireframe approximation better, but costs more time and memory.
Open Ends: Some primitives have optional end caps, which may be turned on and off with this checkbox. As usual, its setting takes effect when you hit the Apply button.

The Sphere Editor

Center: This number field displays and edits the location of the center of the Sphere.
Radius: This number field displays and edits the radius of the Sphere.

The Cone Editor

Base: This field controls the location of the center of the base of the cone.
Base Radius

base, base radius, apex, apex radius, open ends

camera: look at selection, look from selection, reverse view

edit: cut, copy, paste, clear, reset, group, ungroup, open window

create: box, sphere, cone, torus, superellipsoid, blob, new empty group

The CSG Editor

csg type, cell size

Table of Contents

Primitive Objects

Box

Sphere

Cone

Torus

Superellipsoid

Blob

Table of Contents

CSG Groups

Table of Contents

POV-Ray Output

Table of Contents

Everything from here down is the obsolete first draft

World Editor

The World Editor is Mondfarilo's main window. In it you create and manipulate the objects making up your world. There is only one World Editor. Someday we will support editing more than one world at a time, in which case there will be more than one World Editor.

The World Editor contains the following:

Object List: located in the upper-left corner, this shows the names of all the objects belonging to this group. The example group contains a box and a sphere. Click on the names to select or deselect objects. Someday you will be able to select by dragging a marquee in an editing window. The PowerMac version can already do this.
Axis Views: showing the Top, Front and Side views, these are where all the actual editing takes place. Scroll bars let you edit a bigger world than will fit on your screen. Pale blue grid lines aid in sizing and aligning objects. Someday, grid size, grid visibility, and snap-to-grid will be under the user's control.
Camera View: located in the upper-right corner, this gives a perspective rendition of the objects in the group. It has heavy black outlines around a horizontal rectangle with a 4:3 aspect ratio, which is POV-Ray's default. Someday, you will be able specify a different aspect ratio.

Group Editor

A Group Editor is the window where you will spend most of your time. It serves to create and transform the objects making up a group, and to perform CSG operations on them.

CSG Type: is the popup menu on the left side, with which you can choose a Union, Merge, Intersection or Difference.
Cell Size: is a text field in which you may specify the size of the grid used to approximate the CSG surface. This only applies to Intersection and Difference objects. A smaller number here produces a better approximation, but takes more time and memory.
Refresh: causes the surface of an Intersection or Difference object to be laboriously recalculated.

Blob Editor

A Blob Editor is similar to a Group Editor, but instead of showing the objects belonging to a group, it shows the components belonging to a blob primitive. Its Create menu has only one command on it, to create additional components. Instead of CSG controls, it has blob controls:

Threshold: sets the threshold value of the blob as a whole. It must be a positive number. All points in space where the sum of the contributions from each component equals this threshold value are on the surface of the blob.
Field Strength: sets the strength of the selected component, provided there is exactly one selected. A component contributes this strength at its center, decreasing smoothly to zero at the radius and beyond.
Cell Size: controls the size of the grid of cells used to approximate the surface. A smaller number here makes a better approximation, but takes more time and memory.

Mouse-Adjusting the Camera

Dragging: causes the camera's position to orbit around a fixed look-at point. Dragging horizontally changes the "longitude" of the camera. Dragging across the width of the camera window results in a full 360-degree rotation. Dragging vertically changes the "lattitude" of the camera. Dragging across the height of the window results in a trip between the North Pole and the South Pole.
Shift-Dragging: causes the camera's look-at point to orbit around a fixed position.
Ctrl-Dragging: causes the camera's position to move closer to or farther from a fixed look-at point. Dragging towards the top of the window moves closer, and dragging towards the bottom of the window moves farther away. Dragging horizontally has no effect.
Shift-Ctrl-Dragging: changes the focal length of the lens. Dragging towards the top of the window makes the lens more "telephoto," magnifying the image, narrowing the view angle and reducing the effect of perspective. Dragging towards the bottom of the window makes the lens more "wide-angle," shrinking the image, widening the view angle, and enhancing the effect of perspective. Dragging horizontally has no effect.

Mouse-Transforming Objects

In the Axis Views, selected objects are drawn with Editing Handles superimposed. There is an Origin Handle located at the origin, in the center of the red circle, for translating and uniformly scaling. There is a Rotate Handle directly to the right, on the red circle at the 3 o'clock position, and a Scale Handle in the lower right.

Dragging the Origin Handle: translates the object. The object follows the mouse as it moves horizontally and vertically in the window.
Ctrl-Dragging the Origin Handle: uniformly scales the object. Dragging to the right makes the object bigger. Dragging to the left makes the object smaller. Dragging vertically has no effect.
Dragging the Rotate Handle: rotates the object around an axis passing through its origin and perpendicular to the computer screen.
Dragging the Scale Handle: non-uniformly scales the object around its origin, in the plane of the computer screen, preserving its scale along the axis perpendicular to the computer screen.

File Menu

New: Not yet implemented. In a single-world system, it would prompt to confirm, then erase the entire world and close all windows, then create a new World Editor window containing a new empty world. In a multiple-world system, it would simply open a new empty World Editor without disturbing other worlds.
Open: Not yet implemented. In a stand-alone application or a trusted applet, it would read a world in from a file. In an untrusted applet, it would present a text window into which a description of a world (in what format?) could be pasted.
Save: Not yet implemented. In a stand-alone application or a trusted applet, it would save the world in a file. In an untrusted applet, it would present a text window containing a description of the world (in what format?) which the user could paste elsewhere.
POV-Ray: generates a POV-Ray scene description of this window's contents as seen in this window's Camera View. You must choose this command from the World Editor if you want a description of the entire world. In a stand-alone application, it writes the POV-Ray into a file. In an applet, it presents a scrolling window full of text. You must copy and paste the text using your native window system techniques.
Close: closes this window. This command is found in Blob Editors, CSG Editors, and the World Editor of the applet version. The stand-alone application's World Editor has an Exit command instead.
Exit: exits the stand-alone application.

Edit Menu

Mondfarilo maintains a Clipboard for copying and pasting objects. The Clipboard is global, shared by all the editing windows. When we allow multiple worlds, one single clipboard will be shared by all the worlds too.

Clipboard operations all use deep copy semantics. When you copy a group, you also copy the objects in that group, including deeply nested groups. You can edit the copy without affecting the original.

Cut: removes all selected objects from this group and places them on the Clipboard, discarding the previous Clipboard contents.
Copy: places deep copies of all the selected objects on the Clipboard, discarding the previous Clipboard contents.
Paste: makes deep copies of all objects on the Clipboard, and adds the copies to this group.
Clear: removes all selected objects from this group, without making any change to the Clipboard.
Reset Transform: restores all the selected objects to their original, untransformed state. This undoes any translation, rotation or scaling previously applied to those objects.
Group: replaces the selected objects by a group (CSG Union) containing them, thus pushing them one level down the hierarchy.
Ungroup: replaces any selected group objects by their individual contents, thus hoisting those contents one level up the hierarchy.
Open Window: opens a window for editing the selected object, provided that there is exactly one selected object. Otherwise, it does nothing. Furthermore, only blobs and groups have their own editing windows. Editors for the other primitives are not yet implemented.

Camera Menu

Normal Lens: restores the Focal Length of the camera to its default value. It's not really a "normal" lens the way a 50mm or 55mm lens is considered normal for a 35mm camera. In photographic terms, it's actually a bit on the wide-angle side. In POV-Ray terms, it makes the length of the camera's direction vector equal to 1.0, so that a unit square object will fill the frame when it's one unit away from the camera. This results in a ninety-degree angle of view.
Look At Selectee: aims the camera at the selected object's origin, still looking from the same position. Aims at the first selected object if there are more than one. Does nothing if no objects are selected.
Look From Selectee: positions the camera at the selected object's origin, still aimed at the same point. Positions at the first selected object if there are more than one. Does nothing if no objects are selected.
Swap Camera/Focus: reverses the position and look-at point. Instead of viewing target A from vantage point B, you view target B from vantage point A.

Create Menu

The following commands are found on the Create menus belonging to the World Editor and any Group Editors:

Box: creates a cube, with sides of 100 units each, centered at the origin.
Sphere: creates a sphere, with a radius of 50 units, centered at the origin.
Cone: creates a cone along the Z (vertical) axis between -50 and +50, with a radius of 50 units at each end. This results in a cylinder; you can change the base and apex radii to get a tapered cone. Someday there will be separate commands to create cylinders and cones.
Torus: creates a torus centered at the origin, with a major radius of 50 and a minor radius of 10. The torus is rotated around the Y axis for compatibility with POV-Ray, even though the vertical axis would be more consistent with cones.
Blob: creates a blob with a threshold of 30, having one component centered at the origin, with a radius of 50, and a strength of 100.
New Empty Group: create a new group, a CSG union, with no contents. The Open Window command from the File menu opens a Group Editor for adding objects to the new group.

There is only one command on the Create menus belonging to Blob Editors:

Component: creates a new component, centered at the origin, with a radius of 50 and a strength of 100.

Send me some mail.