===============================================================================

                             SpinXForm v0.1

                              Keenan Crane
                             August 16, 2011

===============================================================================


--------------
0. CONTENTS
--------------

  0. CONTENTS
  1. ABOUT
  2. DEPENDENCIES
  3. BUILDING
  4. TESTING
  5. USAGE
   A. INPUTS
   B. COMMAND LINE MODE
   C. INTERACTIVE MODE
  6. FILE FORMATS
   A. Wavefront OBJ
   B. Truevision TGA
  7. SOURCE CODE
  8. LICENSE


-----------
1. ABOUT
-----------

This archive contains a C++ implementation of an algorithm for computing
conformal transformations of polygon meshes.  It is based on the paper

  K. Crane, U. Pinkall, and P. Schroeder, "Spin Transformations of
  Discrete Surfaces," ACM Transactions on Graphics (SIGGRAPH) 2011.

The basic functionality is to take a manifold, triangulated mesh (without
boundary) plus a grayscale image map as input, and produce a new mesh
with the same connectivity but modified vertex positions.  Triangles in the new
mesh will have nearly the same angles and aspect ratios as those from the
original mesh, but with curvature that differs by the amount specified in the
input image.  (See the paper above for more details.)  In the GUI version of
SpinXForm the input image is reloaded from disk every time the deformation is
updated.  This way the user can "paint" a curvature change in some external
program (such as Adobe Photoshop) and immediately view the resulting effect
on the surface.

PLEASE NOTE that this is research code and has not been tested extensively.
Luckily, it was written by a friendly researcher who is happy to help you out
via email in your times of trouble: keenan@cs.caltech.edu

Thanks to Robert Bridson for providing the preconditioned conjugate gradient
code (found in the "pcg" subdirectory).


------------------
2. DEPENDENCIES
------------------

In order to make the code as easy as possible to build, several distributions
are available, each with an increasing number of dependencies:

  -spinxform_nodep  -- no dependencies; should build with any C++ compiler
  -spinxform_opengl -- depends only on OpenGL and GLUT
  -spinxform_fast   -- depends on OpenGL, GLUT, and SuiteSparse

The first two distributions are easiest to build, but also exhibit suboptimal
performance because they use a simple conjugate gradient solver (with only a
diagonal preconditioner).  The "fast" version depends on Tim Davis' CHOLMOD
cholesky factorization library:

http://www.cise.ufl.edu/research/sparse/cholmod/

which in turn depends on SuiteSparse and METIS:

http://www.cise.ufl.edu/research/sparse/SuiteSparse/
http://glaros.dtc.umn.edu/gkhome/views/metis

as well as some (hopefully optimized!) BLAS/LAPACK implementation.  On
UNIX-like systems you will probably end up needing the libraries

  bamd.a
  libcamd.a
  libcolamd.a
  libccolamd.a
  libcholmod.a

from SuiteSparse and

  libmetis.a

from METIS.  If you want to avoid compiling all of SuiteSparse, you can simply
type "make" in each of the appropriate Lib directories (e.g., AMD/Lib) after
setting up UFConfig and copying the resulting library (.a) files to
/usr/local/bin or some other appropriate place.  Further instructions on
building SuiteSparse and its dependencies can be found on the SuiteSparse home
page.

On Mac OS X, the easiest way to link to an efficient BLAS
implementation is by adding the framework

  -framework Accelerate

On other platforms, Kazushige Goto's GotoBLAS library is a popular choice:

  http://www.tacc.utexas.edu/tacc-projects/gotoblas2/


--------------
3. BUILDING
--------------

On UNIX-like systems, you should simply need to type

  make

at the command line in the root install directory.  This should build the
command-line utility "spinxform."  On Windows it may be simplest to install Cygwin:

  http://www.cygwin.com/

which includes an implementation of the GNUMake system which can be used to
execute the Makefiles for SpinXForm, SuiteSparse, and METIS.  If you need to build
code that does not depend on Cygwin DLLs, MINGW is an option:

  http://www.mingw.org/

Finally, a VisualStudio project has been included, but uses only the (slower)
conjugate gradient solver.  For compiling SuiteSparse, METIS, or BLAS
with VisualStudio, you may want to take a look at

  http://matrixprogramming.com/2008/05/umfpack-vc


-------------
4. TESTING
-------------

To test that SpinXForm is working properly, type

   make test

at the command line.  Results produced by SpinXForm will be checked against
reference solutions included in th distribution.  Depending on output
formatting and the libraries used for BLAS, linear solver, etc., your result
may not match the reference solution exactly, but it should be pretty close.


-----------
5. USAGE
-----------

SpinXForm can be executed from the command line (see Section 5B), by running
SpinXForm.app (on Mac OS X), or by running SpinXForm.bat (Windows).  On Mac OS
X the user will be prompted for the mesh file and then the corresponding image
file.  In Windows, inputs are specified by editing SpinXForm.bat.

5A. INPUTS
----------

Meshes should be encoded as Wavefront OBJ files; images should be encoded as
grayscale, 8 bits per pixel Truevision TGA files.  (See Section 6 for more
information on file formats.)  

The input image file represents the requested change in curvature as grayscale
values.  A value of 128 (~50%) represents no change; values greater than 128
indicates an increase in curvature, and values less than 128 indicate a
decrease.

** Note: the input mesh MUST have texture coordinates! **

Values are mapped from the image to the surface using texture coordinates in
the range [0,1] x [0,1].  This means that the image is treated as a SQUARE
image, independent of its actual dimensions.


5B. COMMAND LINE MODE
---------------------

The SpinXForm executable takes two input arguments and one optional output argument:

   spinxform mesh.obj image.tga [result.obj]

These arguments can be specified on the command line or by creating a .BAT file
in Windows.  Specifying an output argument runs SpinXForm in batch mode: rather
than displaying the GUI, results are simply written to the command line.


5C. INTERACTIVE MODE
--------------------

The graphical user interface (GUI) displays the current state of the mesh.  The
view is controlled by clicking and dragging anywhere in the main window.
Right-clicking brings up the main menu with the following options:

  [space] Transform  - reload the image from disk and update the deformation
      [r] Reset Mesh - restore the surface to its original configuration
      [w] Write Mesh - write the transformed mesh to "result.obj"
      [q] Exit       - quit SpinXForm

The "view" submenu contains the following options:

  [s] Smooth Shaded  - draws the surface using smooth shading
  [f] Wireframe      - draws the surface as flat-shaded triangles with outlined edges
  [e] QC Error       - displays the per-face deviation from original triangle shape
  [p] Rho            - displays the requested change in curvature
  [t] Textured       - displays a checkerboard pattern
  [-] Shrink Texture - decreases the size of the checkerboard pattern
  [+] Grow Texture   - increases the size of the checkerboard pattern

Each of these options has a keyboard equivalent, indicated in square brackets [].
Note that the checkerboard pattern will look good only if the initial texture
coordinates come from something like a conformal parameterization of the surface.


------------------
6. FILE FORMATS
------------------

6A. Wavefront OBJ
-----------------

A Wavefront OBJ file specifies vertex and face data for a polygonal surface
mesh, as well as vertex texture coordinates.  Vertex data is specified by lines
of the form

  v [x] [y] [z]

where [x], [y], and [z] are x, y and z vertex coordinates.  Texture coordinates
are similarly specified via

  vt [u] [v]

Face data is specified by lines of the form

  f [i1]/[j1] [i2]/[j2] ... [in]/[jn]

where [i1], [i2], etc., are 1-based indices into the vertex list and [j1],
j[2], etc., are indices into the list of texture coordinates.  For
instance, the following data specifies a simple mesh of a square
consisting of two triangles:

  v 0 0 0
  v 1 0 0
  v 1 1 0
  v 0 1 0
  vt 0 0
  vt 1 0
  vt 1 1
  vt 0 1
  f 1/1 3/3 4/4
  f 1/1 2/2 3/3

Note that SpinXForm supports only meshes where all faces are triangles.  Vertex
normals are ignored.

6B. Truevision TGA
------------------

TGA is a very simple bitmap image format consisting of a fixed amount of header
data followed by a chunk of color data.  A more detailed specification can be
found at

http://en.wikipedia.org/wiki/Truevision_TGA

Note that SpinXForm supports only uncompressed grayscale images at 8 bits per pixel.


-----------------
7. SOURCE CODE
-----------------

As an alternative to the command-line utility, you can of course interface with
the code directly.  Basic usage looks like:

  Mesh mesh;
  Image image;
  mesh.read( "mesh.obj" );                  // read a polygon mesh
  image.read( "image.tga" );                // read an image
  const double scale = 5.;                  // set the magnitude of rho
  mesh.setCurvatureChange( image, scale );  // set the values of rho
  mesh.updateDeformation();                 // compute the solution
  mesh.write( "result.obj" );               // write the transformed surface


-------------
8. LICENSE
-------------

SpinXForm is covered by the following free software license based on the 2-clause
BSD license.  This license is compatible with most other free software licenses,
including the GNU General Public License.

*
* Copyright 2011 Keenan Crane. All rights reserved.
* 
* Redistribution and use in source and binary forms, with or without modification,
* are permitted provided that the following conditions are met:
* 
* 1. Redistributions of source code must retain the above copyright notice, this
*    list of conditions and the following disclaimer.
* 2. 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 AUTHOR ``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 FREEBSD PROJECT 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.
* 
* The views and conclusions contained in the software and documentation are those
* of the author and should not be interpreted as representing official policies,
* either expressed or implied, of any other person or institution.
*