summaryrefslogtreecommitdiff
path: root/src/Alpha_complex/utilities/alphacomplex.md
blob: 527598a92c3ee0963425a5908725a5d1dd29eb2a (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
---
layout: page
title: "Alpha complex"
meta_title: "Alpha complex"
teaser: ""
permalink: /alphacomplex/
---
{::comment}
Leave the lines above as it is required by the web site generator 'Jekyll'
{:/comment}


## 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]({{ site.officialurl }}/doc/latest/fileformats.html#FileFormatsOFF).

**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.
* `-e [ --exact ]` for the exact computation version.
* `-f [ --fast ]` for the fast computation version.

**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.
One can use exact computation. It is slower, but it is necessary when points
are on a grid for instance.
Alpha complex 3d can be weighted and/or periodic (refer to the
[CGAL's 3D Periodic Triangulations User Manual](
https://doc.cgal.org/latest/Periodic_3_triangulation_3/index.html)
for more details).

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]({{ site.officialurl }}/doc/latest/fileformats.html#FileFormatsOFF).

**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.
* `-c [ --cuboid-file ]` is the path to the file describing the periodic domain.
It must be in the format described
[here]({{ site.officialurl }}/doc/latest/fileformats.html#FileFormatsIsoCuboid).
Default version is not periodic.
* `-w [ --weight-file ]` is the path to the file containing the weights of the
points (one value per line).
Default version is not weighted.
* `-e [ --exact ]` for the exact computation version (not compatible with
weight and periodic version).
* `-f [ --fast ]` for the fast computation version.

**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.
* Weights values are explained on CGAL
[Alpha shape](https://doc.cgal.org/latest/Alpha_shapes_3/index.html#title0)
and
[Regular triangulation](https://doc.cgal.org/latest/Triangulation_3/index.html#Triangulation3secclassRegulartriangulation) documentation.