karambola

Description:

Karambola is a program to calculate irreducible (spherical) Minkowski Tensors and cartesian Minkowski Tensors of three-dimensional bodies and surfaces. The surface has to be given in terms of planar and convex polygons in the .poly file format.
Minkowski Tensors can be calculated globally, or for subsets (called ”labels”).
In the demo folder a program called “pointpattern2voronoi” is included, which calculates the Voronoi Diagram of a given point pattern.

Download:

The source code can be found on Github, or as a ZIP archive.

Karambola is written in plain ISO C++ and only needs the GNU Scientific Library to compile. It is available as Free Software under the terms of the GNU General Public License, Version 3 or later. It also includes a copy of Catch2 for unit testing.

Installation

To compile Karambola, use: make
You need the GSL library to compile Karambola: http://www.gnu.org/software/gsl/
(for example, the libgsl-dev or libgsl-devel package on Linux)

To run the test suite, use: make test

Usage

To start Karambola, use the following syntax:
karambola input-file.poly {--labels | --nolabels} [more options...]

You have to use one of the the label flags:
--no-labels to indicate that you want to ignore the labels in the input file, if there are any
--labels to indicate that you want to use the labels in the input file
(an error occurs if the file has no labels and the --labels option is set)

Karambola calculates a standard set of Minkowski Tensors. If you like to compute a single Tensor, you can use the --compute w??? option, i. e. --compute w102.

Not all Minkowski Tensors can be calculated for any given input file. If calculating the Minkowski Tensors for a file is not possible because of missing neighbours, Karambola will indicate that. If, however, you want to calculate the MT by stubbornly applying the formulae nevertheless,
you can use the --force w??? options:
--force w000 --force w200
--force w300 --force w010
--force w210 --force w310
--force w010 --force w210
--force w310 --force w202

If you add the option --reference_centroid, the tensors are calculated in reference to the Minkowski Vectors to the and not in reference to the origin, i. e. the reference point for the Minkowski Tensor Wn20 is the corresponding center of gravity

(1)   \begin{equation*} C_n = \frac{W_n^{10} }{ W_n^{00} } \end{equation*}

You can define the outputfoldername if you use the option
--output outputfoldername or -o outputfoldername

If this option is not set, Karambola creates a folder named inputfilename_mink_val into which the outputfiles will be written.

Output files

Karambola creates a folder named inputfilename_mink_val or if the --output option is set a user defined folder, into which the outputfiles will be written. In the following the different outputfiles are explained:

  • surface_props:
    in this file are some statistics: the shortest edge, longest edge, smallest area and largest area and for every label whether the surface is closed, shared with other labels or open.
    ATTENTION: relatively short edges or small faces in your data (of order 1e-15) may generate ERRORs in the results or unreliable data.
  • w000_w100_w200_w300:
    this file stores the results for the scalar Minkowski functionals.
  • w010_w110_w210_w310:
    this file stores the results for the Minkowski vectors.
  • w020, w120, w220, w320, w102, w202
    this file this file stores the results for the Cartesian Minkowski tensors of rank 2.
  • w020_eigsys, w120_eigsys, w220_eigsys, w320_eigsys, w102_eigsys, w202_eigsys
    this file this file stores the results for the eigenvalues and eigenvectors of the Cartesian Minkowski tensors of rank 2.
  • msm_ql:
    this file this file stores the irreducible Minkowski structure metrics q_l and w_l

poly file format

Minimal example of a file describing a triangle labelled with ’7’ and a quadrangle labelled with ’2’:

POINTS
1: 0.000000000 e+00 0.000000000 e+00
2: 1.000000000 e+00 0.000000000 e+00
3: 0.000000000 e+00 1.000000000 e+00
4: 1.000000000 e+00 1.000000000 e+00
POLYS
1: 1 2 3 < c (0 , 0 , 0 , 7)
2: 1 2 4 3 < c (0 , 0 , 0 , 2)
END

Look at the demo folder to find examples for poly files.

References

The code used in karambola is described in the following publications:

  • [DOI] G. E. Schröder-Turk, W. Mickel, S. C. Kapfer, F. M. Schaller, B. Breidenbach, D. Hug, and K. Mecke, “Minkowski tensors of anisotropic spatial structure,” New journal of physics, vol. 15, iss. 8, p. 83028, 2013.
  • [DOI] G. E. Schröder-Turk, W. Mickel, S. C. Kapfer, M. A. Klatt, F. M. Schaller, M. J. F. Hoffmann, N. Kleppmann, P. Armstrong, A. Inayat, D. Hug, M. Reichelsdorfer, W. Peukert, W. Schwieger, and K. Mecke, “Minkowski Tensor Shape Analysis of Cellular, Granular and Porous Structures,” Adv. mater., vol. 23, iss. 22-23, p. 2535–2553, 2011.