Files

PatchDance provides the ability to open and/or save in several file formats. PatchDance's native file type saves the most information and is by far the fastest in operation, but it is highly application-specific and not intended as a public format.

PatchDance is designed to support plugins for file import/export, but the necessary documentation/support files are not available at the time of this writing.

Most standard file operations are available, and a few more. They are discussed under the File menu section, as well as below in the Summary of file export.

File Import  | File Export  | File Extensions  | Save Alternate | Reusing Options | Polygon Options  | Save Dialog  | DXF Options | 3DMF Export Options  | POV-Ray Export Options | Animation:Master™ Export

---

File Import

PatchDance can read a number of file formats, which can be accessed via the File menu or by dropping a file on the application icon. Currently the only text-file type supported is DXF, so a dropped text file will be interpreted as a DXF file. Plugin writers that want to add support for other files must ensure that they can handle text files of the wrong type.

The standard file dialog adds a popup menu that controls the file type that is displayed (All Types is a choice). Some choices are dimmed if the corresponding type is not yet supported.

The Options checkbox displays a dialog that allows control over various file parameters when reading. Not all file types have options; in this case nothing happens.

Bear in mind that many files contain polygonal data, rather than splines. This can cause an imported model to become quite large. When using imported polygonal shapes, be sure to select Mesh (Flat) when using QuickDraw 3D in the Camera View. Higher resolution adds nothing and greatly increases memory requirements (not a good idea with QuickDraw 3D).

UNDER CONSTRUCTION: This section is incomplete. Specific discussion of import options for specific formats will be added later. Contact Tech Support if you have any questions.

File Export

PatchDance can export in various ways: pure polygonal geometry, surface patch, or geometric primitive, depending on what a given file format supports. At present, the recommended method(s):

1. Geometric primitive - gives the best results in all cases where supported
2. Polygonal geometry - almost universally supported, results in larger files
3. Spline surfaces - NOT recommended. This produces smaller files than polygons, but not all programs can read splines and most have problems interpreting them.

Exporting in other file formats is available when saving, via a popup menu that lists file types and an Options checkbox that allows you to override patchDance's default choices for the chosen type. Normally you should maintain your model in native PatchDance format and Save Copy to export a copy of the model data to render.

File Extensions

Most types of files have standard extensions (.dxf, .pov, etc.) These support file systems that cannot identify files otherwise. (PatchDance's own files do not have a standard extension, since they are only readable on Macintosh computers which do not have this problem.) Use of these extensions is generally optional unless files are to be transferred to other systems that need them, or in the case of Model (.mdl) files for use with Hash's Animation:Master, which does use the extension to identify the file type.

When selecting a file type for export, the appropriate extension is automatically added for you (and the text selected). Simply hit Delete to clear the extension if you wish.

Summary of saving files (with PatchDance's unique features in RED)

See the section on the File menu for more information on accessing these features.

• Save: presents a dialog box the FIRST time, overwrites existing file each succeeding time. You can save in any format the first time, native format will be used thereafter.
• Save As... Saves with a new name/format, and changes the Project to reflect the new file. Mainly an alternative to Save Numbered.
• Save Copy: Saves a copy of the file in any desired format. No effect on the Project (but see Save Alternate).
• Save Default: Saves the current Project as the default project, which is used every time a New Project is created. (Registered users only)
• Save Numbered: Effectively modifies Save to create numbered copies instead of a single copy that is overwritten each time.
• Save Alternate: Very unique! See full explanation below.

---

Save Alternate

This is intended as a shortcut to automatically create copies for rendering or backup. It can work in two basic ways, using Save Alternate in the File menu (an alternative to the Save item), or Save if Auto Export is active (Save Alternate is then the default). It is controlled by the Auto Export checkbox in the Interface section of the Operations Palette. The basic function is to create a saved (Alternate) copy of a Project that is separate from the one created by Save.

The Rules

• The Auto Export checkbox has two functions: when checked it causes Save to be treated as Save Alternate, and causes Save Copy to update the Alternate file.
• Before Saving the first time (invoking Save Alternate instead of Save in a new Project): This saves a copy of the file using any desired name/format. Invoking Save Alternate again resaves, using the same name and format. This is the same as Save except that the file format is kept (not changed to native.)
• After Saving: does nothing unless you have an Alternate file (see above and below).
• After Save AND Save A Copy (Alternate file exists): Save+Auto Export and Save Alternate are identical in this case. The Project is saved as usual, PLUS a new Alternate copy is created (overwriting the old).
• After Save As: Save As resets the Alternate file system (on the assumption that you will want to set up another Alternate file.)

IMPORTANT: Save invokes Save Alternate if Auto Export is ON: you must explicitly choose Save Alternate if Auto Export is OFF.

If this seems complicated, here's how to use it:

• To ALWAYS save your files in another format: use Save Alternate instead of Save. The Auto Export checkbox doesn't matter in this case (as long as you don't use Save).
• To make a copy (either a backup copy, or a copy in a new format for export): Save your file as usual, Save a Copy, then use Save Alternate (or Save with Auto Export ON) when you want to save your Project AND update your copy at the same time.
• To change your Alternate file, Save a Copy with Auto Export ON (this does nothing with it off.)
• To stop making Alternate copies, uncheck Auto Export and use Save as usual.

---

Save Options

This section discusses the available options for the Polygon Generator that creates polygonal geometry from PatchDance's spline surfaces. These options are available for all file formats, in addition to any specialized options that may be available.

Overview of polygons:

PatchDance's polygon system is designed to work quickly and with minimal memory requirements.

Features:

• Three or four sided polygons are available for file formats that support both.
• Polygon normals are consistent (not guaranteed to point "outwards") and can be reversed if needed.
• Polygons are generated in set order: if subdivision doesn't change, the file won't either.
• It is possible to apply two different subdivision methods (controlled by selection status.)
• It is possible to save a given subdivision state and reapply it to the same model. This allows generating data with one-to-one vertex correspondence even if the model is edited. The subdivision data is automatically saved with the file and has no effect on file size.

Additional features for plugin authors:

• The polygon generator scans first for named objects, then the remaining geometry. Connected object patches are processed in groups. For named/primitive objects, it is possible to be notified prior to processing, to allow cancelling polygonization of an object if it is preferable to output it in a different form.
• When activated, the polygon generator feeds polygons to a user callback function. Implementation is extremely simple.
• The standard options (a PowerPlant LPane) are completely available and customizable, even from non-PowerPlant code.

Polygon issues:

• By far the most difficult objects to polygonize are 3 sided patches. If you need them for a model, but they do not render as desired, the following may help:
• Don't over-divide. Sometimes lowering the subdivision level produces smoother rendered surfaces
• Avoid subdividing your model. For example, a sphere exports nearly perfectly, but applying the subdivide command usually results in creasing.
• Use normals if your rendering program/file format supports them. PatchDance calculates surface normals directly from the spline surface, which usually produces better renderings than letting another program determine it from a polygon mesh.

Reusing Options

Polygonization settings are now saved with each Project. You need set them only once, and they will be reused for each subsequent save of that Project. This includes saving to disk with Project files (in Native format only.)

Note the following (which applies ONLY to polygonal files, NEVER to native-format files):

• Only the Polygonization settings are curently saved (the boxed section in the dialog.) File-specific options in general are not. This may change.
• The Show Options checkbox is now checked automatically on the first save of a Project, since you can't be sure what settings might be in effect.
• It is possible to save your favorite settings with a Default Project (and thus apply them to all new Projects.)

---

Save Dialog (DXF)

This section describes the Options dialog for saving DXF files.

The lower (boxed) section controls polygonization, and is the same for all file formats.

DXF Specific options:

Export Names: If checked, assigned names are added to DXF files as comments (code 999). This makes the file much easier to interpret, but also much larger and not all other programs handle comments correctly.

Export QuickColors: If checked, current colors are exported. Note that DXF files contain only indexed colors, and PatchDance's color scheme does not exactly correspond (nor is it always interpreted the same by all programs.)

Export Surfaces Only: If unchecked, splines and Points are exported as well as patches. This is rarely desirable and may confuse other programs (most simply ignore such information).

Polygon Controls (applies to all files that can contain polygonal geometry).

Triangles Only: If checked, do not allow 4 sided polygons. Some formats support only triangles - in this case, this choice is not available.

Don't Export Normals: If unchecked, surface normals are exported to file types that support them. This can slow processing of very large files, and will increase file size. Note that this refers to numerical normal values, NOT the orientation of polygons which is ALWAYS determined.

Warning: Highly curved surfaces may take a lot of polygons to describe. If you get errors when exporting normals, make sure you are subdividing enough. PatchDance calculates normals exactly based on the splines, and can produce "normals" to polygons that make no sense. This usually means that a spline curved "around" a polygon and caused vertex normals to point to opposite sides of a supposedly flat surface. In the case of POV Ray, for example, this causes holes in a mesh object and warnings to remove "Degenerate triangles."

Flip Selected Normals: If checked, normals of selected patches are reversed. This can be useful if your rendering program is unable to handle inverted normals and/or flip them itself. This may conflict with selected/deselected subdivision mode!

Note for Normals: PatchDance is a pure surface modeler: in general, it doesn't know which side is "inside" an object. This may change for named primitives in later versions of the software, and PatchDance's guesses may improve in time for non-primitive objects, but this is a difficult problem to solve in general.

Save Subdivision: If checked, the actual subdivision used is saved with the model and can be reused by selecting the Saved subdivision type. You can manipulate existing geometry freely, but be certain that the saved subdivision values are adequate if you increase curvature! Subdivision data is cleared whenever you create or destroy a spline or patch (a warning appears.) Clearing the data is not undoable - save a copy of the file if you need to keep a set of subdivision settings.

The Saved Subdivision option was designed to allow creation of multiple files with exact one-to-one vertex correspondence (for use with animation, and especially morphing, applications.) A model can be saved once with dual targets (minimal or adaptive subdivision of objects that won't be changed, high fixed subdivision on the parts to be animated) and the subdivision saved so that the model can then be modified and then resaved in exactly the same way.

Using this feature normally requires that the patch processing order not be changed: this can happen (for Named objects) if the order of Names in the Hierarchy dialog is changed. PatchDance scans the Name list and exports Named objects first, followed by non-Named geometry. While manipulating Name order will NOT affect the saved subdivision information (which is saved with each spline individually), it WILL alter the patch processing order. UnNamed geometry is ALWAYS exported in the same order.

Mesh Type: This popup menu controls the type of subdivision applied to the model.

Subdivision Type	Parameter	Parameter Range
None - no subdivision	none	none
Fixed - divide each spline equally	Number of divisions	1 to 4 (2, 4, 8, 16 segments/spline)
Ruler Units - length	maximum length of a line in ruler units	0.1 to 99 units
Max Angle	Maximum surface angle break	15 - 90 degrees
Saved - use previously saved subdivision values	none - see Save Subdivision above	none

The default values are: Fixed subdivision, 1 (2 segments/spline), maximum steps 4.

Subdivision Parameter: A number that controls the subdivision. Values depend on the subdivision type and are discussed above. In general, this field has an allowable range of values and won't let you enter a value outside the range. See Maximum Steps below for a discussion of this field when using Fixed subdivision.

Maximum Steps: The maximum number of times a spline can be subdivided. The absolute maximum is 4 times (resulting in 16 segments.) This is used to limit subdivision to reasonable values (no more than 512 triangles per patch!)

Beginning with v0.6, this value is a popup menu that lists the maximum pieces that can be made of each spline (2,4,8,16), as well as the number of divisions (1 to 4). This is the same value used for Fixed subdivision, and the popup menu can be used as a quick reference.

Apply To: It is possible to have separate subdivision specifications for selected and deselected splines. This defaults to All Splines; to use it, choose selected or deselected and make your settings accordingly. This works correctly with the Save Subdivision checkbox, since actual subdivision values for each spline are saved regardless of the parameters that are used to produce it.

Scaling factor: Default 1. This controls the scale of the exported file. Normally the numerical values exported are the same as the current ruler units in the Modeling Views; this allows you to modify that if desired. Plugin authors can interpret this value in any way desired.

---

3DMF Files

This is the 3DMF-specific section of the Save... Dialog. The lower section contains the Polygon Generator controls, and is discussed here.

Surfaces Only If unchecked, PatchDance will attempt to write vertices and splines (not associated with surfaces) to the file. This isn't supported by all applications, and shouldn't be used unless you're sure you need it. Checked by default.

Polylines are segments When opening a 3DMF file, all created splines are segments rather than straight splines.

Write in text format 3DMF files can be in either text or binary format. Bibary files are smaller and open faster; text files are (somewhat) human readable. Check this if you want to inspect your file in a text processor.

Save as mesh only Don't attempt to write any NURBS patches to the file, use polygonal meshes only. This may be disabled in earlier versions: polygonal output works much better in most cases and is recommended.

About 3DMF files:

PatchDance normally writes all supported primitives as QuickDraw 3D primitive objects (some shapes are written as special case polyhedra.) For this to work, the primitive object must be shown as an Object in the Hierarchy dialog (i.e., a modified object, such as a distorted sphere, becomes a simple mesh.)

Meshes other than named primitives are written as QuickDraw 3D polyhedra. This is a polygonal format designed for this purpose. It is NOT the most efficient format for high performance rendering (such as games). If your models are intended for such use, they should first be run through an optimizing utility, such as Brian Greenstone's 3DMF Optimizer (http://www.realtime.net/~pangea ).

POV-Ray Files

This covers the POV-specific section of the Save... Options Dialog. The lower section contains the Polygon Generator controls, and is discussed here.

More information, including the standard header file for POV-Ray, is provided in "PatchDance Extras".

Prefix file: This is written to the file as an #include statement. PatchDance's standard prefix file contains a few basic definitions and is provided to let you render immediately without any source code editing. Feel free to modify it or substitute your own. This is NOT saved with the project, so if you do use a custom file it is probably easier to name it PatchDancePrefix.inc.

Export as mesh Write all objects as POV Ray meshes (containing triangles or smooth_triangles as appropriate). Unchecking this (if not disabled) results in bicubic_patches being used instead. Patches don't usually work as well as meshes!

No primitives Don't write supported Named Objects as POV Ray primitives (a sphere becomes a collection of polygons.) There should be very little reason to use this.

QuickColors Only Texture with QuickColors only, rather than any assigned textures.

About POV Ray files

PatchDance's implementation of POV Ray was designed as a a simple way to get free, high-quality rendering. Using the standard header file should allow you to render a model using the standard POV Ray distribution, with no source code changes. Of course, tweaking code will often help the results.

POV Ray's primitives are supported to the extent possible. All other objects are witten as individual meshes (containing triangles or smooth_triangles as appropriate). If an object has a Name assigned in the Hierarchy dialog, that name will be added as a comment, allowing you to locate specific objects in POV Ray files.

Marker Points If you create a Point and assign a name to it in the Hierartchy Dialog, it will be written to the file as a comment containing a set of coordinates and the assigned name. This allows you to "mark" location in 3D space and have the coordinates calcualted for you automatically. Uses for this feature include positioning lights and additional cameras.

You can assign any valid POV Ray texture to any patches. For more information see Textures.

PatchDance can export models directly to Hash's Animation:Master. These are in the form of Model (.mdl) files only, and have some limitations but do preserve the spline nature of the models, unlike DXF. This makes it possible to use PatchDance to create objects that can't be done in a reasonable amount of time or at all using Animation:Master's modeling tools. There are no options available for this process.

Limitations:

• There is no provision for texturing or naming objects: the entire PatchDance project is exported as a single Model.
• PatchDance does not support spline hooks: it may be preferable to create parts of models in PatchDance for final assembly in A:M.
• PatchDance offers much greater control of shapes and has a number of operations and options that A:M does not. A:M also constructs splines in a fundamentally different way. This may affect the editability of an exported model. In general, don't count on starting something in PatchDance and tweaking it in A:M: A:M is best used for animation and rendering.

PatchDance does not automatically create patches as A:M does, and allows patch removal. A:M generally respects the explicit list of patches that PatchDance provides, so the internal patch problem is greatly lessened. In some tests, however, A:M has added patches that were not present in the original model; be aware of this possibility. A few PatchDance operations can create internal patches, especially extrusion/lathing of objects containing patches, or overeager use of the Fill Mesh command.

To export a PatchDance model: simply save (preferably a copy) and choose Animation:Master (.mdl) from the popup menu in the Save dialog box. These files MUST have the extension .mdl (added automatically: A:M uses the extension ONLY to determine the file type.) The files generally appear as generic (blank) icons since A:M doesn't define icons for them, and can be opened in A:M as usual. Bear in mind that by default A:M works with Projects, which are different from Models.