1 files changed, 98 insertions, 0 deletions
diff --git a/geom_bottleneck/README b/geom_bottleneck/README
new file mode 100644
index 0000000..8dda148
--- /dev/null
+++ b/geom_bottleneck/README
@@ -0,0 +1,98 @@
+Accompanying paper: M. Kerber, D. Morozov, A. Nigmetov. Geometry Helps To Compare Persistence Diagrams (ALENEX 2016, http://www.geometrie.tugraz.at/nigmetov/geom_dist.pdf)
+
+Bug reports can be sent to "nigmetov EMAIL SIGN tugraz DOT at".
+
+# Dependencies
+
+The program uses the ANN library (http://www.cs.umd.edu/~mount/ANN/),
+modified to support deletion of points from k-d trees.
+The modified version is contained in "bottleneck/src/ann" and "bottleneck/iclude/ANN"
+directories, there is no need to build ANN separately or include ANN's headers.
+
+Your compiler must support C++11.
+
+# Usage:
+
+1. To use a standalone command-line utility bottleneck_dist:
+
+bottleneck_dist file1 file2  [relative_error]. 
+
+If relative error is not supplied, the exact distance is computed.
+file1 and file2 must contain persistence diagrams in plain text format 
+(one point per line, empty lines are ignored, comments can be made with #):
+
+# this is how your input can look like
+x_1 y_1 # two real numbers per line
+...
+# empty lines or comments are ignored
+x_n y_n 
+
+2. To use from your code:
+
+#include "bottleneck.h"
+
+// All classes and functions are in geom_bt namespace
+// (including modified ANN's classes).
+
+std::vector<std::pair<double, double>> diagram1, diagram2;
+// any container class that supports range-for loops will do.
+// A pair represents a single point, 
+// first component = x-coordinate,
+// second component = y-coordinate.
+// ...
+// load your diagrams into diagram1, diagram2 (off-diagonal points).
+// If you data is in plain text format, you can use readDiagramPointSet function:
+
+if (!geom_bt::readDiagramPointSet("diagram1.txt", diagram1)) {
+    // something went wrong: function returns true if it successfully read the file
+    }
+
+// OK: diagram1.txt was read.
+// ...
+// to get exact distance:
+double btDist = geom_bt::bottleneckDistExact(diagram1, diagram2);
+// to get 1% approximation
+double btDistApprox = geom_bt::bottleneckDistApprox(diagram1, diagram2, 0.01);
+// ..............................................................................
+// if diagrams will be used many times, you may want to avoid copying them
+// to DiagramPointSet (which is done internally in each call to 
+bottleneckDistExact/bottleneckDistApprox) and do it yourself once. 
+// Constructor takes two iterators:
+geom_bt::DiagramPointSet ds1(diagram1.begin(), diagram1.end());
+geom_bt::DiagramPointSet ds2(diagram2.begin(), diagram2.end());
+btDist = geom_bt::bottleneckDistExact(ds1, ds2);
+btDistApprox = geom_bt::bottleneckDistApprox(ds1, ds2, 0.01);
+
+Necessary projections (diagonal points) will be added in the bottleneckDistApprox
+function.
+
+See also code in example/bottleneck_dist.cpp.
+
+# Remarks:
+
+1) If bottleneckDistApprox is called with epsilon = 0.0, it will never return.
+2) Empty diagrams are not considered as error.
+3) Modifications made in the ANN code are only valid for 2-dimensional k-d trees.
+Do not use the modified ANN files from the project folder anywhere else.
+4) You can switch to non-geometric version by using another typedef in 
+bottleneck/include/neigb_oracle.h.
+
+# License
+
+The program is distributed under Lesser GPL license.
+
+# Building
+
+CMakeLists.txt in the root directory can be used to make the library (contained 
+in bottleneck/ directory) and the command-line utility (in example/ directory)
+to compute the distance between two diagrams in txt files.
+
+On Linux/Mac:
+
+mkdir build
+cd build
+cmake ..
+make
+
+On Windows (checked with Visual Studio 2015, Community version)
+use cmake-gui to create the solution in build directory and build it with VS.