User Manual
1) What is D-form?
D-form is a deformation engine that can perform a series
of deformations on
three dimensional objects. It's has some features normally
found in modelers,
but it is not a complete modeler. In fact, it cannot
create or delete any part
of an object; it just allows you to alter the shape
of the object.
2) Fine, but do I need D-form?
Well, it was written with POV-Ray in mind, but since
version 1.1.0a I implemented
many import-export formats so the program is useful
for all 3D designers.
3) Oh, I see... but what is POV-Ray?
POV-Ray is a freeware raytracer, that can be found in
Internet as well as in
shareware collections CD-ROMs, BBS, friends...
The starting point to discover POV-Ray is his Official
MacOS Home Page:
http://ourworld.compuserve.com/homepages/povraymac/
The official Home Page is:
http://www.povray.org.
There is a new section of my Home Page dedicated to
POV-Ray for MacOS Hints & Tips.
I strongly suggest to read it because it treats some
possible D-form uses:
http://www.geocities.com/SiliconValley/Way/2419/POVMAChints.html
4) "Raytracer"? Hey, can you explain such term?
No, sorry. This is not the place. But if you are really
interested in raytracing
don't give up!
Try to browse POV-Ray web site (http://www.povray.org)
to obtain more informations.
Or take a look at my 3D web page:
http://www.geocities.com/SiliconValley/Way/2419/3Dgraphics.html
5) I use POV-Ray! Can D-form make my life easier?
Maybe. Keep on reading.
6) Is D-form a finished program?
No. It's pretty far from completeness! It can crash
and it has some bugs.
But if you feel adventurous and patient, you can help
me to enhance D-form in
reliability, and features.
7) It's dangerous to use it?
Well I hope no, but keep in mind that, as alpha software,
it can have strange
behaviors, write garbage on an output file or even not
work at all!
(OK, it's very difficult to damage a Mac using D-form
but be aware that your
Mac can crash, and crashing a computer may always due
to data corruption.
Luckily Mac's file system is pretty solid, but I don't
suggest use D-form or any
other instable software on a disk containing precious
un-baked-up data).
8) Gosh, I better trash it before getting my HD completely wiped clean!
Well, if you use D-form, *** use it at entirely your
own risk ***.
However I doubt It can perform something worse than
crash your Mac...
But if you are afraid trash it now and buy something
else.
9) OK, I accept to risk a little, what I can do now?
Well, reading the docs until the end may be a good starting
point. A little knowing
of the program limits can prevent most crashes.
I know you are curious and want to try out D-form capability
now but
read carefully at least the list of known bugs *before*
using D-form.
10) I want to know more about features!
Yes, it's time to start.
D-form can import 3D objects in the following formats:
a) RAW triangle (.RAW)
b) Amapi text (.txt) (limited to 4 edges polygons)
c) Vision-3D text (.vtxt) (limited to 4 edges polygons)
d) DXF (.DXF) (limited to certain dialect and to 4 edges
polygons)
e) POV-Ray (.POV) files browsing triangle and smooth_triangle
primitives
f) POV-Ray (.POV) files browsing bicubic_patch primitives
a) RAW triangle is the very simpler way to describe
a polygonal object. It can
contain only triangles.
The file is a text document.
The format is:
X1 Y1 Z1 X2 Y2 Z2 X3 Y3 Z3
where X1, Y1 and Z1 are the x, y and z coordinates of
the first vertex of the
triangle. As you can see every line of the text file
is the description of one
triangle. Usually the coordinates of one vertex are
separated by one space
and the vertices are separated by two spaces but I found
RAW files that had
all the nine numbers separated by one space only. The
second format is less
easy to read by a human but it save some space on your
hard disk.
An object containing 10240 triangles is 20Kb smaller
if saved with the second
format. OK, today the HD sizes are hundreds or thousands
of Mb but you can still
have a 40Mb HD or hate to waste space anyway.
D-form can save RAW files in both ways. To turn on/off
one space exporting use
the "One space export" checkbox in "Preferences"
dialog box.
There is a third format (Fractint) that is:
R G B X1 Y1 Z1 X2 Y2 Z2 X3 Y3 Z3
This one stores info about triangle's color in his RGB
components.
This is the format used by Vision-3D RAW output.
To enable-disable RGB reading, use the "Read RGB
values" checkbox in the
"Preferences" dialog window.
b) Amapi text format (.txt) is one of the export formats
Amapi supports.
Amapi is a 3D app (commercial) by TGS (http://www.tgs.com).
Amapi users: if you save a model in text format expect
to wait since Amapi is
unbelievable slow in writing this format. You can use
DXF also to export to D-form,
but the best format is the Amapi's POV-Ray output (see
below).
NOTE: If you don't name the file with the ".txt"
extension Amapi won't recognize it!
NOTE: this format is near to useless for two reasons:
- It allows only to save an object as a bunch of polygons,
no way to maintain
object separation.
- TGS seems to have discontinued it since Amapi no longer
support it.
I leaved it for people who uses D-form with Amapi up
to 2.11.
Use 3DMF instead to export from D-form to Amapi 3.0.
c) Vision-3D text format is one of the export formats
Vision-3D supports. Vision-3D
is a shareware 3D app by Paul Bourke (http://www.mhri.edu.au/~pdb/paul.html).
This format has several info about object's surface
properties. D-form remembers these
properties if the input file was in this format. If
the input format was another and
the object is saved using this format those values are
set to the same default values
that Vision-3D uses.
In future I plan to add the option to set up these properties
from D-form.
d) DXF format is the interchange format of AutoCAD (http://www.autodesk.com),
and
is the "de facto" standard in 3D interchange.
Near all 3D apps supports it.
DXF export is planned for future.
e) The "triangle" and "smooth_triangle"
primitives are described in POV-Ray Docs.
D-form can browse a POV-Ray text description file and,
if it founds a "triangle"
or a "smooth_triangle" statement it reads
it and then displays the triangles.
NOTE: if the triangles are organized in meshes using
the "mesh" keyword, D-form
can recognize different objects and maintain the separation
in the later RAW or Vision-3D
text savings.
Try to open the file "CHESS.INC" in POV3DEMO:OBJECTS
folder.
NOTE: The smoot_triangle's surface normals are ignored.
Only the vertices are read.
NOTE: Amapi's POV-Ray output uses meshes so the best
way to import files from
Amapi to D-form is using POV-Ray format. In this way
object separation is maintained.
Amapi is also able to save with the "smooth_triangle"
primitive.
For more info about the argument read the "Rendering/Converting
polygonal objects"
section of my Home Page at the address:
http://www.geocities.com/SiliconValley/Way/2419/POVmesh.html
f) Bicubic Patches are described in POV-Ray Docs. D-form
can browse a POV-Ray
text description file and, if it founds a "bicubic_patch"
statement it reads it
and then displays the patches. In fact D-form reads
and "remembers" the whole
POV scene description and, after the object is modified
and you save it, D-form
rewrite the POV file on the disk swapping the old patch
coordinates with the
new ones.
NOTE: If one or more vertices of the patches are non
numeric, D-form fails to read
it and can crash.
Try to open the file "TEAPOT.INC" in POVSCN:LEVEL3:TEAPOT
folder.
11) Hey, wait! I don't understand this! What you mean for "non numeric"?
Well, an example can explain better.
This is a patch description:
*** missing: to be added ***
12) I see... Ok, go on explaining.
D-form can open one object at one time, and of one type.
So you cannot open a
triangle mesh object and a B-patch object simultaneously.
When you open an object, the one previously owned in
memory is deleted.
NOTE: D-form doesn't warn you if the previous object
is not saved.
Unfortunately, although I free the memory occupied by
the object, the memory is
doesn't properly released and after a number of openings
the program crashes.
I'm working to fix this.
After an object is loaded you can perform a series of
operations on it.
On the left side of the window there is the Tools button
palette
The button names are (from the upper left):
a) Hand
b) Zoom
c) Rotate
d) Move / Stretch
e) Drag
f) Axis
g) Twist
h) Cut
i) Bend1
l) Bend2
m) Shear
n) Taper
o) Wave
p) Swirl
q) Magnet
After loading a model, just select one Tool by pressing
the relative button.
Then click somewhere in the window and drag the mouse
upward or downward.
The object will be deformed in real time.
Just release the mouse button when you are satisfied
about the deformation
amount.
This works for all the Tools except the drag Tool and
the axis Tool.
The drag Tool will be explained in detail later.
The axis Tool changes the active axis.
When you perform a deformation, for example the twist,
if the "X" axis is selected
the twisting is performed on the X axis.
Keep in mind that the X axis is always rightward, the
Y axis is always upward and
the Z axis always point straight into the screen even
if you selected another
view from the "View" menu other than "Front".
This because when you change the view direction, for
example "Top" is the object
that rotates on the X axis to allow you to face his
upper side.
Let's now see in more detail the Tools:
a) Hand
This Tool allows you to perform free rotation of the
object. It works nearly as
a trackball, just click and drag.
If option key is held down the object rotates around
the active axis.
NOTE: This Tool is not permanent in the sense that if
you choose one of the
views form the "View" menu, the rotation is
lost. But if you save the
object while it's rotated, it will be saved rotated.
NOTE: unlike Rotate, Hand is not undoable.
b) Zoom
This Tool allows you to magnify the object.
Keep in mind that is the object that is being scaled,
not the camera that come
close to it, so if you alter the object's size and then
you save it, it will
have the new size.
NOTE: The Tool does not have any limit, so if you scale
it smaller too much it
will re-start to grow after a certain point, but without
the original shape.
Just don't release the mouse button and go back a little
with the mouse until
the wanted size is reached.
c) Rotate
It works the same way as Hand do but the rotation is
permanent.
If option key is held down the object rotates around
the active axis.
d) Move / Stretch
With this Tool you can move around the object.
If control key is held down the object moves only horizontally
and vertically.
If option key is held down the object is stretched along
the active axis.
If command key is held down the object is stretched
along the plane normal to
the active axis.
e) Drag
By shift-clicking on vertices you can select-deselect
them. With shift-dragging
you can select a bunch of vertices. A selected vertex
is displayed with a red
handle. If you shift-click a selected vertex you will
deselect it but by
shift-dragging on vertices those deselected will be
selected and those yet selected
remain selected. By command-dragging on vertices, instead
you will skip the
situation: those selected are deselected and those deselected
become selected.
By shift-option-clicking or shift-option-dragging vertices
you will select them
as green handles. When you simply drag in the window
the red handles will follow
the cursor movements while green handles will move specularly.
When you drag left red handles, green handles will move
right and vice-versa.
By option-dragging even vertical movement of the green
handles are flipped.
Use green handles when you are deforming a symmetric
shape like, for example a
human head. If you assign red handles to right ear and
green handles to left ear
while you are deforming one ear the other will deform
specularly.
f) Axis
By pressing and holding this button you can choose the
"active" axis.
Most deformations are performed differently, depending
by the active axis.
g) Twist
This one is the first Tool I have developed. It simply
twists the object around
the active axis.
h) Cut
Similar to the twist except that the twist is limited
between a certain part
"around" the origin. The size of this interval
can be adjusted in "Tools setup..."
of the "Tools" menu.
i) Bend1
This bending Tool works like on a pile of playing cards.
The faces remain parallel.
l) Bend2
This bending Tool bends the object as a piece of rubber.
m) Shear
This simple Tool simply shears the objects. If you need
to do only this deformation
on an object it's better to use matrix shear capability
of POV-Ray.
n) Taper
This Tool pinches the object on one side while enlarging
it on the other.
If option key is held down the object is tapered by
one axis only.
o) Wave
This Tool apply a sine function to the object shaping
it as a wave. Phase and
frequency can be adjusted in "Tools setup..."
of the "Tools" menu.
p) Swirl
This Tool swirls the object.
q) Magnet
This Tool consist in a magnetic point that attracts
or repulses points.
You can set up location and strength in "Tools
setup..." of the "Tools" menu.
By option-dragging, the Tool will perform only along
the active axis.
By command-dragging, the Tool will perform only on the
plane orthogonal to the
active axis.
13) OK, and what are those menu for?
File menu:
Open:
This menu item has a submenu with all the input formats:
RAW triangle
Amapi text
Vision-3D text
DXF
POV-Ray triangle
POV-Ray bicubic
Save:
The object is saved in the last format used.
NOTE: When you save and object, his actual orientation
becomes the front view.
If you didn't want the object orientation to change,
just choose "Front" from
the "View" menu before saving.
Save as...:
This menu item has a submenu with all the output formats:
RAW triangle
Amapi Text
Vision-3D Text
POV-Ray Bicubic
NOTE: You have to manually change an eventual extension
when naming the file.
Extensions (like .RAW, .DXF...) are optional on Macintosh,
but writing them in
the file names helps the format recognition. Only Amapi
*requires* that the
Amapi text files have the right extension (.txt for
Amapi text, .b3d for 3DMF...)
or it wouldn't read them.
Revert:
Restore the object as it was last saved.
Preferences...
Use FastBox preview:
D-form will use a FastBox when performing some operation
(like rotating, zooming...).
Check this option if you have a slow machine.
Write RGB values:
If this option is on D-form will write RGB components
in Fractint RAW format.
If no RGB values are memorized, then all R, G and B
values are stored as "0".
NOTE: In this case importing such object in Vision-3D
will result in a black object.
One space export:
If this option is on D-form will save RAW files with
one space only between
vertices. If is off two spaces are used (more compatible).
Show handles:
D-form does not show handles when dragging vertices.
Checking off
this option speeds up the dragging redraw.
Reduce shown edges:
D-form displays only one edge for each triangle when
performing
some operations. Another trick to speed up redrawing.
This option does not have effect on Bezier objects.
Show only involved:
This behaves differently from polygonal to Bezier objects:
Polygons: D-form redraws only the polygons directly
involved in some deformation.
Bezier: D-form shows only the mesh of the patches with
at least one handle selected.
Yet another trick to speed up.
Zoom:
Distance:
Change this two parameters if you want to change the
amount of perspective.
No of digits:
When D-form saves a file it's the number of digits
saved for each
floating point value (vertices coordinates).
Small values can distort you object.
High values will do your file bigger.
Light source location:
X:
Y:
Z:
Sets the position of the light source.
Quit:
Quits D-form.
Edit menu:
Undo:
Undo/Redo the last operation.
NOTE: the Hand Tool is not undoable.
Cut:
Copy:
Paste:
Clear:
Usual operations. You can operate only with text in
dialog boxes.
View menu:
Front:
Back:
Top:
Bottom:
Left:
Right:
Rotate the object to display his front, back...
Centre:
Centre the object in the origin.
Fit to window:
Scales the object to make it entirely visible.
NOTE: this option does not centre the object. If you
want to object to fill the
entire window you must centre it with the "Centre"
menu item from "View" menu
and than choose "Fit to window" menu item
from "View" menu.
Perspective:
Toggles perspective on/off.
Render type:
This menu item has a submenu with all the rendering algorithms:
Wireframe:
This is the fastest.
Hidden lines:
Similar to wireframe but shows only visible polygons.
Flat shading:
This gives a solid appearance to the object. Faster than Hidden lines.
ShadeFrame:
This is the slowest algorithm. It combines shading and
wireframe.
Useful when selecting vertices.
NOTE: Bicubic patch objects are always displayed in wireframe.
Options menu:
Directional drag:
Whit this option on when you drag a vertex it will attract
all the point nearer
than a certain radius from the dragged vertex. The vertices
will move in the same
direction that the dragged do.
You can change the radius value in "Tools setup..."
of the "Tools" menu.
Elastic drag:
Similar to Directional but now vertices follows the
dragged vertex and tend to
"reach" it. The effect obtained is similar
at dragging the surface of
an inflated balloon.
You can change the radius value in "Tools setup..."
of the "Tools" menu.
Deform selected:
Whit this item toggled on the deformations are performed
only on the selected
vertices and not to the whole object.
This is a powerful option and, well used, allows the
creation of interesting objects
very easy starting from much simpler ones.
Tools menu:
Translate...:
Rotate...:
Scale...:
Perform these operations to the object. If more than
one field are filled
the operation are performed in this order: X, Y, Z.
NOTE: The "Rotate..." menu item performs permanet
rotations like the Rotate Tool.
Triangulate:
Triangulates all the four sided polygons.
Note that you choose to save an object as RAW triangle,
triangulation is automatically
performed.
Polygonize:
Converts a bicubic_patch object to a polygonal one.
Note that you must choose
"Patch subdivision..." before, to set up the
wanted smoothness.
Tools setup...:
Cut setup:
Value:
Vertices in the interval between -Value e +Value around
the origin are
twisted when the Cut Tool is used. Other vertices
rotates around the active
axis.
Wave setup:
Frequency:
Phase:
Set up frequency and phase of the Wave Tool.
Specular:
Disabled.
Magnet setup:
Magnet location:
X:
Y:
Z:
Sets the coordinates of the magnet.
Field strength:
Sets the strength of the magnet.
Drag setup:
Radius:
Vertices nearer the radius follows the dragged vertex
if Directional
drag ore Elastic drag are on.
Tool deformation multiplier:
This value affects the amount of transformation per
mouse movement.
Think it as a mouse sensitive value.
If you find that a certain Tool is performed with too
little precision, set this
value to a fraction of 1.
For example a value of 0.5 will make the Hand Tool
rotate the objects at half speed.
Patch subdivision...:
u:
v:
When polygonating patches D-form uses u and v as number
of subdivisions.
NOTE: POV-Ray has not the same fine tuning. In bicubic_patch
statement u_div
and v_div values are used as exponent of 2 to calculate
the number of subdivision.
So in POV-Ray you can have only 1, 2, 4, 8, 16, 32...
while D-form can use any
integer value. This because 8 can be too "low"
and 16 too "slow".
14) OK, I'm tired of reading! Tell me the bugs so I can start!
Known incompatibilities are:
- D-form does not work with Aaron. Really don't know
why.
- D-form does not run under Executor, a Mac emulator
for PC. I will try to
fix this because D-form is wanted by PC community,
but it will *never* gonna be
available for Intel.
I know of people that successfully ran D-form under
Fusion, another Mac emulator for PC.
Known bugs that will probably ore surely bring to a crash are:
- D-form have problems releasing memory. It seems like
it does not release
memory at all! This cause to a crash if you open much
object without quitting.
You can monitor memory usage by choosing "About
this Macintosh..." (or "About this
computer..." on recent systems) from Apple menu.
Other bugs:
- The lower the number of colors the fastest the redraw.
In B/W however you
cannot distinguish between red handles and green ones.
The optimal screen depth
for D-form millions of colors. At lower screen depth
if you display the object using
flat shading or ShadeFrame it will be dithered.
- If a very large object is opened, attempts to scale
it smaller (with the Scale Tool)
may fail. Use the "Fit to window" menu item
if this happens.
- If two or more vertices became coincident there is
no way to separe them.
- The bicubic patch models provided are not 100% mathematically
correct. I don't
know the relative coordinates to obtain perfect spheres,
cylinders... If you do know
mail me.
- The undo option does not always... undo!
- After an undo the "Undo" menu Item doesn't
switch to "Redo" but, if selected, it
actually redo.
- This documentation is plenty of grammar errors. Blame
the author and his English
teachers!
- D-form does not support any of the Apple Events.
NOTE to beta testers.
Thank you all for patience and courage. Note that I
have very little free time
to develop D-form so don't expect your suggestion and
bug reports to be instantly
turned into code improvement. I will answer soon to
mail anyway.
Try to test D-form robustness. D-form should now check
the correctness of input files,
and of data inserted in text fields of dialog windows.
Don't use D-form on a un-backed up HD. Give it enough
memory and quit it every now
and again to clean up memory or it will crash. Give
D-form to your friends if you
want but make them read the docs carefully *before*
use.
D-form is freeware!
This means that you can use it for free and you can
distribute to anyone but only
unmodified copies with all the files (docs, models).
15) What hardware are you using now?
Power Macintosh G3/233, 96 Mb RAM, 512Kb Level II Backside
Cache, ATI Rage II 6 Mb VRAM,
Western Digital 4 Gb EIDE & Quantum Fireball 1280
SCSI external, CD-ROM 24X ATAPI,
ArtMedia 17" Trinitron, Digicom Leonardo 56, MacOS
8.5.1 ITA.
I would like to thank also:
Dario (Captain Blood) Manzoni: who years ago showed
me some 3D demos on his Amiga 2000
and then I started 3D programming (my first challenge
was a spinning cube!)
Eduard (ESP) Schwan: who has ported POV-Ray to MacOS
and helped me during development.
Mauro (Scienza) Marchesi: who helped me with matrix
math.
Paul Bourke and all the people of the povray.programming
newsgroup: who helped during
the development of the rendering algorithms.
All the beta testers and whoever wrote me about D-form.
All the source code is written entirely on algorithms invented from scratch except:
- bicubic patch mesh computation that I found on book
"3D Computer Graphics" by
Alan Watt.
- DXF input that is a modified version of the code of
Stephen B. Coy.
- The mergesort algorithm that Is a modified version
of the LL_MSORT.C by Ray Gardner.
D-form is written in plain 100% object-free C. Efforts
are made to make
it as fast as possible even on low end machines. (I
received mail that stated
that D-form is effetively fast!)
D-form development started a nice day of February 1996.
Bugs, suggestions, flames, money donations, jokes?
Diego Krota
E-Mail: dkrota@geocities.com (if this address may
be no longer valid in future
go to my Home Page and you will find the new address)
Home Page: http://www.geocities.com/SiliconValley/Way/2419
D-form Home Page: http://www.geocities.com/SiliconValley/Way/2419/D-form.html
This page was created using TextToHTML. TextToHTML is a free software for Macintosh and is (c) 1995,1996 by Kris Coppieters