Document utilies in README files using Markdown + move/rename some utilities

Only missing doc for now: Garland_heckbert

git-svn-id: svn+ssh://scm.gforge.inria.fr/svnroot/gudhi/branches/add_utils_in_gudhi_v2@2752 636b058d-ea47-450e-bf9e-a15bfbe3eedb

Former-commit-id: 7ba0113762b6622130835dc9e372acfae29c2db8

1 files changed, 131 insertions, 0 deletions

diff --git a/src/Alpha_complex/utilities/README b/src/Alpha_complex/utilities/README
new file mode 100644
index 00000000..30e1b187
--- /dev/null
+++ b/src/Alpha_complex/utilities/README
@@ -0,0 +1,131 @@
+# Alpha_complex #
+
+## `alpha_complex_3d_persistence` ##
+This program computes the persistent homology with coefficient field Z/pZ of the 3D alpha complex built from a 3D point cloud. The output diagram contains one bar per line, written with the convention:
+
+`p dim b d`
+
+where `dim` is the dimension of the homological feature, `b` and `d` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients (`p = p1*...*pr` is the product of prime numbers *pi* such that the homology feature exists in homology with *Z/piZ* coefficients).
+
+**Usage**
+`alpha_complex_3d_persistence <input OFF file> <p> <min_persistence>` 
+where
+`<input OFF file>` is the path to the input point cloud in OFF format.
+`<p>` is the characteristic p of the coefficient field *Z/pZ* for computing homology. It must be a stricly positive integer.
+`<min_persistence>` is the minimal lifetime of homology feature to be recorded. Enter a negative value to see zero length intervals. It must be a floating-point number >= -1.
+
+**Example**
+`alpha_complex_3d_persistence ../../data/points/tore3D_300.off 2 0.45`
+
+outputs:
+```
+Simplex_tree dim: 3
+2  0 0 inf 
+2  1 0.0682162 1.0001 
+2  1 0.0934117 1.00003 
+2  2 0.56444 1.03938 
+```
+
+Here we retrieve expected Betti numbers on a tore 3D:
+```
+Betti numbers[0] = 1
+Betti numbers[1] = 2
+Betti numbers[2] = 1
+```
+
+N.B.: 
+* `alpha_complex_3d_persistence` only accepts OFF files in dimension 3.
+* Filtration values are alpha square values.
+
+
+
+
+## `periodic_alpha_complex_3d_persistence` ##
+This program computes the persistent homology with coefficient field Z/pZ of the 3D periodic alpha complex built from a 3D point cloud. The output diagram contains one bar per line, written with the convention:
+
+`p dim b d`
+
+where `dim` is the dimension of the homological feature, `b` and `d` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients (`p = p1*...*pr` is the product of prime numbers *pi* such that the homology feature exists in homology with *Z/piZ* coefficients).
+
+**Usage**
+`periodic_alpha_complex_3d_persistence <input OFF file> <p> <min_persistence>`
+where
+`<input OFF file>` is the path to the input point cloud in OFF format.
+`<p>` is the characteristic p of the coefficient field *Z/pZ* for computing homology. It must be a stricly positive integer.
+`<min_persistence>` is the minimal lifetime of homology feature to be recorded. Enter a negative value to see zero length intervals. It must be a floating-point number >= -1.
+
+**Example**
+`periodic_alpha_complex_3d_persistence ../../data/points/grid_10_10_10_in_0_1.off ../../data/points/iso_cuboid_3_in_0_1.txt 3 1.0`
+
+outputs:
+```
+Periodic Delaunay computed.
+Simplex_tree dim: 3
+3  0 0 inf 
+3  1 0.0025 inf 
+3  1 0.0025 inf 
+3  1 0.0025 inf 
+3  2 0.005 inf 
+3  2 0.005 inf 
+3  2 0.005 inf 
+3  3 0.0075 inf 
+```
+
+Here we retrieve expected Betti numbers on an 3D iso-oriented cuboids:
+```
+Betti numbers[0] = 1
+Betti numbers[1] = 3
+Betti numbers[2] = 3
+Betti numbers[3] = 1
+```
+
+N.B.: 
+* `periodic_alpha_complex_3d_persistence` only accepts OFF files in dimension 3.
+* In this example, the periodic cube is hard coded to { x = [0,1]; y = [0,1]; z = [0,1] }
+* Filtration values are alpha square values.
+
+
+
+
+
+## `alpha_complex_persistence` ##
+This program computes the persistent homology with coefficient field Z/pZ of the dD alpha complex built from a dD point cloud. The output diagram contains one bar per line, written with the convention:
+
+`p dim b d`
+
+where `dim` is the dimension of the homological feature, `b` and `d` are respectively the birth and death of the feature, and `p` is the characteristic of the field *Z/pZ* used for homology coefficients (`p = p1*...*pr` is the product of prime numbers pi such that the homology feature exists in homology with Z/piZ coefficients).
+
+**Usage**
+`alpha_complex_persistence [options] <OFF input file>`
+
+**Allowed options**
+
+* `-h [ --help ]` Produce help message
+* `-o [ --output-file ]` Name of file in which the persistence diagram is written. By default, print in std::cout.
+* `-r [ --max-alpha-square-value ]` (default = inf) Maximal alpha square value for the Alpha complex construction.
+* `-p [ --field-charac ]` (default = 11)     Characteristic p of the coefficient field Z/pZ for computing homology.
+* `-m [ --min-persistence ]` (default = 0) Minimal lifetime of homology feature to be recorded. Enter a negative value to see zero length intervals.
+
+**Example**
+`alpha_complex_persistence -r 32 -p 2 -m 0.45 ../../data/points/tore3D_300.off`
+
+outputs:
+```
+Alpha complex is of dimension 3 - 9273 simplices - 300 vertices.
+Simplex_tree dim: 3
+2  0 0 inf 
+2  1 0.0682162 1.0001 
+2  1 0.0934117 1.00003 
+2  2 0.56444 1.03938 
+```
+
+Here we retrieve expected Betti numbers on a tore 3D:
+```
+Betti numbers[0] = 1
+Betti numbers[1] = 2
+Betti numbers[2] = 1
+```
+
+N.B.: 
+* `alpha_complex_persistence` only accepts OFF files in dimension d.
+* Filtration values are alpha square values.