Debian Codegraph @

src/common/doc/file_formats.h

raw
1 /* This file is part of the Gudhi Library - https://gudhi.inria.fr/ - which is released under MIT.
2 * See file LICENSE or go to https://gudhi.inria.fr/licensing/ for full license details.
3 * Author(s): Clément Jamin
4 *
5 * Copyright (C) 2017 Inria
6 *
7 * Modification(s):
8 * - YYYY/MM Author: Description of the modification
9 */
10
11 #ifndef DOC_COMMON_FILE_FORMAT_H_
12 #define DOC_COMMON_FILE_FORMAT_H_
13
14 namespace Gudhi {
15
16 /*! \page fileformats File formats
17
18 \tableofcontents
19
20 \section FileFormatsOFF OFF file format
21
22 OFF files must be conform to format described here: http://www.geomview.org/docs/html/OFF.html
23
24 OFF files are mainly used as point cloud inputs. Here is an example of 7 points in a 3-dimensional space. As edges and
25 faces are not used for point set, there is no need to specify them (just set their numbers to 0):
26
27 \include points/alphacomplexdoc.off
28
29 For dimensions bigger than 3, the dimension can be set like here:
30 \verbatim
31 # Dimension is no more 3
32 nOFF
33 # dimension 4 - 7 vertices - 0 face - 0 edge
34 4 7 0 0
35 # Point set:
36 1.0 1.0 0.0 0.0
37 7.0 0.0 0.0 0.0
38 4.0 6.0 0.0 0.0
39 9.0 6.0 0.0 0.0
40 0.0 14.0 0.0 0.0
41 2.0 19.0 0.0 0.0
42 9.0 17.0 0.0 0.0
43 \endverbatim
44
45
46 \section FileFormatsPers Persistence Diagram
47
48 Such a file, whose extension is usually `.pers`, contains a list of persistence intervals.<br>
49 Lines starting with `#` are ignored (comments).<br>
50 Other lines might contain 2, 3 or 4 values (the number of values on each line must be the same for all lines):
51 \verbatim
52 [[field] dimension] birth death
53 \endverbatim
54
55 Here is a simple sample file:
56 \verbatim
57 # Persistence diagram example
58 2 2.7 3.7
59 2 9.6 14.
60 # Some comments
61 3 34.2 34.974
62 4 3. inf
63 \endverbatim
64
65 Other sample files can be found in the `data/persistence_diagram` folder.
66
67 Such files can be generated with `Gudhi::persistent_cohomology::Persistent_cohomology::output_diagram()` and read with
68 `Gudhi::read_persistence_intervals_and_dimension()`, `Gudhi::read_persistence_intervals_grouped_by_dimension()` or
69 `Gudhi::read_persistence_intervals_in_dimension()`.
70
71
72 \section FileFormatsIsoCuboid Iso-cuboid
73
74 Such a file describes an iso-oriented cuboid with diagonal opposite vertices (min_x, min_y, min_z,...) and (max_x, max_y, max_z, ...). The format is:<br>
75 \verbatim
76 min_x min_y [min_z ...]
77 max_x max_y [max_z ...]
78 \endverbatim
79
80 Here is a simple sample file in the 3D case:
81 \verbatim
82 -1. -1. -1.
83 1. 1. 1.
84 \endverbatim
85
86
87 \section FileFormatsPerseus Perseus
88
89 This file format is a format inspired from the Perseus software
90 (http://www.sas.upenn.edu/~vnanda/perseus/) by Vidit Nanda.
91 The first line contains a number d begin the dimension of the
92 bitmap (2 in the example below). Next d lines are the numbers of top dimensional cubes in each dimensions (3 and 3
93 in the example below). Next, in lexicographical order, the filtration of top dimensional cubes is given (1 4 6 8
94 20 4 7 6 5 in the example below).
95
96 \image html "exampleBitmap.png" "Example of a input data."
97
98 The input file for the following complex is:
99 \verbatim
100 2
101 3
102 3
103 1
104 4
105 6
106 8
107 20
108 4
109 7
110 6
111 5
112 \endverbatim
113
114 To indicate periodic boundary conditions in a
115 given direction, then number of top dimensional cells in this direction have to be multiplied by -1. For instance:
116
117 \verbatim
118 2
119 -3
120 3
121 1
122 4
123 6
124 8
125 20
126 4
127 7
128 6
129 5
130 \endverbatim
131
132 Indicate that we have imposed periodic boundary conditions in the direction x, but not in the direction y.
133
134 Other sample files can be found in the `data/bitmap` folder.
135
136 \note Unlike in Perseus format the filtration on the maximal cubes can be any double precision number.
137 Consequently one cannot mark the cubes that are not present with `-1`'s. To do that please set their filtration value
138 to \f$+\infty\f$ (aka. `inf` in the file).
139
140 */
141 } // namespace Gudhi
142
143 #endif // DOC_COMMON_FILE_FORMAT_H_