psalm.txt

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.