Root/solidify/README

1solidify - Merge two opposing faces of a part into a solid
2==========================================================
3
4Solidify is a tool for adjusting the orientation of two opposing faces
5(surfaces) of a three-dimensional part such that they correctly align
6with each other, and to generate output that represents the volume
7(solid) enclosed between the two faces.
8 
9This work is distributed under the terms of the GNU GENERAL PUBLIC
10LICENSE, Version 2:
11
12  This program is free software; you can redistribute it and/or modify
13  it under the terms of the GNU General Public License as published by
14  the Free Software Foundation; either version 2 of the License, or
15  (at your option) any later version.
16
17For your convenience, a copy of the complete license has been included
18in the file COPYING.GPLv2.
19
20
21Theory of operation
22-------------------
23
24The shape of a three-dimensional part can be reconstructed by scanning
25two opposing faces of the part. The part is then the space between the
26two faces.
27
28When doing this in practice, a few problems arise. One of them is that
29the faces will not be perfectly opposed. E.g., the part being scanned
30may be inclined, rotated, or shifted. Solidify implements the following
31operations:
32
33- change the inclination of the part along the x and y axis (i.e., the
34  part's z plane is tilted). The general assumption is that the part is
35  scanned with its main surfaces parallel to the z plane and that only
36  small adjustments are necessary.
37
38- change the part's height above the z plane. There is a conceptual z0
39  plane, parallel to the z plane, that is coplanar with a reference
40  surface in the face. The height of the z0 plane above the z plane
41  can be adjusted.
42
43- set the distance between the z0 plane of the top face and the z0 plane
44  of the bottom face. This defines the thickness at some point of the
45  part.
46
47- align the two faces by rotating them around the z axis and by shifting
48  them in the x and y direction.
49
50Except for setting the distance between z0 planes, all these operations
51are interactive. Solidify furthermore provides visual clues that help to
52minimize anomalies.
53
54Solidify reads faces as comma-separated point clouds generated by
55Dr.Picza3. It outputs a set of files that define the part in POV-Ray.
56
57
58Starting a project
59------------------
60
61For a project, the following information is necessary:
62
63- the name of the project file. If the file does not yet exist, solidify
64  starts a new project. Solidify stores information pertaining to the
65  project, such as the names of the file containing the faces and the
66  orientation set for the faces.
67
68  Solidify project files typically have the extension .sfy.
69
70- two text files containing the two faces as comma-separated point
71  clouds. If a file name ends with the extension .bz2, solidify will
72  uncompress the file on the fly with bunzip2.
73
74  If instead of a file name a HTTP or HTTPS URL is given, solidify will
75  try to download the file with "wget" into a directory called .cache.
76  This directory must be manually created for this purpose. On further
77  invocations, solidify will load the file directly from the cache.
78
79- the distance between the z0 planes of the two faces. Typically, this
80  is the thickness of the part in some area that is flat on both sides.
81  The distance is measured in millimeters.
82
83To generate a project name.sfy with the faces top.svn and bottom.sfy
84and a z0 distance of 1.5 mm, run
85
86$ solidify name.sfy top.csv bottom.csv 1.5
87
88Solidify will load the faces (this can take a while) and then show the
89top face for z0 plane editing.
90
91
92Leaving solidify
93----------------
94
95To exit solidify and save the current settings in the project file,
96simply press "q". To quit without saving, terminate solidify by pressing
97^C in the shell.
98
99
100Changing an existing project
101----------------------------
102
103Start solidify with the name of the project file, e.g.,
104
105$ solidify name.sfy
106
107Solidify will load the face files and then show the top face for z0
108plane editing.
109
110
111Adjusting the z0 plane
112----------------------
113
114There are four buttons at the right side of the screen. The ones labeled
115"A" and "B" are for editing the top and bottom faces.
116
117Note that each face has its own z0 plane, which is controlled
118independently from the of the other z0 plane.
119
120
121Display
122- - - -
123
124The center area of the screen shows the respective face from the top.
125Areas below the z0 plane are shown in red, areas above the z0 plane are
126in green. Intersections of the z0 plane with the face are shown in blue.
127
128The intensity of the color increases with the distance between the face
129and the z0 plane. To make it easier to see which way the planes are
130facing, areas with only a small difference and thus often directly
131adjacent to an intersection (blue) are colored with more intense red and
132green.
133
134Below and on the right side of the central view, lateral projections of
135cuts at the cursor position are shown.
136
137
138Control
139- - - -
140
141The z0 plane is manipulated with the mouse wheel. Rotating the mouse
142wheel with the pointer near the center of the main view raises or lowers
143the z0 plane. Outside the center, rotating the mouse wheel tilts the z0
144plane by pushing or pulling at the pointer position.
145
146The center area is marked with a yellow circle that becomes visible when
147approaching it with the mouse pointer.
148
149
150Workflow
151- - - -
152
153There are two objectives when adjusting the z0 plane:
154
155- it should intersect the face at the point(s) that define the distance
156  between z0 planes, and
157
158- the z0 plane should be parallel to the principal orientation of the
159  part
160
161As a first step, it's usually best to pick one or two flat reference
162areas containing the zones where the distance was measures, and to tilt
163the z0 plane until it is roughly parallel to these areas. This can be
164easily seen on the lateral projections.
165
166Then the z0 plane is be raised or lowered until it intersects. The
167result should be a large blue field that covers the reference areas.
168
169If the part is not only tilted but also warped, it may not be possible
170to evenly level it. For achieving as good an adjustment as possible, one
171should attempt to maximize and evenly distribute the blue areas on the
172main view.
173
174
175Aligning the faces
176------------------
177
178When clicking the "A+B" or "B+A" button, both faces are shown
179superimposed, with the bottom face rotated around the y axis.
180
181With "A+B", the top face is manipulated, with "B+A" the bottom face.
182The display is the same in both cases.
183
184
185Display
186- - - -
187
188The following colors are used:
189
190- white: both faces overlap
191- green: only the top face. There are no points in the bottom face at
192  this location
193- green: only the bottom face
194- blue: the top face is below the bottom face
195
196
197Control
198- - - -
199
200Again, the faces are controlled with the mouse wheel and the function of
201the wheel depends on whether the pointer is in the central area or not.
202The central area is marked with a yellow circle that is displayed when
203the mouse pointer approaches it.
204
205To rotate the face around its center, move the mouse pointer outside the
206center area and spin the mouse wheel. The larger the distance from the
207center, the faster the face spins.
208
209Spinning the mouse wheel when the pointer is inside the central area
210shifts the face along the x and y axis. (*) The central circle is
211divided into four areas: in the left and right area, the face is shifted
212horizontally, in the upper and lower area, the face is shifted
213vertically.
214
215(*) When shifting the bottom face, the direction depend on the face's
216    rotation. This is a bug but it has no other ill consequences.
217
218
219Workflow
220- - - -
221
222The faces usually don't overlap perfectly. The goal is thus to
223distribute the red or green overlaps evenly.
224
225If significant portions of the part are drawn in blue, this means that
226the orientation or the height of the z0 planes is not correct.
227
228If the part is very thin, it may be necessary to raise the faces a but
229above the z0 plane to keep the faces from intersecting due to warping.
230
231
232Rendering with POV-Ray
233----------------------
234
235                                                                       |
236When invoked with the option -p, solidify generates the following three
237files:
238
239- name.inc: a POV-Ray file that renders the part. The part is called
240  "Part_name"
241- name-top.pgm: a PGM (Portable GrayMap) image containing a height field
242  for the top face
243- name-bot.pgm: height field of the bottom face
244
245Invocation is as follows:
246
247$ solidify -p name.sfy
248
249A part can be used in a POV-Ray scene by #including its name.inc file
250and then placing the object.
251

Archive Download this file

Branches:
master



interactive