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. This file must not yet exist. Solidify
64  store information pertaining to the project, such as the names of the
65  file containing the faces and the orientation set for the faces.
66  Solidify project files typically have the extension .sfy.
67
68- two text files containing the two faces a comma-separated point
69  clouds. If a file name ends with the extension .bz2, solidify will
70  uncompress the file on the fly with bunzip2.
71
72  If instead of a file name a HTTP or HTTPS URL is given, solidify will
73  try to download the file with "wget" into a directory called .cache.
74  This directory must be manually created for this purpose. On further
75  invocations, solidify will load the file directly from the cache.
76
77- the distance between the z0 planes of the two faces. Typically, this
78  is the thickness of the part in some area that is flat on both sides.
79  The distance is measured in millimeters.
80
81To generate a project name.sfy with the faces top.svn and bottom.sfy
82and a z0 distance of 1.5 mm, run
83
84$ solidify name.sfy top.csv bottom.csv 1.5
85
86Solidify will load the faces (this can take a while) and then show the
87top face for z0 plane editing.
88
89
90Leaving solidify
91----------------
92
93To exit solidify and save the current settings in the project file,
94simply press "q". To quit without saving, terminate solidify by pressing
95^C in the shell.
96
97
98Changing an existing project
99----------------------------
100
101Start solidify with the name of the project file, e.g.,
102
103$ solidify name.sfy
104
105Solidify will load the face files and then show the top face for z0
106plane editing.
107
108
109Adjusting the z0 plane
110----------------------
111
112There are four buttons at the right side of the screen. The ones labeled
113"A" and "B" are for editing the top and bottom faces.
114
115Note that each face has its own z0 plane, which is controlled
116independently from the of the other z0 plane.
117
118
119Display
120- - - -
121
122The center area of the screen shows the respective face from the top.
123Areas below the z0 plane are shown in red, areas above the z0 plane are
124in green. Intersections of the z0 plane with the face are shown in blue.
125
126The intensity of the color increases with the distance between the face
127and the z0 plane. To make it easier to see which way the planes are
128facing, areas with only a small difference and thus often directly
129adjacent to an intersection (blue) are colored with more intense red and
130green.
131
132Below and on the right side of the central view, lateral projections of
133cuts at the cursor position are shown.
134
135
136Control
137- - - -
138
139The z0 plane is manipulated with the mouse wheel. Rotating the mouse
140wheel with the pointer near the center of the main view raises or lowers
141the z0 plane. Outside the center, rotating the mouse wheel tilts the z0
142plane by pushing or pulling at the pointer position.
143
144The center area is marked with a yellow circle that becomes visible when
145approaching it with the mouse pointer.
146
147
148Workflow
149- - - -
150
151There are two objectives when adjusting the z0 plane:
152
153- it should intersect the face at the point(s) that define the distance
154  between z0 planes, and
155
156- the z0 plane should be parallel to the principal orientation of the
157  part
158
159As a first step, it's usually best to pick one or two flat reference
160areas containing the zones where the distance was measures, and to tilt
161the z0 plane until it is roughly parallel to these areas. This can be
162easily seen on the lateral projections.
163
164Then the z0 plane is be raised or lowered until it intersects. The
165result should be a large blue field that covers the reference areas.
166
167If the part is not only tilted but also warped, it may not be possible
168to evenly level it. For achieving as good an adjustment as possible, one
169should attempt to maximize and evenly distribute the blue areas on the
170main view.
171
172
173Aligning the faces
174------------------
175
176When clicking the "A+B" or "B+A" button, both faces are shown
177superimposed, with the bottom face rotated around the y axis.
178
179With "A+B", the top face is manipulated, with "B+A" the bottom face.
180The display is the same in both cases.
181
182
183Display
184- - - -
185
186The following colors are used:
187
188- white: both faces overlap
189- green: only the top face. There are no points in the bottom face at
190  this location
191- green: only the bottom face
192- blue: the top face is below the bottom face
193
194
195Control
196- - - -
197
198Again, the faces are controlled with the mouse wheel and the function of
199the wheel depends on whether the pointer is in the central area or not.
200The central area is marked with a yellow circle that is displayed when
201the mouse pointer approaches it.
202
203To rotate the face around its center, move the mouse pointer outside the
204center area and spin the mouse wheel. The larger the distance from the
205center, the faster the face spins.
206
207Spinning the mouse wheel when the pointer is inside the central area
208shifts the face along the x and y axis. (*) The central circle is
209divided into four areas: in the left and right area, the face is shifted
210horizontally, in the upper and lower area, the face is shifted
211vertically.
212
213(*) When shifting the bottom face, the direction depend on the face's
214    rotation. This is a bug but it has no other ill consequences.
215
216
217Workflow
218- - - -
219
220The faces usually don't overlap perfectly. The goal is thus to
221distribute the red or green overlaps evenly.
222
223If significant portions of the part are drawn in blue, this means that
224the orientation or the height of the z0 planes is not correct.
225
226If the part is very thin, it may be necessary to raise the faces a but
227above the z0 plane to keep the faces from intersecting due to warping.
228
229
230Rendering with POV-Ray
231----------------------
232
233                                                                       |
234When invoked with the option -p, solidify generates the following three
235files:
236
237- name.inc: a POV-Ray file that renders the part. The part is called
238  "Part_name"
239- name-top.pgm: a PGM (Portable GrayMap) image containing a height field
240  for the top face
241- name-bot.pgm: height field of the bottom face
242
243Invocation is as follows:
244
245$ solidify -p name.sfy
246
247A part can be used in a POV-Ray scene by #including its name.inc file
248and then placing the object.
249

Archive Download this file

Branches:
master



interactive