Add file formats + cheatsheet to the website.

docs/css/toc.css

@@ -0,0 +1,5 @@
+label[for="toc"]+.md-nav__list .md-nav__list .md-nav__list {
+    display: none;
+}
+
+.md-nav--secondary .md-nav__list .md-nav__list { display: none }

docs/file-formats/bf.md

@@ -0,0 +1,12 @@
+.bf - bone forests
+==================
+
+------------------------------------------------------------------------
+
+A .bf file contains a "bone forest". Normally a skeleton for linear blend skinning is a "bone tree" with a single root. But this format may store multiple trees, hence a forest.
+
+Each line contains data about a vertex (joint) of the bone forest:
+
+    [weight index] [parent index] [x] [y] [z] [undocument optional data]
+
+Indices begin with 0. The weight index is -1 if the bone does not have an associated weight. The parent index is -1 for root nodes. The x,y,z coordinates are offset vectors from this joint's parent's location (for roots, an offset from the origin).

docs/file-formats/dmat.md

@@ -0,0 +1,30 @@
+.dmat - dense matrices
+======================
+
+------------------------------------------------------------------------
+
+A .dmat file contains a dense matrix in column major order. It can contain ASCII or binary data. Note that it is uncompressed so binary only reduces the file size by 50%. But writing and reading binary is usually faster. In MATLAB, binary is almost 100x faster.
+
+ASCII
+-----
+
+The first line is a header containing:
+
+    [#cols] [#rows]
+
+Then the coefficients are printed in column-major order separated by spaces.
+
+Binary
+------
+
+Binary files will also contain the ascii header, but it should read:
+
+    0 0
+
+Then there should be another header containing the size of the binary part:
+
+    [#cols] [#rows]
+
+Then coefficients are written in column-major order in Little-endian 8-byte double precision IEEE floating point format.
+
+**Note:** Line endings must be `'\n'` aka `char(10)` aka line feeds.

docs/file-formats/index.md

@@ -0,0 +1,45 @@
+libigl file formats
+===================
+
+- [.bf](./bf.html) ASCII files for representing skeletal bone "forests"
+- [.dmat](./dmat.html) uncompressed ASCII/binary files for dense matrices
+- *.ele* Element (triangle or tet) list. This format comes in similar flavors: [tetgen's](http://tetgen.berlios.de/fformats.ele.html), [stellar's](http://www.cs.berkeley.edu/~jrs/stellar/#fileformats), and [triangle's](https://www.cs.cmu.edu/~quake/triangle.ele.html). The formats of TetGen and stellar are identical upto conventions on index ordering and number of allowed attributes (unverified).
+- [.face](http://wias-berlin.de/software/tetgen/fformats.face.html) TetGen's file format for simplicial facets.
+- [.mesh](http://www.ann.jussieu.fr/frey/publications/RT-0253.pdf#page=33) Medit's triangle surface mesh + tetrahedral volume mesh file format, see page 33, section 7.2.1
+- *.node* List of points (vertices). Described identically (upto accepted dimensions, use of attributes and boundary markers) by [Triangle](https://www.cs.cmu.edu/~quake/triangle.node.html), [TetGen](http://tetgen.berlios.de/fformats.node.html), and [Stellar](http://www.cs.berkeley.edu/~jrs/stellar/#fileformats).
+- [.off](http://wias-berlin.de/software/tetgen/fformats.off.html) Geomview's polyhedral file format
+- [.obj](http://en.wikipedia.org/wiki/Wavefront_.obj_file#File_format) Wavefront object file format. Usually unsafe to assume anything more than vertex positions and triangle indices are supported
+- [.ply](http://en.wikipedia.org/wiki/PLY_%28file_format%29) Polygon File Format, supporting ASCII and binary encoding
+- [.png](https://en.wikipedia.org/wiki/Portable_Network_Graphics) Portable Network Graphics image file. IGLLIB (in the libiglpng extra) supports png image files via the [yimg](https://github.com/yig/yimg) library. Alpha channels and compression are supported.
+- *.poly* Piecewise-linear complex. This format comes in many similar but importantly different flavors: [triangle's](https://www.cs.cmu.edu/~quake/triangle.poly.html), [tetgen's](http://tetgen.berlios.de/fformats.poly.html), [pyramid/SVR's](http://sparse-meshing.com/svr/0.2.1/format-poly.html)
+- [.rbr](./rbr.html) ASCII files for saving state of ReAntTweakBar
+- [.stl](http://en.wikipedia.org/wiki/STL_(file_format)) 3D Systems'CAD and 3D printing mesh file format. ASCII and binary versions.
+- [.tga](http://en.wikipedia.org/wiki/Truevision_TGA) Truevision TGA or TARGA image file format. IGLLIB supports only very basic reading and writing RGB/RGBA files without colormaps and (unverified) run-length compression.
+- [.tgf](./tgf.html) ASCII files for representing control handle graphs
+- [.wrl](http://en.wikipedia.org/wiki/VRML#WRL_File_Format) VRML (Virtual Reality Modeling Language) file format for 3D scenes.
+- [.xml](./xml.html) XMLSerializer's file format containing the serialization of object data structures.
+
+
+### Triangle mesh file format performance
+
+[.obj](http://en.wikipedia.org/wiki/Wavefront_.obj_file#File_format) and [.off](http://tetgen.berlios.de/fformats.off.html) file formats support meshes with arbitrary polygon degrees. However, often we are only working with triangle meshes. Further, .obj files do not have useful headers revealing the number of elements. For triangle meshes, .off and .obj are inferior file formats to the [.mesh](http://www.ann.jussieu.fr/frey/publications/RT-0253.pdf#page=33) file format. The current (version 0.1.6) IO functions for these file formats perform as follows for reading and writing a 300,000 triangle mesh:
+
+    writeOBJ:  1.33742 secs
+    writeOFF:  0.510111 secs
+    writeMESH: 0.218139 secs
+
+    readOBJ:   1.3782 secs
+    readOFF:   0.691496 secs
+    readMESH:  0.242315 secs
+
+This reveals that .mesh is 6.5x faster than .obj and about 2.5x faster than .off.
+
+While .obj files support normals, it is typically much faster to (re)compute normals from the geometry using `per_face_normals`, `per_vertex_normals`, `per_corner_normals` than to read and write them to files.
+
+It gets even better if you're willing to use a nonstandard format. If your triangle mesh is in (`V`,`F`) then you can read and write those variables as dense matrices of doubles to [.dmat](./dmat.html) uncompressed **binary** files. This not only ensures perfect precision but also big speed ups. On that same 300,000 triangle mesh, .dmat achieves:
+
+    writeDMAT: 0.0384338 secs
+
+    readDMAT:  0.0117921 secs
+
+This reveals that binary .dmat files are 34x/116x faster at writing and reading than .obj and a hefty 5x/20x over .mesh. In this case it may pay to compute normals once into `N` and also read and write it to a .dmat file.

docs/file-formats/rbr.md

@@ -0,0 +1,16 @@
+.rbr - ReAntTweakbar state file
+===============================
+
+------------------------------------------------------------------------
+
+An .rbr file contains the saved values of the ReAntTweakBar class. It is used to load and save variables (and states specified via callbacks) stored in an AntTweakBar GUI.
+
+Each line contains the name of the AntTweakBar item, the type of item and the value as a string:
+
+    [name]: [type] [value]
+
+As per AntTweakBar's own advice, names should not contain spaces. Names should also not contain colons (`:`). An example of a line looks like:
+
+    my_rotation: TW_TYPE_QUAT4 0.0111272 -0.00101157 0.00648534 -0.999917
+
+Not all AntTweakBar types are currently supported. See `igl/ReAntTweakbar.h` for an up-to-date list of supported types.

docs/file-formats/tgf.md

@@ -0,0 +1,20 @@
+.tgf - control handle graphs
+============================
+
+------------------------------------------------------------------------
+
+A .tgf file contains a graph of describing a set of control handles/structures: point controls, bones of a skeleton and cages made of "cage edges".
+
+The first part of the file consists of lines regarding each vertex of the graph. Each line reads:
+
+    [index] [x] [y] [z] [undocument optional data]
+
+Indices begin with 1 and should proceed in order. Then there should be a line with a sole:
+
+    #
+
+The next section concerns the edges of the graph. Each line corresponds to an edge:
+
+    [source index] [dest index] [is bone] [is pseudo-edge] [is cage edge] [undocument other data]
+
+Bone edges trump pseudo and cage edges.