diff options
Diffstat (limited to 'src/common/doc/file_formats.h')
| -rw-r--r-- | src/common/doc/file_formats.h | 143 |
1 files changed, 143 insertions, 0 deletions
diff --git a/src/common/doc/file_formats.h b/src/common/doc/file_formats.h new file mode 100644 index 00000000..4af5d45c --- /dev/null +++ b/src/common/doc/file_formats.h @@ -0,0 +1,143 @@ +/* This file is part of the Gudhi Library - https://gudhi.inria.fr/ - which is released under MIT. + * See file LICENSE or go to https://gudhi.inria.fr/licensing/ for full license details. + * Author(s): Clément Jamin + * + * Copyright (C) 2017 Inria + * + * Modification(s): + * - YYYY/MM Author: Description of the modification + */ + +#ifndef DOC_COMMON_FILE_FORMAT_H_ +#define DOC_COMMON_FILE_FORMAT_H_ + +namespace Gudhi { + +/*! \page fileformats File formats + + \tableofcontents + + \section FileFormatsOFF OFF file format + + OFF files must be conform to format described here: http://www.geomview.org/docs/html/OFF.html + + OFF files are mainly used as point cloud inputs. Here is an example of 7 points in a 3-dimensional space. As edges and + faces are not used for point set, there is no need to specify them (just set their numbers to 0): + + \include points/alphacomplexdoc.off + + For dimensions bigger than 3, the dimension can be set like here: + \verbatim + # Dimension is no more 3 + nOFF + # dimension 4 - 7 vertices - 0 face - 0 edge + 4 7 0 0 + # Point set: + 1.0 1.0 0.0 0.0 + 7.0 0.0 0.0 0.0 + 4.0 6.0 0.0 0.0 + 9.0 6.0 0.0 0.0 + 0.0 14.0 0.0 0.0 + 2.0 19.0 0.0 0.0 + 9.0 17.0 0.0 0.0 + \endverbatim + + + \section FileFormatsPers Persistence Diagram + + Such a file, whose extension is usually `.pers`, contains a list of persistence intervals.<br> + Lines starting with `#` are ignored (comments).<br> + Other lines might contain 2, 3 or 4 values (the number of values on each line must be the same for all lines): + \verbatim + [[field] dimension] birth death + \endverbatim + + Here is a simple sample file: + \verbatim + # Persistence diagram example + 2 2.7 3.7 + 2 9.6 14. + # Some comments + 3 34.2 34.974 + 4 3. inf + \endverbatim + + Other sample files can be found in the `data/persistence_diagram` folder. + + Such files can be generated with `Gudhi::persistent_cohomology::Persistent_cohomology::output_diagram()` and read with + `Gudhi::read_persistence_intervals_and_dimension()`, `Gudhi::read_persistence_intervals_grouped_by_dimension()` or + `Gudhi::read_persistence_intervals_in_dimension()`. + + + \section FileFormatsIsoCuboid Iso-cuboid + + 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> + \verbatim + min_x min_y [min_z ...] + max_x max_y [max_z ...] + \endverbatim + + Here is a simple sample file in the 3D case: + \verbatim + -1. -1. -1. + 1. 1. 1. + \endverbatim + + + \section FileFormatsPerseus Perseus + + This file format is a format inspired from the Perseus software + (http://www.sas.upenn.edu/~vnanda/perseus/) by Vidit Nanda. + The first line contains a number d begin the dimension of the + bitmap (2 in the example below). Next d lines are the numbers of top dimensional cubes in each dimensions (3 and 3 + in the example below). Next, in lexicographical order, the filtration of top dimensional cubes is given (1 4 6 8 + 20 4 7 6 5 in the example below). + + \image html "exampleBitmap.png" "Example of a input data." + + The input file for the following complex is: + \verbatim + 2 + 3 + 3 + 1 + 4 + 6 + 8 + 20 + 4 + 7 + 6 + 5 + \endverbatim + + To indicate periodic boundary conditions in a + given direction, then number of top dimensional cells in this direction have to be multiplied by -1. For instance: + + \verbatim + 2 + -3 + 3 + 1 + 4 + 6 + 8 + 20 + 4 + 7 + 6 + 5 + \endverbatim + + Indicate that we have imposed periodic boundary conditions in the direction x, but not in the direction y. + + Other sample files can be found in the `data/bitmap` folder. + + \note Unlike in Perseus format the filtration on the maximal cubes can be any double precision number. + Consequently one cannot mark the cubes that are not present with `-1`'s. To do that please set their filtration value + to \f$+\infty\f$ (aka. `inf` in the file). + +*/ +} // namespace Gudhi + +#endif // DOC_COMMON_FILE_FORMAT_H_ |