Initial commit of quartet project source code.

Author: crawforddoran

.gitignore

@@ -2,7 +2,9 @@
 *.slo
 *.lo
 *.o
-*.obj
+#*.obj
+obj/*
+obj_debug/*
 
 # Precompiled Headers
 *.gch
@@ -26,3 +28,8 @@
 *.exe
 *.out
 *.app
+quartet
+quartet_release
+view_tet
+view_tet_release
+

Makefile

@@ -0,0 +1,104 @@
+# Makefile for quartet
+#
+# This Makefile depends on a file called "Makefile.defs" which contains
+# platform-specific definitions.
+#
+# To build quartet, first run "make depend" (which relies on g++ version 3.1 or
+# higher) and then either "make" (equivalent to "make debug") or "make release".
+#
+# This is for GNU make; other versions of make may not run correctly.
+
+MAIN_PROGRAM = quartet
+SRC = predicates.cpp           \
+      geometry_queries.cpp     \
+      sdf.cpp                  \
+      trimesh.cpp              \
+      tet_mesh.cpp             \
+      feature.cpp              \
+      read_obj.cpp             \
+      tet_quality.cpp          \
+      match_features.cpp       \
+      optimize_tet_mesh.cpp    \
+      make_signed_distance.cpp \
+      make_tet_mesh.cpp        \
+      main.cpp
+
+VIEWER_PROGRAM = view_tet
+VIEWER_SRC = gluvi.cpp             \
+             view_tet.cpp          \
+             feature.cpp           \
+             read_obj.cpp          \
+             predicates.cpp        \
+             geometry_queries.cpp  \
+             tet_mesh.cpp          \
+             tet_quality.cpp
+
+
+SRC_ALL = $(SRC) $(VIEWER_SRC)
+
+include Makefile.defs
+
+# object files
+RELEASE_OBJ = $(patsubst %.cpp,obj/%.o,$(notdir $(SRC)))
+VIEWER_RELEASE_OBJ = $(patsubst %.cpp,obj/%.o,$(notdir $(VIEWER_SRC)))
+DEBUG_OBJ = $(patsubst %.cpp,obj_debug/%.o,$(notdir $(SRC)))
+VIEWER_DEBUG_OBJ = $(patsubst %.cpp,obj_debug/%.o,$(notdir $(VIEWER_SRC)))
+
+.PHONY: all
+all: debug
+
+# how to make the main target (debug mode, the default)
+$(MAIN_PROGRAM): $(DEBUG_OBJ)
+	$(LINK) $(DEBUG_LINKFLAGS) -o $@ $^ $(LINK_LIBS)
+
+# how to make the main target (release mode)
+$(MAIN_PROGRAM)_release: $(RELEASE_OBJ)
+	$(LINK) $(RELEASE_LINKFLAGS) -o $@ $^ $(LINK_LIBS)
+
+# how to make the viewer application (debug mode, the default)
+$(VIEWER_PROGRAM): $(VIEWER_DEBUG_OBJ)
+	$(LINK) $(DEBUG_LINKFLAGS) -o $@ $^ $(LINK_LIBS) $(VIEWER_LIBS)
+
+# how to make the viewer application (release mode)
+$(VIEWER_PROGRAM)_release: $(VIEWER_RELEASE_OBJ)
+	$(LINK) $(RELEASE_LINKFLAGS) -o $@ $^ $(LINK_LIBS) $(VIEWER_LIBS)
+
+# how to compile the predicates.cpp source file
+# This is different because optimization must be disabled 
+# (at least, according to the TetGen source... not sure if it's true or not)
+obj/predicates.o: src/predicates.cpp
+	$(CC) -c $(RELEASE_FLAGS) -O0 -o $@ $^
+obj_debug/predicates.o: src/predicates.cpp
+	$(CC) -c $(DEBUG_FLAGS) -O0 -o $@ $^ 
+
+
+.PHONY: release
+release: $(MAIN_PROGRAM)_release $(VIEWER_PROGRAM)_release
+
+.PHONY: debug
+debug: $(MAIN_PROGRAM) $(VIEWER_PROGRAM)
+
+# how to compile each file
+.SUFFIXES:
+obj/%.o:
+	$(CC) -c $(RELEASE_FLAGS) -o $@ $<
+obj_debug/%.o:
+	$(CC) -c $(DEBUG_FLAGS) -o $@ $<
+
+# cleaning up
+.PHONY: clean
+clean:
+	-rm -f obj/*.o $(MAIN_PROGRAM) $(VIEWER_PROGRAM) obj_debug/*.o $(MAIN_PROGRAM)_release $(VIEWER_PROGRAM)_release *core
+
+# dependencies are automatically generated
+.PHONY: depend
+depend:
+	-mkdir obj
+	-rm -f obj/depend
+	$(foreach srcfile,$(SRC_ALL),$(DEPEND) -MM src/$(srcfile) -MT $(patsubst %.cpp,obj/%.o,$(notdir $(srcfile))) >> obj/depend;)
+	-mkdir obj_debug
+	-rm -f obj_debug/depend
+	$(foreach srcfile,$(SRC_ALL),$(DEPEND) -MM src/$(srcfile) -MT $(patsubst %.cpp,obj_debug/%.o,$(notdir $(srcfile))) >> obj_debug/depend;)
+
+-include obj/depend
+-include obj_debug/depend

Makefile.defs

@@ -0,0 +1,31 @@
+# This file is included into the main Makefile, providing it with
+# local machine settings.
+# Most of it is platform-specific compilers, flags, and libraries.
+# See below examples for which variables should be defined.
+
+# For example, on a Linux PC this will likely work:
+DEPEND = g++
+CC = g++ -Wall
+RELEASE_FLAGS = -O3 -DNDEBUG -funroll-loops
+DEBUG_FLAGS = -g
+LINK = g++
+LINK_LIBS = -lm
+VIEWER_LIBS = -lGL -lGLU -lglut
+
+# Should work for Mingw (with freeglut installed)
+#DEPEND = g++
+#CC = g++ -Wall
+#RELEASE_FLAGS = -O3 -DNDEBUG -funroll-loops
+#DEBUG_FLAGS = -g
+#LINK = g++
+#LINK_LIBS = -lm
+#VIEWER_LIBS = -lopengl32 -lglu32 -lfreeglut
+
+# On Mac OS X (on a G5), this probably will work:
+#DEPEND = g++
+#CC = g++ -Wall
+#RELEASE_FLAGS = -DNDEBUG -fast # add -mcpu=7450 for a G4, or -mcpu=750 for a G3 since -fast enables 970(G5) instructions by default
+#DEBUG_FLAGS = -g
+#LINK = g++
+#LINK_LIBS = -lm -lobjc
+#VIEWER_LIBS = -framework OpenGL -framework GLUT

README

@@ -0,0 +1,188 @@
+Quartet
+*******
+
+A tetrahedral mesh generator based on Jonathon Shewchuk's isosurface stuffing 
+algorithm in combination with the A15 acute tetrahedral tile.
+
+written by:
+Robert Bridson (www.cs.ubc.ca/~rbridson)
+Crawford Doran (www.crawforddoran.com)
+--------------------------------------
+
+
+Overview
+==========
+
+Quartet converts a watertight triangle mesh into a high-quality uniform 
+tetrahedral mesh that closely approximates the geometry, up to the curvature 
+implied by the specified grid sampling (dx). Optionally, the tetrahedral mesh 
+can be warped to match sharp features on the input, and also improved by a 
+quality optimization pass.
+
+
+Building Quartet
+=================
+
+1) It may be necessary to edit Makefile.defs in order to ensure that 
+   platform-specific variables are set correctly. These include the compiler,
+   linker, and all flags associated with them, including libraries.
+2) Run 'make depend'
+3) Run 'make' and/or 'make release' ('make' is equivalent to 'make debug')
+
+
+Running Quartet
+==================
+
+Quartet is run from the command line with the following syntax:
+
+quartet <input.obj> <dx> <output.tet> [-f <feature.feat>] [-a <angle_threshold>]
+[-s <surface.obj>] [-i] [-o]
+
+- <input.obj> is the OBJ file containing the surface to be converted to a 
+  tetrahedral mesh.
+- <dx> is the grid spacing used in the isosurface stuffing algorithm. The 
+  generated tetrahedra will be approximately this size.
+- <output.tet> is a path to the file where the resulting tetrahedral mesh will 
+  be saved.
+
+The optional flags have the following effects:
+-f <features.feat>   -- The given file <features.feat> contains lists of 
+                        points and edges indicating sharp corners and ridges 
+                        in the input. The output mesh will resolve these 
+                        features as well as possible.
+-a <angle_threshold> -- Auto-detects sharp features in the input.  Edges with
+                        a dihedral angle smaller than <angle_threshold> degrees
+                        will be resolved in the output as well as possible.
+                        In addition, these features will be written to a file
+                        called 'auto.feat' (which can then be fed to the -f 
+                        option in future executions).
+-s <surface.obj>     -- The boundary of the resulting tetrahedral mesh is
+                        written to <surface.obj>.  This is largely for 
+                        convenience of visualizing the result.
+-i                   -- Intermediate stages of the mesh generation process are
+                        saved to disk in files named 'N_*_.tet' where N is the 
+                        numbering of the steps.
+-o                   -- Perform quality optimization on the resulting 
+                        tetrahedral mesh.
+
+Example inputs can be found in the 'meshes' directory.  For the inputs with
+sharp features, corresponding .feat files are provided.
+
+Example usages:
+quartet dragon.obj 0.01 dragon_01.tet -o -s dragon.obj
+quartet fandisk.obj 0.1 fandisk_1.tet -f fandisk.feat
+quartet block.obj 0.5 block_5.tet -a 110.0 -o
+
+
+Running view_tet
+==================
+
+We have included an OpenGL viewer application for visualizing resulting tet 
+meshes.  The viewer is called view_tet, and can be called with the following 
+syntax:
+
+view_tet <input.tet> [-s] [-f <features.feat>] [-p (x|y|z)<cutting-plane-pos>]*
+[-w <num_tets>]
+
+Here, <input.tet> is the TET file produced by quartet containing the tet mesh.
+
+The optional flags have the following effects:
+-s                            -- Assume that <input.tet> is actually
+                                 <input.obj> and read it in as a surface
+                                 mesh from an OBJ file.
+-f <features.feat>            -- Displays the sharp features in the file
+                                 <features.feat> alongside the mesh.
+-p (x|y|z)<cutting-plane-pos> -- Specifies a plane to cut the mesh so the
+                                 viewer can see "inside" of it.  The plane is
+                                 specified by which coordinate axis is its 
+                                 normal and its position along that axis.
+                                 Multiple planes can be specified with multiple
+                                 occurrences of this flag.
+-w num_tets                   -- Draw the mesh so that the <num_tets>
+                                 worst-quality tetrahedra are highlighted.
+
+Example usages:
+view_tet block.tet -p x0.0
+view_tet dragon.obj -s
+view_tet fandisk.tet -f fandisk.feat -w 10
+
+Once view_tet is running, the viewer can be controlled with the following 
+inputs:
+
+Shift+LeftMouseButton   -- Rotate camera
+Shift+RightMouseButton  -- Zoom camera
+Shift+MiddleMouseButton -- Pan camera
+
+
+
+Source Code overview
+======================
+
+The following files make up the quartet source:
+
+Utilities / Data Structures:
+
+util.h
+ - a bunch of small useful functions
+
+vec.h
+ - a convenience wrapper around fixed-length arrays (for vectors in 3D etc.)
+
+array3.h
+ - a convenience wrapper around STL vectors to get 3D arrays
+
+sdf.h/cpp
+ - a signed-distance-field data structure for working with level sets
+
+read_obj.h/cpp
+ - code to read in a Wavefront .OBJ file
+
+trimesh.h/cpp
+ - a simple half-edge triangle mesh data structure
+
+tet_mesh.h/cpp
+ - an index-based tetrahedral mesh data structure.  Maintains incidence 
+   relationships as necessary for fast adjacency queries.
+
+features.h/cpp
+ - Data structures representing sharp features of a triangle mesh and 
+   aggregations of those features (called FeatureSets)
+
+
+Meshing Functions:
+
+geometry_queries.h/cpp
+ - some simple and not-so-simple geometric operations needed for creating
+   signed distance functions from triangle meshes.
+   Uses Jonathan Shewchuk's robust geometric predicates code, found in 
+   predicates.cpp (http://www.cs.cmu.edu/~quake/robust.html).
+
+make_signed_distance.h/cpp
+ - code for robustly creating a fairly accurate signed distance function
+   of a watertight triangle mesh, sampled on a regular 3D grid.
+
+make_tet_mesh.h/cpp
+ - code to create a quality tetrahedral mesh of the interior of a level set
+
+tet_quality.h/cpp
+ - functions for measuring quality of tetrahedra based on various metrics
+
+match_features.h/cpp
+ - code to restore desired sharp features onto a tetrahedral mesh
+
+optimize_tet_mesh.h/cpp
+ - code to improve the overall quality of a given tetrahedral mesh.  Uses as 
+   much data from the meshing step (ie: sdf, sharp features, etc.) as possible.
+
+main.cpp
+ - quartet command-line program 
+
+
+Viewer Application:
+
+gluvi.h/cpp
+ - code for creating a simple generic OpenGL viewer application
+
+view_tet.cpp
+ - view_tet main code file for viewing tet meshes
+

TODO

@@ -0,0 +1,53 @@
+- A better build setup (eg: cmake)
+
+- Iteratively alternate between optimization and progressive feature matching
+
+- Alternative feature matching strategies
+    - Move neighbors when snapping vertex (ie: energy/spring model, 
+        displacement kernel).
+    - Snap lattice vertices to features before doing isosurface stuffing.
+    - OR Snap lattice vertices to feature endpoints (not full features) 
+        before doing isosurface stuffing.
+
+- Ensure optimality of path search
+    - Right now not guaranteed to be optimal because the tet inversion test
+      depends on the path taken to a particular vertex, not just the edges
+      and weights of the graph.
+
+- Use tet quality metrics to choose optimal paths during edge snapping
+    (instead of just minimizing the distance that vertices are moved).
+    - This may require Bellman-Ford (for negative edge weights), because
+        it's possible that snapping a vertex could actually improve the 
+        tet that it's a part of (our distance-minimizing algorithm
+        assumes that moving a vertex will always make the tet worse).
+
+- Improve mesh data structure efficiency
+    - ie: adjacency list for triangle mesh, O(1) neighbor lookup, improve 
+        efficiency of graph search in match_features
+          - Efficient TriMesh class created (half-edge data structures),
+            but it isn't applicable to the mesh we've been using that 
+            indexes into the vertices of a TetMesh.
+
+
+Less important stuff:
+- Better tet-mesh data structures
+    - More efficient traversal of edges, triangles.
+
+- Tet Quality measures
+    - Design pattern for plugging in arbitrary quality measure?
+
+- FeatureSet::consolidate()
+
+- Allow topology changes when matching features.
+    - If unable to find path between two vertices separated by two boundary
+        triangles, do an "edge split" or "edge flip" on the edge separating 
+        them.
+
+- Curvature for automatic feature detection to detect feature points.
+
+- Additional misc optimizations
+
+- Handle more mesh file formats
+    - .OFF (input, triangles)
+    - .ELE (output, tets)
+