PATCHDANCE

Draft User Manual

Release 2.2
April 3, 2000

PatchDance was written using MetroWerks CodeWarrior™ C++ for PowerPC and the PowerPlant™ application framework. PowerPlant Constructor™ and Mathemaesthetics Resorcerer™ were used to construct the interface. The Debugger™ by Jasik Designs proved invaluable.

Thanks to Jordan Zimmerman for his excellent Color MDEF.

Questions/comments? Want to register, perhaps even pay the shareware fee and have the program's full capability available? If so, and you have a modem ready, e-mail the author here!

OVERVIE W Various topics

OBJECTS REFERENCE The Hierarchy and Objects systems

PREFERENCES All settings and preferences

EXAMPLES

INTRODUCTION: (DON'T SKIP THIS!)

A few suggestions:

Use the manual with the program running. Most examples consist of step-by-step instructions for performing various operations, and it is in your interest to work through them. Since the manual graphics are very limited (nonexistent as yet) it would be hard to get the same benefit just from reading.
While PatchDance itself is fine for beginners, this manual is not yet adequate for learning 3D modeling from scratch. It is assumed that you are a reasonably experienced Macintosh user, familiar with 3D terms and concepts (orthographic views, lofting, lathing, etc). and Bezier spline drawing (as used in most 2D drawing packages that support splines).
The manual is provided as an html document (like a World Wide Web page). Blue and/or Underlined text is a hyperlink that will take you to more information on a topic. There is also a table of contents (by chapter) in each section, to allow quick movement between files. For this to work, ALL manual parts must be located in the same folder (as delivered).
This file can be printed from your web browser, or (in most cases) saved in text form. This naturally removes most formatting and all graphics.
The Manual is provided as an Internet Explorer file. To use with Netscape, open each section with Netscape and Save as Source. (Internet Explorer doesn't do this reliably, Netscape does.)

Most 3D programs are object oriented, meaning that they work with complex objects: spheres, cubes, meshes. Better ones allow for adjusting individual vertices, but very few allow you to create and destroy them, or arbitrarily create objects by simply creating new points and splines.

PatchDance is vertex oriented: all objects, regardless of their source, are treated as collections of points, (and splines and surface patches); most operations work on any or all SELECTED points, splines, and patches regardless of which "object" they belong to. The only other Macintosh modeler offering this degree of control is Sculpt3D™, whose power and interface helped to inspire PatchDance. This method gives tremendous flexibility in what CAN be built, but may take some getting used to. Sculpt users will find PatchDance familiar in many ways, but should not assume that they already know how to use it.

All this power comes at a price: export and rendering is difficult, texture mapping is limited, and modeling operations that are based on specific types of objects don't work. As a result, starting with v0.4.8 PatchDance is becoming partially object oriented. This will begin with the ability to export objects rather than huge numbers of patches and/or polygons, and progress to object oriented modeling and very high-end texture mapping, using QuickDraw 3D. And the vertex oriented tools are still there when needed!

TERMINOLOGY: (DON'T SKIP THIS!)

POINT / VERTEX

These terms are used interchangeably. Both refer to a specific point in 3D space, containing a Point/Vertex entity. Point is used more often in this manual: vertex implies a corner point, where plane polygons join; a PatchDance Point joins curved splines and may not form a visible corner.

PatchDance operates on arbitrary sets of points, splines, and patches. Points help to define splines and patches: a point can exist alone while the others cannot.

SELECTION

In general, tools operate on all selected points and ignore deselected points. (the Arrow tools, when used for dragging, are an exception). Points are usually created in the selected state and are displayed in the current selected color; deselected points are displayed in a different (deselected) color (see Preferences). Selection can be changed in a variety of ways (see Arrow (A, C, N), Marquee (M), the Selection Menu, and Hierarchy). It makes absolutely no difference where the selected points are located or what they are connected to. You can scale half of two different objects at once, or rotate half the points in a single object. You can also delete any part of an object, add new parts to existing objects one point/spline at a time, and individually texture any patch in a model.

A few operations refer to selected splines or patches. A spline is selected if BOTH its endpoints are selected; a patch is selected if ALL the points that make it up are selected.

IMPORTANT: Normally, selected points stay selected until you explicitly deselect them. Points may be selected in any order or combination by any available method, with no effect on each other. By default, clicking in empty space has NO effect on selection. (This can be changed by setting "Alternate Interface" in the Preferences.)

IMPORTANT: The ability to work with arbitrary Point sets is the key to patchdance's power; however, vertex editing of objects can destroy their status as named Objects and convert them into collections of patches. The key is to use vertex level modeling to create complex, asymmetrical objects, while leaving as much geometry as possible in Object form.

SPLINES

Important notes about Splines and Patches follow this section.

PatchDance uses cubic Bezier splines to construct objects. Most modern drawing packages use similar type splines, and they should already be familiar. Note, however, that PatchDance's implementation provides completely 3D splines and has more options than most 2D programs.

Two-dimensional programs usually limit a point to 2 splines, forming a linear object that is called a path. PatchDance has no limit to the number of splines attached to a point (allowing you to create 3D meshes as well as paths). PatchDance does use the term Path in a special sense, see Spline Paths for details.

There are 3 basic spline types that you will encounter: All 3 types are identical (internally) and can be freely converted, but they behave differently and many dialogs and tools allow you to choose the type you want to create.

Smooth (also called simply a spline or a standard spline): Any spline, which can be curved or not. Don't forget, a spline may appear straight in one view and curved in another. Strictly speaking, ALL splines are smooth.
Segments: These behave exactly like lines/polylines in non-spline based programs, essentially like rubber bands. They are actually standard splines whose handles are located at their associated endpoints (the handles can be easily dragged off to produce a curved spline). See Spline Arrow (B) (deleting a handle, moving handles) and Pen (P) (creates a segment when clicked and not dragged). When a segment's handles are displayed, they're drawn on top of their endpoints: this causes affected points to appear in the handle color rather than the selected or deselected colors. Any spline whose handles happen to be very close to its endpoints will look and behave like a segment: they are not formally distinguished by the software except that they may be created as an option in several operations.
Straight: These are splines that are not segments but happen to be straight (3D) lines. When PatchDance creates them (as an option), both handles are located at the midpoint of the spline. The handles can of course be freely moved to produce a curved spline. Note that these DO NOT behave at all like segments when their endpoints are adjusted.

There is no direct provision for permanently unlocking the handles on a point to create a corner. Corners are made by option-dragging a point with the Arrow (A) or Spline Arrow (B) tool and can be removed simply by adjusting a handle with the option key up. Many modeling functions can also produce corners.

PATCHES

PatchDance describes a surface (what you see in a rendering) as a collection of Patches. A patch is a closed figure made of 3 or 4 splines (3 or 4 connected points) that contains a Patch entity. There is no limitation as to the shape or size of a patch: ANY splines can be used. Patches render smoothly regardless of size or shape (they are a mathematically defined surface), though they may appear faceted in the Camera window, which emphasizes speed rather than image quality.

The terms "Spline mesh" and "Surface" are often used interchangeably but they are not the same thing. Unlike many polygonal modelers, PatchDance does not automatically create a surface whenever it finds a suitable closed shape. If you draw a square with the Pen tool, you will have exactly what you see: an EMPTY square shape that is INVISIBLE in a rendering. (You could choose Make Patch or Fill Mesh from the Patches submenu of the Model menu to "fill in" selected, 3 or 4 sided, closed shape(s)). You can use the Camera window to ensure that you have surfaces everywhere you want them before starting a high-quality rendering.

Most 3D operations automatically generate patches when they create a surface. In general, the Pen (P) tool is designed for creating spline paths that are then used by the 3D forming operations (Loft, Extrude, Lathe, etc) to create a patch surface. While you certainly may create a surface one spline at a time, it is usually not the best way. When exporting PatchDance models to other software, empty meshes may become surfaces if they contain closed shapes meeting the other program's definition of a surface and the other program is capable of reading the information (many programs cannot handle pure spline/mesh data).

OBJECTS:

PatchDance defines objects as any collection of Points, splines, and patches that can be managed as a unit. When the word is capitalized (Object) it refers to an object that has been defined and named by PatchDance as a result of the modeling operation that created it. This allows, for instance, for a sphere to be exported as a sphere primitive rather than a mass of polygons, and to be assigned a default testure mapping appropriate to a sphere.

Obviously, vertex level editing of an Object can change its nature and remove its Object status. This new capability will require some practice to use efficiently: edit where necessary, leave alone as much as possible.

There are two other basic types of objects, neither of which has special significance:

Connected objects are composed of all points connected by splines (plus their splines and associated patches). This type of object can be easily manipulated, by selecting or dragging with the Object Arrow (C).
Named objects are collections of entities that have been given a name in the Hierarchy dialog. These objects can be selected / deselected / hidden / shown via the controls in the Hierarchy dialog, or by using the Name Arrow (N) tool. Their value lies in the fact that they don't have to be connected, and it is possible to give names to patches and splines as well as points (of course, operating on a patch or spline actually means operating on all its points).

IMPORTANT NOTES: More about Splines and Patches

PatchDance was designed to place as few limitations as possible upon the user: there should be almost nothing that CANNOT be built. On the other hand, there are some allowed operations that will lead to problems or cause poor results.

Cubic Bezier splines are easier to work with than B-Splines (NURBS are a type of B-Spline) and very versatile. Their main limitation is that they cannot form mathematically exact circles and ellipses (conic sections). For non-drafting purposes, though, they are generally accurate enough. B-Splines can also make it easier to create fair (equal slope) curves; PatchDance has special added support for this.

It is possible, though not generally recommended, to create more than one spline between 2 points. (This cannot be done with the Pen Tool (P).) It is NOT possible to make a 2 sided patch, so this type of construction will ALWAYS render as a hole.

It is easy to divide splines into smaller pieces: try not to use more than 120°of curvature in a single spline (PatchDance itself never exceeds 90°, and this is even better). Large curvatures lead to highly "stressed" surfaces that can cause problems with the camera view (in shaded mode) and spline based operations such as path extrusion. It may also increase rendering time and memory usage, even if the actual number of patches is less.

PatchDance surfaces are based on a mathematical formulation called a Coons patch. These are very general (no limitations on boundary curves) but may lead to problems if used carelessly. Several points to remember:

Don't try to use the absolute minimum number of patches. As with a polygonal program, breaking up complicated shapes may improve your model and actually speed up rendering. For example, it is quite possible (and legal) to make a 4 sided patch shaped like a 4 leaf clover, and even to have its "lobes" overlap each other. Such a construction may not work well with certain functions, including subdivision, file export, and (especially) the shaded Camera View. Subdividing such a patch once (into 4 new patches) solves most of these problems.
When possible, export your Projects as polygonal files for rendering. Spline-based export is possible, but tends to be more difficult and is not always consistently handled by other programs; most rendering programs are polygonally based in any case, and tend to produce better results with less effort that way.

Using QuickDraw 3D

PatchDance supports many QuickDraw 3D features. In order to use them, you must install the QuickDraw 3D shared libraries (available online, or preinstalled on late model Power Macintoshes). This in turn requires that you have at least 16MB of RAM (and several MB) free, or the system won't work: commands requiring it will either be disabled or display an alert.

The Show Clipboard command also requires the QuickDraw 3D Viewer shared library.

When importing or rendering large models, be aware that much more memory than 16MB may be required. PatchDance should be able to recover from most out-of-memory errors, but that definitely isn't guaranteed.

INTERFACE: (DON'T SKIP THIS!)

PatchDance generally uses a "standard" interface, familiar to Macintosh users. There are a few exceptions, discussed below. Also see Selection, which is quite different from standard behavior.

Many menu items are enabled whether or not they can actually be done. This doesn't mean that a given operation is possible, it's just not practical to check all the possibilities every time the menu bar is updated. If you try to do something that doesn't make sense, you'll be notified by an alert, usually with a reason, which is more helpful than a disabled item anyway.

MODIFIER KEYS: A lot of effort went into making these consistent! Modifiers can be added wherever it makes sense. There are several exceptions and tool dependent uses: see individual Tool descriptions. In most cases, the Prompt Window at the bottom of the screen lists the modifier keys available with the current tool.

Selection operations: Shift means deselect, option means swap. No key usually means select. Also applies to the Selection menu . See Arrow (A) for a minor, common-sense exception.
Shift - constrains a drag. The constraint is usually 45°, but some operations are 90°only (i.e., the Hand (H)).
Command - Normally means to snap (current snap mode, see Snap) when clicking and/or releasing the mouse. With the Pen (P), command means to join a new spline to an existing point. Also see Arrow (A) and Deform (Q).
Option - For most interactive tools, option-clicking sets the cursor (add Command to snap). It also has operation-specific uses. See Arrow (A, B) and Scissors (2) for examples.
Control, Caps Lock - operation specific. These usually switch between tool modes. Caps Lock (not always available) can be used to set a mode. Control usually reverses any (optional) mode in effect. In the case of the Arrow (A) and Object Arrow (C), Caps Lock is not used but Control is; for the Mover (D), Caps Lock switches between two quite different modes, and Control can be used to switch back (i.e., set your preferred mode, use Control to temporarily access the other).

The Snap and QuickColor Palettes have unique modifier key arrangements: they are listed on the palette.

COLOR BUTTONS

These are used to set colors. They consist of a small square of color with a black border. Clicking causes the Color Picker to appear. If a Color Button is Command-clicked,the Color Picker does not appear, but the current color is copied to an internal clipboard. (Note that the cursor becomes an eyedropper.) When a button is then Option-clicked (note that the cursor changes to a paint bucket) the copied color is pasted into the new button. This allows copying colors without having to write down numbers from the Picker dialog. See Preferences Dialog for an example of these buttons.
It is also possible to enter colors in HTML format ( #rrggbb): to do this, shift-click the button.

IMPORTANT: The buttons on the QuickColor Palette are NOT Color Buttons: the standard QuickColors are changed in the Preferences Dialog.

THUMBWHEEL

The thumbwheel feature allows you to quickly adjust a numeric value without having to type a new number. It's difficult to explain in print: type a value into an edit field, place the cursor in the middle, and press the up/down arrow keys until you see how it works. Note that the FIRST time you press a key, the target digit (if deselected) is selected but not changed. You CANNOT use the up/down arrow keys to move to the beginning or end of an edit box; use Home and End instead.

SLIDE WIDGET

This is a small, low overhead replacement for the standard Mac slider type control. They are used only for interactive (real time) operations that provide their own feedback, and where there is not enough room for a standard slider. Examples are the roll and zoom controls at the bottom of the Camera window. When these are clicked and the mouse dragged (horizontally, in this case) the result is immediately displayed in the Camera window, as well as numerically in the edit fields next to the controls. Slide Widgets always have a red border, unlike all other controls.

NUMERIC DATA

Fields for numeric entry can be picky about what they accept. If the computer beeps and/or refuses to accept a keystroke, chances are you are trying to enter a value of the wrong type (some fields accept only integer values) or outside the allowed bounds: the allowed range (if any) is usually listed in the Prompt Bar at the bottom of the screen if you point to the edit field.

3D CURSOR:

Also called the Cursor (capitalized). It should be clear from the context whether the normal (mouse cursor) is intended. The 3D Cursor appears in the Modeling windows as a small cross in the current Marker color. It has several uses:

Setting a depth or reference in the current view. Many operations use the Cursor as a starting point: i.e., the Rotate (R) tool uses the cursor as a center of rotation, and the Object tool creates objects at the cursor depth.
Marking an axis, such as the axis of rotation for the Lathe. In this case, the depth is not important, only the line passing through the Cursor.
Indicating a point of interest by snapping it to the point.