3DFaces
/
libigl_Martin


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327328329330331332333334335336337338339340341342343344345346347348349350351352353354355356357358359360361362363364365366367368369370371372373374375376377378379380381382383384385386387388389390391392393394395396397398399400401402403404405406407408409410411412413414415416417418419420421422423424425426427428429430431432433434435436437438439440441442443444445446447448449450451452453454455456457458459460461462463464465466467468469470471472
							<!DOCTYPE html>
<html>
<head>
	<meta charset="utf-8"/>
	<title>libigl</title>
	<meta name="author" content="Alec Jacobson and Daniele Panozzo and others"/>
	<link type="text/css" rel="stylesheet" href="../tutorial/style.css"/>
<script type='text/javascript' src='http://cdn.mathjax.org/mathjax/latest/MathJax.js?config=TeX-AMS-MML_HTMLorMML'></script>
<link rel='stylesheet' href='http://yandex.st/highlightjs/7.3/styles/default.min.css'>
<script src='http://yandex.st/highlightjs/7.3/highlight.min.js'></script>
<script>hljs.initHighlightingOnLoad();</script>
</head>
<body>

<h1 id="compilinglibiglasastaticlibrary">Compiling libigl as a static library</h1>

<blockquote>
<p>Warning: compiling libigl as a static library is considerably more difficult
than using it as a header-only library (see <code>../README.md</code> instead). Do it
only if you are experienced with C++ and you want to improve your compilation
times.</p>
</blockquote>

<p>Libigl is developed most often on Mac OS X, though has current users in Linux
and Windows.</p>

<h3 id="linuxmacosxcygwin">Linux/Mac OS X/Cygwin</h3>

<p>Libigl may also be compiled to a static library. This is advantageous when
building a project with libigl, since when used as an header-only library can
slow down compile times.</p>

<p>To build the entire libigl library producing <code>lib/libigl.a</code>, issue:</p>

<pre><code>cd build
make lib
</code></pre>

<p>You may need to edit <code>Makefile.conf</code> accordingly. Best to give yourself an
<code>IGL_USERNAME</code> and add a custom install suite for yourself. Then you can enable
appropriate extras.</p>

<h4 id="extras">Extras</h4>

<p>Once you&#8217;ve set up an <code>IGL_USERNAME</code> and enabled extras within Makefile.conf.
You can build the extra libraries (into <code>lib/ligiglpng.a</code>, <code>lib/libiglmatlab.a</code>,
<code>lib/libigltetgen.a</code>, <code>lib/libiglmosek.a</code>, etc.) by issuing:</p>

<pre><code>cd build
make extras
</code></pre>

<h4 id="examples">Examples</h4>

<p>You can make a slew of examples by issuing:</p>

<pre><code>cd build
make examples
</code></pre>

<h4 id="external">External</h4>

<p>Finally there are a number of external libraries that we include in
<code>./external/</code> because they are either difficult to obtain or they have been
patched for easier use with libigl. Please see the respective readmes in those
directories.</p>

<h5 id="installinganttweakbar">Installing AntTweakBar</h5>

<p>To build the a static AntTweakBar library on Mac OS X issue:</p>

<pre><code>cd external/AntTweakBar/src
make -f Makefile.osx.igl
</code></pre>

<h5 id="installingtetgen">Installing Tetgen</h5>

<p>To build the tetgen library and executable on Mac OS X issue:</p>

<pre><code>cd external/tetgen
make clean
rm -f obj/*.o
make -f Makefile.igl tetgen
rm -f obj/*.o
make -f Makefile.igl tetlib
</code></pre>

<h5 id="installingmedit">Installing medit</h5>

<p>To build the igl version of the medit executable on Mac OS X issue:</p>

<pre><code>cd external/medit
make -C libmesh
make -f Makefile.igl medit
</code></pre>

<h5 id="installingembree2.0">Installing Embree 2.0</h5>

<p>To build the embree library and executables on Mac OS X issue:</p>

<pre><code>cd external/embree
mkdir build
cd build
cmake ..
# Or using a different compiler
#cmake .. -DCMAKE_C_COMPILER=/opt/local/bin/gcc -DCMAKE_CXX_COMPILER=/opt/local/bin/g++
make
# Could also install embree to your root, but libigl examples don't expect
# this
#sudo make install
</code></pre>

<h5 id="installingtinyxml2">Installing tinyxml2</h5>

<p>To build the a static tinyxml2 library on Mac OS X issue:</p>

<pre><code>cd external/tinyxml2
cmake .
make
</code></pre>

<h5 id="installingyimg">Installing YImg</h5>

<p>To build the a static YImg library on Mac OS X issue:</p>

<pre><code>cd external/yimg
make
</code></pre>

<p>You may need to install libpng. Systems with X11 might find this already
installed at <code>/usr/X11/lib</code>.</p>

<h3 id="windowsexperimental">Windows (Experimental)</h3>

<p>To build a static library (.lib) on windows, open Visual Studio 2010.</p>

<ul>
<li>New &gt; Project &#8230;</li>
<li>Visual C++ &gt; Win32</li>
<li>Win32 Console Application</li>
<li>Name: libiglVisualStudio</li>
<li>Uncheck &#8220;Create directory for solution&#8221;</li>
<li>Then hit OK, and then Next</li>
<li>Check &#8220;Static Library&#8221;</li>
<li>Uncheck &#8220;Precompiled headers&#8221;</li>
<li>Add all include/igl/*.cpp to the sources directory</li>
<li>Add all include/igl/*.h to the headers directory</li>
<li>Open Project &gt; libigl Properties&#8230;</li>
<li>Add the path to eigen3 to the include paths</li>
<li>Change the target name to libigl</li>
<li>Build and pray (this should create libigl.lib</li>
</ul>

<p><a href="http://msdn.microsoft.com/en-us/library/ms235627(v=vs.80).aspx">Source</a></p>

<h2 id="examples">Examples</h2>

<p>To get started, we advise that you take a look at a few examples:</p>

<pre><code>./examples/hello-world/

./examples/meshio/

./examples/basic-topology/

./examples/ReAntTweakBar/
</code></pre>

<h2 id="extras">Extras</h2>

<p>Libigl compartmentalizes dependences via its organization into a <em>main</em> libigl
library and &#8220;extras.&#8221;</p>

<h3 id="bbw">bbw</h3>

<p>This library extra contains functions for computing Bounded Biharmonic Weights, can
be used with and without the <a href="#mosek">mosek</a> extra via the <code>IGL_NO_MOSEK</code>
macro.</p>

<h3 id="boost">boost</h3>

<p>This library extra utilizes the graph functions in the boost library for find
connected components and performing breadth-first traversals.</p>

<h3 id="cgal">cgal</h3>

<p>This library extra utilizes CGAL&#8217;s efficient and exact intersection and
proximity queries.</p>

<h3 id="embree">embree</h3>

<p>This library extra utilizes embree&#8217;s efficient ray tracing queries.</p>

<h3 id="matlab">matlab</h3>

<p>This library extra provides support for reading and writing <code>.mat</code> workspace
files, interfacing with Matlab at run time and compiling mex functions.</p>

<h3 id="mosek">mosek</h3>

<p>This library extra utilizes mosek&#8217;s efficient interior-point solver for
quadratic programs.</p>

<h3 id="png">png</h3>

<p>This library extra uses <code>libpng</code> and <code>YImage</code> to read and write <code>.png</code> files.</p>

<h3 id="svd3x3">svd3x3</h3>

<p>This library extra implements &#8220;as-rigid-as-possible&#8221; (ARAP) deformation
techniques using the fast singular value decomposition routines
written specifically for 3x3 matrices to use <code>SSE</code> intrinsics. This extra can
still be compiled without sse support and support should be determined
automatically at compile time via the <code>__SSE__</code> macro.</p>

<h3 id="tetgen">tetgen</h3>

<p>This library extra provides a simplified wrapper to the tetgen 3d tetrahedral meshing
library.</p>

<h3 id="viewer">viewer</h3>

<p>This library extra utilizes glfw and glew to open an opengl context and launch
a simple mesh viewer.</p>

<h3 id="xml">xml</h3>

<p>This library extra utilizes tinyxml2 to read and write serialized classes
containing Eigen matrices and other standard simple data-structures.</p>

<h2 id="development">Development</h2>

<p>Further documentation for developers is listed in
<a href="../style_guidelines.html">style_guidelines.html</a>.</p>

<h2 id="license">License</h2>

<p>See <code>LICENSE.txt</code></p>

<h2 id="zipping">Zipping</h2>

<p>Zip this directory without .git litter and binaries using:</p>

<pre><code>git archive -prefix=libigl/ -o libigl.zip master
</code></pre>

<h2 id="explicitspecializationoftemplatedfunctions">Explicit specialization of templated functions</h2>

<p>Special care must be taken by the developers of each function and
class in the libigl library that uses C++ templates. If this function
is intended to be compiled into the statically linked libigl library
then function is only compiled for each <i>explicitly</i> specialized
declaration. These should be added at the bottom of the corresponding
.cpp file surrounded by a</p>

<pre><code>#ifdef IGL_STATIC_LIBRARY
</code></pre>

<p>Of course, a developer may not know ahead of time which
specializations should be explicitly included in the igl static lib.
One way to find out is to add one explicit specialization for each
call in one&#8217;s own project. This only ever needs to be done once for
each template.</p>

<p>The process is somewhat mechanical using a linker with reasonable error
output.</p>

<p>Supposed for example we have compiled the igl static lib, including the
cat.h and cat.cpp functions, without any explicit instanciation. Say
using the makefile in the <code>libigl</code> directory:</p>

<pre><code>cd $LIBIGL
make
</code></pre>

<p>Now if we try to compile a project and link against it we may get
an error like:</p>

<pre><code>Undefined symbols for architecture x86_64:
&quot;Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; igl::cat&lt;Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; &gt;(int, Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; const&amp;, Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; const&amp;)&quot;, referenced from:
uniform_sample(Eigen::Matrix&lt;double, -1, -1, 0, -1, -1&gt; const&amp;, Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; const&amp;, int, double, Eigen::Matrix&lt;double, -1, -1, 0, -1, -1&gt;&amp;)in Skinning.o
&quot;Eigen::SparseMatrix&lt;double, 0, int&gt; igl::cat&lt;Eigen::SparseMatrix&lt;double, 0, int&gt; &gt;(int, Eigen::SparseMatrix&lt;double, 0, int&gt; const&amp;, Eigen::SparseMatrix&lt;double, 0, int&gt; const&amp;)&quot;, referenced from:
covariance_scatter_matrix(Eigen::Matrix&lt;double, -1, -1, 0, -1, -1&gt; const&amp;, Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; const&amp;, ArapEnergy, Eigen::SparseMatrix&lt;double, 0, int&gt;&amp;)in arap_dof.o
arap_rhs(Eigen::Matrix&lt;double, -1, -1, 0, -1, -1&gt; const&amp;, Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; const&amp;, ArapEnergy, Eigen::SparseMatrix&lt;double, 0, int&gt;&amp;)in arap_dof.o
</code></pre>

<p>This looks like a mess, but luckily we don&#8217;t really need to read it
all. Just copy the first part in quotes</p>

<pre><code>Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; igl::cat&lt;Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; &gt;(int, Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; const&amp;, Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; const&amp;)
</code></pre>

<p>, then append it
to the list of explicit template specializations at the end of
<code>cat.cpp</code> after the word
<strong>template</strong> and followed by a semi-colon.
Like this:</p>

<pre><code>#ifdef IGL_STATIC_LIBRARY
// Explicit template specialization
template Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; igl::cat&lt;Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; &gt;(int, Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; const&amp;, Eigen::Matrix&lt;int, -1, -1, 0, -1, -1&gt; const&amp;);
#endif
</code></pre>

<p>Then you must recompile the IGL static library.</p>

<pre><code>cd $LIBIGL
make
</code></pre>

<p>And try to compile your project again, potentially repeating this
process until no more symbols are undefined.</p>

<p><code>It may be useful to check that you code compiles with
no errors first using the headers-only version to be sure that all errors are from missing template
specializations.</code></p>

<p>If you&#8217;re using make then the following command will
reveal each missing symbol on its own line:</p>

<pre><code>make 2&gt;&amp;1 | grep &quot;referenced from&quot; | sed -e &quot;s/, referenced from.*//&quot;
</code></pre>

<p>Alternatively you can use the <code>autoexplicit.sh</code> function
which (for well organized .h/.cpp pairs in libigl) automatically
create explicit instanciations from your compiler&#8217;s error messages.
Repeat this process until convergence:</p>

<pre><code>cd /to/your/project
make 2&gt;$LIBIGL/make.err
cd $LIBIGL
cat make.err | ./autoexplicit.sh
make clean
make
</code></pre>

<h3 id="benefitsofstaticlibrary">Benefits of static library</h3>

<ul>
<li><strong>Faster compile time</strong>: Because the libigl library
is already compiled, only the new code in ones project must be
compiled and then linked to IGL. This means compile times are
generally faster.</li>
<li><strong>Debug or optimized</strong>: The IGL static
library may be compiled in debug mode or optimized release mode
regardless of whether one&#8217;s project is being optimized or
debugged.</li>
</ul>

<h3 id="drawbacksofstaticlibrary">Drawbacks of static library</h3>

<ul>
<li><strong>Hard to use templates</strong>: Special
care</a> (by the developers of the library) needs to be taken when
exposing templated functions.</li>
</ul>

<h1 id="compressed.h.cpppair">Compressed .h/.cpp pair</h1>

<p>Calling the script:</p>

<pre><code>scripts/compress.sh igl.h igl.cpp
</code></pre>

<p>will create a single header <code>igl.h</code> and a single cpp file <code>igl.cpp</code>.</p>

<p>Alternatively, you can also compress everything into a single header file:</p>

<pre><code>scripts/compress.sh igl.h
</code></pre>

<h3 id="benefitsofcompressed.h.cpppair">Benefits of compressed .h/.cpp pair</h3>

<ul>
<li><strong>Easy incorporation</strong>: This can be easily incorporated
 into external projects.</li>
</ul>

<h3 id="drawbacksofcompressed.h.cpppair">Drawbacks of compressed .h/.cpp pair</h3>

<ul>
<li><p><strong>Hard to debug/edit</strong>: The compressed files are
 automatically generated. They&#8217;re huge and should not be edited. Thus
 debugging and editting are near impossible.</p></li>
<li><p><strong>Compounded dependencies</strong>:
 An immediate disadvantage of this
 seems to be that even to use a single function (e.g.
 <code>cotmatrix</code>), compiling and linking against
 <code>igl.cpp</code> will require linking to all of <code>libigl</code>&#8217;s
 dependencies (<code>OpenGL</code>, <code>GLUT</code>,
 <code>AntTweakBar</code>, <code>BLAS</code>). However, because all
 depencies other than Eigen should be encapsulated between
 <code>#ifndef</code> guards (e.g. <code>#ifndef IGL_NO_OPENGL</code>, it
 is possible to ignore certain functions that have such dependencies.</li>
 <li><strong>Long compile:</strong> Compiling <code>igl.cpp</code> takes a long time and isn&#8217;t easily parallelized (no <code>make -j12</code> equivalent).</li>
 </ul></p></li>
</ul>

<p>Here&#8217;s a tiny test example using <code>igl.h</code> and <code>igl.cpp</code>. Save the following in <code>test.cpp</code>:</p>

<pre><code>#include &lt;igl.h&gt;
#include &lt;Eigen/Core&gt;

int main(int argc, char * argv[])
{
Eigen::MatrixXd V;
Eigen::MatrixXi F;
return (argc&gt;=2 &amp;amp;&amp;amp; igl::read_triangle_mesh(argv[1],V,F)?0:1);
}
</code></pre>

<p>Then compile <code>igl.cpp</code> with:</p>

<pre><code>g++ -o igl.o -c igl.cpp -I/opt/local/include/eigen3 -DIGL_NO_OPENGL -DIGL_NO_ANTTWEAKBAR
</code></pre>

<p>Notice that we&#8217;re using <code>-DIGL_NO_OPENGL -DIGL_NO_ANTTWEAKBAR</code> to disable any libigl dependencies on OpenGL and AntTweakBar.</p>

<p>Now compile <code>test.cpp</code> with:</p>

<pre><code>g++ -g -I/opt/local/include/eigen3/ -I/usr/local/igl/libigl/ -L/usr/local/igl/libigl/ -ligl -DIGL_NO_OPENGL -DIGL_NO_ANTTWEAKBAR -o test
</code></pre>

<p>Try running it with:</p>

<pre><code>./test path/to/mesh.obj
</code></pre>

<p>The following bash one-liner will find all source files that contain the string <code>OpenGL</code> but don&#8217;t contain and <code>IGL_NO_OPENGL</code> guard:</p>

<pre><code>grep OpenGL `grep -L IGL_NO_OPENGL include/igl/*`
</code></pre>

<h3 id="optional">Optional</h3>

<ul>
<li>OpenGL (disable with <code>IGL_NO_OPENGL</code>)

<ul>
<li>OpenGL &gt;= 4 (enable with <code>IGL_OPENGL_4</code>)</li>
</ul></li>
<li>AntTweakBar (disable with <code>IGL_NO_ANTTWEAKBAR</code>) Last tested 1.16 (see
 <code>libigl/external/AntTweakBar</code>)</li>
<li>GLEW Windows and Linux</li>
<li>OpenMP</li>
<li>libpng libiglpng extra only</li>
<li>Mosek libiglmosek extra only</li>
<li>Matlab libiglmatlab extra only</li>
<li>boost libiglboost, libiglcgal extra only</li>
<li>SSE/AVX libiglsvd3x3 extra only</li>
<li>CGAL libiglcgal extra only

<ul>
<li>boost</li>
<li>gmp</li>
<li>mpfr</li>
</ul></li>
<li>CoMiSo libcomiso extra only</li>
</ul>

<h3 id="optionalincludedinexternal">Optional (included in external/)</h3>

<ul>
<li>TetGen libigltetgen extra only</li>
<li>Embree libiglembree extra only</li>
<li>tinyxml2 libiglxml extra only</li>
<li>glfw libviewer extra only</li>
<li>LIM liblim extra only</li>
</ul>

</body>
</html>