Utilities

Alpha complex

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 birth death

where dim is the dimension of the homological feature, birth and death are respectively the birth and death of the feature, and p is the characteristic of the field Z/pZ used for homology coefficients (p must be a prime number).

Usage

alpha_complex_persistence [options] <input OFF file>

where <input OFF file> is the path to the input point cloud in nOFF ASCII format.

Allowed options

  • -h [ --help ] Produce help message
  • -o [ --output-file ] Name of file in which the persistence diagram is written. Default print in standard output.
  • -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

N.B.:

  • Filtration values are alpha square values.

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 birth death

where dim is the dimension of the homological feature, birth and death are respectively the birth and death of the feature, and p is the characteristic of the field Z/pZ used for homology coefficients (p must be a prime number).

Usage

alpha_complex_3d_persistence [options] <input OFF file>

where <input OFF file> is the path to the input point cloud in nOFF ASCII format.

Allowed options

  • -h [ --help ] Produce help message
  • -o [ --output-file ] Name of file in which the persistence diagram is written. Default print in standard output.
  • -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_3d_persistence ../../data/points/tore3D_300.off -p 2 -m 0.45

N.B.:

  • alpha_complex_3d_persistence only accepts OFF files in dimension 3.
  • Filtration values are alpha square values.

exact_alpha_complex_3d_persistence

Same as alpha_complex_3d_persistence, but using exact computation. It is slower, but it is necessary when points are on a grid for instance.

weighted_alpha_complex_3d_persistence

Same as alpha_complex_3d_persistence, but using weighted points.

Usage

weighted_alpha_complex_3d_persistence [options] <input OFF file> <weights input file>

where

  • <input OFF file> is the path to the input point cloud in nOFF ASCII format.
  • <input weights file> is the path to the file containing the weights of the points (one value per line).

Allowed options

  • -h [ --help ] Produce help message
  • -o [ --output-file ] Name of file in which the persistence diagram is written. Default print in standard output.
  • -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

weighted_alpha_complex_3d_persistence ../../data/points/tore3D_300.off ../../data/points/tore3D_300.weights -p 2 -m 0.45

N.B.:

periodic_alpha_complex_3d_persistence

Same as alpha_complex_3d_persistence, but using periodic alpha shape 3d. Refer to the CGAL’s 3D Periodic Triangulations User Manual for more details.

Usage

periodic_alpha_complex_3d_persistence [options] <input OFF file> <cuboid file>

where

  • <input OFF file> is the path to the input point cloud in nOFF ASCII format.
  • <cuboid file> is the path to the file describing the periodic domain. It must be in the format described here.

Allowed options

  • -h [ --help ] Produce help message
  • -o [ --output-file ] Name of file in which the persistence diagram is written. Default print in standard output.
  • -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

periodic_alpha_complex_3d_persistence ../../data/points/grid_10_10_10_in_0_1.off ../../data/points/iso_cuboid_3_in_0_1.txt -p 3 -m 1.0

N.B.:

  • Cuboid file must be in the format described here.
  • Filtration values are alpha square values.

Bottleneck distance

bottleneck_read_file_example

This program computes the Bottleneck distance between two persistence diagram files.

Usage

bottleneck_read_file_example <file_1.pers> <file_2.pers> [<tolerance>]

where

  • <file_1.pers> and <file_2.pers> must be in the format described here.
  • <tolerance> is an error bound on the bottleneck distance (set by default to the smallest positive double value).

Cover complex

Nerve

This program builds the Nerve of a point cloud sampled on an OFF file. The cover C comes from the preimages of intervals covering a coordinate function, which are then refined into their connected components using the triangulation of the .OFF file.

The program also writes a file SC.txt. The first three lines in this file are the location of the input point cloud and the function used to compute the cover. The fourth line contains the number of vertices nv and edges ne of the Nerve. The next nv lines represent the vertices. Each line contains the vertex ID, the number of data points it contains, and their average color function value. Finally, the next ne lines represent the edges, characterized by the ID of their vertices.

Usage

Nerve <OFF input file> coordinate resolution gain [--v]

where

  • coordinate is the coordinate function to cover
  • resolution is the number of the intervals
  • gain is the gain for each interval
  • --v is optional, it activates verbose mode.

Example

Nerve ../../data/points/human.off 2 10 0.3

  • Builds the Nerve of a point cloud sampled on a 3D human shape (human.off). The cover C comes from the preimages of intervals (10 intervals with gain 0.3) covering the height function (coordinate 2).

python KeplerMapperVisuFromTxtFile.py -f ../../data/points/human.off_sc.txt

  • Constructs human.off_sc.html file. You can now use your favorite web browser to visualize it.

VoronoiGIC

This util builds the Graph Induced Complex (GIC) of a point cloud. It subsamples N points in the point cloud, which act as seeds of a geodesic Voronoï diagram. Each cell of the diagram is then an element of C.

The program also writes a file *_sc.off, that is an OFF file that can be visualized with GeomView.

Usage

VoroniGIC <OFF input file> samples_number [--v]

where

  • samples_number is the number of samples to take from the point cloud
  • --v is optional, it activates verbose mode.

Example

VoroniGIC ../../data/points/human.off 700

  • Builds the Voronoi Graph Induced Complex with 700 subsamples from human.off file. ../../data/points/human_sc.off can be visualized with GeomView.

Cubical Complex

cubical_complex_persistence

This program computes persistent homology, by using the Bitmap_cubical_complex class, of cubical complexes provided in text files in Perseus style. See here for a description of the file format.

Example

cubical_complex_persistence data/bitmap/CubicalTwoSphere.txt

  • Creates a Cubical Complex from the Perseus style file CubicalTwoSphere.txt, computes Persistence cohomology from it and writes the results in a persistence file CubicalTwoSphere.txt_persistence.

periodic_cubical_complex_persistence

Same as above, but with periodic boundary conditions.

Example

periodic_cubical_complex_persistence data/bitmap/3d_torus.txt

  • Creates a Periodical Cubical Complex from the Perseus style file 3d_torus.txt, computes Persistence cohomology from it and writes the results in a persistence file 3d_torus.txt_persistence.

Rips Complex

rips_persistence

This program computes the persistent homology with coefficient field Z/pZ of a Rips complex defined on a set of input points, using Euclidean distance. The output diagram contains one bar per line, written with the convention:

p dim birth death

where dim is the dimension of the homological feature, birth and death are respectively the birth and death of the feature, and p is the characteristic of the field Z/pZ used for homology coefficients (p must be a prime number).

Usage

rips_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. Default print in standard output.
  • -r [ --max-edge-length ] (default = inf) Maximal length of an edge for the Rips complex construction.
  • -d [ --cpx-dimension ] (default = 1) Maximal dimension of the Rips complex we want to compute.
  • -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.

Beware: this program may use a lot of RAM and take a lot of time if max-edge-length is set to a large value.

Example 1 with Z/2Z coefficients

rips_persistence ../../data/points/tore3D_1307.off -r 0.25 -m 0.5 -d 3 -p 2

Example 2 with Z/3Z coefficients

rips_persistence ../../data/points/tore3D_1307.off -r 0.25 -m 0.5 -d 3 -p 3

rips_distance_matrix_persistence

Same as rips_persistence but taking a distance matrix as input.

Usage

rips_persistence [options] <CSV input file>

where <CSV input file> is the path to the file containing a distance matrix. Can be square or lower triangular matrix. Separator is ‘;’.

Example

rips_distance_matrix_persistence data/distance_matrix/full_square_distance_matrix.csv -r 15 -d 3 -p 3 -m 0

Witness complex

For more details about the witness complex, please read the user manual of the package.

weak_witness_persistence

This program computes the persistent homology with coefficient field Z/pZ of a Weak witness complex defined on a set of input points. The output diagram contains one bar per line, written with the convention:

p dim birth death

where dim is the dimension of the homological feature, birth and death are respectively the birth and death of the feature, and p is the characteristic of the field Z/pZ used for homology coefficients.

Usage

weak_witness_persistence [options] <OFF input file>

Allowed options

  • -h [ --help ] Produce help message
  • -l [ --landmarks ] Number of landmarks to choose from the point cloud.
  • -o [ --output-file ] Name of file in which the persistence diagram is written. By default, print in std::cout.
  • -a [ --max-sq-alpha ] (default = inf) Maximal squared relaxation parameter.
  • -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.
  • -d [ --cpx-dimension ] (default = 2147483647) Maximal dimension of the weak witness complex we want to compute.

Example

weak_witness_persistence data/points/tore3D_1307.off -l 20 -a 0.5 -m 0.006

N.B.: output is random as the 20 landmarks are chosen randomly.

strong_witness_persistence

This program computes the persistent homology with coefficient field Z/pZ of a Strong witness complex defined on a set of input points. The output diagram contains one bar per line, written with the convention:

p dim birth death

where dim is the dimension of the homological feature, birth and death are respectively the birth and death of the feature, and p is the characteristic of the field Z/pZ used for homology coefficients.

Usage

strong_witness_persistence [options] <OFF input file>

Allowed options

  • -h [ --help ] Produce help message
  • -l [ --landmarks ] Number of landmarks to choose from the point cloud.
  • -o [ --output-file ] Name of file in which the persistence diagram is written. By default, print in std::cout.
  • -a [ --max-sq-alpha ] (default = inf) Maximal squared relaxation parameter.
  • -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.
  • -d [ --cpx-dimension ] (default = 2147483647) Maximal dimension of the weak witness complex we want to compute.

Example

strong_witness_persistence data/points/tore3D_1307.off -l 20 -a 0.5 -m 0.06

N.B.: output is random as the 20 landmarks are chosen randomly.

common

off_file_from_shape_generator

Generates a pointset and save it in an OFF file. Command-line is:

off_file_from_shape_generator on|in sphere|cube|curve|torus|klein <filename> <num_points> <dimension> <parameter1> <parameter2>...

Warning: “on cube” generator is not available!

Examples

off_file_from_shape_generator on sphere onSphere.off 1000 3 15.2

  • Generates an onSphere.off file with 1000 points randomized on a sphere of dimension 3 and radius 15.2.

off_file_from_shape_generator in sphere inSphere.off 100 2

  • Generates an inSphere.off file with 100 points randomized in a sphere of dimension 2 (circle) and radius 1.0 (default).

off_file_from_shape_generator in cube inCube.off 10000 3 5.8

  • Generates a inCube.off file with 10000 points randomized in a cube of dimension 3 and side 5.8.