Make your own free website on Tripod.com

D-form 1.3.1a

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


Original file name: D-form Docs 1.3.1a - converted on Friday, 21 January 2000, 20:02

This page was created using TextToHTML. TextToHTML is a free software for Macintosh and is (c) 1995,1996 by Kris Coppieters