-
Notifications
You must be signed in to change notification settings - Fork 5
/
Copy pathpsalm.txt
230 lines (170 loc) · 7.34 KB
/
psalm.txt
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
PSALM
=====
NAME
----
*psalm* - pretty subdivision algorithms on meshes
SYNOPSIS
--------
*psalm* ['arguments'] ['file']
DESCRIPTION
-----------
*psalm* is a mesh compiler, using meshes in several data formats (+OBJ+,
+OFF+, +OBJ+) as its input, and generating _subdivided_ meshes in turn.
Currently, Catmull-Clark, Doo-Sabin, and Loop subdivision schemes have
been implemented.
The user may change several parameters of the subdivision algorithm,
such as the *weights* that are used for extraordinary vertices of the
mesh. Furthermore, rudimentary pruning capabilitites have been
implemented.
*psalm* can work without any parameters. It will expect input from
+STDIN+ and write its data to +STDOUT+. For displaying the status
(subdivision might take long), +STDERR+ is used. The user may specify
+STDOUT+ and +STDIN+ by using a single dash, +-+, as the argument for
output and input operations.
If an input file has been specified, but not output file, the suffix
+.subdivided+ will be added to the input file. For example, subdividing
a file +example.ply+ without specifying an output file results in
+example.subdivided.ply+.
OPTIONS
-------
There are three categories of parameters: General, tuning, and pruning.
The general parameters are used for *psalm*'s basic operations. Tuning
parameters affect the internal workings of the algorithms. Pruning
parameters enable simple removal operations for meshes.
General
~~~~~~~
*-a, --algorithm* '<algorithm>'::
Selects the subdivision algorithm to use on the input mesh. Valid
values for '<algorithm>' are:
* +catmull-clark+, +catmull+, +clark+, +cc+ [default]
* +doo-sabin+, +doo+, +sabin+, +ds+
* +loop+, +l+
*-o, --output* '<file>'::
Sets output file. If not present, +STDOUT+ will be used. A single dash
will be interpreted as +STDOUT+.
*-t, --type* '<type>'::
Sets type of input data. If not present, the type of input and output
data is guessed from the file extension. Valid values for '<type>' are:
* +obj+ (Wavefront OBJ files)
* +off+ (Geomview object files)
* +ply+ (Stanford PLY files)
*-n, --steps* '<n>'::
Sets number of subdivision steps to perform on the input mesh. This
parameter is +0+ by default.
*-s, --statistics*::
Prints statistics and progress bars to +STDERR+.
*-h, --help*::
Shows a help screen.
Tuning
~~~~~~
*-b, --b-spline-weights*::
Instructs algorithms to use the normal B-spline weights for the regular
subdivision case even if the current weight scheme would apply different
weights. *This parameter affects the shape of the resulting surfaces.*
*-c, --handle-creases*::
Algorithms try to subdivide crease and boundary edges whenever this is
possible.
*-p, --parametric*::
Forces algorithms to calculate new points using parametrical methods
instead of geometrical methods. May affect the running time of the
algorithm.
*-w, --weights* '<weights>'::
Selects type of weights that are used for the subdivision algorithm.
Algorithms may choose to ignore this parameter. Valid values for
'<weights>' are:
* +catmull-clark+, +catmull+, +clark+, +cc+
* +default+
* +degenerate+
* +doo-sabin+, +doo+, +sabin+, +ds+
*-e, --extra-weights* '<file>'::
Overrides default weight of subdivision schemes by reading them from
'<file>'. The precise format of this file depends on the subdivision
algorithm that is used.
Pruning
~~~~~~~
*--remove-faces* '<n1>, <n2>, ...'::
Removes faces whose number of sides matches one of the numbers in the
list. Use commas to separate list values.
*--remove-vertices* '<n1>, <n2>, ...'::
Removes vertices whose valency matches one of the numbers in the list.
Use commas to separate list values.
EXAMPLES
--------
.File conversion
By default, no subdivision is performed. Thus, the following command may
be used to convert between +obj+ and +ply+, for example:
psalm -o output.ply input.obj
.Catmull-Clark subdivision
Perform three steps of Catmull-Clark subdivision, writing to an output
file:
psalm [-a cc] -n 3 -o output.ply input.ply
Ditto, but using Doo-Sabin weights:
psalm [-a cc] -n 3 -w doo-sabin -o output.ply input.ply
Ditto, but using degenerate and B-spline weights, while removing all
triangular faces from the result:
psalm [-a cc] -n 3 -w degenerate -b --remove-faces 3 -o output.ply input.ply
.Doo-Sabin subdivision
Perform three steps of Doo-Sabin subdivision, writing to +STDOUT+:
psalm -a ds -n 3 -o - input.ply
Ditto, but reading from +STDIN+:
psalm -a ds -n 3 -o -
Ditto, but using parametrical point creation and handling creases:
psalm -a ds -c -p -n 3 -o - input.ply
Using extra weights:
psalm -a ds -e W_DS_Reif_1.txt -n 3 -o - input.ply
BUGS
----
* The type of input and output files cannot be specified
separately. This is by design.
* *psalm* abuses +STDERR+ for its status reports. Otherwise,
+STDOUT+ could not be used for the real output.
AUTHOR
------
*psalm* is developed by Bastian Rieck (onfgvna@evrpx.eh; use +rot13+ to
descramble).
FILES
-----
*psalm* is shipped with several example meshes:
- +W_DS_Reif_[1-5].txt+: Extra weights from U. Reif's publication ``A
unified approach to subdivision algorithms near extraordinary
vertices''
- +Hexahedron.off+: A cube in +OFF+ format.
- +Hexahedron.ply+: A cube in +PLY+ format. The mesh is used courtesy of
http://people.sc.fsu.edu/~jburkardt[John Burkardt].
- +Hole_[3,6].ply+: A 3-sided and a 6-sided hole used for testing the
limit behaviour of the algorithms.
- +Icosahedron.ply+: An icosahedron in +PLY+ format. The mesh is used
courtesy of http://people.sc.fsu.edu/~jburkardt[John Burkardt].
- +Icosahedron.obj+: The +PLY+ file converted to +Wavefront OBJ+ format
by http://meshlab.sourceforge.net[MeshLab].
- +Klein_Bottle.obj+: A Klein bottle in +Wavefront OBJ+ format (using
quadrangles). The mesh is provided courtesy of *Pierre Alliez* by the
http://shapes.aimatshape.net[AIM@SHAPE shape repository].
- +Klein_Bottle.ply+: A triangulated version of the Klein bottle mesh,
created by http://meshlab.sourceforge.net[MeshLab].
- +Surface.obj+: A simple regular surface.
- +Tetrahedron.obj+: A tetrahedron in +OBJ+ format. The mesh is used
courtesy of http://people.sc.fsu.edu/~jburkardt[John Burkardt].
COPYRIGHT AND LICENCE
---------------------
Copyright 2010, Bastian Rieck. All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
- Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
- Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials provided
with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.