psalm - pretty subdivision algorithms on meshes
psalm [arguments] [file]
psalm is a mesh compiler, using meshes in several data formats
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
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
example.ply without specifying an output file results in
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.
-a, --algorithm <algorithm>
Selects the subdivision algorithm to use on the input mesh. Valid values for algorithm are:
-o, --output <file>
Sets output file. If not present,
STDOUTwill be used. A single dash will be interpreted as
-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
Prints statistics and progress bars to
Shows a help screen.
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.
Algorithms try to subdivide crease and boundary edges whenever this is possible.
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:
-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.
--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.
By default, no subdivision is performed. Thus, the following command may
be used to convert between
ply, for example:
psalm -o output.ply input.obj
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
Perform three steps of Doo-Sabin subdivision, writing to
psalm -a ds -n 3 -o - input.ply
Ditto, but reading from
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
The following packages are required for building libpsalm:
- Recent version of cmake
The type of input and output files cannot be specified separately. This is by design.
STDERRfor its status reports. Otherwise,
STDOUTcould not be used for the real output.
psalm is developed by Bastian Rieck (firstname.lastname@example.org; use
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
Hexahedron.ply: A cube in
PLYformat. The mesh is used courtesy of 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
PLYformat. The mesh is used courtesy of John Burkardt.
PLYfile converted to
Wavefront OBJformat by MeshLab.
Klein_Bottle.obj: A Klein bottle in
Wavefront OBJformat (using quadrangles). The mesh is provided courtesy of Pierre Alliez by the AIM@SHAPE shape repository.
Klein_Bottle.ply: A triangulated version of the Klein bottle mesh, created by MeshLab.
Surface.obj: A simple regular surface.
Tetrahedron.obj: A tetrahedron in
OBJformat. The mesh is used courtesy of 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.